audit

type Absence struct {
	Key   string    `json:"key"`             // the key claimed absent from the committed set
	Size  int       `json:"size"`            // number of committed keys the proof is against
	Left  *Neighbor `json:"left,omitempty"`  // committed key just below Key in sort order; nil if Key sorts before all
	Right *Neighbor `json:"right,omitempty"` // committed key just above Key in sort order; nil if Key sorts after all
}

type AbsenceBundle struct {
	Format  string         `json:"format"`  // AbsenceFormat
	RunID   string         `json:"run_id"`  // the run whose key set the proof is against; must equal STH.RunID
	Absence Absence        `json:"absence"` // the non-membership proof
	STH     SignedTreeHead `json:"sth"`     // the signed commitment to the key set the proof is proven against
}

type Alg = agent.Alg

type Anchor interface {
	Publish(ctx context.Context, runID string, sth SignedTreeHead) error
}

type AnchorEntry struct {
	Format string         `json:"format"` // AnchorEntryFormat
	Seq    int            `json:"seq"`    // the entry's position in the anchor log
	RunID  string         `json:"run_id"` // the run whose commitment was published
	STH    SignedTreeHead `json:"sth"`    // the published signed tree head
}

type ApprovalVerdict struct {
	// Need is the expected policy's k.
	Need int `json:"need"`
	// ToolName and Args are the call the approvers decided on, from the proven request.
	ToolName string          `json:"tool_name"`
	Args     json.RawMessage `json:"args,omitempty"`
	// Counted lists the approvers whose approval counted in the recount, in journal order.
	Counted []string `json:"counted"`
	// DeniedBy lists the approvers whose counted decision was a denial.
	DeniedBy []string `json:"denied_by,omitempty"`
	// Ignored lists every other disclosed decision, with the reason it did not count.
	Ignored []IgnoredDecision `json:"ignored,omitempty"`
	// Times lists the two times of every counted decision (approvals and denials), in journal
	// order, with sanity flags under DefaultDecisionTimeTolerance (see FlagDecisionTimes). They are
	// for a person reading the verdict: no time, and no flag, affects the count or OK.
	Times []DecisionTime `json:"times,omitempty"`
	// AskedAt is when the run asked for approval, by the run's clock: for a gated plan flow node the
	// recorded_at of its proven request (agent.ApprovalRequest), else that of the proven
	// approval-pending record (agent.ApprovalWait); "" when the evidence holds neither with a time
	// (each decision is then flagged FlagAskedUnknown).
	AskedAt string `json:"asked_at,omitempty"`
	// Requesters are the requesters the recount excluded, from the proven run:principal record
	// (agent.RunPrincipal.Requesters: the principals of the runs above the run, root first, then the
	// run's own), when the expected policy excludes the requester
	// (agent.ApprovalPolicy.ExcludePrincipal); empty otherwise, or when the evidence does not prove
	// one.
	Requesters []string `json:"requesters,omitempty"`
	// Reask and ReaskedAt: when the gate asked again over a recorded tally it did not act on, why
	// (agent.PendingReapproval, agent.PendingSoDReapproval) and when (its recorded_at, by the run's
	// clock), from the newest proven re-ask note (agent.ApprovalReaskStep); empty when the evidence
	// holds none. Display only, like AskedAt.
	Reask     string `json:"reask,omitempty"`
	ReaskedAt string `json:"reasked_at,omitempty"`
	// HeadAt is when the signed tree head the evidence is proven under was signed (its
	// TimestampNanos, in agent.FormatTimestamp's form): every record it covers, the decisions
	// included, was journaled by then.
	HeadAt string `json:"head_at,omitempty"`
	// Problems lists every way the evidence is inconsistent with itself or with the expected
	// policy: an omitted decision the gate read, a recount that disagrees with the gate's
	// journaled tally, a different enforced policy, or records out of order. Any problem fails
	// the verdict.
	Problems []string `json:"problems,omitempty"`
	// OK reports no Problems and at least Need approvals counted.
	OK bool `json:"ok"`
}

type ApproverCert struct {
	Leaf  *x509.Certificate
	Chain []*x509.Certificate // the accepted path, leaf first, ending at the anchor
	// Anchor is the key of the trust anchor the chain ended at.
	Anchor SPKIHash
	// Scheme is the decision scheme derived from the leaf's key. A record whose approver_alg differs
	// from it does not count.
	Scheme Alg
	// PublicKey is the leaf key in the encoding NewVerifier reads for Scheme.
	PublicKey []byte
	// Identity is the verified canonical identifier of the leaf.
	Identity string
	// LeafHash is the SHA-256 of the leaf's DER, which the v4 decision bytes commit to.
	LeafHash [32]byte
	// KeyHash is the SHA-256 of the leaf's SubjectPublicKeyInfo: two counted decisions by different
	// approver ids with equal KeyHash are one key and do not both count.
	KeyHash SPKIHash
}

type AttenuateFunc func(parent Grant, subAgent string) Grant

type AttenuationConfig struct {
	// Store is the journal the sub-runs journal to, where each child grant is recorded as
	// a durable leaf of its sub-run. Give it the store the parent and the sub-agent use, for a
	// unified, provable journal.
	Store *agent.Journal
	// Narrow derives each child grant from the parent's (see AttenuateFunc).
	Narrow AttenuateFunc
	// Rules says how each scope key may narrow; CheckAttenuation enforces it before a child
	// grant is signed.
	Rules ScopeRules
}

type AuditedEventStore struct {
	// contains filtered or unexported fields
}

type AuditedStore struct {
	// contains filtered or unexported fields
}

type CRLInfo struct {
	Hash       [32]byte // SHA-256 of the DER
	Number     *big.Int
	ThisUpdate time.Time
	NextUpdate time.Time
	Entries    int
}

type CanonicalConfig struct {
	// Scheme is the one URI scheme accepted. Empty means "https".
	Scheme string
	// Host is the one URI host accepted, in lowercase. Empty means no URI identifier is accepted.
	Host string
	// Path matches the URI path (the part after the host, starting with "/"). Empty means the
	// default: "/person/" followed by 32 lowercase hex digits. It is matched against the whole
	// path, whatever anchors the expression has. Configure exactly one spelling of the id.
	Path *regexp.Regexp
}

type Canonicalizer interface {
	// Name identifies the function (for the identity record).
	Name() string
	// Version changes when the function's results do.
	Version() int
	// Canonical returns the canonical form of s as an identifier of the given kind, or an error when
	// s is not in the accepted profile.
	Canonical(kind IDKind, s string) (string, error)
}

type CertApprover struct {
	// ApproverID is the approver id this verifier serves: the key of the policy's identity map.
	ApproverID string
	// Policy is the compiled certificate policy of the gate.
	Policy *CertIdentity
	// Heads returns the signed tree heads of the run known to the caller (the anchor log's list, not
	// the producer's). A(d) is the time of the smallest head that covers the decision. Nil means no
	// head is known and no decision is provable.
	Heads func(runID string) ([]SignedTreeHead, error)
	// LogKey verifies the heads. Nil verifies none.
	LogKey Verifier
	// ClockTolerance is how far a larger head may be stamped before a smaller one without the heads
	// contradicting each other (default one minute).
	ClockTolerance time.Duration
	// Status holds the CRLs behind the revocation check. Nil means no status: no decision counts.
	Status *StatusSnapshot
	// StatusParams are the status rule's parameters (the window, the declared CA period, holds...). For a
	// live gate set CountLive and MaxStatusAge, and Now supplies the clock for each check; an offline
	// audit leaves Now nil and the rule judges the series against the decision.
	StatusParams StatusParams
	// Now, when set, is read for each decision to set StatusParams.Now.
	Now func() time.Time
	// ExecNow, when set, is the clock of the execution-time check (VerifyCertExec); otherwise Now, and
	// when that is nil too, the wall clock. It exists so a test or a deterministic simulation can move the
	// execution check in time apart from the count.
	ExecNow func() time.Time
	// RequesterIdentity, when set, maps a requester principal (as the run records it) to the canonical
	// identifier of the person, so separation of duties can exclude the requester by identifier. Without
	// it the roster is used: a principal equal (ASCII case folded) to an approver id of the identity map
	// maps to that approver's identifier, which only repeats the exclusion by approver id: a bank that
	// wants a requester who holds no approver id (a login that maps to a person) excluded by identity
	// must supply this function. A requester it cannot map is then excluded by approver id only, and
	// the finding carries a warning; without the function no warning is made.
	RequesterIdentity func(principal string) (identifier string, ok bool)
	// ExecStatusAge is how old the newest CRL of the leaf's issuing CA may be when the call is about to
	// run (the status check before execution). ValidateConfig requires that CA's period to be at most
	// half of it. It is set from the CA's actual period; there is no default.
	ExecStatusAge time.Duration
	// ExecStatusAgeFor is the same age for each CA tier above the leaf's issuing CA, by issuer key: the
	// status of an intermediate rests on its issuer's CRL, which an offline root publishes rarely. Every
	// CA in an accepted chain above the leaf's issuer must be named here (the execution check holds the
	// call otherwise), and ValidateConfig requires, for each: CAPeriodFor + CAOverlapFor <=
	// ExecStatusAgeFor <= StatusParams.MaxStatusAgeFor. A CA's tier is its position in the accepted
	// chain, never its key: the leaf's issuing CA always uses ExecStatusAge.
	ExecStatusAgeFor map[SPKIHash]time.Duration
	// CAOverlapFor is, for a CA tier, how long after its period ends the CA may still be publishing the
	// next CRL (an offline root's ceremony slack, AD CS's CRL overlap); the oldest status a gate can hold
	// for that CA is CAPeriodFor plus this. Zero is allowed.
	CAOverlapFor map[SPKIHash]time.Duration
	// PolicyEffectiveFrom is when the certificate policy took effect (the bank's change record), kept in
	// the identity record so the mapping at A(d) is knowable years later. ValidateConfig requires it.
	PolicyEffectiveFrom time.Time
	// StatusArchive receives the bytes of a CRL above agent.MaxStatusInline, which the journal records
	// by hash only. Without one the gate refuses to count on such a CRL.
	StatusArchive StatusArchive
	// GoDebug is the x509 settings of GODEBUG the process runs under (they change how certificates
	// verify), as the operator DECLARES them: the engine does not read the environment, so this is a
	// declaration, recorded as such in the identity record. Generate it from the real process settings and
	// check it at startup with CheckDeclaredGoDebug(declared, os.Getenv("GODEBUG")).
	GoDebug string
}

type CertError struct {
	Reason string
	Detail string
}

type CertIdentity struct {
	// contains filtered or unexported fields
}

type CertStatus struct {
	Serial *big.Int
	// Revoked: a CRL lists the certificate with an effective time E at or before A(d) (outside any
	// routine grace). E, ReasonCode, Compromise and RevokedBy describe the listing with the earliest E.
	Revoked    bool
	E          time.Time
	ReasonCode int
	Compromise bool     // keyCompromise, cACompromise or aACompromise: the bank's process treats a counted decision as disputed
	RevokedBy  [32]byte // hash of the CRL that lists it
	// Tier is the evidence of absence when not Revoked.
	Tier StatusTier
	// S is the thisUpdate of the latest usable CRL, LC that of the first CRL beyond notAfter when
	// one is established (LCKnown), Unbounded when expired entries are retained.
	S, LC     time.Time
	LCKnown   bool
	Unbounded bool
	// Stale: usable-in-time CRLs exist but fail the live freshness rules.
	Stale bool
	// Window is W' for this certificate.
	Window time.Duration
	// Used are the hashes of the CRLs that count as evidence of absence, in thisUpdate order.
	Used [][32]byte
	// Note says why the tier is not final.
	Note string
	// Caveat is stated with the verdict: what the status does not cover. Empty only when there is no
	// status.
	Caveat string
	// PolicyRefusal: the finding is the status policy refusing a certificate that was ever on hold
	// (StatusParams.AllowHolds off), not a revocation the CA recorded for the decision's time. It
	// refuses even a decision made before a later hold, so it must not be read as "revoked at E".
	PolicyRefusal bool
	// Basis says what the status rests on: "status issued at or after the decision", or "live count:
	// status issued before the decision (provisional only)". A tier is not a verification: only Final
	// is, and a live count never is. Empty when there is no status.
	Basis string
	// Warning is set when the series shows something the declared CAPeriod does not allow (a gap
	// longer than the CA said it would leave), or the snapshot evicted CRLs the verdict needed
	// (EvictionGap). It does not change the tier by itself; the gap already limits it.
	Warning string
	// EvictionGap: the snapshot evicted CRLs from the range the verdict needs, so it is at most
	// provisional.
	EvictionGap bool
}

type ChainStatus struct {
	Certs   []CertStatus
	Revoked bool       // any certificate revoked with E <= A(d)
	Tier    StatusTier // the weakest certificate's tier (meaningful when not Revoked)
}

type Consistency struct {
	First int      `json:"first"` // m: the earlier tree size
	Size  int      `json:"size"`  // n: the current tree size
	Path  [][]byte `json:"path"`  // proof hashes
}

type ConvergenceContent struct {
	Digest      string          `json:"digest"`      // the policy digest this certificate certifies (treated as opaque here)
	Certificate json.RawMessage `json:"certificate"` // the opaque, serialized convergence certificate bytes
}

type CoverageBound struct {
	MaxRecords int
	// MaxAge, with Now, flags a decision still uncovered MaxAge+Tolerance after its recorded_at.
	// Without a Now it is not applied.
	MaxAge    time.Duration
	Now       time.Time
	Tolerance time.Duration // clock skew allowed between the recorder and the checker
}

type CoverageReport struct {
	RunID          string             `json:"run_id"`
	Records        int                `json:"records"`
	Heads          int                `json:"heads"`        // heads that verified and belong to this journal
	LargestHead    int                `json:"largest_head"` // the largest such head's size, 0 if none
	Decisions      []DecisionCoverage `json:"decisions"`
	RejectedHeads  []RejectedHead     `json:"rejected_heads,omitempty"`  // ignored: invalid, or not this run's
	DivergentHeads []DivergentHead    `json:"divergent_heads,omitempty"` // signed for this run, and not this journal's
	// NoCountedHeads is set when the journal holds decisions and no head counted: every head given
	// was ignored or divergent (a wrong -pubkey makes every head ignored), or none was given. With a
	// bound set, OK is false then: nothing shows a decision is inside it.
	NoCountedHeads bool `json:"no_counted_heads,omitempty"`
	// contains filtered or unexported fields
}

type CurrentGrantProof struct {
	Format      string      `json:"format"`      // CurrentGrantFormat
	Leaf        ProofBundle `json:"leaf"`        // the ledger's last leaf under the presented head
	Consistency Consistency `json:"consistency"` // from the verifier's last-seen size to Leaf.STH.Size
}

type DecisionCoverage struct {
	Step       string `json:"step"`
	Approver   string `json:"approver,omitempty"` // empty for a decision recorded without a signature (Approve)
	Index      int    `json:"index"`              // the record's 0-based position in the journal
	RecordedAt string `json:"recorded_at,omitempty"`
	Status     string `json:"status"`
	// Basis says what made an overdue decision overdue: BasisRecords, or BasisAge. Empty otherwise.
	Basis string `json:"basis,omitempty"`
	// CoveredBySize is the size of the smallest verified head that includes the record, 0 if none.
	CoveredBySize int `json:"covered_by_size,omitempty"`
	// Behind is how many records the journal holds after this one.
	Behind int `json:"behind"`
	// Note says what limits the finding: "no recorded time" for a record with no usable
	// recorded_at (an unsigned agent.Approve decision records none), which an age bound treats as
	// over the bound.
	Note string `json:"note,omitempty"`
}

type DecisionReceipt struct {
	Format    string          `json:"format"` // ReceiptFormat
	RunID     string          `json:"run_id"`
	ToolUseID string          `json:"tool_use_id"`
	ToolName  string          `json:"tool_name"`
	Args      json.RawMessage `json:"args"`        // the call's arguments, as the approver signed them
	ArgsSHA   string          `json:"args_sha256"` // SHA-256 of the canonical arguments, lowercase hex: what the signature binds
	Approver  string          `json:"approver"`
	Approved  bool            `json:"approved"`
	DecidedAt string          `json:"decided_at"` // the approver's clock, signed (agent.FormatTimestamp form)
	Alg       Alg             `json:"alg"`
	Signature []byte          `json:"signature"`
	// Cert is the leaf-first DER certificate chain of a certificate-bound decision (base64 in JSON),
	// signed under agent.DecisionFormatCert: the signature binds the leaf's hash, so a receipt whose
	// chain is stripped or swapped does not verify. Empty for a bare-key decision. Certificates are
	// public values; a receipt still holds no key material.
	Cert [][]byte `json:"cert,omitempty"`
	// Record is the journal record's name, Index its position in the run's journal (0 is the
	// journal header), and RecordedAt when it was journaled, by the clock of the process that wrote
	// it (not signed by the approver).
	Record     string `json:"record"`
	Index      int    `json:"index"`
	RecordedAt string `json:"recorded_at"`
	// LeafHash is the journal record's leaf hash (JournalLeafHash), lowercase hex: what a head's
	// tree holds at Index, and what a redaction tombstone keeps of the record.
	LeafHash string `json:"leaf_hash"`
	// Anchor is the proof that a signed head of the journal commits to the decision at Index: the
	// record's inclusion under that head. It is empty on a receipt just written and added by
	// AnchorReceipt (bide audit verify-receipts -update) once a signed head covers the decision.
	// Everything above it is the approver's claim: Record, Index, RecordedAt and LeafHash are not
	// signed, and nothing in a receipt without an Anchor shows the application ever journaled the
	// decision. With an Anchor it does, and only then can CheckReceipt say the decision was deleted.
	Anchor *ProofBundle `json:"anchor,omitempty"`
}

type DecisionTime struct {
	Approver   string   `json:"approver"`
	Step       string   `json:"step"`
	DecidedAt  string   `json:"decided_at"`
	RecordedAt string   `json:"recorded_at,omitempty"`
	Flags      []string `json:"flags,omitempty"`
}

type DivergentHead struct {
	Size   int    `json:"size"`
	Reason string `json:"reason"`
}

type ECDSAP256Signer struct {
	Priv *ecdsa.PrivateKey // the P-256 private key that signs
}

type ECDSAP256Verifier struct {
	Pub *ecdsa.PublicKey // the P-256 public key that verifies
}

type EarnedAuthority struct {
	// contains filtered or unexported fields
}

type Ed25519Signer struct {
	Priv ed25519.PrivateKey // the Ed25519 private key that signs
}

type Ed25519Verifier struct {
	Pub ed25519.PublicKey // the Ed25519 public key that verifies
}

type EventInclusion struct {
	Format string `json:"format"` // EventInclusionFormat
	Salt   []byte `json:"salt"`   // the proven event's salt (agent.SaltSize bytes)
	Inclusion
}

type EventLog struct {
	// contains filtered or unexported fields
}

type EventStore interface {
	// Append durably records leaf at position seq (0-based, contiguous) for runID. It MUST be
	// append-only and idempotent on (runID, seq): re-appending an already-stored seq with the
	// SAME bytes is a no-op (so a retried mirror is safe), while a DIFFERENT leaf at an
	// existing seq must fail with an error that wraps ErrSeqTaken (a fork / tamper attempt, or a
	// lost race with another writer of that position, of which exactly one wins). A seq beyond the
	// next position, or a negative one, is a gap and must error without wrapping ErrSeqTaken. The
	// store may be shared by several handles or processes; every one sees the same positions.
	// Positions are contiguous per run, so a writer that wants seq n must have seen n-1 stored.
	Append(ctx context.Context, runID string, seq int, leaf []byte) error
	// Load returns every leaf for runID in seq order (0..n-1), or nil if the run is unknown.
	Load(ctx context.Context, runID string) ([][]byte, error)
}

type EvidenceAction struct {
	// Label is a short human description of the action: the tool-use id for "tool", the step name
	// for "step", the called tool's name for "call", the approver id for "approval", "approval
	// tally" for "approval-tally", and "grant <issuer> -> <subject>" for "grant".
	Label string `json:"label"`
	// Kind is the action category, one of "tool", "step", "grant", "call", "approval", or
	// "approval-tally"; the proven record must be of that kind.
	Kind EvidenceKind `json:"kind"`
	// Ref is the identifier the action was selected by: the tool-use id ("tool", "call"), the record
	// name ("step", "approval", "approval-tally"), or the grant digest ("grant").
	Ref string `json:"ref,omitempty"`
	// Bundle is the inclusion proof that this action is a committed leaf under the package's STH.
	Bundle ProofBundle `json:"bundle"`
}

type EvidenceConsistency struct {
	// From is an earlier signed journal head of the same run. Proof.First must equal From.Size.
	From SignedTreeHead `json:"from"`
	// Proof is the RFC 6962 consistency proof from From's tree to the package STH's tree.
	Proof Consistency `json:"proof"`
}

type EvidenceGrants struct {
	// Chain is the delegation chain, root-first to leaf-last, as signed grants (may be a single grant).
	Chain []SignedGrant `json:"chain"`
	// Anchored is one ProofBundle per grant in Chain, in the same order, proving that exact signed
	// grant is committed in the signed log.
	Anchored []EvidenceAction `json:"anchored"`
}

type EvidenceItem struct {
	Kind     EvidenceKind `json:"kind"`  // the item's kind: an action kind, KindRunCertificate, or KindConsistency
	Label    string       `json:"label"` // the human label for the item
	Ref      string       `json:"ref,omitempty"`
	Verified bool         `json:"verified"` // whether this item verified under the key
	Note     string       `json:"note"`     // plain-English detail, on success or failure
}

type EvidenceKind string

type EvidenceOption func(*evidenceOptions)

type EvidencePackage struct {
	// Format is the domain-separated format/version tag (EvidenceFormat).
	Format string `json:"format"`
	// RunID is the run this evidence is about; it must equal STH.RunID.
	RunID string `json:"run_id"`
	// Label is an optional producer-supplied description of what this evidence establishes (e.g.
	// "Q3 refund approvals"). No proof covers it; the seal attributes it to the log key holder.
	Label string `json:"label,omitempty"`
	// Alg and PublicKey name the key that signed the STH and the seal: its scheme and its encoded
	// public key (see NewVerifier), carried so a reader knows which key to obtain out of band.
	// Verify requires them to equal the verifier's; it never trusts them as the key.
	Alg       Alg    `json:"alg"`
	PublicKey []byte `json:"public_key"`

	// STH is the run's signed journal head: the commitment every action proof below is checked
	// against. One STH is built for the whole package so all proofs share one root. Its Timestamp is
	// when the package's commitment was made.
	STH SignedTreeHead `json:"sth"`

	// Actions are the material tool calls / steps proven included in the signed log. Each carries a
	// human label and the ProofBundle proving that one action is a leaf under the STH's root.
	Actions []EvidenceAction `json:"actions"`

	// Grants optionally carries the authority behind the run: the delegation chain (root-first) as
	// signed grants, plus a ProofBundle per grant proving the grant leaf is anchored in the signed
	// log. It is nil when the caller did not request grants (WithGrants).
	Grants *EvidenceGrants `json:"grants,omitempty"`

	// RunCertificate optionally carries the proof-carrying run certificate (only-approved-policies +
	// policies-convergence-certified) for the whole run. It is nil unless WithRunCertificate was set.
	RunCertificate *RunCertificate `json:"run_certificate,omitempty"`

	// Consistency optionally carries an append-only consistency proof from an earlier signed head of
	// this run's journal to STH. It is nil unless WithConsistencyFrom was set.
	Consistency *EvidenceConsistency `json:"consistency,omitempty"`

	// Signature is the seal: the log key's signature, under Alg, over the seal tag and the SHA-256
	// of the package's JSON with Signature empty (see Seal). A package changed after sealing, including one with actions appended, fails to
	// verify until resealed.
	Signature []byte `json:"signature"`
}

type EvidenceReport struct {
	// OK is the overall verdict: true only when the package-level checks pass and every item verified.
	OK bool `json:"ok"`
	// RunID echoes the package's run id; when OK it is the run the signed STH commits to.
	RunID string `json:"run_id"`
	// Label echoes the package's optional label; when OK it is the label the log key sealed.
	Label string `json:"label,omitempty"`
	// STHVerified is true when the signed tree head is authentic under the verifying key and is a
	// journal head of RunID. Every action proof is checked against this same root.
	STHVerified bool `json:"sth_verified"`
	// Problems lists every package-level failure (format, seal, key, run binding), empty when none.
	Problems []string `json:"problems,omitempty"`
	// Items is one verdict per proven item (each action, each anchored grant, the run certificate, and
	// the consistency proof), in report order.
	Items []EvidenceItem `json:"items"`
}

type EvidenceVerifyOption func(*evidenceVerifyOptions)

type Grant struct {
	ID      string            `json:"id"`              // unique identifier for this grant
	Issuer  string            `json:"issuer"`          // principal that authorized the grant (resolves to the signing key)
	Subject string            `json:"subject"`         // actor the grant authorizes to act
	Scope   map[string]string `json:"scope,omitempty"` // domain-defined constraints (e.g. limits); a child keeps every one, equal or narrower
	// NotAfterUnix is the expiry in Unix seconds; zero never expires, and only a grant whose parent
	// never expires may be zero.
	NotAfterUnix int64  `json:"not_after_unix,omitempty"`
	ParentRef    string `json:"parent_ref,omitempty"` // Digest of the grant this was attenuated from; empty for a root grant
}

type HybridSigner struct {
	Ed Ed25519Signer // the Ed25519 component signer
	ML MLDSASigner   // the ML-DSA-65 component signer
}

type HybridVerifier struct {
	Ed Ed25519Verifier // the Ed25519 component verifier
	ML MLDSAVerifier   // the ML-DSA-65 component verifier
}

type IDKind string

type IdentityPolicy struct {
	// Anchors are the CA certificates this gate trusts: not the system roots. Each must be a CA with
	// an allowed key (see the algorithm profile in the design note).
	Anchors []*x509.Certificate
	// Inter pins the intermediates a chain may pass through, by key. A certificate carried in a
	// decision that is not pinned is ignored. A policy with no pins accepts leaves issued directly by
	// an anchor.
	Inter []SPKIHash
	// Distrust ends trust in an anchor or pinned intermediate (by key) for decisions provable at or
	// after the given time, without voiding earlier history. It is how a compromised CA is retired.
	Distrust map[SPKIHash]time.Time
	// Identity maps EVERY approver id of the gate, bare-key approvers included, to the identifier of
	// that approver's person. Two ids that canonicalize to one identifier are refused: one person is
	// one seat.
	Identity map[string]string
	// IDKind is the kind of the one subject alternative name a leaf must carry.
	IDKind IDKind
	// EKU is the extended key usage a leaf must carry. It is checked by hand and also along the
	// chain: every CA certificate that carries extended key usages must permit it.
	EKU asn1.ObjectIdentifier
	// AllowEmailProtectionEKU accepts id-kp-emailProtection in place of EKU. Set it only when the
	// anchors are a dedicated issuing CA for approvers: every S/MIME certificate carries that usage,
	// often with different key handling.
	AllowEmailProtectionEKU bool
	// Policy is the certificate policy OID the leaf must assert. The bank's CA asserts it only after
	// single sign-on with multi-factor step-up and a key generated or held in hardware; bide cannot
	// see either, it can require that the CA says so.
	Policy x509.OID
	// Canonical maps identifiers to their one canonical form. Nil selects NewCanonicalizer with no
	// configuration, which suits IDEmail only: an IDPersonURI policy must supply one (it needs the
	// host).
	Canonical Canonicalizer
	// MaxChain bounds the path from the leaf to the anchor, and the number of certificates a decision
	// may carry. Zero means 4; at most 8.
	MaxChain int
	// Skew is how far a decision's signed time may lie after the time it became provable
	// (decided_at <= A + Skew). Zero means 2 minutes.
	Skew time.Duration
	// AnchorGrace is how long after the leaf's notAfter a decision may first become provable
	// (A <= notAfter + AnchorGrace). Zero means 60 seconds.
	AnchorGrace time.Duration
	// RSA2048Until permits RSA-2048 CA keys while the attested time (here A(d), the time the decision
	// became provable) is strictly before it; many bank roots are still RSA-2048. Zero refuses them,
	// and anything under 2048 bits is always refused: the default is RSA-3072 or better. The field has
	// the same meaning and name in the RFC 3161 verifier's policy.
	RSA2048Until time.Time
	// MaxLeafLifetime bounds notAfter minus notBefore. Zero means 24 hours; at most 31 days.
	MaxLeafLifetime time.Duration
	// NotBeforeBackdate is how much earlier than the real issue a CA stamps notBefore (Microsoft AD CS
	// and EJBCA both back-date it by about ten minutes to absorb clock skew), added to MaxLeafLifetime
	// so that a certificate the CA issued for exactly that lifetime is not refused. It widens only the
	// lifetime check: it moves no validity bound, and the certificate is valid from its notBefore as
	// stamped. Zero declares no back-dating and is never assumed; at most one hour.
	NotBeforeBackdate      time.Duration
	RequireNameConstraints bool
	// RequirePolicyOnCAs refuses a path in which an issuing CA carries no certificatePolicies
	// extension (an anchor that does not issue the leaf directly is not required to). Without it a
	// CA with no extension is unconstrained, so the bank's policy OID is only the leaf's assertion.
	// Recommended: put certificatePolicies on the issuing CA, naming the approver policy, and set
	// this. It is off by default only so that a policy can be adopted before the CA is reissued.
	RequirePolicyOnCAs bool
}

type IgnoredDecision struct {
	Approver string `json:"approver"`
	Step     string `json:"step"`
	Reason   string `json:"reason"`
}

type Inclusion struct {
	Index int      `json:"index"` // the record's position in the journal
	Size  int      `json:"size"`  // the journal length the root committed to
	Path  [][]byte `json:"path"`  // sibling hashes, leaf-to-root
}

type JournalExport struct {
	Format  string   `json:"format"`  // JournalExportFormat
	RunID   string   `json:"run_id"`  // the run the journal is of
	Records [][]byte `json:"records"` // each record's stored bytes, in persisted order
}

type KeyFunc func(agent.Record) []string

type KeySet struct {
	Kind   string  // tree kind committed in the signed head, e.g. TreeToolUse
	Prefix string  // every key the set yields (and every key proven absent from it) starts with Prefix
	Key    KeyFunc // projects one journal record onto the set
}

type MLDSASigner struct {
	Priv *mldsa.PrivateKey // the ML-DSA-65 private key that signs
}

type MLDSAVerifier struct {
	Pub *mldsa.PublicKey // the ML-DSA-65 public key that verifies
}

type MemAnchorLog struct {
	// contains filtered or unexported fields
}

type MemEventStore struct {
	// contains filtered or unexported fields
}

type Neighbor struct {
	Key   string    `json:"key"`   // the committed key adjacent to the absent key
	Proof Inclusion `json:"proof"` // inclusion proof placing Key at its index in the committed key set
}

type NotifyEventVerdict struct {
	Trail  string       `json:"trail"`
	Key    string       `json:"key"`
	Kind   string       `json:"kind"`
	RunID  string       `json:"run_id,omitempty"`
	Status NotifyStatus `json:"status"`
	// Why says, in a sentence, what makes the status a problem or what the status rests on.
	Why string `json:"why,omitempty"`
	// InJournal is true when a journal supplied shows the event.
	InJournal bool `json:"in_journal,omitempty"`

	EventAt     time.Time `json:"event_at,omitzero"`
	ObservedAt  time.Time `json:"observed_at,omitzero"`
	DeadlineAt  time.Time `json:"deadline_at,omitzero"`
	FirstSentAt time.Time `json:"first_sent_at,omitzero"`
	AckedAt     time.Time `json:"acked_at,omitzero"`
	ClearedAt   time.Time `json:"cleared_at,omitzero"`
	Attempts    int       `json:"attempts,omitempty"`
	Rounds      int       `json:"rounds,omitempty"`
	// Detection is ObservedAt - EventAt: how long the event was unseen. Delivery is AckedAt -
	// ObservedAt. Total is AckedAt - EventAt.
	Detection time.Duration `json:"detection_ns,omitempty"`
	Delivery  time.Duration `json:"delivery_ns,omitempty"`
	Total     time.Duration `json:"total_ns,omitempty"`
	// Auth is how the acknowledged delivery was authenticated.
	Auth *agent.NotifyAuth `json:"auth,omitempty"`
	// Receiver is the receiver the event was to ("default" when the trail names none): the verdicts
	// of one receiver are the answer to whether every event reached it. Level is the step of an
	// escalation chain for a NotificationEscalated event, 0 otherwise.
	Receiver string `json:"receiver,omitempty"`
	Level    int    `json:"level,omitempty"`
}

type NotifyReport struct {
	Trails   []NotifyTrailReport  `json:"trails"`
	Events   []NotifyEventVerdict `json:"events"`
	Problems []string             `json:"problems,omitempty"`
}

type NotifyStatus string

type NotifyTrail struct {
	// contains filtered or unexported fields
}

type NotifyTrailExport struct {
	Format string   `json:"format"` // NotifyTrailExportFormat
	Trail  string   `json:"trail"`  // the trail's name (agent.NotifyTrailName)
	Leaves [][]byte `json:"leaves"` // each leaf, in position order
}

type NotifyTrailReport struct {
	Trail   string `json:"trail"`
	Records int    `json:"records"`
	// Anchored is true when a signed head over the trail verified, and the trail's first HeadSize
	// records are exactly the leaves it commits to.
	Anchored bool `json:"anchored"`
	HeadSize int  `json:"head_size,omitempty"`
	// Heads counts the signed heads supplied for the trail, each of which verified and commits to a
	// prefix of it; HeadSize and HeadTime are the newest's.
	Heads int `json:"heads,omitempty"`
	// Tail counts the records after the newest head: read, but not attested by it. TailSince is
	// the time of the first of them and TailAge is how long before Now that was: how long the oldest
	// unattested record has gone without a signed head over it.
	Tail      int           `json:"tail,omitempty"`
	TailSince time.Time     `json:"tail_since,omitzero"`
	TailAge   time.Duration `json:"tail_age_ns,omitempty"`
	HeadTime  time.Time     `json:"head_time,omitzero"`
	// Violations are the ways the trail is malformed, out of order, or does not match its head.
	Violations []string `json:"violations,omitempty"`
}

type NotifyVerifyInput struct {
	// Trails are the notification trails to verify. A trail the journals say is owed events and
	// that is not here is read as a trail with no records.
	Trails []NotifyTrailExport
	// Heads are signed tree heads over the trails (SignNotifyTrail, or the ones an
	// AuditedEventStore publishes as the trail is written), matched to a trail by RunID, which is the
	// trail's name. A trail may have several, as an anchor log holds one for every size: each is
	// verified under Verifier and must commit to a prefix of the trail, and the largest is the
	// newest. They are verified under Verifier.
	Heads []SignedTreeHead
	// Verifier verifies Heads. It is required if there are any, or unless Unanchored.
	Verifier Verifier
	// Unanchored allows a trail with no signed head. The trail is then read but nothing attests that
	// it is complete or unaltered, and the report says so (NotifyTrailReport.Anchored is false).
	Unanchored bool
	// Journals are run journals the events are cross-checked against: every gate, halt and abort
	// they show is expected in the trail of its root run.
	Journals []JournalExport

	// Routing, if set, is the notifier's routing (agent.RoutingOf, the same options the notifier was
	// built with): each event that needs a person must have been delivered to the receivers it
	// routes to (NotifyRouting.Receivers, the method the notifier routes by), and each escalation
	// step that was due to its chain's receiver. A missing delivery is NotifyStatusNoDelivery. An
	// approval routed by its approvers needs its journal to be supplied, to know them; without it
	// the approval is not checked. Without Routing, per-receiver completeness is not checked: the
	// trail alone cannot know the routing.
	Routing *agent.NotifyRouting

	// Strict makes a warning status (NotifyStatus.Warning) a problem, so an audit fails on it.
	Strict bool

	// Now is the time pending and overdue events are judged at; time.Now if zero.
	Now time.Time
	// MaxAck, if positive, is the longest an event may wait, from the time the run entered the state
	// (the observation time if the record has none) to its acknowledgement; an event past it is late
	// or overdue even within its recorded deadline. The recorded deadline always applies.
	MaxAck time.Duration
	// Grace is how long after an event began a missing observation is not yet a failure. It is the
	// notifier's detection window: the default, 5 minutes, matches agent.WithNotifyHaltAge and the
	// default deadline.
	Grace time.Duration
	// RecoveryFailingAfter is how long a recovery failure episode may be open before a
	// recovery_failing event is owed. The default, 15 minutes, is the notifier's.
	RecoveryFailingAfter time.Duration
	// MaxTailAge is the longest a record may sit after the newest signed head of its trail,
	// unattested. A trail whose oldest unattested record is older than this at Now is a violation
	// (the check that a notifier's automatic anchoring is keeping up; zero does not apply it). An
	// event whose observation, acknowledgement or clearing is only in that tail is
	// NotifyStatusUnattested, a problem, unless MaxTailAge is positive and every tail record of the
	// event is no older than it. Zero, the default, is strict. A record accepted by the bound is
	// accepted without a signature: its content and its time (written by whoever appended it) are
	// trusted.
	MaxTailAge time.Duration
	// MaxClockSkew is how far a record may be dated before the one that precedes it (the writers'
	// clocks differ) before the trail is out of order. The default is DefaultClockSkew.
	MaxClockSkew time.Duration
}

type PolicyContent struct {
	Digest string `json:"digest"` // the policy owner's stable identifier (treated as opaque here)
	Policy string `json:"policy"` // the serialized governed policy bytes
}

type PolicyConvergence struct {
	Digest      string      `json:"digest"`      // the used policy digest this evidence is for
	PolicyLeaf  ProofBundle `json:"policy_leaf"` // proof the policy leaf is anchored in the run STH
	Certificate ProofBundle `json:"certificate"` // proof the convergence-certificate leaf is anchored in the same tree
}

type ProofBundle struct {
	Format      string         `json:"format"`       // ProofFormat
	RunID       string         `json:"run_id"`       // the run whose journal the record and STH belong to; must equal STH.RunID
	RecordBytes []byte         `json:"record_bytes"` // the single disclosed action: the bytes the journal stores for it
	Inclusion   Inclusion      `json:"inclusion"`    // its RFC 6962 audit path
	STH         SignedTreeHead `json:"sth"`          // the signed commitment it is proven against
}

type ReceiptFinding struct {
	Verdict ReceiptVerdict
	Detail  string
}

type ReceiptIdentity struct {
	Approver string
	// Identifier is the verified canonical identifier of the leaf (the identity the policy maps the
	// approver id to).
	Identifier string
	// DisplayName is the leaf's subject common name, if it has one. It is the CA's label for a
	// person, not part of the identity: it is never compared or counted.
	DisplayName string
	// LeafHash and AnchorKey are the SHA-256 of the leaf's DER and of the trust anchor's
	// SubjectPublicKeyInfo, in hex; Chain is the hash of each certificate of the accepted path, leaf first.
	LeafHash, AnchorKey string
	Chain               []string
	NotBefore, NotAfter time.Time
	// DecidedAt is the approver's signed time; AnchoredAt is A, the time the decision became provable,
	// from TimeSource.
	DecidedAt, AnchoredAt time.Time
	TimeSource            string
	// Revocation is "not checked": VerifyIdentity does not look at revocation status, so the result is
	// never a verdict that the decision counts.
	Revocation string
}

type ReceiptVerdict string

type RejectedHead struct {
	Size   int    `json:"size"`
	Reason string `json:"reason"`
}

type RunCertSpec struct {
	// ApprovedPolicies is the allowlist of policy digests the run was permitted to exercise. Every
	// policy the run actually used must be a member, or CertifyRun fails: a certificate cannot be
	// issued for a run that exercised a disallowed policy. It is not written into the certificate:
	// the verifier supplies its own allowlist.
	ApprovedPolicies []string
	// Signer signs the used-policy head. It must hold the key that signed the run's journal head
	// (the log's tree-head key), so a verifier checks both heads under one out-of-band key;
	// CertifyRun refuses another. Evidence sets it to its own signer.
	Signer Signer
	// TimestampNanos stamps the used-policy head, in Unix nanoseconds. It must not be earlier than
	// the journal head's. Evidence sets it to its own timestamp.
	TimestampNanos int64
}

type RunCertificate struct {
	// Format is RunCertificateFormat.
	Format string `json:"format"`

	// RunID is the run this certificate is about. It must equal STH.RunID and
	// UsedPolicyAbsence.RunID, both signed.
	RunID string `json:"run_id"`

	// Properties names the asserted properties, so a reader sees the scope without decoding the
	// bindings. v1: exactly "only-approved-policies", "policies-convergence-certified".
	Properties []string `json:"properties"`

	// UsedPolicies is the sorted, distinct set of policy digests exercised by governed actions in the
	// run, recomputed from the committed leaves (PoliciesUsed). It is disclosed in full because the
	// only-approved-policies property is completeness-bearing: the verifier recomputes the key-set
	// root over this set and confirms UsedPolicyAbsence commits to it, so the set cannot omit a
	// policy that was in fact used.
	UsedPolicies []string `json:"used_policies"`

	// UsedPolicyAbsence is the signed commitment to the run's used-policy key set: a PolicyUsedKeys
	// tree head (NewAbsenceTreeHead) whose Journal is STH's tree. Its Size is the number of distinct
	// used policies and its Root is the RFC 6962 root over their sorted keys.
	UsedPolicyAbsence SignedTreeHead `json:"used_policy_absence"`

	// Convergence carries, per used policy digest and in UsedPolicies order, the anchored evidence
	// that the policy is certified convergent: the policy-leaf ProofBundle and the convergence-leaf
	// ProofBundle, both bound to the run STH below. The oracle cross-check (does the policy actually
	// converge) is performed by the verifier with a checker, as verify-convergence does; these
	// bundles establish the cryptographic root (anchored, digest-linked, same tree) that the oracle
	// check hangs off.
	Convergence []PolicyConvergence `json:"convergence"`

	// STH is the run's signed journal head: the commitment the policy and convergence bundles are
	// proven against and the journal tree the used-policy set was projected from.
	STH SignedTreeHead `json:"sth"`
}

type RunVerification struct {
	// OK is the overall verdict: true only when every asserted property held.
	OK bool `json:"ok"`
	// OnlyApprovedPolicies is true when every used policy is in the allowlist AND the disclosed
	// used-policy set is bound to this run's journal by the signed used-policy head (completeness).
	OnlyApprovedPolicies bool `json:"only_approved_policies"`
	// ConvergenceCertified is true when every used policy has an anchored policy leaf and convergence
	// leaf, authentic and in the same signed tree, with linking digests. It does NOT include the
	// oracle cross-check, which the caller performs separately (the CLI does, with -checker).
	ConvergenceCertified bool `json:"convergence_certified"`
	// Reasons carries human-readable detail for any property that failed (empty on full success).
	Reasons []string `json:"reasons,omitempty"`
	// Policies carries, when ConvergenceCertified holds, what the verification read from each used
	// policy's leaves, in UsedPolicies order, so a caller that cross-checks a policy (the CLI's
	// -checker runs the external oracle on it) checks exactly the bytes that were verified.
	Policies []VerifiedPolicy `json:"policies,omitempty"`
}

type SPKIHash [32]byte

type ScopeRule func(parent, child string) bool

type ScopeRules map[string]ScopeRule

type SignedGrant struct {
	Grant Grant  `json:"grant"` // the grant whose canonical bytes are signed
	Alg   Alg    `json:"alg"`   // signature scheme the issuer used (see signing.go)
	Sig   []byte `json:"sig"`   // issuer's signature over Grant.Bytes()
}

type SignedTreeHead struct {
	Format   string `json:"format"` // STHFormat
	TreeHead        // the commitment being signed
	// Alg names the signature scheme (see signing.go). It is signed with the head.
	Alg       Alg    `json:"alg"`
	Signature []byte `json:"signature"` // signature over TreeHead.canonical(Alg) under Alg
}

type Signer interface {
	// Alg names the scheme.
	Alg() Alg
	// PublicKey returns the encoded public key of the signing key (see NewVerifier for the
	// encoding of each scheme), or nil if the signer holds no usable key.
	PublicKey() []byte
	// Sign returns a signature over message, or an error if the key is unusable.
	Sign(message []byte) ([]byte, error)
}

type SnapshotOption func(*StatusSnapshot)

type StatusArchive interface {
	PutStatus(ctx context.Context, hash string, der []byte) error
}

type StatusError struct {
	Reason string
	Detail string
}

type StatusParams struct {
	// W is the compromise-reporting window the bank commits to (default 24 hours). W' = min(W, L(C)
	// - A(d)) is what a certificate's own life leaves.
	W time.Duration
	// MinW is the smallest W' for a final verdict (default 30 minutes).
	MinW time.Duration
	// RoutineGrace: for routine reasons (affiliationChanged, superseded, cessationOfOperation,
	// privilegeWithdrawn) a decision with A < E + RoutineGrace still counts. Compromise reasons,
	// unspecified and certificateHold never get grace. Default 0.
	RoutineGrace time.Duration
	// Now, when non-zero, applies freshness: a CRL is evidence of absence only while Now < nextUpdate
	// and Now - thisUpdate <= MaxStatusAge, and not when dated in the future. It does not relax the
	// rule that evidence is issued at or after the decision (see CountLive). A freshness check without
	// a positive MaxStatusAge accepts no evidence (a configuration mistake fails closed). Leave Now
	// zero for an offline audit, which judges the series against the decision, not the clock.
	Now          time.Time
	MaxStatusAge time.Duration
	// MaxStatusAgeFor overrides MaxStatusAge for the issuing CA with the given key. An offline root
	// publishes the CRL that covers its issuing CA rarely (Microsoft AD CS: weekly), so the status of
	// that CA certificate rests on a CRL days old; the policy says so for that issuer only, and the leaf's
	// CRLs keep the global limit. Zero means the global limit, never unlimited; a negative value or one over 400 days makes the status unknown.
	MaxStatusAgeFor map[SPKIHash]time.Duration
	// CountLive is the live gate's counting mode and needs Now: a fresh CRL issued before the decision
	// is accepted, so a decision is not held for a CRL period. A verdict resting on status issued
	// before the decision is provisional, never final (its Basis says so): a revocation effective
	// before the decision may be reported after that CRL. A live count that finds a CRL at or after
	// the decision and its window can be final like any other. An audit never sets it.
	CountLive bool
	// Distrust adds distrust dates to the policy's own, by issuer key: status signed by that key with
	// thisUpdate at or after the date is no information. It is the auditor's overlay.
	Distrust map[SPKIHash]time.Time
	// Retained says the bank's CA keeps the entries of expired certificates for as long as audits
	// need them (recorded retention in the policy), as expiredCertsOnCRL does per CRL. It is the
	// bank's recorded statement, not something the CRLs show.
	Retained bool
	// CAPeriod is the CA's declared issuance period (the design note's CAPeriod, the same value that
	// bounds ExecStatusAge): consecutive CRLs of the series are issued no further apart than this.
	// Time coverage, and so the first CRL beyond notAfter (L(C)), is shown by it, not by nextUpdate: a
	// CA may issue earlier than nextUpdate (hourly issue, 24 hour validity), so a producer who omits a
	// CRL cannot be caught by nextUpdate alone. Zero declares nothing: with no CAPeriod and no
	// ConsecutiveNumbers no verdict is final. A series whose observed gap exceeds it carries a Warning.
	CAPeriod time.Duration
	// CAPeriodFor overrides CAPeriod for the issuing CA with the given key.
	CAPeriodFor map[SPKIHash]time.Duration
	// ConsecutiveNumbers is for a CA whose CRL numbers increase by exactly one with every CRL it
	// issues (bases and deltas alike): consecutive numbers then show that no CRL lies between two.
	// Off by default; a CA that skips numbers, shares a counter oddly or resets after a restore would
	// otherwise never reach final.
	ConsecutiveNumbers bool
	// CoverageTolerance absorbs publication jitter in time coverage (default one minute).
	CoverageTolerance time.Duration
	// ThisUpdateSkew is how much earlier than its real issue a CA stamps thisUpdate (Microsoft AD CS back-dates
	// it by about ten minutes). A CRL is then really issued at thisUpdate plus the skew: a hold released
	// before the next CRL is released no later than that, and a CRL's age is measured from it.
	// ThisUpdateSkewFor overrides it per issuing CA. Zero takes thisUpdate at face value; it is never
	// assumed. It is the CA's own configuration (AD CS: ClockSkewMinutes), declared from a capture of
	// that CA, with room for the variation of a few seconds (the release bound adds CoverageTolerance).
	// A negative value or one over 30 minutes is refused: the certificate has no information.
	ThisUpdateSkew    time.Duration
	ThisUpdateSkewFor map[SPKIHash]time.Duration
	// AllowHolds accepts certificates that have been on hold (certificateHold, removeFromCRL). Off by
	// default: a removeFromCRL entry's date is the CA's own (RFC 5280 does not define it as the
	// release time), so a CA that stamps the original hold date makes a release look old and could hide
	// a decision made during the hold when the CRLs that list the hold are missing. Without it any
	// hold or release entry for the certificate refuses it wholesale. Banks should not use holds on
	// approver certificates (revoke and re-issue); opt in only for a CA whose release dates have been
	// checked (the conformance captures record what EJBCA and AD CS write).
	AllowHolds bool
}

type StatusSnapshot struct {
	// contains filtered or unexported fields
}

type StatusTier int

type TimeCheck struct {
	AskedAt   string
	HeadAt    string
	Tolerance time.Duration
}

type TreeHead struct {
	Kind  string `json:"kind"`   // which tree: TreeJournal, TreeEvents, or an absence kind
	RunID string `json:"run_id"` // the run the tree is about
	Size  int    `json:"size"`   // number of leaves committed
	Root  []byte `json:"root"`   // RFC 6962 Merkle root over those leaves
	// TimestampNanos is when the head was signed, in Unix nanoseconds (time.Now().UnixNano()); see
	// CheckTimestamp.
	TimestampNanos int64 `json:"timestamp_nanos"`
	// Journal is set on an absence key-set tree: the journal tree (of the same run) whose
	// records the key set was projected from. It is nil on a journal or event tree.
	Journal *TreeRef `json:"journal,omitempty"`
}

type TreeRef struct {
	Size int    `json:"size"` // number of leaves
	Root []byte `json:"root"` // RFC 6962 Merkle root over them
}

type VerifiedPolicy struct {
	Digest      string          `json:"digest"`
	Policy      string          `json:"policy"`
	Certificate json.RawMessage `json:"certificate"`
}

type Verifier interface {
	// Alg names the scheme.
	Alg() Alg
	// PublicKey returns the encoded public key (see NewVerifier), or nil if the verifier holds none.
	PublicKey() []byte
	// Verify reports whether signature is valid over message. A verifier without a usable key
	// verifies nothing; it never panics.
	Verify(message, signature []byte) bool
	// KeyIDs identifies the signing keys behind Verify (see agent.ApproverVerifier.KeyIDs and
	// KeyID), so every Verifier is an agent.ApproverVerifier. A verifier without a usable key
	// reports none.
	KeyIDs() []string
}