Documentation
¶
Overview ¶
Package sample writes a journal of runs in every state the bide view run list tells apart, driven by the real runtime on scripted models and fake tools (no API key, no network, no hand-written records), with the evidence, keys and flow configs that go with it. It is the journal behind bide sample, behind the run viewer guide's screenshots, and behind the runview and cmd/bide tests, which read it back through each store:
bide sample -out sample bide view -db sample/sample.db
The runs are agent refund runs (completed, halted with an unknown outcome, halted and then resolved, waiting at a 2-of-3 approval gate, approved with signatures, in progress, cancelled), a saga that aborted, a run made of durable steps only, and plan flow runs (completed on the graph path, waiting at a gated node, approved, halted). Where a crash is part of the story, one write is lost.
The output is deterministic except for salts: the same runs, IDs, states, kinds, start times and record sequence on every call, and the same keys and decisions' signatures. The runs take their times from a fixed clock (agent.WithClock), and the keys come from fixed, public seeds (sample keys: never use them for anything real). Three things the runtime stamps from the wall clock are fixed at the store the runs write to: an attempt marker's attempted_at, and a plan flow's started_at, its gates' approval-request and approval-pending recorded_at and its run:complete's recorded_at (plan has no clock option). Every record carries a random salt (and an attempt marker a random claim ID), which the sample leaves random, as the runtime draws them; so the digests over salted records (the Merkle roots of the signed tree heads, and the evidence packages that hold them) differ between calls. Compare two calls with Unsalted. Only the live run (Live) uses real time.
Index ¶
Constants ¶
const LiveRun = "refund-live"
LiveRun is the ID of the run Live drives.
Variables ¶
Base is the start of the first run; each run starts seven minutes after the one before.
var Flows embed.FS
Flows are the sample's flow configs (flows/*.yaml): refund-v1 (the gate needs 2 of 3, and four assertions hold), refund-v2 (the gate needs 1 of 3, a weakened approval policy), and refund-bypass (a vip arm skips the gate: a violated assertion).
Functions ¶
func Live ¶
Live drives one more refund run, LiveRun, in real time against s, so a page following it (bide view, live mode) can be watched: the run starts and its first model turn is held, it takes the lookup, pauses at the 2-of-3 gate, gets the two signed approvals one pace apart, refunds and completes. Each step takes about pace. Unlike Write it uses the wall clock and real randomness, so its records differ from run to run; it returns when the run completes or ctx is done.
func Unsalted ¶
Unsalted is an entry's bytes without what the runtime draws at random: the record's salt and an attempt marker's claim ID. It is what two calls of Write agree on.
func WriteNotifyTrail ¶ added in v0.17.0
func WriteNotifyTrail(ctx context.Context, j *agent.Journal, es audit.EventStore, prefix string) error
WriteNotifyTrail runs the real notifier's catch-up sweep (agent.NotifyPending) twice over the sample's journal, with a scripted sink and a fixed clock, and so writes the notification trail the Needs attention list reads, into es. The first sweep, at 10:10 UTC on the sample's first day, is acknowledged for every event it sees except the halted refund-1042, whose sink refuses it: that delivery is failing. The second, at 10:40, finds the 10:10 refund-1042 event past its 5-minute deadline (overdue) and sees the halted flow node of triage-3003 for the first time, whose sink refuses too (failing, not yet overdue). prefix is the one given to Write.
What it records is deterministic but for the random salt each trail record carries.
Types ¶
type Result ¶
type Result struct {
Runs []Run
// LogPub is the public key the evidence is signed with, as bide audit -pubkey takes it.
LogPub string
// ApproverKeys is each approver's public key text, the file bide view -approver-keys reads.
ApproverKeys map[string]string
// Evidence is the evidence package of each run it was exported for, by run ID: the completed
// refund run, and the approved one with its gate's signatures.
Evidence map[string]audit.EvidencePackage
}
Result is what Write made besides the journal.
Source Files