Concepts
Bide is a Go framework for AI agents that move money: risky calls approved, every action recorded and verifiable. It rests on crash-safe execution (a side effect fires at most once), people in control (signed approvals, separation of duties, notifications), and proof of everything (a verifiable audit trail). The vocabulary, defined once. Terms are grouped by the layer they belong to. See the docs index for the guides that use them.
The durable core
- Journal: the append-only log of a run. Every model turn, tool result, and durable step is a named record. Replaying the journal reconstructs the run's state, which is how resume works.
- Step: one named, memoized unit of work (
Step, or the internal tool-result record). A step runs at most once per run: on resume a recorded step returns its stored result without re-executing. - At-most-once: a non-idempotent side effect (a charge, an email, a physical actuation) fires at most once, even across crashes. On an unknown outcome the run halts rather than risk a repeat. Contrast at-least-once systems, which re-run and require idempotent steps.
- Resume: re-invoking
Runwith the same run ID replays the journal and continues from where it stopped. - Pause: the sealed error a run returns when it stops durably and waits:
*ApprovalPending,*InterruptPending,*SignalPending,*TimerPending,*Stopped(a kill switch holds the run) or*OutcomeUnknown.IsPause/AsPausedetect one through wrapping; it is not a failure, and the run resumes when re-invoked withPaused().RootRunIDonce the condition is met. - OutcomeUnknown: returned when a non-retriable side effect was started but its outcome was never recorded. The run stops for confirmation instead of guessing. Its
CauseisHaltCrashed(a marker with no live claimant known) orHaltContended(another driver won the claim and may be running the effect). - Reconciler: what clears an
OutcomeUnknownwithout a human. Most non-idempotent effects still leave a queryable record (a sent-message id, a row); a reconciler queries it, decides, and callsResolveHalt(ctx, journal, halt.Ref(), outcome).WithMinHaltAge(d)refuses to resolve a halt younger thand, measured from the live attempt (a provider's record can lag the send), returningHaltTooYoungso the caller waits, and aHaltContendedhalt is resolved only with it (where it stands in for the live-driver check,dmust cover the tool's real worst-case run time, not itsToolSpec.Timeout: a late result is still recorded, and a tool that ignores cancellation runs past the timeout; the lease check is unaffected); it also refuses while a driver holds the run's lease (HaltInFlight), or, on a store that cannot lease runs, withoutWithMinHaltAge(unlessWithoutLiveDriverCheck);WithEvidence(v)marks the injected resultReconciledand journals what was read to decide, so a reconciled outcome stays distinguishable from a clean one. - Safety: a tool's declaration of how it may be retried on an unknown-outcome resume, as plain data:
ReadOnly(no side effects, always safe) andIdempotent(safe to repeat: the tool de-duplicates downstream itself, with a key it derives orNextOnceKey). The zero value is a side effect. Each call's result journals the Safety it ran under, and a saga rollback reads that record. Maps onto MCP tool annotations. - ToolSpec: everything the agent knows about a tool: name, title, description, input and output schemas,
Safety,Approval(a human gate, set withWithApproval) andTimeout(WithTimeout). The agent reads a tool's spec once, when the tool is registered (itsSpec()), and decides every call from that copy. Tool middleware sees it asToolCall.Spec. - Retry-safe tool: a tool that may re-run from the top on an unknown-outcome resume:
Safety.ReadOnlyorIdempotent. Pausing primitives (Interrupt,Sleep,Await) require one.
High availability
- Lease: a per-run lock so normally only one process drives a run at a time. A crashed holder's lease expires (by the store's clock) and another node takes over. A holder that stalls past its lease can wake still driving; its drive is cancelled with
ErrLeaseLost, and the attempt claim, not the lease, keeps its side effects at most once. - Recover: after a restart, re-drive in-flight runs, in one pass.
Listerenumerates a store's runs that hold no terminal marker (the store filters out finished ones), sub-agent runs (IsSubRun) and session runs (IsSessionRun) are left to the root run and the session that drive them, and the rest are handed, with theirrun:start, to aResumer(ResumeAgent,ResumeTyped,ResumeAny), which drives each under the options its first drive journaled. A run with norun:startis skipped and reported once per process. - Cancel and Status:
Cancelends a run withrun:cancelled(a saga is rolled back first, on arun:cancel-requestedrequest its drive answers);Statusreads a run's state (not started, started, completed, aborted, cancelled) from its journal, andRunStatus.EndedAtsays when the end marker was written, if it records a time. The first end marker in journal order is a run's end. - RecoverLoop:
Recoverrepeated for the life of a process, so a dead holder's run is taken over automatically once its lease expires.
Ambient and pauses
- Sleep / WaitUntil: durable timers. A run pauses until a wall-clock deadline, journaled so the pause survives a restart. They run inside an agent's tools; a plan flow node cannot call them yet (known limitations).
- Waker: the pluggable trigger that re-invokes a sleeping run when its timer is due (or when an event is delivered).
Schedule(ctx, Wake)returns an error; a failed schedule fails the run with an error wrappingErrStorageand records nothing, so a re-drive (RecoverLoop) schedules again.MemWakeris the in-process reference. - Interrupt / Resume: durable human-in-the-loop. A tool pauses the run to request a typed decision; recording the answer and re-running continues.
- Approval: a durable pre-execution gate. A tool built with
WithApproval(SingleApproval())(or an m-of-nApprovalPolicy) halts the run as*ApprovalPendingbefore it executes; recordingagent.Approveand re-running lets it proceed or skips it. Distinct fromInterrupt, which pauses inside a running tool to collect a typed value. See the approval guide; an approver decides from a terminal withbide approve(guide). - m-of-n approval: an approval gate that needs k signed decisions from a bounded, named set of n approvers (
ToolSpec.Approval, set withagent.WithApprovaland anApprovalPolicy). Each approver signsApprovalDecisionBytesover the exact call (run, call id, tool, canonical arguments) and the time they decided (decided_at, their clock, signed), and records it withSubmitDecision, which adds when bide recorded it (recorded_at); neither time affects the count. Each distinct decision is its own record, and an approver's first valid one counts (TallyApprovals, the rule shared by the gate and the auditor), so a forged or mistaken record never locks an approver out. A seat is a key: the gate refuses, withErrConfig, a policy two of whose approvers' verifiers report one key identity (ApproverVerifier.KeyIDs). WithExcludePrincipal(separation of duties) no requester fills a seat: the run's journaled principal (OnBehalfOf, in itsrun:principal) or that of any run above it. The gate proceeds at k approvals, denies once k is unreachable, and otherwise pauses with the runningApprovalTally; at the outcome it records the tally, including the policy it enforced and every decision it read.audit.ApprovalEvidenceexports the request, decisions, tally, and result, andaudit.VerifyApprovals(orbide audit verify-approvals) checks offline that k named approvers approved this call before it ran, detecting an omitted decision, a recount mismatch, or a different enforced policy. - Separation of duties:
ApprovalPolicy.ExcludePrincipalmakes an m-of-n gate never count a decision by a requester of the run (its journaled principal, or that of any run above it, compared ignoring ASCII case). The excluded decision is recorded and markedReasonRequester; it fills no seat. Bide compares ids; it cannot see that one person holds two of them. See the approval guide. - Approval deadline:
ApprovalPolicy.Timeout(timeout:in a plan config'sapprovalblock) gives a gate a deadline, measured from its recorded request and recorded once (approval-deadline:<call>), so a redeploy that changes the timeout does not move a gate already waiting. A gate past its deadline with no terminal count records its expiry as its outcome, insert-once like a pass, so whichever outcome is recorded first stands and an expiry and a pass cannot both be recorded. The call never runs (the model readsagent.ExpiredResult; a plan flow returnsplan.ErrApprovalExpired), a decision recorded after the deadline is shown as not counted and never counts, andSubmitDecision,Approve, the approvals endpoint andbide approverefuse one (agent.ErrApprovalExpired). The notifier sendsapproval_expired. See deadlines. - Approval intake:
approvals.Handler, anhttp.Handleran application mounts so approvers can fetch a gated call and post a signed decision (bide approve -to <url>, or a browser page the organization hosts that signs with a non-extractable key). The handler verifies the decision against the recorded call and the approver's enrolled key and records it through the application's own journal; who may reach it is the deployment's job (WithAuth). See the approval guide. - Decision receipt:
audit.DecisionReceipt(formatbide.audit.decision-receipt.v1), the signed decision an approver keeps: the run, call, tool, arguments, approver, verdict and time, the signature, and where the journal holds the record (its name, position and when it was written), with no key material.Verifychecks it on its own;audit.CheckReceipt(bide audit verify-receipts) decides whether the signed tree heads of the journal commit to the decision, so a decision deleted before it was anchored is noticed. The intake returns one with each decision it records, andbide approvewrites one. See Audit. - Notifier: what tells a person that a run halted on an unknown outcome or waits at an approval gate (
agent.WithNotifier). The shipped delivery is a signed HTTPS webhook (notify.NewWebhook); events can be routed by kind or approver, escalated when not acknowledged by a deadline, and closed by aresolvedall-clear; an audited trail records each attempt and whether the sink acknowledged it, where an acknowledgement means the endpoint answered 2xx, not that a person read it. See notifications. - Kill switch: a durable emergency stop (
agent.StopControl,agent.StopSwitch,agent.WithStopSwitch). A stop covers every run, one tool or one agent; covered runs return*Stoppedbefore any side effect begins and resume when it is lifted. A call that has begun finishes; a held call writes no attempt marker (or records its claim as not started). Basic mode trusts store access; audited mode signs and needs a lift quorum. Operators set, list and lift stops withbide stop. See the kill switch guide. - Signal / Await: an external event delivered into a run, journaled at most once.
AwaitForraces a signal against a durable deadline. Ordered channels (Enqueue/Receive/Ack) give exactly-once streaming consumption. The guarantee: at-least-once transport in, exactly-once application. - Saga: a sequence of steps with compensations that run in reverse order on failure.
Governed state (Tier-2, gsm)
- gsm: the convergence engine underneath governed state. At build time it checks that concurrent agents applying the same events converge to the same valid state, against the conditions of a machine-checked convergence theorem.
Buildreturns a machine only after the table oracle, Go generated from gsm's machine-checked Rocq proof, re-checks it in-process, and for combinator rules inside its fragment and within a cost cap, the rules oracle re-checks it from the rules as well; a federation's own conditions, including the event-order checks C1 and C2, are checked by gsm's Go code. bide requires gsm v0.14.0; v0.13.0 added the C1 and C2 checks (v0.12.0 had neither), and v0.12.0 fixed theBuildgap of v0.11.0 for event guards and effects that read variables another event writes. Exact scope: known limitations. - Governed state: shared state described as a registry of variables, invariants, and events. The governor prevents, repairs, or halts on invariant violations.
- Convergence: order-independent agreement on the replayed state, certified at build time, not assumed.
CertifyConvergenceemits a portableConfluenceCertificate, re-checkable offline, which also records the delivery obligations gsm reports (undeclared pairs that need causal order, events that need deduplication). - Federation: multiple governed registries connected by morphisms, converging across boundaries (trees, multi-source DAGs, monotone cycles). A source is authoritative over its targets' shared components, which makes the federated repair terminate in a unique valid normal form; event order across registries is safe because
Federation.Buildchecks cross-registry CC (C1) and repaired CC (C2) and rejects a federation that fails either.
Accountability
- Threat model: what bide prevents, detects and does not address, by actor (threat model); key custody and retention are in the operations guidance.
- Merkle tree / STH: the audit spine. Records hash into a tree; a signed tree head (STH) commits to the whole log. Inclusion and consistency proofs are checkable offline.
- Signature scheme: what signs an STH, an evidence seal, a grant or an approver's decision, named by its
Alg:ed25519,ecdsa-p256(what most HSMs and cloud KMS can sign),ml-dsa-65, or theed25519+ml-dsa-65hybrid. Every artifact names its scheme and a verifier refuses a signature of another scheme. - Anchoring: publishing an STH to an independent log, which upgrades integrity to tamper-evidence against the operator. The shipped production anchor writes each head to an S3 bucket under Object Lock (anchoring), or to a Google Cloud Storage bucket with a locked retention policy (anchoring).
- ProofBundle: a portable proof that a specific record is included under a signed tree head. It carries the record as the bytes the journal stores for it (
record_bytes), which the verifier hashes without re-encoding. - Absence proof: a checkable proof that no record with a given key exists in the log (
ProveAbsent/VerifyAbsence), so "this never happened" is provable, not just unlogged. Completes the trio with inclusion and consistency proofs. - EvidencePackage: a whole run's evidence in one portable file: a signed tree head plus an inclusion proof per material action, and optionally the run certificate, grant chain, and consistency proof. Built with
audit.Evidenceand checkable offline withbide audit verify-evidence. The package is sealed by signing a fixed-size digest of itself (formatbide.audit.evidence.v6), so a signer with a message size limit, such as AWS KMS, can seal a package of any size; v5 packages still verify. - RunCertificate: a proof-carrying attestation of behavioral-property compliance over a whole run, checkable offline.
- Grant / delegation: a signed capability a sub-agent can only narrow (attenuate).
VerifyDelegationChainchecks the chain offline;EarnedAuthoritywidens scope from a clean trail. - Quorum: governed k-of-n agreement among voters, with the tally anchored and re-checkable offline.
- Key custody: where a signing key lives. An
audit.Signersigns without exposing its key, so the key can sit in a PKCS#11 token (an HSM), AWS KMS, Google Cloud KMS or Azure Key Vault and never in the application's memory or on its disk; verifiers hold only the public key. Ed25519 or ECDSA P-256 (Azure Key Vault has only P-256). An approver decides from a terminal with an HSM, AWS KMS, Google Cloud KMS or Azure Key Vault key throughbide-hsm approve, and gets its certificate request frombide-hsm csr. See key custody. - Selective disclosure: revealing some records while proving the rest exist, without showing their content. It limits what you reveal; it does not encrypt. See the security model.
- Flow / conformance: the
planpackage is an optional builder of plan flows over the same durable core. AFlowis a reified topology of durable steps, authored in typed Go or loaded from declarative config (plan.Load);TopologyandRenderMermaidexpose its shape, andConformchecks a run's journal against it, proving the run followed the declared topology or flagging where it diverged. See the plan flows guide.
Structure
- Footprint: the set of invariants (or variables) a tool or event can affect. Disjoint footprints commute, which is what lets governance verification stay local.
- Port and adapter: the core defines interfaces (
Model,Store,Tool,Anchor, ...); adapters plug in at the edges. The core carries no provider or infrastructure dependency. See extension points. - Tool-result codec:
provider.ToolResultCodec(packagemodel/provider, the kit adapters are built from) controls how a tool result is rendered for the model. The default (provider.JSONToolResultCodec) passes canonical JSON;codec/gcfencodes GCF (Graph Compact Format), a more token-efficient encoding for structured data, wired per adapter withWithToolResultCodec. It changes only what the model reads: the journal and audit trail keep the canonical JSON.