Skip to content

The durability guarantee ​

This is the precise statement of the core guarantee (guarantee 1 in the README). README and marketing assert it; this document specifies it, including exactly where it stops.

What the guarantee is ​

Every step that completed is durably recorded before the run depends on it, and on restart the run resumes from that record instead of redoing completed work. A non-idempotent side effect is never executed a second time.

The unit of protection is the journaled step. The moment a step's outcome is written to the store, it is safe: resume replays it from the journal rather than re-running it.

The three cases when a crash hits ​

  1. Crash before a step ran → nothing recorded → resume runs it fresh. Correct.

  2. Crash after a step ran and its result was journaled → resume reads the result, skips re-execution. Correct.

  3. Crash in the gap (the side effect fired but its result was not journaled yet) → this is the dangerous window every other system re-runs into (the double-charge). Bide wrote an attempt marker before firing, so on resume it sees "this non-idempotent thing was attempted, outcome unknown" and halts (OutcomeUnknown) instead of guessing. It does not silently re-run, and it does not silently assume success.

    The gap between writing the marker and calling the effect is not dangerous when the process survives it: a driver cancelled there (a shutdown, a lost lease, a sibling's failure) or whose store fails there does not call the effect, and records that the attempt did not start. That attempt then no longer halts a resume, and the effect is attempted again under a new marker, claimed exclusively like the first. A process that dies in that gap records nothing, so its marker halts as in case 3.

    A tool timeout (WithTimeout) is treated the same way. A call that returns a result is recorded even after its deadline, since the outcome is known. A side effect that returns an error after its deadline may have been cut off after its effect took place, so nothing is recorded, the drive fails with ErrToolOutcomeUnknown, and a resume halts as in case 3. A retry-safe tool records that error instead (in a saga, SagaAborted.UnknownOutcome names it). "After its deadline" is judged by the deadline itself, not only by the context's error, whose timer can lag; the run's own deadline is judged the same way. Only a call whose tool was actually called is judged so. "Not called" needs positive proof: the base handler refused the call, or the middleware chain returned without entering it and said so with ErrToolNotCalled. Such a call fails as a known error, or, if the run itself was cancelled, records its claim as never started. A chain that returned an error without entering the base handler, and without ErrToolNotCalled, may have reached the tool some other way, so a side effect's outcome is unknown and a resume halts; the base handler refuses any invocation that comes after the chain returned, whether the call was refused before or never entered. "Failed" needs positive proof too: when the tool began and did not itself fail, but the chain returned an error (a middleware turned the tool's success into an error), a side effect's outcome is unknown: nothing is recorded, the drive fails with ErrToolOutcomeUnknown, and a resume halts. A retry-safe tool records that error, except a saga step that changes state (Idempotent, not ReadOnly), which is recorded with an unknown outcome and named in SagaAborted.UnknownOutcome. Such a step writes no attempt marker; when it is compensable, its journaled arguments mark that an attempt may have begun, so a later known failure of a step an earlier drive began is recorded with an unknown outcome too, as is one a middleware ran again after an invocation that did not itself fail. A result needs positive proof as well: a chain that answers while any invocation of the call's tool is still running in the process (a middleware that left next running, a sibling invocation, one a cancelled drive left behind) has an unknown outcome, and no invocation begins the tool once the chain has returned, so a side effect halts and a retry-safe saga step is reported in SagaAborted.UnknownOutcome, never compensated before its effect lands. A rollback that re-runs such a step to learn its result reports a re-run whose outcome is unknown the same way.

The same holds when nothing crashed and a caller simply invokes the run again (a client retrying after a lost response, a redelivered job, a sub-agent or session turn re-entered on resume):

  1. Re-invoking a finished run → the run's completion marker is journaled → it returns the recorded final answer without asking the model for another turn (to a drive with the input it answered; another input is ErrConfig). Correct. This matters because the protection is keyed by the tool call the model emitted: a fresh model turn could request the same side effect again under a new call id, which the journal would treat as new work. A crash after the final answer was journaled but before the marker was written is handled the same way: the resumed run finishes with the recorded answer and writes the marker, without a model call.

Case 3 is the whole moat. The precise phrasing is at-most-once: the side effect fires zero or one times, never twice. It is not "exactly-once": an unresumable crash in that window can leave it having fired once but unconfirmed, and the system stops for a human/policy decision rather than pretending it knows.

What a resume reads from the journal, and what it reads live ​

A resumed run decides from its journal, never from configuration that may have changed since. What the journal holds, and so what a resume cannot be talked out of by a redeploy:

  • every model turn and tool result, each call's attempt marker, and every approval decision (a recorded denial or expiry is final even if the tool's gate is removed later) and terminal m-of-n tally, and the deadline of a gate with a timeout, fixed once (approval-deadline:<call>);
  • signals, interrupt answers, timer wake times, AwaitFor outcomes, channel messages and acks, and WithRetrieval documents;
  • the run's input (a message, images included) and whether it runs as a saga (run:start), and for a session turn the transcript it started from; an unfinished run resumed with another input, with WithSaga() when it is not a saga, or as typed when it is untyped (or the other way round), is ErrConfig, and so is a completed run driven with another input; a saga's later drives run it as a saga whether or not they pass WithSaga();
  • the per-run options its first caller passed (run:start, see agent.RunStart): the turn limit and token budget, the system prompt, sampling, tool choice, the tool filter, a typed run's output mode and answer schema, and the principal (OnBehalfOf, AuthorityRef). Every later drive, Resume and a recovery drive included, runs under them; a later drive's different limit is journaled as an amendment (run:limits:<n>) and binds the drives after it; any other different setting is ErrConfig, before any model call. The tool filter is enforced when a call is dispatched: a call outside it is refused with an error result recorded, and its tool never runs;
  • a run's end: run:complete, run:aborted (a saga's finished rollback) or run:cancelled (agent.Cancel, or a cancelled saga's finished rollback). The first in journal order is the run's end for every reader. After Cancel returns, no side effect fires under a claim won after it, in the run or anywhere in its tree (a sub-agent's run, a SubRunFor run, a delegation, which read the root's cancellation), nor in a plan flow's run; calls already past their check finish, and a retry-safe call already dispatched in the current turn may still run;
  • in a saga's rollback, which calls completed, failed, or were attempted, and the Safety and approval gate each completed call ran under (Record.Safety, Record.Approval): a completed write is rolled back even if its tool was relabelled ReadOnly since, and a call whose tool is no longer registered is reported uncompensated (or halts, if it was attempted with no result);
  • the requesters an approval gate with ExcludePrincipal excludes: the run's principal and those of the runs above it, in run:principal (agent.RunPrincipal) and run:start, for a flow run as for an agent run (a flow run journals the identity Flow.Run is given with WithIdentity, or the one its context carries, and a run started inside another's drive records that drive's chain). The gate reads them from the journal on every evaluation, so a redeploy or a later drive cannot change who may not approve; a gate that excluded the requester journals them in its terminal tally, and an offline audit recounts from the proven run:principal, which holds nothing of the run's input;
  • for a flow (plan), its flow name and input (run:start, kind flow), its topology digest, each switch's choice, and each node's attempt marker (a node runs as an agent.Journal.Step, so a node attempted as a side effect halts on resume even if it is relabelled retry-safe since); a flow run resumed with another input or flow, or driven by an Agent, is ErrConfig; a finished flow run records run:complete with its output, which a later drive returns.

run:start also records when the run's first drive started (started_at, RunStart.StartedAt: UTC, RFC 3339 with milliseconds, by the drive's clock). It is informational, for listing runs: no drive, resume, recovery pass or at-most-once check reads it, a drive is never held to it, and a run whose run:start holds none (written by an earlier version) or another value resumes the same way. run:aborted likewise records when a saga's finished rollback ended the run (aborted_at, in the same format, by the drive's clock, beside the reason as reason), also informational; a run:aborted an earlier version wrote is the reason alone and loads and behaves the same. The records that resolve something a person was told about each note when they were written (recorded_at, Record.RecordedAt: UTC, RFC 3339 with milliseconds): a single approver's decision (agent.Approve), an interrupt answer (AnswerInterrupt) and a signal (Signal), the result agent.ResolveHalt injects, a run's end marker (run:complete, run:aborted, run:cancelled) and a saga's rollback request (run:cancel-requested). The time is the claim of the process that wrote the record, by agent.WithClock where the call takes it (Approve, ResolveHalt, Cancel, AnswerInterrupt, Signal), else the run's clock, else the wall clock (ResolveHalt takes WithClock, else the wall clock: it is not a drive of the run, and its claim marker and WithMinHaltAge use the same clock); the first write sets it and a repeated call keeps it. Nothing signs it (the resolver of a halt, unlike an m-of-n approver, holds no key) and the Merkle trail anchors it once a signed head covers the record. It is informational like started_at: no drive, gate, claim, replay, resume or recovery pass reads it, and a record written before it existed has none, which readers report as absent (agent.Status reports EndedAt empty), never filled in. A tool result a model-driven call produces carries no time: its attempt marker's attempted_at says when the effect was tried (wall clock), and the marker's recorded_at says it on the clock the run was driven with. The journal's other wall-clock times are each attempt marker's, the deadlines a run sets itself (a timer's wake time, an AwaitFor deadline), and an approval gate's display times: when the run paused at the gate (ApprovalWait.RecordedAt) or recorded a flow gate's request (ApprovalRequest.RecordedAt) and, on each signed m-of-n decision, when the approver decided (decided_at, by the approver's clock, inside the signature) and when it was journaled (recorded_at, by the submitting process's clock: its claim, not signed, anchored by the Merkle trail once a signed head covers it). A gate without a timeout never reads those: it checks decided_at only as signed bytes, orders decisions by journal position, and counts the same whatever the times say. A gate with a timeout (ApprovalPolicy.Timeout) reads the request time, which fixes its deadline once, and a decision's recorded_at; the run's clock says whether the deadline has passed. Its expiry is the gate's outcome, recorded insert-once under the name a passing tally or a single decision would take, so an expiry and a pass cannot both be recorded: whichever outcome is recorded first stands. A gate that expired never runs its call (the model reads agent.ExpiredResult; a plan flow returns plan.ErrApprovalExpired), and a decision recorded after the deadline, or written after the expiry was recorded, is shown as not counted and does not count (agent.ReasonLate, agent.ReasonAfterExpiry), even if its signed decided_at is on time (decided_at is the approver's clock and does not decide it). Skew between the run's clock and a deciding process's moves the edge by the skew (deadlines).

Configuration is live by design: it governs what a drive does next, not what the journal already says happened. A drive uses the configuration it is given for:

  • the agent's own system prompt (WithSystemPrompt given to New, and WithSystemPromptFunc, which is called once by each drive that sends the model a request, before its first one), sampling and tool choice, where the run journaled none of its own, and the response format, the model, and model middleware, for the turns that drive makes. Each model turn journals what it was given: digests of the system prompt and the tool set it was sent (Record.PromptDigest, Record.ToolsDigest), the model that answered (Record.Model), and its finish reason, so an audit can tell which configuration produced each answer;
  • the tool set offered to new turns, and each tool's spec (Safety, approval gate, timeout, read once when the agent is built) and tool middleware for a call that has not run yet (a pending call to a tool no longer registered fails with ErrUnknownTool);
  • the approval gate for a call with no recorded denial or expiry, under the gate's current policy (but not its deadline, once recorded: a redeploy that changes Timeout does not move a gate already waiting);
  • the agent's WithMaxTurns and WithTokenBudget limits, where the run journaled none of its own, compared with the turns and tokens the journal records, so raising a limit lets a stopped run continue (a journaled limit is raised by a later drive's amendment);
  • the clock (WithClock), for whether a timer, an AwaitFor deadline or an approval deadline is due and for WithMinHaltAge;
  • the identity's Actor and the grant the drive is given (the WithIdentity option, or the run's context), which the tools a drive runs see, with the principal the run journaled;
  • a governor's policy (govern): governed state is the shared event log replayed under the current machine.

The boundary conditions (where the claim stops) ​

  • The store must survive the crash. Durability is inherited from the journal's backend. If you use the in-memory store and the process dies, there is nothing to resume from: that is a dev/test store, not a durability claim. SQLite / Postgres / etc. is where the guarantee actually lives, and only as far as that storage's own durability (fsync, replication) holds.
  • A taint policy adds a check point, not a guarantee against injection. With agent.WithTaintPolicy, a side-effecting call of a tainted turn is held at the same place as the tool's own gate, before the attempt claim, until the escalation gate (the instance <call>#taint) has passed or the call is refused; a call that waits has no marker, and at-most-once is unchanged. What it does not give is in the untrusted content guide.
  • The write to the store must itself be atomic/durable. The guarantee reduces to "the journal did or did not record this step"; it relies on the store committing atomically. It does not defend against the storage layer lying about a commit.
  • Two drivers of one run. Leases normally keep one process driving a run, but no lease can guarantee that: a holder stalled past its TTL (a long GC pause, a suspended VM, a partition) wakes still driving. The guarantee does not rely on the lease. Before a non-idempotent side effect, a driver writes the attempt marker as an exclusive claim, and only the driver whose claim the store kept runs it; the other halts (OutcomeUnknown, cause HaltContended). This relies on the store recording a step name at most once across processes (the SQLite and Postgres stores use a primary key), which is the atomic write above. Leases are deliberately not fenced (no token that the store checks on each write): the side effect happens outside the store, where no token could be checked, so only a claim written before the effect can stop a second one; see known limitations.
  • The journal must be in a format this version reads. Every run's journal starts with a header naming its journal format (agent.JournalFormat), written before the run's first record. A version refuses, before reading or writing anything, a run whose header names a format it does not support, or whose journal has no header first (one written before the header existed), with *agent.JournalVersionError. So an older binary never adds records to a run a newer one started, and no journal is read under rules it was not written for. Before 1.0 every release writes the one dev tag bide.journal.v1-dev, which is not bumped when the keys or the record shape change between pre-releases, so resuming a run across pre-releases is not guaranteed (see known limitations). 1.0 writes bide.journal.v1 and refuses every pre-release journal.
  • The tool must declare its safety accurately. ReadOnly re-runs freely, Idempotent retries, and only an unmarked non-idempotent write gets the attempt-marker/halt treatment. Mislabel a card-charge as idempotent and you have opted out of the protection. A call keeps the safety it fired under: the attempt marker is written only for a call that was not retry-safe when it fired, so a resume halts on a marker without a result whatever the tool is declared as by then (relabelled retry-safe, or no longer registered at all), and a Step attempted as a side effect halts even if the resuming code passes a retry-safe WithSafety. The marker needs no new field for this, so markers written by earlier versions are read the same way: every one of them means "not retry-safe, halt", unless the driver that wrote it recorded that its attempt never started. A completed call's result records the Safety it ran under, so a saga rollback compensates (or lists as uncompensated) a write whose tool was relabelled ReadOnly since. The one case not covered: a call that was retry-safe when it fired writes no marker, so if it is cut off with no result and its tool is relabelled a side effect before the resume, the resume runs it again and a rollback treats it as never started.
  • It is at-most-once for the side effect, not "the agent always finishes." A crash can still leave a run halted and needing intervention. The promise is safety (no double-fire, no lost completed work), not liveness (guaranteed completion without help).

A stop ​

A kill switch (guide) holds covered runs as a pause. It adds no way for a side effect to fire twice: a stop never writes an attempt marker, never clears one, and never starts a call. It can only record, on a claim it won and that provably never began, that the attempt did not start (the same record a cancellation writes). A call that had begun when the stop was read finishes and is journaled; a marker with no result halts for its outcome before, during and after a stop and its lift. What a stop does not guarantee is timing: a stop is seen by a call about to begin as soon as the store shows it (and within the poll interval by the other checks), and a call past its last check is not stopped. Model 16 checks these rules within its bounds; it does not model the staleness bound in time.

The one-sentence version ​

Not "it can't crash," and not even "it always recovers automatically." It is: when it crashes, you never lose completed work and you never double-execute a side effect, and in the one genuinely ambiguous window it stops and tells you instead of guessing.

Apache-2.0 licensed.