Verifiable audit trail
The durable journal records every step of a run. The audit package turns it into a verifiable, tamper-evident, selectively-disclosable record: the compliance/enterprise side of the moat: provable at-most-once side effects plus a cryptographic record of exactly what the agent did. Stdlib-only (crypto/sha256, crypto/ed25519, crypto/mldsa), no external deps.
Security model (read this first)
- Integrity: unconditional. Any modify / insert / delete / reorder of a journal record changes the commitment.
- Tamper-evidence: only when you anchor the commitment out-of-band: sign it with a key the app tier doesn't fully control, and/or publish it to a separate trust domain. A hash chain or Merkle tree stored in the same database an attacker fully controls can be rewritten and re-hashed. The guarantee is: "you committed the root elsewhere, so divergence is provable."
- This is by design; anchoring is a real deployment requirement, not an optional extra.
- One key, many trees, no confusion: the log key signs several kinds of tree for a run (its journal, the absence key sets projected from it, its event stream). Every signed tree head commits to its kind and its run ID, and a key-set head also commits to the journal tree it was projected from. Every verifier requires the kind it expects, so a head signed for one tree never verifies as another, and the run ID a verifier reports is the run the signer committed to.
- Stored bytes, never re-encoded: a journal leaf commits to the bytes the journal stores for the record (
agent.Record.Raw), verbatim. A proof carries those bytes (record_bytes, base64) and the verifier hashes exactly them; it decodes them only to display the record and to check its role (its kind and name). A field this release does not know is ignored, so a record written by a newer release verifies, and what a proof commits to never depends on how this release encodes a record. Before decoding, the bytes must read one way to every JSON reader: a duplicate name, a name that is a case variant of a record field ("Kind"beside"kind"), invalid UTF-8, or an escaped lone surrogate isaudit.ErrMalformed, and a producer refuses to prove such a record. - Canonical bytes: grants, seals, and event and anchor leaves are hashed or signed over JSON, which is injective only over valid UTF-8 (encoding/json rewrites invalid bytes to U+FFFD). A grant, event, or anchor entry with invalid UTF-8 in any string is refused rather than committed or verified.
bide auditreads every artifact withaudit.UnmarshalStrict, which rejects duplicate keys, keys that differ from a field only in case, unknown fields, invalid UTF-8, escaped lone surrogates, and base64 that is not the standard encoding of its bytes (line breaks, stray bits), and checks a message part against the fields of its type, so the file a person reads is exactly the data that is verified. It checks theformatof every artifact it meets first, including one artifact carried inside another (a signed tree head inside a proof), so an artifact of another format fails withaudit.ErrFormat. - Errors, not booleans: every verifier returns an
error, and onlynilmeans verified. A failure wraps exactly one ofaudit.ErrNotVerified(read and understood, and it does not hold),audit.ErrFormat(not a format this version reads), oraudit.ErrMalformed(cannot be read as what it claims to be;ErrFormatwraps it, and it wrapsagent.ErrProtocol). A caller's mistake, such as no verifier, wrapsagent.ErrConfig. The report verifiers (EvidencePackage.Verify,VerifyRun,VerifyApprovals) return their report together with the error. - Format policy (before 1.0): producers write the current format of each artifact and verifiers read only the current format; an artifact an older release made is refused with
ErrFormatand is re-created from the journal. From 1.0 on, verifiers will read the current format and the one before it.
The four primitives
| API | Proves | A verifier needs |
|---|---|---|
Head + Sign / VerifySignature | the whole run is intact | the head + signature |
Root / Prove / VerifyInclusion | one record is in a committed run, without revealing the rest | that record's stored bytes + its O(log n) proof + the root |
ProveConsistency / VerifyConsistency | history was only appended, never rewritten/reordered | two roots + the proof |
TreeHead / SignTreeHead / Verify | a signed commitment binding scheme, kind, run, root, size, and time | the STH + a Verifier for the key |
Head is a linear SHA-256 hash chain (simple whole-run commitment). Root is the RFC 6962 Merkle tree: the same commitment, but it supports per-record inclusion proofs and consistency proofs. Use Head when you only ever reveal the whole run; use Root (+ STH) when selective disclosure or append-only proofs matter.
Encoding versions. A journal leaf hashes as SHA-256(0x00 || "bide.audit.journal-leaf.v1\x00" || stored bytes), where the stored bytes are the record as the journal holds it (agent.Record.Raw; audit.JournalLeafHash computes it). A record built in memory has no stored bytes and so no leaf. A record a redaction replaced with a tombstone keeps its place in the journal tree through the leaf hash the tombstone records (and its name, which a journal export therefore still carries for it), so the root and every other record's proof are unchanged; it can no longer be proven itself. What the redacted record said is gone, so nothing is projected from a journal holding one: the absence key sets (NewAbsenceTreeHead, SignAbsenceRoot, ProveAbsent, ProveAbsentBundle), the run certificate's used-policy set (CertifyRun), and the event stream (EventLogFromJournal, PersistJournal) refuse it with audit.ErrRedacted, rather than omit the record and, say, prove absent a call the journal tree commits. They refuse a record whose stored bytes read two ways to JSON readers too (audit.ErrMalformed, the rule a proof's record bytes follow), so nothing is projected from one reading of a record while a reader of the journal sees another. A projection reads what each record's stored bytes (Record.Raw) decode to, since the journal tree binds those bytes and not the record's fields, and refuses a record whose fields were changed after it was read (audit.ErrMalformed). A redaction reaches only the journal: event leaves PersistJournal wrote before it keep the redacted record's content, so a deployment that redacts deletes or redacts the run's event trail in its EventStore too. The stored bytes do not HTML-escape (unlike v0.6.0's) and include the record's salt: 32 random bytes a store sets when it first journals the record (agent.JournalEntry), so that a proof's sibling hashes cannot be matched against a guessed neighbouring record. A record without a 32-byte salt is refused. Every other kind of leaf carries its own tag too (bide.audit.key-leaf.v1, bide.audit.event-leaf.v3, bide.audit.anchor-leaf.v1), so a leaf names its kind and version and a root over leaves of one version never equals a root over another's. Event leaves are salted too (since v2; v1 event leaves were not) and, from v3, name their kind and fields in snake_case (see Committing the event stream). Key-set leaves are not salted: an absence proof names its neighbouring keys in plain text by design. Anchor-log leaves are not salted either: each entry holds a signed tree head whose root and signature a proof holder cannot compute, so an anchor proof's path confirms a neighbouring entry only to someone who already holds that exact signed head. Signed tree heads sign the bide.audit.sth.v5 encoding, which includes the signature scheme (v4 did not; v3 signed untagged, unsalted leaves; v0.6.0 signed bide.audit.sth.v1), which audit/verify checks too, and Head seeds its chain with bide.audit.v2. A journal written before salts existed cannot be proven: re-run or re-journal it, and re-anchor under the new version rather than comparing with an older head.
Continuous anchoring: AuditedStore + the Anchor port
The primitives above are pull-based (commit when you ask). AuditedStore makes anchoring automatic and push-based, and it's the piece that operationalizes the security model's "anchor out-of-band" requirement. Wrap any Store and every journal write is signed and published to a separate trust domain with no changes to the agent loop:
anchor := audit.NewMemAnchorLog() // your external transparency log
store, err := audit.NewAuditedStore(inner, audit.Ed25519Signer{Priv: priv}, anchor) // a drop-in Store
if err != nil {
return err // a nil store or anchor, or a signer without a usable key (agent.ErrConfig)
}
j, err := agent.NewJournal(store)
if err != nil {
return err
}
ag, err := agent.New(model, j, agent.WithTools(tools...))
if err != nil {
return err
}
ag.Run(ctx, runID, agent.UserText(input)) // each step → a signed STH, publishedThe signer is any audit.Signer: Ed25519Signer, MLDSASigner, or HybridSigner (see Signature schemes), or an Ed25519 or ECDSA P-256 key held in a PKCS#11 token, AWS KMS or Google Cloud KMS (see Key custody).
On every journal growth (each Insert that stores an entry) AuditedStore commits the run's Merkle root, signs an STH, and calls Anchor.Publish. It anchors after every insert, whether it stored the entry, found it stored (another writer's, or the retry of a write that committed but reported an error), or failed (it may have committed all the same), and publishes only when the run's journal grew past its last anchored head. The journal header is anchored together with the run's first record, so a run's anchored heads never stop at its header. Anchoring is serialized per run, so the heads one AuditedStore publishes for a run only ever grow, even when parallel tool calls land at once. Anchoring is a side channel: a Publish failure never fails the durable step (the write already succeeded; failing it could wrongly retry a non-idempotent step), so publish errors go to an optional OnError hook instead, and the run's next write anchors a head covering the unanchored entries (a replay that writes nothing does not). A run's last write has no next write, and a write under a context that is done is not anchored (it is reported to OnError with the context's error): on OnError, call Reanchor(ctx, runID) once the anchor is reachable, which publishes a head over the whole journal if no published head covers it. When two processes anchor the same run (around a lease handoff), a smaller head can reach the anchor after a larger one; both are valid, so monitors compare a run's heads by size, not by arrival.
Bounding how often heads are published: WithMinInterval
By default every journal write publishes a head. For an anchor that keeps each head for years (an S3 Object Lock bucket, a timestamping service that bills per token) that is one retained object per write. AuditedStore.WithMinInterval(d) and AuditedEventStore.WithMinInterval(d) publish at most one head per run or trail per d: growth inside the interval is held back and published as one head that covers all of it, by a timer at the end of the interval, not only by a later write.
- Immediate, always: a run's or trail's first head, a run's end (the write of
run:complete,run:abortedorrun:cancelled),Reanchor,Flush(which also publishes everything held back, so call it before the process exits),ReanchorRuns, and for trailsReanchorPendingandAnchorTrails(the notifier's sweep and recovery pass). The cooldown after a failed publish still applies to a trail. - The window, while the process lives: a record is covered by a published head at most
d(plus one publish) after it was written. It is not "one head perd" in the other direction: there is never a later gap, because the timer publishes what no later write does. A failed publish on the timer goes toOnErrorand the timer is re-armed with a doubling wait (the interval, at least a second, up to five minutes or the interval if longer), so the bound survives an outage andFlushandPendingstill know the run.OnErrorhears the first failure of a streak only, andOnRecovered(fn)is called when a publish succeeds after one, so an outage is one page and one all-clear, not a stream. - The window after a crash: a process that dies loses its timers, so what it held back stays unanchored until the next start or recovery pass, not for
d.AuditedStore.ReanchorRuns(ctx, filter)is that pass for journals: call it at start (withagent.RunFilter{ExcludeHolding: ...}set to the end markers to skip finished runs), or rely onagent.Recoverfor the runs it drives (it callsReanchor). For notification and event trails the notifier's sweep and recovery pass (AnchorTrails) already is it. Between the crash and that pass the journal is intact and the records are simply not under a head; a monitor sees a latest head older than the journal. - How far the tail goes is shown to a verifier.
bide audit verify-decision-coveragelists the positions of the journal's last records that are under no signed head and how long ago the newest counted head was signed, andverify-receiptsprints the count for each journal it is given (a receipt for a decision in that tail is pending, not failed). Withverify-decision-coverage -max-unanchored DURATIONit fails when the newest head is older than that and records follow it: inside the bound the tail is consistent with a head held back byWithMinInterval, over it a failed publish or a signer that stopped. Without the flag it reports the tail and cannot tell the two apart. The age is by the signer's clock and is an upper bound on the tail's age. - Heads of one run still only grow, and
dof zero (the default) or less turns it off. It trades the density of heads for the cost of keeping them: choosedas the longest you accept records being unanchored, given what it costs to hold a head.
AuditedStore implements Unwrap() Store, so it keeps every optional capability of the store it wraps and adds none: agent.Lease, agent.Recover and agent.RecoverLoop find the inner store's Leaser and Lister through it (see agent.Capability). Leases are not journaled, so acquiring, renewing or releasing one anchors nothing.
A decision another process wrote is under no head until someone signs again. An application that holds the log key signs only on its own writes. A decision written by another process (a command writing the database, an approver's tool) is a journal write the AuditedStore did not make, so no signed head covers it until the application next writes to that run, and for a rejection nobody re-runs that may be never. agent.RecoverLoop (and agent.Recover, one pass) closes the gap: for each run it drove that ended waiting on an approval (*agent.ApprovalPending) or a halt resolution (*agent.OutcomeUnknown), including every one of several joined pauses from parallel sub-agents, it calls Reanchor on the journal's store (found through Unwrap, as agent.Reanchorer; agent.WithReanchor names another function, or nil to turn it off, and agent.WithReanchorTimeout bounds each call, half the lease TTL by default, so a hung anchor cannot hold a run's lease and a concurrency slot). That adds no listing and no scan, only a read of each such run's journal, and writes nothing to the journal. A decision is signed within one pass for a run that pass drives and whose re-sign succeeds: not for a run another holder leases, not while the anchor is failing (the error goes to WithRecoverErrors and the next pass tries again), and not for a run no pass drives. Two things to read in the result: "covered" means a signed head includes the record, not that the record is authentic (re-signing ratifies what the database holds, an unsigned agent.Approve decision or a record written by anyone with write access included; verify-approvals is the check that a decision is genuine), and the per-run lock that keeps an AuditedStore's heads growing is process-local, so a recoverer and an application process anchoring one run can publish a size-12 head and then a size-10 one, which a monitor can misread as a rollback: read a run's heads by size. To check from outside, see bide audit verify-decision-coverage below, and for which verb to run, the note under it.
Anchor is a bring-your-own port: implement Publish(ctx, runID, sth) against the transparency log you trust (a CT-style log, a notary/timestamping service, another account's WORM store, a public ledger). MemAnchorLog is the reference: an append-only log that keeps its own RFC 6962 tree over the published STHs, so a monitor can prove a given STH was anchored (Prove + VerifyAnchorInclusion; each entry carries format bide.audit.anchor-entry.v1) and that the anchor log itself only grew (ProveConsistency
VerifyConsistency). That is the full end-to-end chain: journal record → inclusion proof → signed tree head → provably anchored in an independent, append-only log.
Committing the event stream, not just the journal
Head/Root above commit over the durable journal (the resume substrate). An EventLog applies the same RFC 6962 machinery to Agent.Stream's semantic event stream: the lifecycle a UI/operator actually observes (turn boundaries, tool start/finish, approvals, the final answer). This closes the seam where durability lived in the journal but the observable event feed was ephemeral: now "stream for the UI" and "commit a provable audit trail" are one pass.
log := audit.NewEventLog()
// Record drains the stream, commits every event, and forwards it live to the UI:
res, err := audit.RecordStream(log, agentStream, func(e agent.RunEvent) { render(e) })
var msg agent.Message
if res != nil {
msg = res.Message
}
root := log.Root() // RFC 6962 commitment over what was observed, in order
sig, _ := audit.Sign(root, signer) // anchor it out-of-band, same caveat as the journal
// Later: prove ONE observed event (e.g. the approval) without revealing the rest.
proof, _ := log.Prove(approvalIndex)
err = audit.VerifyEventInclusion(root, approvalEvent, proof) // nil means includedThe event log gets the full transparency-log surface, reusing the journal's STH and consistency machinery unchanged:
sth, _ := audit.SignTreeHead(log.TreeHead(runID, time.Now().UnixNano()), signer) // kind "events", run, root, size, time
sth.Verify(v) // anchored commitment (nil = authentic)
audit.VerifyEventInclusion(sth.Root, event, proof) // check proofs vs the STH root
// Between two published event STHs, prove the observed trail was only appended to:
cproof, _ := laterLog.ProveConsistency(sth1.Size)
audit.VerifyConsistency(sth1.Root, sth2.Root, cproof)TreeHead / SignedTreeHead / Verify / Consistency are the same types used over the journal (Size counts events instead of records, and Kind is audit.TreeEvents, so an event head never verifies as a journal head), so an auditor learns one verification flow.
Durable vs live: where the event log lives
An EventLog filled from the live stream is in-memory, so a crash loses it, and its Root even shifts between a fresh run and its own replay (live-only events like token deltas differ). For the durable audit artifact, don't store a second log: derive it from the journal, which is already the crash-safe, at-most-once substrate.
log, _ := audit.EventLogFromJournal(ctx, journal, runID) // projection of the DURABLE journal
sth, _ := audit.SignTreeHead(log.TreeHead(runID, ts), signer) // anchor THIS: crash-durable, resume-stableEventLogFromJournal projects the journal to the same semantic events Agent.Stream re-emits on resume (agent.ReplayEvents: assembled assistant turns + completed tool calls, in order). Because that sequence is a deterministic function of the persisted records, its Root/STH are byte-identical before and after a crash, and a crash mid-run leaves a provable append-only prefix of the completed trail (verified by ProveConsistency). Token-level deltas aren't journaled, so they aren't in the durable projection; the durable content is turns and tool results, which is what a compliance log should commit anyway. The live EventLog remains the real-time UI view; the journal projection is the anchored artifact.
A separate lifecycle: the BYO EventStore port
The journal is the resume substrate and may be garbage-collected after a run; a compliance trail often has to outlive it (keep for years, on WORM storage, in a different trust domain). EventStore is the bring-your-own port for that: append canonical event leaves to a backend you run, on its own retention lifecycle, and rebuild an EventLog from it later.
// Mirror the run's durable trail into your store (idempotent: call it whenever).
audit.PersistJournal(ctx, evStore, journal, runID)
// Later, even after the journal is deleted: anchor and prove from the store alone.
log, _ := audit.LoadEventLog(ctx, evStore, runID)
sth, _ := audit.SignTreeHead(log.TreeHead(runID, ts), signer)
proof, _ := log.Prove(i) // + audit.VerifyEventInclusion(sth.Root, event, proof)PersistJournal is fed from the journal projection, not the live stream, on purpose: the projection is deterministic and resume-stable, so re-mirroring after a crash appends the same leaves at the same positions (idempotent, never forks). The store contract is append-only and idempotent on (runID, seq): a different leaf at an existing position is rejected as a fork, with an error that wraps audit.ErrSeqTaken (so a writer that lost a race for a position can tell it from a real failure with errors.Is). MemEventStore is the in-memory default; a real backend is a Postgres table with UNIQUE(run_id, seq) and insert-only grants, or object storage with object-lock/WORM.
Durable stores. store/sqlite and store/postgres ship one: store.EventStore() returns an audit.EventStore that keeps the trail in the same database as the journal, in a bide_events table (WithTablePrefix applies) keyed by (run_id, seq). Each Append is a single insert-if-absent statement committed before it returns, so a crash leaves the trail as of the last committed leaf and a re-run of PersistJournal appends the rest, and writers racing for one position, from any connection or node, have exactly one winner. Point it at a database with its own retention and grants if the trail has to outlive the journal's. The conformance suite audit/eventstoretest.Run checks any EventStore against the contract: append and load, byte fidelity, the same-leaf no-op, ErrSeqTaken for a different leaf, gaps, and racing writers.
Each leaf is a kind-tagged canonical encoding, so event types never collide, and ModelEvent carries the inner delta's kind. Kinds and event fields are snake_case (turn_started, model_event/text_delta, tool_completed with tool_use_id, name, result, is_error): the stream event types carry snake_case JSON tags, so the leaf does not depend on Go field names. An event of a type the log does not name is refused. Root/Head/Sign behave exactly as they do over the journal, and the signing path is shared. (Prototype: audit/eventsink.go.)
Event leaves are salted, like journal leaves. An event leaf hashes as SHA-256(0x00 || "bide.audit.event-leaf.v3\x00" || {"kind":...,"event":...,"salt":...}), where salt is the event's own 32 random bytes (base64). Prove returns an audit.EventInclusion: the event's salt plus the shared Inclusion (index, size, audit path). An event proof discloses exactly: the event (held by the verifier), its salt, its index, the log's size, and the O(log n) sibling hashes on its path. It does not disclose any other event's content, kind, or salt, and those hashes cannot be tested against a guessed event (an approval with a known call ID, a two-valued tool result): the salt a guess would need is disclosed only by that event's own proof. Where the salt comes from:
EventLog.Add(and soRecord) draws a fresh salt fromcrypto/rand. The salt lives in the in-memory log; keep the log (or the proofs you took from it) to prove against its root later.EventLogFromJournalandPersistJournalsalt each projected event withSHA-256("bide.audit.event-salt.v1\x00" || record salt), where the record salt is the random salt of the journal record the event projects (agent.ProjectEventsnames that record). The journal persists that salt, so the projection stays deterministic and resume-stable, and the hash is one-way: an event proof does not disclose the record's journal salt.PersistEventdraws a fresh salt, or reuses the salt already stored at that position, so a retry is a no-op. Do not mix it withPersistJournalon one run: they salt the same event differently, and the second reports a fork.
An EventStore stores each leaf, salt included, verbatim, so LoadEventLog after a restart has the same root and each proof discloses the stored salt. LoadEventLog refuses a leaf that is not a salted v3 leaf. v1 event leaves were unsalted and v2 leaves spelled their kinds and fields in Go case: a trail persisted under either cannot be loaded or proven; re-mirror it from the journal with PersistJournal into a fresh store and re-anchor.
Producing a proof: ProofBundle, the CLI, and the standalone verifier
The primitives above are the machinery; a ProofBundle is the portable artifact for a single action you hand an auditor (for a whole run, see the evidence bundle below). It packages a single disclosed record as the bytes the journal stores for it (RecordBytes), its inclusion path, and the signed tree head it is proven against, and it verifies offline against a public key obtained out-of-band:
// Produce: prove one tool call happened, against an anchored STH. Semantic, not by index.
bundle, _ := audit.ProveToolCall(ctx, journal, runID, toolUseID, sth) // or audit.ProveRecord(..., index, sth)
blob, _ := json.Marshal(bundle) // journal / email / publish it
// Verify: offline, trusting only the out-of-band public key. nil means verified.
err := bundle.Verify(audit.Ed25519Verifier{Pub: pub}) // STH signature, kind and run binding, size binding, inclusion
rec, _ := bundle.Record() // the proven record, decoded for displayA record's index is its position in the run's journal, where the journal header (the record named @journal, which names the journal format) is always leaf 0; prove records by what they are (ProveToolCall, ProveStep) rather than by index where you can.
Verify fails closed (an error wrapping audit.ErrNotVerified) on forged record bytes, a proof not bound to the signed size, a head that is not a journal head of the bundle's RunID, or the wrong key or scheme. Verify hashes RecordBytes as they are; Record() decodes them, ignoring a field this version does not know, so a record a newer release wrote verifies and displays here, but refusing (audit.ErrMalformed) bytes that would read differently to another JSON reader: duplicate or case-variant names, invalid UTF-8, escaped lone surrogates. The public key must come from the anchor operator, not the bundle: that is what makes it proofs you verify, not logs you trust.
A record can say when it was written: Record.RecordedAt (recorded_at) on a single approver's decision, a result ResolveHalt injected, and a run's end marker. The proof commits to it with the rest of the record, so it cannot change once a signed head covers the record, but it is the writing process's claim and no clock is vouched for (the resolver of a halt signs nothing; an m-of-n approver signs only decided_at). bide audit verify prints it after its verdict, and bide audit verify-evidence appends it to a tool call's or step's line (recorded at <time> by the clock of the process that wrote it). A record with no time prints nothing, and a time that is not in the canonical form is printed quoted. It is informational: nothing in verification reads it.
For the auditor who does not write Go, the bide audit CLI wraps this (prove over an exported journal + STH, verify over a bundle + key; only exit 0 means verified). And for a third party who will not import the SDK at all, audit/verify is a stdlib-only package (no agent, no gsm) that checks inclusion, consistency, and STH signatures under all three schemes (verify.TreeHead(h, sig, v) with a verify.NewVerifier(alg, pub)) from raw leaf bytes (a proof's record_bytes, hashed as they are): they can vendor just that, or reimplement it from RFC 6962 and check us against it. The two verification paths are cross-checked bit-for-bit in the tests so the standalone mirror cannot drift.
Artifact formats
Every proof artifact is JSON with snake_case names throughout, and each top-level artifact names its layout in a "format" field:
| Artifact | format | Constant |
|---|---|---|
SignedTreeHead | bide.audit.sth.v5 | audit.STHFormat |
ProofBundle | bide.audit.proof.v3 | audit.ProofFormat |
AbsenceBundle | bide.audit.absence.v3 | audit.AbsenceFormat |
RunCertificate | bide.audit.runcert.v3 | audit.RunCertificateFormat |
CurrentGrantProof | bide.audit.current-grant.v3 | audit.CurrentGrantFormat |
EventInclusion | bide.audit.event-inclusion.v3 | audit.EventInclusionFormat |
EvidencePackage | bide.audit.evidence.v6 (v5 still verifies, see below) | audit.EvidenceFormat |
AnchorEntry | bide.audit.anchor-entry.v1 | audit.AnchorEntryFormat |
JournalExport | bide.audit.journal-export.v1 | audit.JournalExportFormat |
NotifyTrailExport | bide.audit.notify-trail-export.v1 | audit.NotifyTrailExportFormat |
DecisionReceipt | bide.audit.decision-receipt.v1 | audit.ReceiptFormat |
A grant's canonical bytes (Grant.Bytes, signed and digested) start with bide.audit.grant.v2 (audit.GrantFormat). A bundle looks like this (the record bytes, path, and signature abbreviated):
{"format":"bide.audit.proof.v3","run_id":"r1","record_bytes":"eyJuYW1lIjoidG9vbDpjMSIs...",
"inclusion":{"index":1,"size":3,"path":["...","..."]},
"sth":{"format":"bide.audit.sth.v5","kind":"journal","run_id":"r1","size":3,"root":"...",
"timestamp_nanos":1000,"alg":"ed25519","signature":"..."}}The producers (ProveRecord, ProveAbsentBundle, CertifyRun, ProveCurrentGrant, EventLog.Prove, Evidence, SignTreeHead, ExportJournal, ExportNotifyTrail) set the format; every verifier requires it, and audit.UnmarshalStrict checks it before it reads anything else, at the top level and in every artifact one carries. An artifact without a format, or with another one (a bide.audit.proof.v2 bundle, a signed tree head from before v5, which carried no format), fails with an error wrapping audit.ErrFormat that names the format this version reads. Before 1.0 a verifier reads only the current format of each artifact. Proofs are cheap to remake from the journal, so re-create an old artifact with the current producer rather than converting it.
The run-level evidence bundle: EvidencePackage
A ProofBundle proves one disclosed action. For a whole run, audit.Evidence assembles the run's evidence into a single portable file: one signed tree head, an inclusion proof per material action, and optionally the run certificate, the authority grant chain, and a consistency proof. It is pure JSON (store it, email it, publish it) and verifies offline:
pkg, _ := audit.Evidence(ctx, journal, runID, signer, time.Now().UnixNano(),
audit.WithAllToolCalls(), audit.WithRunCertificate(spec), audit.WithGrants(),
audit.WithConsistencyFrom(earlierSTH)) // an earlier signed head of this run, e.g. from the anchor log
report, err := pkg.Verify(v, audit.WithApprovedPolicies(allowlist...)) // trusting only the out-of-band key
// err == nil: verified; errors.Is(err, audit.ErrNotVerified): report says what failedVerify trusts the verifier you pass, never the key embedded in the package, and every field of the package is verified or derived from verified data:
Formatmust beaudit.EvidenceFormat(bide.audit.evidence.v6) oraudit.EvidenceFormatV5(bide.audit.evidence.v5, verified but never produced); any other isaudit.ErrFormat, and the package'salgandpublic_keymust be the scheme and key of the verifier you pass: a verifier for any other key does not verify the package, even one whose signatures would check.The STH must be an authentic journal head of the package's
RunID, so the run the report names is the run the log key signed.Each action proof must verify against that same tree, and its
Kind,Label, andRefmust be what the proven record says (a tool result cannot be shown as an approval by someone else).Grants.Chainmust be exactly the grants the anchored leaves prove, one per leaf, in order.The run certificate must be for this run and this tree, and is checked against the allowlist you pass with
WithApprovedPolicies; a package that carries a certificate fails without one.The consistency proof is checked from its earlier signed head (an authentic journal head of the same run, of the size the proof starts from) to the package STH.
Label, the one field no proof covers, is covered by the seal:Evidenceends withpkg.Seal(signer), the log key's signature over a fixed-size digest of the whole package, so nothing can be edited, added, or dropped after sealing. A caller that adds actions afterwards reseals.The seal's signed message is
"bide.audit.evidence.v6.seal\x00"followed by the 32-byte SHA-256 of the package's JSON withsignatureempty (60 bytes under every scheme: a 28-byte tag and a 32-byte digest, whatever the package's size), so a signer with a message size limit can seal any package: AWS KMS signs at most 4096 bytes, and a 12-action package is about 11 KB. Abide.audit.evidence.v5package, made before this, signed the tag"bide.audit.evidence.v5.seal\x00"and the whole JSON instead;Verifystill checks it that way (andbide audit verify-evidenceprints aNOTEline for it), so evidence already issued stays verifiable. Nothing produces v5, andSealrefuses a v5 package (re-create the evidence for a v6 seal). A v6 package relabelled v5, or the reverse, does not verify, since the two seals differ.The package JSON that is hashed is exactly Go's
encoding/json.Marshalofaudit.EvidencePackagewithsignatureset to null: struct fields in declaration order, no white space,omitemptyfields (label,grants,run_certificate,consistency, an action'sref, a head'sjournal) left out when empty; a nil slice isnull, an empty byte slice is""and an empty list is[], byte slices as standard padded base64, and strings escaped as Go escapes them:<,>and&as\u003c,\u003e,\u0026(inside the nested STH and bundles too), U+2028 and U+2029 as\u2028and\u2029, backspace, form feed, newline, return and tab as\b,\f,\n,\r,\t, the other control characters below 0x20 as\u00XX, and 0x7f and all other text (non-ASCII included) as UTF-8, unescaped. A verifier in another language that parses and re-serializes the package will not get these bytes; hash the package as Go writes it, or reproduce the rules. This vector (also pinned byTestEvidence_SealTestVector) checks an implementation: seedSHA-256("bide evidence seal test vector")for the Ed25519 key (public keyb34c6b63f9aab350160a34a2d7437023e9ac57b903b8796933b09e9535ee4318), and the package{"format":"bide.audit.evidence.v6","run_id":"run-\u003c1\u003e\u0026","label":"a\u003cb\u003e\u0026\u2028","alg":"ed25519","public_key":"s0xrY/mqs1AWCjSi10NwI+msV7kDuHlpM7CelTXuQxg=","sth":{"format":"bide.audit.sth.v5","kind":"journal","run_id":"run-\u003c1\u003e\u0026","size":1,"root":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=","timestamp_nanos":1,"alg":"ed25519","signature":"AQI="},"actions":[],"signature":null}whose SHA-256 is
a25f2b4d2292044fa7cfce2f13f903dd1af45b356c24f545318cdd8bb8579d79, so the signed message is"bide.audit.evidence.v6.seal\x00"followed by those 32 bytes, and the seal is6a890e49f287d27e5c9568d35a7dcfc7b7acd166024cdfd1d1773ae42f3ac96420a050f5b11d48b508bcef7579100fb301912f49ec48becfb5f80859526f1c04.A second vector, same key, covers control characters and nil versus empty slices (the label is the bytes
00 07 08 0c 0a 0d 09 1f 7f c3a9; the head'srootis nil and itssignatureempty;actionsis nil):{"format":"bide.audit.evidence.v6","run_id":"r","label":"\u0000\u0007\b\f\n\r\t\u001f<0x7f>é","alg":"ed25519","public_key":"s0xrY/mqs1AWCjSi10NwI+msV7kDuHlpM7CelTXuQxg=","sth":{"format":"bide.audit.sth.v5","kind":"journal","run_id":"r","size":0,"root":null,"timestamp_nanos":1,"alg":"ed25519","signature":""},"actions":null,"signature":null}(
<0x7f>stands for the one byte 0x7f.) Its SHA-256 isb00738e35cd95337fa1d72b3595a52575a450d9b12a508cf2f6d85431807a978and its seal is019dca1ace3e93e9970fe0894a5766a0c6ccf74d243322f9767e139f78dbb7e9966a1fefcb0c280d3822f9d6a34e33f8f5e573713b59e7df96149c2f4bb2be00(TestEvidence_SealTestVector2).Every signed head the package carries (its STH, each action and grant bundle's head, the run certificate's heads, and the consistency proof's earlier head) follows the timestamp rule below.
The package must prove something: one action, grant, run certificate, or consistency proof at least. A package with none of them does not verify, so an empty report never reads as a clean audit.
One check needs inputs the package deliberately does not carry: grant issuer signatures (they need the issuers' keys, checked with VerifyDelegationChain against your own PKI). For the auditor who does not write Go, bide audit verify-evidence verifies the same file and prints a plain-English PASS/FAIL.
Timestamps
A signed tree head's TimestampNanos (timestamp_nanos) is when it was signed, in Unix nanoseconds (time.Now().UnixNano(), as AuditedStore stamps it). Verifiers hold every signed head they are shown to one rule (audit.CheckTimestamp, audit.CheckTimestampOrder):
- the timestamp is positive;
- it is not later than the verifier's clock plus an allowed skew (
audit.DefaultClockSkew, five minutes;WithClockSkewandbide audit -max-clock-skewchange it, andWithVerifyTimechecks as of another moment); - where one head extends another it is not earlier: a consistency proof's earlier head is not later than the head it proves grown, and a run certificate's used-policy head is not earlier than the journal head it was projected from.
EvidencePackage.Verify applies the rule to every head a package carries, and bide audit applies it to every signed head in every file it reads. The rule does not limit how old a head may be (an audit reads old heads), and it does not order heads of different runs or anchor-log entries, which are independent. ProofBundle.Verify, SignedTreeHead.Verify, and VerifyRun check signatures and bindings only; a caller that uses them directly applies CheckTimestamp too. A head that breaks the rule is an error wrapping audit.ErrNotVerified. A grant's NotAfterUnix is a separate expiry in Unix seconds, checked by Grant.Expired and VerifyCurrentGrant against the caller's clock; an evidence package carries no per-action time to compare it with, so EvidencePackage.Verify does not check it.
Approval evidence: k approvers signed off before the action
For a tool gated by an m-of-n approval policy, audit.ApprovalEvidence produces the complete evidence under one signed tree head, in journal order: the model turn that requested the call, every decision record the gate read (valid or not), the gate's recorded tally, and the call's result. To add it to a package that already carries the call (built with WithToolCall or WithAllToolCalls), drop the trailing result entry and reseal the package:
approvals, _ := audit.ApprovalEvidence(ctx, journal, runID, toolUseID, pkg.STH)
pkg.Actions = append(pkg.Actions, approvals[:len(approvals)-1]...) // the result is already packaged
_ = pkg.Seal(signer) // the package changed after Evidence sealed itpkg.Verify checks each item's inclusion under the tree head like any other action. Like grant issuer signatures, the approval claim needs inputs the package does not carry (the approvers' public keys and the expected policy), so audit.VerifyApprovals checks it from the package and those keys: it refuses keys that put two of the policy's approvers on one key, recounts the decisions with the gate's own rule against the proven call, and reports a problem if the evidence omits a decision the gate read, if the recount disagrees with the recorded tally, or if the gate enforced a different policy. bide audit verify-approvals runs the same check from the command line. audit.ProveApproval proves a single decision by its record name. See the approval guide and examples/approval.
Notification evidence: were the people told?
A run that halts on an unknown outcome or waits at an approval gate stops until a person acts, and the notifier writes what it did about that to its own audited trail (notify:<run> in an EventStore, one salted event leaf per record). audit.VerifyNotifications and bide audit notifications answer the auditor's question from that trail and the run journals, offline: was every event that needed a person notified, was it acknowledged, and when? A gate that asks again over a tally it does not act on (see a run approved under an earlier decision format) is an event of its own, owed its own notification.


The trail is signed and anchored when the application asks for it, and the verifier says what each case costs. Wrap the trail's event store in an audit.AuditedEventStore (see the notifications guide) and every growth of a trail publishes a signed tree head to an Anchor, as AuditedStore does for a journal, with the same Signer. Without it, audit.SignNotifyTrail signs a head by hand. Without any signed head the verifier still reads the trail strictly, and the report marks it UNANCHORED: whoever can write the event store could have deleted or reordered records, and nothing in the trail shows it. With heads, the first head_size records must be exactly the leaves the newest head commits to, and every other head the trail was given must match the prefix it names, so a deleted, reordered or changed record is found (exit 1) even when it was rewritten after the newest head was published. Records after the newest head are read and reported as not attested: the report gives their count (tail), the time of the first (tail_since) and how long ago that was (tail_age_ns), and -max-unattested makes a gap older than a bound a failure. An event whose observation, acknowledgement or clearing is only in the tail is unattested, a problem, because whoever can append to the stored trail could have written it. -max-unattested (library MaxTailAge) is the one knob: with a nonzero bound, an event resting on tail records no older than it is accepted (so is a recovery state, from failing_since and recovered records, that rests on the tail: a keyless record is judged as the recovery-state verdict recovery-state:<trail>), for a live trail between heads. Those records are accepted without a signature, so their content and their times, which whoever appended them wrote, are trusted; the default, 0, is strict. A record deleted from that tail cannot be found.
Per-receiver completeness. The trail cannot know the routing, so by default a fan-out that reached one receiver passes. -routing routing.json (library Routing) takes the notifier's routing, which you write with agent.RoutingOf(opts...) from the same options you pass the notifier, so the two cannot differ: each halt, approval, abort and recovery failure must have a delivery to the receivers NotifyRouting.Receivers gives it (the method the notifier routes by: the kind's route, or for an approval the receivers of its approvers, which needs the gate's journal), and each escalation step that is due (its deadline and the grace passed, the event neither acknowledged nor, for an approval, cleared or resolved) must have a delivery to its chain's receiver. One without is no_delivery and fails. Overdue notices and all-clears are not checked this way. Without -routing, per-receiver completeness is not checked.
trail := agent.NotifyTrailName(runID) // "notify:<run>"
// At the notifier's side: an audit.AuditedEventStore around evStore signs and anchors the trail as it
// is written. To sign a head by hand instead, on a schedule:
head, _ := audit.SignNotifyTrail(ctx, evStore, trail, signer, time.Now())
// Export what the auditor needs (or let `bide audit notifications -db` read the stores).
tx, _ := audit.ExportNotifyTrail(ctx, evStore, trail) // format bide.audit.notify-trail-export.v1
jx, _ := audit.ExportJournal(ctx, journal, runID)
rep, err := audit.VerifyNotifications(audit.NotifyVerifyInput{
Trails: []audit.NotifyTrailExport{tx}, Heads: []audit.SignedTreeHead{head}, Verifier: verifier,
Journals: []audit.JournalExport{jx},
})
// err wraps audit.ErrNotVerified if an event was never notified, was acknowledged late, or is overdueWhat it checks, and the status each event gets:
- A strict read. Every leaf must be a notification record of a kind and shape this version reads, in canonical form. An unknown record kind, an unknown field, a duplicate key or a leaf that is not a notification record is an error (exit 4), not a record to skip: a verifier that skipped what it could not read would pass a trail it did not check. (The notifier's own reader keeps such a record in its position so a rolling upgrade keeps delivering; the verifier does not.)
- A history a notifier writes. An event is observed once and first; nothing follows its acknowledgement or clearing; an acknowledgement follows a claim and carries a send time, an attempt count and a 2xx status (or none, for a sink that is not HTTP); an
overduerecord follows the deadline and states the latency the times imply; an overdue notice follows theoverduerecord it reports, and an all-clear follows the acknowledgement or clearing it reports; records are dated in order, within-max-clock-skew(the writers' clocks differ); recovery failure episodes open and close in turn; a halt or approval observation'sop_run,op_kindandop_idagree with its key; the open trail, which lists the events whose all-clear may still be owed, is a chain of daily segments (notify:@open:<date>) joined by seals, with a yearly index of segments (notify:@open:index:<year>): each sealed segment's successor starts with a checkpoint equal to what the sealed one folds to (agent.FoldOpen), an unwatch happens only while its event is listed, nothing follows a seal, the backfill is recorded once, only the first segment starts without a checkpoint, the index lists the segments in creation order, each in the index of its own year, and a segment it names exists unless it is the first or the last created (with signed heads, any missing segment is a finding: a deleted newest segment, or one a writer has not created yet, which a sweep repairs, so run the audit again); every record is dated within its segment's UTC day (a record written by a process whose clock is behind its segment, because another process's clock ran ahead and sealed into a later day, has its time moved later, to the segment's start or just after the record before it, and keeps its own clock reading inclock_at: a time is only ever moved later, so a delivery never looks earlier than it was, and the verifier requiresclock_atto be earlier than the time and only on open-trail records) (a seal, in the day of the segment it seals into), a seal may skip days nobody ran on but not a segment an index lists, and every deliveredoutcome_unknown,approval_pendingorrecovery_failingevent in a run trail is listed on the open trail, or was observed before it and covered by a recorded backfill (at most two passes, the second no earlier than the window the first recorded (WithNotifyUpgradeWindow, a day by default), which is what catches an event a process of the previous version delivered, without listing it, during a rolling upgrade; the first new-version scan of an unfinished run lists such an event at once, so during an upgrade the audit can report an event as unlisted until then, and set the window to the time the upgrade takes to reach every process); the open-trail record kinds are a violation on a run's trail. With signed heads, each open-trail segment and index needs its own (the sameSignNotifyTrailheads as a run's trail), so a record or a whole segment deleted from either end is found.bide audit notifications -dband-postgres-envread every yearly index from 2026 (the year the open trail began), the segments they name and the segments those seal into (and the index of each segment's year, however far ahead), and a run that the open trail lists but that has no journal in the store is reported as a warning (-strictfails on it) while its trail is verified all the same. A run's events are in the trail of its root run (a plan flow's run is its own root). A trail that breaks a rule is reported with the record and the rule (exit 1). - Routing and escalation. Each event's receiver and, for an escalation step, its level are in the trail (the
receiverandlevelof itsobservedrecord), so every verdict names the receiver and the report counts statuses per receiver (CountsByReceiver;bide audit notificationsprints a line for each). A receiver'sackedis the answer to whether that receiver was told. The history rules extend to the chain: an escalation step (escalated:<level>:<key>) must follow an observed event of a kind that is escalated, not cleared and, unless it is an approval, not acknowledged (itself or an earlier step); it must be dated after the event's deadline (step 1) or the previous step's own deadline (later steps, whose predecessor must be observed); its level agrees with its key and is within the bound of four; it is never overdue; an all-clear and an overdue notice go to the receiver of their event; a delivery to one of several receivers (to:<receiver>:<key>) names that receiver in its record. The cross-check accepts any delivery of a gate (to:<receiver>:<key>) as the gate being observed, and judges each delivery on its own. What it cannot know is the routing and escalation that was configured: a gate whose trail shows one delivery may have been routed to two receivers, and a halt that was never escalated may have had no chain. - The journal cross-check. Every approval gate, unknown-outcome halt (an attempt marker with no result) and aborted run a supplied journal shows must be observed in the trail of its root run. A gate with no
observedrecord isnever_notified, even when everything the trail does hold is clean, which is the case a check of the trail alone cannot catch. An event younger than-grace(default 5 minutes, the notifier's detection window) isnot_yet_due. A recovery failure episode open longer than-recovery-failing-after, anoverduerecord with no overdue notice, and a clearing after a delivery was attempted with no all-clear are each owed a notification the same way. - A verdict per event.
acked(with the times: when the run entered the state, when the notifier saw it, when the sink acknowledged it, the attempts, and how the delivery was authenticated);acked_late(acknowledged after the event's recorded deadline, or after-max-ackfrom when the run entered the state);pendingandfailing(open, within the deadline);overdue(open, past the deadline or-max-ack);cleared_before_notificationandcleared_unacknowledged(the event stopped being current first);never_notified;unobserved_resolved(a gate the journal shows decided that the trail never observed) andall_clear_untimed(an acknowledged event the journal shows resolved, with no all-clear in the trail, where the resolving record holds no time: one an earlier version wrote): warnings, shown asnote: WARNING, that fail the audit only under-strict.acked_late,overdueandnever_notifiedalways fail it. - A late all-clear. A gate's decisions (m-of-n, or a single approver's
agent.Approve) and the resultagent.ResolveHaltinjects for a halt each carry arecorded_at; if the newest is older than-graceand the trail, which acknowledged the gate, has no all-clear, the all-clear isnever_notified.
$ bide audit notifications -db run.db -sth notify-r1.sth.json -pubkey keys/log.pub
INFO trail notify:r1: 6 records; signed head over the first 6 (signed 2026-10-13T09:30:00Z)
PASS acked approval_pending approval:r1:c1:0 began 2026-10-13T09:00:00Z observed 2026-10-13T09:00:01Z acknowledged 2026-10-13T09:00:02Z after 2 attempt(s), 2s after it began [hmac-sha256 current, mTLS, TLS 1.3]
FAIL never_notified outcome_unknown halted:r1:tool:c2:1760346000000 began 2026-10-13T09:05:00Z (the journal shows the event and the trail has no record of it)What this does not prove: that anyone read a notification (an acknowledgement is the sink's 2xx, and bide audit cannot see past the sink); the times are the notifying processes' clocks, bounded above only by the head's signed timestamp; an event that left no trace in the journals supplied (a halt that a later result resolved, or a gate in a run whose journal was not supplied) and no record in the trail cannot be found; the resolution times are the resolving processes' unsigned claims; and an all-clear owed for an event whose resolving record holds no time (a journal an earlier version wrote) is a warning, not a verdict. Take the public key from the operator out of band, as for any signed head.
Cap ledger evidence: did the caps hold?
A cumulative amount cap is a total kept in a reserved journal run per window. The total is what stops the next refund, so it is also what an attacker with write access to the store would change: a deleted slot or a valid release appended to a live reserve lets more through than the limit. bide audit caps recomputes each window from its slots, compares the slots with the cap-reserve record each call left in its own run, and, with the signed heads an AuditedStore anchored, checks that the ledger is the one that was signed and that nothing was written after the newest head. Without heads it reads the ledgers and says so on its first line: it finds inconsistencies it can see, and a writer who keeps the slots and the records consistent is not one of them. See the guide.
Decision receipts: noticing a decision deleted before it was anchored
A decision recorded in the journal is covered by a signed tree head only once the application next writes to the run (AuditedStore signs a head after a write, and a decision written by another process, such as bide approve, is not one of the application's writes). In that window nothing signed contradicts a journal from which the decision is later removed, and the head signed after the removal commits to the journal without it. An approver closes the gap with a receipt (audit.DecisionReceipt, written by bide approve): the signed decision, the call's arguments as signed, the journal record's name and position, and when it was recorded, with no key material.
DecisionReceipt.Verify(v) checks a receipt on its own: the arguments hash to args_sha256, and the signature verifies, under the approver's key, over agent.ApprovalDecisionBytes of exactly that run, call, tool, arguments, approver, decision and time. audit.CheckReceipt(receipt, journal, heads, logKey) then decides whether the signed heads commit to the decision. "Should contain" is positional, never by time: the approver's machine and the application keep different clocks and heads reach an anchor out of order, so a head's timestamp and a receipt's recorded_at (display only) decide nothing. A journal only grows, and the decision is at the receipt's index, so a head whose size is above index commits to a journal prefix that includes that position, and the prefix must hold the decision there. CheckReceipt rebuilds the prefix's root from the journal and compares it with the head's. The verdicts:
| Verdict | Meaning | Failure |
|---|---|---|
anchored | a head that matches the journal reaches the position, and the decision is there | no |
redacted (anchored) | as anchored, and a redaction has since replaced the record with a tombstone that keeps its leaf hash: a legitimate redaction, not a deletion | no |
pending | the journal holds the decision and no head reaches its position yet (the application has not written to the run since) | no |
decision deleted after signing | only for a receipt that carries an anchoring proof (the decision's record under a signed head A): a signed head B that matches the journal reaches the position and commits to something else there. The log's signer signed A with the decision and B without it | yes |
receipt not matched by the journal (the approver's claim) | the journal does not hold the decision at the receipt's position (under a matching signed head, or with no head reaching it). Without an anchoring proof nothing shows the application ever journaled the decision: the receipt's record, index and leaf_hash are unsigned, and a decision signed with an approver's key and never submitted yields the same verdict. It proves a deletion only if the receipt is trusted | yes |
unchecked | a head reaches the position but does not match the journal given, or the receipt's anchoring proof does not hold, so it says nothing of the decision (a journal that does not match a signed head fails its own verification) | yes, in verify-receipts |
Making deletion provable. When a signed head commits to the decision, bide audit verify-receipts -update writes the anchoring proof into the receipt file (audit.AnchorReceipt: the record's inclusion under the smallest signed head that matches the journal, an audit.ProofBundle in the receipt's anchor field; an atomic rewrite that keeps the file's mode and changes nothing the approver signed). It is verify-receipts -update, not a bide approve flag, because verify-receipts already holds every input (journal export, signed heads, log key, approver keys) and bide approve stays a signer that needs no anchor. The proof is made only of what holds, and a redacted record, whose bytes are gone, cannot get one. From then on a head B that matches the journal and holds something else at the position is a contradiction of signed head A, checked against the journal rather than against A: the head sizes and the signing order do not matter. The receipt format stays v1 (the field is optional; the format has been v1 since v0.17.0). Run -update once the decision is anchored, and keep the updated receipt.
Without an anchoring proof the receipt's leaf_hash is the approver's unsigned claim, so a plain record at the position holds only if it is the decision itself (its approver, signature and decided_at are signature-bound), and the claimed hash is trusted only for a redaction tombstone, which keeps nothing else. Only a receipt carrying a valid anchoring proof is evidence against a forged tombstone. The check is as fresh as the journal export and the heads supplied: a write or a head that came after them is not seen.
Heads that do not verify under the log key, or are of another run, are ignored, and heads are read by size, never by arrival order. What this does not do: it checks only decisions whose receipts someone kept, so a decision deleted before its approver made a receipt, or before a receipt got its proof, is not proved deleted, and a head that stops short of the position says nothing, however late it was signed. bide audit verify-receipts is the command line (below).
Certificate-bound receipts. A receipt that carries the approver's certificate chain is not checked with -approver-keys: verify-receipts -identity-policy <file> (with -pubkey, the log's key) checks it against the gate's certificate policy at the time the decision became provable, the time of the smallest signed head that covers it (from the receipt's own anchoring proof, else from the heads given), and prints the identity, that time and its source, and the certificate's validity. It does not check revocation status and says so: the result is an IDENTITY line, not a PASS, and the summary counts these receipts apart from the verified ones; it is the identity check, not the gate's final or provisional verdict. A is the earlier of the receipt's own anchoring head and the heads given. Without -identity-policy such a receipt fails and the line names the flag. The policy file and the single-receipt form are in Human approval.
Which verb to run. The approver runs verify-receipts on the receipts they kept: it asks whether their decision was kept, and notices one deleted after a head committed to it. The operator or an auditor runs verify-decision-coverage on a journal export and the heads: it needs no receipts and asks whether every decision in the journal is under a signed head within a bound, which is how a decision left unsigned (no head covers it past -max-records or -max-age) is found while it is still unsigned. They classify heads by one rule and read head files the same way (a head, or an anchor log with one per line), so on the same journal and heads they do not disagree: an anchored decision is anchored in one and covered in the other; one no head reaches is pending in both; a head the log key signed for the run that the export does not match (a stale or cut export, or a record removed), of any size, fails both. They differ in what they bound: verify-receipts has no age or position bound for a pending decision, and verify-decision-coverage does. Run both when you can.
CLI reference: bide audit
The bide audit command (cmd/bide, its code in internal/auditcli) is the auditor-facing front end for the whole proof surface. It is dependency-light: it imports only the core and audit packages and no store backend, so every produce verb operates on an exported journal (an audit.JournalExport, format bide.audit.journal-export.v1: each record's stored bytes, verbatim, obtained with audit.ExportJournal(ctx, store, runID) and written as JSON; its first record is the journal header) plus a signed tree head, and every verify verb needs only a bundle and an out-of-band public key. Build it with go build ./cmd/bide (or install it: brew install bide-ai/tap/bide). Every verb and flag is in the CLI reference.
Conventions shared across verbs:
-pubkeyaccepts a key in text form,<alg>:<hex>(ed25519,ecdsa-p256,ml-dsa-65, ored25519+ml-dsa-65, asaudit.FormatPublicKeywrites it) or bare hex of a 32-byte ed25519 key, or a path to a file holding either (read withaudit.ParsePublicKey; anything else exits 4 with a message). An ed25519 key, alone or in a hybrid, must be oneaudit.CheckEd25519PublicKeyaccepts: canonically encoded and in the prime-order subgroup, since a small-order key verifies forged signatures (a weak key exits 4). A value that is itself a key is always taken as the key and never opened as a file, so a file of that name in the working directory cannot substitute another key. An artifact signed under another scheme than the key's does not verify (exit 1). The key must come from the anchor operator out-of-band, never from the bundle: that is what makes it a proof you verify rather than a log you trust.- Every artifact must carry the format this version reads (see Artifact formats); one made by an older release exits 4 with a message naming the format (
bide audit -versionlists the formats this version reads). - Every JSON input is read strictly (
audit.UnmarshalStrict): a duplicate key, a key that matches a field only case-insensitively, an unknown field, invalid UTF-8, an escaped lone surrogate, or base64 that is not the standard encoding of its bytes exits 4, so a file cannot show a reader one value while the verifier checks another. - Produce verbs (
prove,prove-absent) write the bundle to-out, or to stdout if-outis omitted; the "wrote <file>" line goes to stderr so stdout stays clean for piping. - Verify verbs print a one-line
OK: .../FAIL: ...verdict and set the exit status (see Exit status below). Only 0 means verified. This is the CI-gate contract. - A usage error is any command line the CLI does not read in full: a missing required flag, an unknown flag, a help request (
-h), or an argument that is not a flag (flag parsing stops there, so a flag after it would go unread). None of them is a verdict, so none exits 0. - Every verb takes
-max-input-bytes <n>: an input file (bundle, journal, key file, digest list, policy, evidence package) larger than n bytes is an error (exit 4); no input is read further than one byte past the cap. The default is 256 MiB; a value below 1 is a usage error. - Every verb takes
-max-clock-skew <duration>(default5m): every signed tree head in every file it reads must follow the timestamp rule (see Timestamps above) against this machine's clock, or the verb fails (exit 1). A negative skew is a usage error. - Every verb takes
-json, before or after the verb (bide audit -json verify ...orbide audit verify ... -json): stdout is then one JSON object instead of the text report, withtool,version,verb,exit_code,result(verified,produced,not_verified,usage_error,no_verdictorunusable_input),verified(true only whenexit_codeis 0 and the verb is a verify verb),output(the text report's lines),errors, and, for a produce verb without-out,artifact(the bundle). Error messages still go to stderr as well. bide audit -versionprints the version and every artifact format this version reads, and which verbs read it;bide audit -version -jsonprints the same as JSON.- On a terminal the text report is colored: each
PASS/OKline gains a green ✓, eachFAILline a red ✗, and a verify verb ends with a banner,VERIFIEDin green (with the signed tree's size and Merkle root, dimmed) orFAILEDin red. The noteverify-evidenceputs on every approver decision line ("check the signatures and the count with VerifyApprovals") is said once, before the banner, so each line fits the terminal. The words are otherwise the same, so a reader who cannot tell the colors apart loses nothing. Written to a file or a pipe, and under-json, the report is the plain text it always was. Every verb takes-color=auto|always|never(defaultauto), before or after the verb;NO_COLORset to any value, orTERM=dumb, turnsautooff.


| Verb | Required flags | Optional flags | Proves / checks |
|---|---|---|---|
prove | -journal, -sth, and one of -tool <id> / -index <n> | -out | Build a ProofBundle for one record (by tool-use id or journal index) against a signed tree head. |
verify | -bundle, -pubkey | A ProofBundle is authentic under the key, its head is a journal head of the bundle's run, and it is bound to its signed size. | |
prove-absent | -journal, -sth, -key (tool:<id> or policy:<digest>) | -out | Build an AbsenceBundle proving a tool call / governed policy never appears, against a signed key-set head of the matching kind (audit.SignAbsenceRoot with ToolUseKeys or PolicyUsedKeys) whose source journal is the exported journal. |
verify-absent | -bundle, -pubkey | An AbsenceBundle is authentic: its head is a signed key-set head of the kind the key belongs to (tooluse: keys need a tool-use head, policy_used: keys a used-policy head) for the bundle's run, and the key is absent from it. Reports the journal size the absence covers. | |
verify-governance | -policy | -digest <hex>, -checker <astchecker> | Recompute the policy digest from the published bytes (independent of gsm); with -digest, assert it matches; with -checker, run the external verified oracle to certify the policy converges. |
verify-governed-action | -action, -policy-bundle, -pubkey | -checker | End to end: both bundles authentic and in the same signed tree, the action bundle a tool call's result and the policy bundle the policy leaf (audit:policy:<digest>, a StepValue) for the digest it carries, the action's embedded policy digest links to the anchored policy leaf, the leaf's bytes hash to that digest, and (with -checker) the policy converges. |
verify-convergence | -cert-bundle, -policy-bundle, -pubkey | -checker | An anchored ConfluenceCertificate links to the policy leaf (each bundle must be the leaf it is read as: audit:convergence:<digest> and audit:policy:<digest>, both StepValue); with -checker, the oracle's convergence verdict must AGREE with the certificate, so overstated convergence is caught; the compensation-free (CRDT) classification is cross-checked only when the oracle emits a compensation_free= line, and otherwise stays producer-reported (the CLI prints a note saying so). |
verify-quorum | -name, -tally, -vote (repeatable), -pubkey, -k | -commit | A governed k-of-n quorum: the tally and every vote bundle authentic, in the same signed tree and run, and recorded by the quorum named -name; the disclosed votes exactly the votes the tally records; the recorded tally recomputes from them (a forged tally is caught); and votes_for >= k; with -commit, a governed commit (a tool call's result) is anchored in the same tree. |
verify-run | -cert, -pubkey, and at least one of -approved <digest> (repeatable) / -approved-file <file> (both together form one allowlist) | -checker <astchecker> | A proof-carrying run certificate: the used-policy set is bound by a signed used-policy head to this run and to the certificate's journal tree, and is a subset of the approved allowlist (only-approved-policies), and every used policy has an anchored, digest-linked convergence certificate in the run's signed tree (policies-convergence-certified); with -checker, the oracle's convergence verdict on each used policy must AGREE with its certificate. |
verify-receipts | -receipt (file or directory, repeatable), -journal (export per run, repeatable; two exports of one run are refused as an unusable input, exit 4), -heads (a head, or one per line; repeatable), -pubkey, -approver-keys | -update (store the anchoring proof) | Decision receipts written by bide approve: each signature verifies for the approver's key over the exact call it states, and the signed heads commit to the decision at its journal position (audit.CheckReceipt). Prints one line per receipt: PASS when anchored or redacted, INFO when pending (exit 0), FAIL for decision deleted after signing (proven receipts only), receipt not matched by the journal and unchecked (exit 1). A missing journal for a receipt's run, or an unreadable input, is exit 4. |
redactions | -trail <file> with -journal <export> (repeatable, one per run: two exports of one run are refused as an unusable input, exit 4), or -db / -postgres-env (every run's journal and the trail from a store; -run), and -sth (repeatable) with -pubkey, or -unanchored | Verifies the redaction trail audit.RedactJournal writes: every record is signed by the redaction key and bound to its position and predecessor (BAD_SIGNATURE for a planted or altered one, which accounts for nothing and does not stop a later erasure, REORDERED for a replayed, copied or reordered one, whatever head covers it; -deployment, required, names the deployment it must be signed for), complete under its signed heads (TRAIL_ALTERED for a deleted or changed record, UNATTESTED_TAIL after the newest head, UNANCHORED with none), every begin has an end (INCOMPLETE), every tombstone in the journals is named by a trail record with the same name and leaf hash (UNACCOUNTED, NAME_MISMATCH, HASH_MISMATCH: a tombstone's name is outside the journal's hashes, so the signed trail is what attests it), every record the trail lists is erased (NOT_ERASED), a tombstone's time is that of a pass that listed it (TIME_MISMATCH), the trail names no run it was given no journal for (UNCHECKED: a trail checked against no journal checked nothing), and no erasure ran without a covering signed journal head (UNCOVERED) or left the run's events in the event store (EVENT_COPIES_KEPT), or began while a legal hold the trail shows covered the run (REDACTED_UNDER_HOLD); the holds the trail shows in force are listed and, against a database, compared with the store's (HOLD_NOT_IN_STORE, HOLD_NOT_IN_TRAIL, HOLD_DIFFERS; HOLD_UNMATCHED for a lift or placement the trail does not match; LIFT_UNAUTHORIZED for a lift whose embedded second-person authorization does not check out, with -authorizer-pubkey pinning the authorizers and -require-lift-authorization making one mandatory). -pubkey is required. A pass is judged by its last record: a failed pass the same plan later finished is a note. -trail-db and -trail-postgres-env read the trail from a store kept apart from the journal. An operator's signed acknowledgement (bide journal acknowledge) of a planted leaf, naming its position and hash, turns BAD_SIGNATURE, REORDERED and MALFORMED for that leaf into a note. A tombstone is accounted for only by the pass that erased it, never by a later plan that listed it as already redacted. | |
verify-decision-coverage | -journal, -heads (repeatable), -pubkey | -max-records <n>, -max-age <d>, -max-age-tolerance <d>, -now <time> | Every approval decision in a journal export is covered by a signed tree head, or is within the stated bound. A head counts only if it verifies under the key, is a journal head of the export's run, and is the root of the export's own prefix of its size; heads are used by size, in any order, never by arrival or timestamp. A head the log key signed for this run that does not match the export (the export is shorter than the head, or its prefix differs) is divergent, and fails the verb: a decision deleted from an export, or an export cut before it, looks exactly like that, so re-export the journal and run again. A head that does not verify, or is another run's, is ignored with a note. A decision is covered, pending, or overdue. Overdue by position: the journal holds -max-records or more records after the decision and no head covers it (no clock involved). Overdue by age, only with -max-age: the decision's unsigned recorded_at is more than -max-age plus the tolerance before -now (default: this machine's clock), the weaker basis since the recorder's clock is its own; a decision with no recorded time (an unsigned agent.Approve decision records none) is over an age bound. A decision a redaction replaced with a tombstone is listed too (note redacted) and bounded like any other. If the journal holds decisions and no head counts at all (a wrong -pubkey ignores every head), the verb prints a WARNING, and fails when a bound is set, since nothing shows any decision inside it. The bounds are only as strong as the export is complete. With no bound nothing is overdue. Halt resolutions are not checked. |
verify-approvals | -evidence, -pubkey, -call, -need, -approvers, -approver-keys | -approved <digest> (repeatable), -approved-file <file> (together, one allowlist, required when the package carries a run certificate); -exclude-principal (the expected policy excludes the run's requester: the package must prove the run's run:principal, the requesters' decisions are listed as ignored, and a gate that did not exclude the requester fails) | An m-of-n approval gate from an EvidencePackage: the request, every decision the gate read, its recorded tally, and the call's result all verify in one signed tree and in order; recounting the decisions with the approvers' keys (a JSON object of id to key text, <alg>:<hex> or bare ed25519 hex; two of the policy's approvers on one key, or a weak key, is an unusable input) against the exact call reproduces the recorded tally; the gate enforced the expected policy; and at least k approved. Catches an omitted decision, which verify-evidence alone cannot. |
notifications | exported files: -trail (repeatable) and -pubkey with -sth per trail, or -unanchored; or a store: -db or -postgres-env, with the same | -journal (repeatable, one per run: two exports of one run are refused as an unusable input, exit 4), -run <id> (store only), -strict, -max-ack <duration>, -grace <duration>, -recovery-failing-after <duration>, -as-of <time>, and with a store -stop-policy <file>, -stop-root <digest>, -stops-within <duration> (the kill switch's stops: each must have been told, and each lift) | That every event that needed a person (an unknown-outcome halt, an approval gate, an aborted run, a recovery failure, an overdue notice, an all-clear) was notified and acknowledged in time: the trail is read strictly and is a history a notifier writes; with a signed head, the trail's first records are exactly what the head commits to; every gate, halt and abort a journal shows is observed. Exit 1 on acked_late, overdue, never_notified, or a trail that does not hold together. See Notification evidence. |
stops | an exported trail -trail or a store (-db, -postgres-env), and -stop-policy (the pinned policy as JSON), with -pubkey and -sth for the trail's head, or -unanchored | -stop-root <digest>, -max-unattested <duration>, -as-of <time>, -sign-head -log-key <file> -head-out <file> (with -db or -postgres-env and -pubkey: verify first, then sign a head over exactly the verified records and append it as one JSON line, which -sth reads back; run it on a schedule) | That the kill switch's stop trail holds together and matches the control run: each record verifies under the pinned policy and the chain of signed policy transitions from its root (a forged or foreign record is a problem, and a pin the chain does not reach is one too); with a signed head, the first records are exactly what the head commits to, so a deleted or reordered record is found; against a store, every record of the control run is in the trail and the reverse. Prints each stop and whether it is in force. Exit 1 on any of those. |
caps | a store: -db or -postgres-env, with -pubkey and -sth for the heads of the ledger runs, or -unanchored | -namespace <ns>, -rule <name>, -window <id>, -run <id> (each narrows the audit, and the report lists what it did not check) | That the amount-cap ledgers hold together: each ledger run reads under the ledger's own rules, its window total is the sum of its live reserves, and its slots agree with the cap-reserve records of the runs that made the calls (a deleted slot, a changed slot, a slot no run recorded); with signed heads, the ledger is what the newest head signs and the entries after it are NOT_ATTESTED and fail. Unanchored, the report says first that whoever can write the store can delete a slot or append a release undetected. Prints the over-limit slots counted under a waiver, and the reconcile exposure (information). Read-only. Exit 1 on any finding. |
verify-evidence | -evidence, -pubkey | -approved <digest> (repeatable), -approved-file <file> (together, one allowlist) | A run-level EvidencePackage: the format, seal, and key are right, the signed tree head is an authentic journal head of the package's run, every packaged action proof verifies against it with the kind and label its record says, the grant chain is the anchored grants, the consistency proof holds between its two signed heads, and any run certificate is for this run and passes against the given allowlist (required when the package carries one). Prints one line per item and an overall PASS/FAIL. A step whose key holds a call ID (approval-pending:, approval-request:, approval-tally:, approval-deadline:, approval:, gate-reason:, attempt:tool:, approval-exec-hold:, approval-identity:, approval-pause:) is named by that ID as the other verbs show it, e.g. step "approval-pending" of call "c2#taint"; the stored key, which escapes the ID (approval-pending:c2%23taint), is unchanged. |
The -checker flag points at the external verified oracle binary (the astchecker extracted from the axiom-free Coq proof); the CLI does not ship it, and without it the governance verbs verify only the cryptographic root and say so. The checker's verdict is its exit status: 0 for a convergent policy, 1 for one that does not converge. Anything else gives no verdict: a checker that cannot be started, exits with another status (the astchecker exits 2 on a usage or parse error), or is killed by a signal, or whose output has a compensation_free line that reads as neither true nor false, or as both. Then the verb prints an ERROR: ... line, not a FAIL verdict, and exits 3, so a broken checker is never reported as a policy that does not converge, nor as agreement with a certificate. The digest is recomputed here from a hardcoded gsm-policy-v1 domain-separation tag rather than taken from gsm, so neither root of trust depends on the producer. The CLI reads no environment variables but NO_COLOR and TERM, which decide only whether the text report is colored (see below), never a verdict, and the one that notifications -postgres-env <name> names, which holds a Postgres DSN (so the credential is never on a command line). notifications -db, stops -db and their -postgres-env open the store read-only and are in the full bide command; the audit-only build (-tags bide_audit_only) links no store driver and reads exported files.
Exit status
| Status | Meaning |
|---|---|
| 0 | Verified. For prove and prove-absent: the artifact was written. |
| 1 | The inputs were read and understood, and they do not verify: a bad signature or proof, a digest that does not link, a quorum or approval gate that did not hold, a policy the checker says does not converge (or disagrees with its certificate about), a signed head that breaks the timestamp rule. |
| 2 | Usage error: a missing, unknown, or malformed flag, an argument that is not a flag, a help request, an unknown verb. Nothing was read. |
| 3 | No verdict: the -checker gave none (see above), or an internal error in the CLI (an output it could not write, a bug). |
| 4 | An input is unreadable or unusable: a missing or unreadable file, one over -max-input-bytes, JSON that does not read strictly, an unknown or unsupported format (an old artifact, or one carrying an old signed tree head), a public key that is not one (or of an unknown scheme), or an artifact of the wrong type for its flag (a policy leaf given as the action, an absence bundle given to verify, a key of no known key set). For prove and prove-absent, inputs that cannot make the proof (no such record, a head that does not commit to the journal, a key that is present) are 4 as well. |
Only 0 means verified. Treat every other status as a failure, and treat 4 as a failure, never as something to retry: a tampered format field, or an artifact swapped for one of another type, yields 4, not 1. The statuses follow the library's errors: an error wrapping audit.ErrNotVerified is 1, and one wrapping audit.ErrFormat or audit.ErrMalformed is 4.
When a command meets several conditions, the status is the highest-ranked of them: a usage error is exclusive (nothing is read after it); otherwise 1 over 4 over 3. To make that hold, a verb reads every input it was given and runs every check that does not depend on an unusable one: a tampered action bundle beside an unreadable policy bundle exits 1, a checker that gives no verdict beside an unreadable action bundle exits 4, and a policy the checker says does not converge exits 1 even when the action bundle beside it cannot be read. With an unreadable -approved-file, verify-run and verify-evidence still run every check that does not read the allowlist (the certificate is checked against its own used-policy set) and exit 1 if one fails, otherwise 4. A quorum bundle recorded by another quorum is a verdict (1): it is the right type of artifact, and it does not prove the claim.
RFC 6962 conformance
The Merkle tree, inclusion proofs, and consistency proofs implement RFC 6962 (Certificate Transparency): the same construction CT logs use. The implementation is checked against the published RFC 6962 reference test vectors (the canonical 8-leaf tree roots at all sizes), plus inclusion round-trips, a hand-derived consistency vector, and rewrite-detection tests. It is not a homegrown look-alike.
End-to-end compliance flow
// 1. After a run, commit to the journal and PUBLISH a signed tree head.
th, _ := audit.NewTreeHead(ctx, journal, runID, time.Now().UnixNano())
sth, _ := audit.SignTreeHead(th, signer) // publish/anchor sth (out-of-band)
// 2. Later, an auditor asks: "did the agent issue THIS charge?"
// Disclose only that one record's stored bytes + its inclusion proof, nothing else.
proof, _ := audit.Prove(ctx, journal, runID, chargeIndex)
recs, _ := journal.History(ctx, runID)
charge := recs[chargeIndex].Raw() // the bytes the journal stores for it
// 3. The auditor verifies, from public artifacts alone (nil means it holds):
_ = sth.Verify(v) // the commitment is authentic
_ = audit.VerifyInclusion(sth.Root, charge, proof) // the charge is in it
// ...revealing no other customer, prompt, or PII.
// 4. Prove the log only grew between two published STHs (no retroactive edits):
cproof, _ := audit.ProveConsistency(ctx, journal, runID, sth1.Size)
audit.VerifyConsistency(sth1.Root, sth2.Root, cproof)That is a privacy-preserving, third-party-verifiable audit trail: prove a single action happened, in a committed run whose history is provably append-only, without exposing the rest.
Governed actions: proving which policy admitted the action
For a governed action (a gsm event applied through the Tier-2 governor), the audit trail can commit not only to the fact that the action happened but to the policy it ran under. An attested govern.EventTool (one whose EventToolConfig.PolicyDigest is set) embeds a policy digest (an opaque identifier, e.g. gsm.Registry.PolicyDigest) and the resulting state_digest (gsm.State.Digest) in the tool's journaled result, so one committed leaf binds the action, the policy that admitted it, and the exact state it produced, and the same ProofBundle that proves the action commits to all three. The SDK treats both digests as opaque; it does not depend on the policy engine's serialization or state layout.
If the deployment binds an acting identity to the run (the agent.WithIdentity option, carrying Actor, OnBehalfOf, and AuthorityRef), the attested EventTool also stamps those fields into the same leaf, so an inclusion proof commits to who acted, on whose behalf, and under what authority, not merely that the action happened under the policy. Identity is assigned by the deployment from its own auth layer (an IdP, a signed grant, a service identity), never by the model, and it rides the context so governed actions and sub-agents inherit it. The proof commits to the identity CLAIM; authenticating the principal is the operator's IdP/PKI, and the attribution is only as strong as the key custody behind the run's signatures.
The verifier then closes a second, independent root of trust:
# recompute the policy digest from the published bytes and, with the external verified
# oracle (astchecker, extracted from the axiom-free Coq proof), certify the policy converges:
bide audit verify-governance -policy policy.machine -digest <hex-from-bundle> -checker ./astcheckerverify-governance recomputes the digest from the published format without importing the policy engine, and runs a checker it did not write, so neither root of trust depends on the producer: the log is tamper-evident (cryptographic root) and the policy is provably convergent (mathematical root), over one artifact.
The policy is not only referenced by digest, it is anchored in the log. audit.RecordPolicy commits the serialized policy as a dedicated leaf (a StepValue record keyed by its digest, idempotent per run), so the policy is covered by the same signed tree head and inclusion proofs as the actions taken under it. audit.ProvePolicy builds a ProofBundle for that leaf. An auditor pairs it with an action's ProofBundle whose result embeds the same digest: both verify under the same out-of-band key, both bind to the same tree (same STH root and size), and their digests link, so the action provably ran under a policy anchored in the same committed run. audit.PolicyContent is the disclosed leaf payload (the serialized policy plus its digest), which the auditor feeds to verify-governance to recompute the digest from the bytes and certify convergence.
The CLI does this whole cross-link in one command:
# both bundles authentic and in the same signed tree, the action's policy digest links to the
# anchored policy leaf, the leaf's bytes hash to that digest, and (with -checker) the policy converges:
bide audit verify-governed-action -action action.json -policy-bundle policy.json -pubkey <key> -checker ./astcheckerAnchoring the convergence proof itself
gsm.Registry.Build checks convergence exhaustively at build time (WFC over every repair chain, CC over every independent event pair, on the valid states (and the zero state); see known limitations) and returns a Report. govern.CertifyConvergence(report, digest) carries that result across as a portable ConfluenceCertificate: the WFC and CC verdicts, the longest compensation chain, the number of pairs checked, the state count, a CompensationFree flag, and the delivery obligations gsm v0.13.0 reports: the undeclared event pairs that do not commute and so need causal order (causal_order_required), the events a duplicate delivery would change (not_idempotent), and the rules whose writes were clamped into range (saturations); see known limitations. That flag is the CRDT.v subsumption result made visible: CRDTs are exactly the compensation-free fragment, so MaxRepairLen == 0 marks a machine that needs no coordinator, while a positive value marks a compensation-bearing policy that is strictly more expressive than any CRDT. audit.RecordConvergence anchors the certificate as a leaf keyed by the same policy digest, and audit.ProveConvergence proves it, so the convergence evidence rides the same signed tree head and inclusion proofs as the policy and the actions. audit keeps the certificate opaque, exactly as it does the policy digest: it imports no gsm.
The certificate is a producer claim, so the verifier does not trust it: verify-convergence re-establishes the claims from the disclosed policy bytes with the external oracle and fails if the oracle disagrees. It cross-checks both facts. Convergence: the oracle certifies (or refutes) it, and a certificate that says convergent while the oracle refutes is rejected. Classification: the oracle also certifies the compensation-free (CRDT-fragment) verdict, via compensationFree in AstChecker.v (a machine-checked, axiom-free predicate: no in-domain state ever needs repair, the AST analogue of "max repair depth = 0"), emitted as a compensation_free=<bool> line the CLI parses and compares. So a certificate that overstates convergence is always caught, and one that overstates the CRDT classification is caught when the oracle emits that line. An oracle that does not emit it leaves the classification producer-reported: the CLI prints a note saying so rather than passing it silently. compensationFree_step_no_repair is in the axiom-free gate alongside check_sound_converges. verify-convergence and verify-run print each delivery obligation a certificate records; they are conditions of the convergence claim, so they do not change the verdict, and they are producer-reported (the oracle does not re-derive them). A certificate written before bide recorded them has none of their keys: it still verifies, and the CLI notes that it records no obligations.
# both bundles authentic and in the same signed tree, the certificate certifies the anchored
# policy's digest, the leaf's bytes hash to it, and the oracle's convergence AND compensation-free
# verdicts agree with the certificate:
bide audit verify-convergence -cert-bundle cert.json -policy-bundle policy.json -pubkey <key> -checker ./astcheckerBinding the resulting state, and checking it by replay
Each governed leaf also commits the state_digest the action produced (gsm.State.Digest, a stable domain-separated hash over the packed state, meaningful because the policy pins the layout) and the event's position in the governor's order. Because gsm's convergence engine is deterministic given a policy and an event sequence, a verifier holding the policy can build a reference machine, replay the governor's events at positions [0, position], and reproduce the committed state_digest. For a PersistentGovernor those events are its shared EventLog, whichever processes and runs wrote them; for an in-memory Governor shared by several runs, they are the governed leaves of all those runs ordered by position. Replaying one run's own events is enough only when nothing else acts on the same governor. Any divergence means the runtime's committed state does not match what the verified reference computes for that policy. This is a per-run differential check of the actual execution against the verified reference, not merely of the policy in isolation (govern/attested_replay_test.go demonstrates it end to end). It is not a refinement proof: it checks the events this run actually took, not the runtime's behavior for all possible inputs, so the refinement gap stays open.
Proving a negative: no action under a disallowed policy
The set of policies a run exercised is itself provable. Governed-action leaves are keyed by their policy digest (the audit.PolicyUsedKeys key set), so the run's used-policy commitment (AbsenceRoot, a Merkle tree over the sorted distinct keys with adjacency-checked non-membership) commits exactly the policies that were used. An auditor:
- recomputes the used set with
used, err := audit.PoliciesUsed(records)and confirms every digest is in the approved set (each approved policy having been oracle-certified convergent, as above). To check a signed used-policy head against the journal, it recomputes the head's root and size withroot, size, err := audit.AbsenceRoot(records, audit.PolicyUsedKeys). Both return an error rather than a set when the journal cannot be projected:audit.ErrRedactedwhen a record is redacted (its action, and so its policy, cannot be read) andaudit.ErrMalformedwhen a record's stored bytes read two ways, so a recomputation never confirms a head that omits a policy the journal commits; - for any digest that is not approved, obtains an anchorable
audit.AbsenceBundleviaaudit.ProveAbsentBundle(records, audit.PolicyUsedKeys, audit.PolicyUsedKeyFor(digest), sth)and verifies it offline withbundle.Verify(v, audit.PolicyUsedKeys)(nil means verified), proving no governed action ran under that policy.
The negative has teeth: the commitment is over the run's actual key set (the head must commit to the key set of the journal it names, or ProveAbsentBundle refuses), so you cannot prove absence of a policy that was in fact used. And it cannot be borrowed from another tree: each key set is a KeySet with its own tree kind and key prefix (ToolUseKeys is absence/tool-use over tooluse: keys, PolicyUsedKeys is absence/policy-used over policy_used: keys), the signed head commits to its kind, its run, and its source journal tree, and Verify requires the head to be of the set you name and the key to carry that set's prefix. A tool-use head cannot prove a policy absent, and a journal head cannot prove anything absent. The tool-use key set holds every call the run started, not only completed ones: every call a model turn requested (the request is journaled before the call starts, and a retry-safe call journals no attempt marker, so a call whose result was lost leaves only its request), a result, an attempt marker journaled before a side effect fired (the effect may have happened though no result was recorded), and a saga failure. A call the model requested that never ran, and a Step's attempt marker (which adds the step's name as a key), can only make an absence proof for that key impossible, never a wrong one. Every producer and recomputation of a key set refuses a journal it cannot project: one holding a redacted record (audit.ErrRedacted), and one holding a record whose stored bytes read two ways to JSON readers (audit.ErrMalformed, the rule a proof's record bytes follow). The absence covers the journal up to the size the head names; that it is the run's final head comes from the anchor log.
The auditor persona produces and checks these from the command line, as with inclusion. Absence proofs verify against a separate key-set commitment, signed in one call with audit.SignAbsenceRoot(records, keySet, journalHead, signer, ts) (it refuses records that are not the journal journalHead commits to); keys are built with audit.ToolUseKeyFor(id) or audit.PolicyUsedKeyFor(digest):
# prove no tool call with this ID, or no governed action under this policy digest, ever happened:
bide audit prove-absent -journal run.json -sth used-policy-sth.json -key policy:<digest> -out absent.json
bide audit verify-absent -bundle absent.json -pubkey <key> # exit 0 = authentically absentScope, stated precisely: this proves the action ran under a policy that is anchored in the log and provably convergent, in a committed, append-only run; that each governed leaf binds the action, the policy, and the resulting state, and that replaying the policy over the run's governed events reproduces every committed state; and that no governed action ran under a policy outside the approved set. Combined with the approved policies being oracle-certified convergent and invariant-preserving, that supports "no violation was admitted." Two limits remain, stated plainly: it is a policy-level negative, not a per-action state-validity proof; and the replay checks the events this run actually took, not the runtime's behavior for all inputs, so the runtime refinement gap is open and this is not an end-to-end execution proof. No proof feature remains on the roadmap; what is left is operational (a hosted anchor service).
Proof-carrying runs
The primitives above prove one fact at a time: this action happened, this policy was anchored, this policy is convergent, this policy was not used. A proof-carrying run composes them into one portable certificate asserting behavioral-property compliance over a WHOLE run, checkable offline against a single signed tree head. The innovation is the composition, not new cryptography: a RunCertificate binds together the used-policy absence commitment, the anchored policy and convergence leaves, and the run's STH, and VerifyRun re-derives every property from the disclosed proofs.
v1 asserts three properties, each dischargeable from a committed leaf:
- only-approved-policies: every policy digest exercised by a governed action in the run is a member of the auditor's approved allowlist (an argument to
VerifyRun; the certificate carries no allowlist of its own). This is the completeness-bearing property: it commits WHICH policies were used, via the used-policy commitment (aPolicyUsedKeyshead). The used set is exactly the sorted distinct keys that tree commits to, so the verifier recomputes that root from the disclosed set and confirms the signed head commits to it. That is what gives the negative teeth: a policy that was in fact used cannot be dropped from the disclosed set without changing the root and breaking the signature check. - binding: the used-policy head is bound to this run and this journal, not merely signed by the right key. Its signed encoding commits to kind
absence/policy-used, to the run ID, and to the journal tree (size and root) the set was projected from, andVerifyRunrequires that journal tree to be exactly the certificate's signed journal head, itself a journal head of the certificate's run. A used-policy head from another run, from another point or history of this run, or a tool-use head cannot stand in, and the used set is the projection of the same records the convergence bundles are proven against. - policies-convergence-certified: for each used policy digest, an anchored convergence certificate leaf exists in the same signed tree as the policy leaf and links to its digest, exactly as
verify-convergenceestablishes. With-checker, the external oracle is run on each disclosed policy's bytes and its verdict must AGREE with the certificate, so a certificate that overstates convergence is caught.
Composing them yields "every governed state in the run was produced by an approved, oracle-certified-convergent policy," so the enforced invariant held throughout the governed boundary.
// Emit: recompute the used-policy set, confirm it is a subset of the allowlist, and assemble the
// anchored policy + convergence proofs for each used policy against the run's signed tree head.
sth, _ := audit.SignTreeHead(th, signer)
cert, _ := audit.CertifyRun(ctx, journal, runID, sth, audit.RunCertSpec{
ApprovedPolicies: []string{policyDigest},
Signer: signer, // must hold the key that signed sth
TimestampNanos: time.Now().UnixNano(),
})
// Anchor the certificate itself so it is provable in the run (mirrors RecordPolicy / RecordConvergence):
audit.RecordRunCertificate(ctx, journal, runID, cert) // + audit.ProveRunCertificate(..., laterSTH)
// Verify: offline, against the auditor's allowlist, trusting only the out-of-band key.
res, err := audit.VerifyRun(cert, allowlist, v) // err == nil: both properties hold; res says which failedThe CLI verifies the same certificate for an auditor who does not write Go, and takes the allowlist as its own input (the certificate carries none, so a producer cannot pass by widening its own set):
# only-approved-policies (used set bound to the run's signed used-policy head and a subset of the allowlist)
# and policies-convergence-certified (each used policy anchored and digest-linked); with -checker the
# oracle's verdict on each policy must agree with its certificate:
bide audit verify-run -cert runcert.json -pubkey <key> -approved <digest> -checker ./astcheckerScope, stated precisely: the certificate proves properties of the governed, committed boundary of the run: which policies ran, that each is on the approved allowlist, and that each has an anchored convergence certificate that (with the oracle) is confirmed convergent. It does NOT prove the model's judgment was correct, that ungoverned side effects were appropriate, or the runtime-refinement claim (the replay differential check covers the events this run took, not all inputs). The used-policy completeness rests entirely on the used-policy key-set commitment described above, and covers the journal up to the certificate STH's size; that this STH is the run's final head is a fact the anchor log supplies, not the certificate. Property support for authority-bounded (every governed action under a grant descending from the root, via VerifyDelegationChain) and quorum-backed commits composes from the same seams and is deferred to a later version. Runnable end to end in examples/govern/proof-carrying-run.
Signature schemes and post-quantum anchoring
Everything the package signs goes through an audit.Signer, and everything it verifies through an audit.Verifier: both name their scheme (Alg(), a typed audit.Alg) and their encoded public key (PublicKey()). SignTreeHead(th, signer), Sign, SignAbsenceRoot, Evidence and Seal, CertifyRun (through RunCertSpec.Signer), NewAuditedStore, and SignGrant take a signer; SignedTreeHead.Verify, ProofBundle.Verify, AbsenceBundle.Verify, EvidencePackage.Verify, VerifyRun, VerifyApprovals, VerifyCurrentGrant, VerifySignature, and SignedGrant.Verify take a verifier. audit.NewVerifier(alg, pub) builds a verifier from an encoded key, audit.VerifierOf(signer) the one for a signer's key, and audit.ParsePublicKey / audit.FormatPublicKey read and write the <alg>:<hex> text form the CLI takes.
SignedTreeHead always carries its alg, and the scheme is part of the signed bytes (bide.audit.sth.v5: scheme, kind, run ID, size, root, timestamp, and the source journal of a key-set head), so a head's signature is never read under another scheme, and the kind and run binding hold whichever scheme signs. An evidence package names its key by {alg, public_key}, and EvidencePackage.Verify refuses a verifier whose scheme or key is not that one. Four schemes are available, all in the Go 1.27 standard library, so this adds no dependency:
ed25519(Ed25519Signer): small, fast, FIPS-approved. Its key can be held in a PKCS#11 token, AWS KMS or Google Cloud KMS instead of in memory (Key custody).ecdsa-p256(ECDSAP256Signer, FIPS 186-5): for keys that live where Ed25519 does not: many HSMs, AWS KMS and Azure Key Vault sign P-256 and not Ed25519. See ECDSA P-256 for the exact encodings.ml-dsa-65(MLDSASigner, FIPS 204): post-quantum.ed25519+ml-dsa-65(HybridSigner): accepted only if both signatures verify. Each component signs its own label followed by the message (bide.hybrid.ed25519.v1andbide.hybrid.mldsa65.v1), after the IETF composite-signature construction, so the ed25519 half stripped out of a hybrid signature verifies neither as a hybrid signature nor as a plain ed25519 signature over the same head.
Why it matters here specifically: audit anchors are long-lived, so they face a harvest-now, forge-later exposure. The signature is the quantum-vulnerable part; the SHA-256 Merkle hashing is not affected and is unchanged. Choosing ML-DSA or hybrid for the anchor signature addresses the signature exposure without touching the tree. One toolchain constraint: crypto/mldsa is unavailable under Go's FIPS 140-3 module v1.0.0 (ed25519 and ECDSA P-256 keep working there), and available under v1.26.0 and later (see the security model). Pick per buyer: a buyer pinned to module v1.0.0 takes ed25519 or ECDSA P-256, a post-quantum-focused buyer takes ML-DSA or hybrid.
ECDSA P-256
The wire formats are fixed so a signer and a verifier written apart (an HSM adapter, a verifier in another language) agree on every byte:
| Part | Form |
|---|---|
| Scheme name | ecdsa-p256 (audit.AlgECDSAP256) |
| Hash | SHA-256 over the exact message bytes (the bytes Ed25519 would sign); a KMS in digest mode signs SHA-256(message) |
| Signature | 64 bytes, r || s, each a 32-byte big-endian integer (IEEE P1363), not ASN.1 DER |
| Canonical form | 1 <= r < n and 1 <= s <= (n-1)/2 (low S); a verifier refuses anything else, including the valid high-S twin of a signature, so a signature has one encoding and nobody can turn one valid signature into a second |
| Public key | 65 bytes, the SEC1 uncompressed point 0x04 || X || Y, on the curve; compressed, hybrid and infinity encodings and off-curve points are refused (ErrMalformed) |
| Text form | ecdsa-p256: and 130 lowercase hex digits (audit.FormatPublicKey); bare hex is always read as Ed25519, never as P-256 |
| Key identity | audit.KeyID("ecdsa-p256", point): the scheme and the SHA-256 of the 65-byte point |
Why r || s and not DER: a DER signature has several encodings of one value (BER padding, leading zeros), so accepting it means a parser that is strict in a way every implementation must copy; a fixed 64 bytes has no such room, and Azure Key Vault and PKCS#11 CKM_ECDSA already return it. AWS KMS returns DER, so an adapter converts it once with audit.ECDSAP256SignatureFromDER (strict DER in, canonical low-S r || s out); audit.ECDSAP256SignatureFromRaw does the same for a raw r || s (an HSM's high-S output becomes low-S by s = n - s), and audit.ECDSAP256PublicKeyFromSPKI reads the point out of the SubjectPublicKeyInfo a KMS GetPublicKey returns. Low S is enforced because ECDSA is malleable: (r, n-s) verifies whenever (r, s) does.
Two differences from Ed25519 to know about. Signing is randomized (crypto/ecdsa mixes the key and the message into the nonce), so signing the same tree head twice gives two different valid signatures where Ed25519 and ML-DSA give the same bytes; a decision's journal record is named by the decision (call, approver, verdict, scheme, decided_at), not by its signature, so re-signing and resubmitting one decision, even concurrently, is one record (agent.DecisionStep). And the scheme works inside every version of the FIPS 140-3 module (crypto/ecdsa), unlike ML-DSA under v1.0.0.
P-256 is not a hybrid half. The hybrid scheme stays ed25519+ml-dsa-65. A hybrid exists for its post-quantum half, and no HSM or cloud KMS signs ML-DSA yet, so a P-256 + ML-DSA hybrid would not move the keys into the HSM either. Hybrid post-quantum keys inside an HSM are deferred:HybridSigner's halves are the concrete Ed25519Signer and MLDSASigner types, which hold their keys in process memory. A deployment that needs the log key in an HSM or KMS uses ed25519 (the key custody signers sign it today) or ecdsa-p256 (verifiable now; the signers gain a P-256 mode separately), and one that needs post-quantum protection today keeps the hybrid key in the process.
Every artifact that names a scheme (a tree head, an evidence package, an approval decision's Alg) takes ecdsa-p256 with no format change: the scheme is a string in the artifact, and an older verifier that does not know it refuses the artifact (ErrMalformed) rather than misreading it. The standalone audit/verify package verifies it too (verify.NewVerifier("ecdsa-p256", point)).
Signed authority grants and the delegation chain
Identity binds who acted (see above); a grant binds by what authority, non-repudiably. audit.Grant{Issuer, Subject, Scope, NotAfterUnix, ParentRef} is a statement by a principal authorizing an actor within a scope; its canonical bytes (Grant.Bytes) start with the bide.audit.grant.v2 tag and are both signed and digested. SignGrant signs it with the issuer's own key (an audit.Signer: Ed25519, ECDSA P-256, ML-DSA, or hybrid), distinct from the log's tree-head key, so the authorization is attributable to the principal, not the operator. RecordGrant / ProveGrant anchor and prove it as a leaf like a policy, and a governed action's agent.Identity.AuthorityRef is set to the grant's Digest, so the action links to an in-log, issuer-signed authority.
ParentRef hash-links a grant to the one it was attenuated from, so a holder can mint a strictly narrower sub-grant for a sub-agent without returning to the root issuer (capability attenuation). VerifyDelegationChain checks a root-to-leaf chain: each hop signed by its issuer, and each child a valid delegation of its parent (CheckAttenuation): its ParentRef is the parent's digest, its issuer is the parent's subject (only the holder of a grant can delegate it), it expires no later than the parent (a child of an expiring grant is never non-expiring), and it keeps every one of the parent's scope constraints, unchanged or narrowed by the ScopeRule you supply for that key (audit.ScopeRules{"limit": audit.NumericAtMost} for a limit). An auditor thus confirms a sub-agent's authority descends, unbroken and never widened, from a root principal each hop signed. Runnable end to end in examples/govern/delegation; the delegation guide states the rules in full.
Attenuation by default. AttenuatingSubAgent wires this into the sub-agent seam so narrowing is the default, not something the caller remembers to do. Bind the acting grant and signer once at the root with WithGrant; then each delegation through the tool mints a narrower child grant (linked to the parent, expiring no later, checked with CheckAttenuation before it is signed, and anchored as a leaf of the call's own sub-run), rebinds the sub-run's identity to it, and propagates it so a deeper delegation narrows again. With no grant on the context it is a plain sub-agent that inherits identity, so it is safe either way. The wrapped sub-agent still runs its own full loop and reasons autonomously; only its authority shrinks. The result is that capabilities monotonically decrease down a delegation tree by construction, and the chain stays provable via VerifyDelegationChain.
Earned authority. audit.EarnedAuthority drives a grant's scope from the agent's track record: authority starts at a baseline rung, is promoted one rung after a clean streak (capped by the ladder's top), and resets to baseline the instant an anomaly is flagged. Each change re-issues a signed grant that is a child of the root (keeping the root's expiry and every root constraint), so the earned limit provably never exceeds the root ceiling (every earned grant passes VerifyDelegationChain with audit.EarnedRules, so even a buggy controller cannot widen past what the root principal authorized). A demotion takes the higher grant out of use at once: every issued grant is appended to a ledger run, and only the ledger's last leaf is current (ProveCurrentGrant / VerifyCurrentGrant against the ledger's latest signed head, which an offline verifier takes from the anchor log; the proof must name the ledger run, and must extend the last ledger head the verifier saw, so neither another run's leaf nor an older head passes as current). The asymmetry is the safety property: promotion is slow, capped, and evidence-gated; attenuation is immediate and ungated, because shrinking authority is always safe. It is deliberately a durable, sequential controller rather than a convergent machine, because earning is temporal and order-dependent (a promotion does not commute with a compliant action); the enforcement of the limit it sets stays a convergent gsm invariant on the work machine. Runnable in examples/govern/earned-authority.
Next
RFC 6962 is fully covered (Head, inclusion, consistency, STH) over both the journal and, via the event→audit sink (EventLog / Record / TreeHead / ProveConsistency), the semantic event stream (live via EventLog, crash-durable via EventLogFromJournal / agent.ReplayEvents, and on a separate lifecycle via the BYO EventStore port / PersistJournal), all sharing one verification surface. Continuous anchoring is done: AuditedStore auto-signs an STH per durable step and publishes it through the Anchor port to a reference external transparency log (MemAnchorLog) that is itself append-only and verifiable. Proof ergonomics are done too: a portable ProofBundle (ProveToolCall / ProveRecord / Verify), the bide audit CLI, and a stdlib-only standalone verifier (audit/verify).
Candidate extensions if a use case needs them, in rough priority:
Absence proofsDone (audit/absence.go): prove a thing did NOT happen (no charge, no approval for an ID) over an RFC 6962 tree of the run's sorted distinct keys.AbsenceRoot,ProveAbsent/VerifyAbsence, and the anchorableAbsenceBundle. Adapted dependency-free from the siblingmerkle-stratamodule, with one soundness correction: we verify the two bracketing neighbors are ADJACENT (consecutive indices), which merkle-strata omits, so a present key cannot be hidden between non-consecutive neighbors.- Stratified / grouped trees (
merkle-strata, MIT, stdlib-only): group leaves by step type or agent for O(groups) diffs and per-agent scoped verification/disclosure, useful at multi-agent scale. Note: this restructures the currently-flat RFC 6962 tree, so weigh it against the clean CT-compatible consistency proofs we already have; add alongside, do not replace, the linear tree. Anchoradapters against real external logs (Trillian/CT, a public ledger, a notary/timestamping service), and witness cosigning so a shared anchor's forks are detectable (only relevant if the anchor is a service you do not control).Batched/periodic anchoringDone:WithMinIntervalonAuditedStoreandAuditedEventStore(above).- Journal compaction with proof continuity (design note: compaction): seal a closed prefix into a signed checkpoint plus a deterministic state snapshot, carry the previous root forward as the next segment's first leaf, and drop the sealed raw records. Proofs survive the boundary via a signed checkpoint chain; the load-bearing invariant is that only a closed prefix may be sealed, so at-most-once is never broken. Not implemented.
- Pinned cross-language canonicalization so non-Go verifiers can reproduce leaf bytes (today a leaf is
agent.EncodeRecordof the record, which is exactly the bytes every store persists and is pinned by golden tests, and a record with invalid UTF-8 in a string field is refused, so leaves are injective; but the encoding is specified by its Go implementation rather than a written wire format).