Skip to content

Architecture ​

How the runtime is put together is in the design doc; the vocabulary is in Concepts; the module split is in module structure. This page is the map of the source.

Reading the code ​

Test files sit next to the code they test, as Go convention has it, in the same directory with a _test.go suffix, named for the area they cover. The lists below name the source files to open first, in reading order.

The core path ​

A run is a sequence of journaled steps. Read in this order: the journal, the step that memoizes one operation, the claim that keeps a side effect at most once, the lease that keeps two drivers off one run, the loop that drives it, the approval gate and the check before a gated call executes, the notifier that tells a person, and the audit log that proves afterwards what happened.

  1. Journal and step: journal.go (the Store port and the Journal the engine writes through), record.go (what one journal entry is), step.go (Journal.Step, named-step memoization), keys.go (the rules that keep journal keys apart).
  2. Claims and leases: attempt.go (the attempt marker: an exclusive claim before a side effect), lease.go (run leasing, so one node drives a run), halt.go (a non-idempotent call whose outcome is unknown halts; ResolveHalt settles it).
  3. The loop: loop.go (the single loop behind Run and Stream), runapi.go (Run, Resume, Stream, RunTyped), recovery.go (Recover and RecoverLoop re-drive unfinished runs), pause.go (Sleep, Interrupt, Signal/Await, the durable pauses).
  4. Approvals and the exec gate: approval.go (the m-of-n gate's data model and policy check), toolexec.go (tallying decisions and calling the tool), exec_gate.go (the re-check, immediately before the call, that the gate still holds), deadline.go (approval timeouts).
  5. The notifier: notify.go (public surface), notify_engine.go (delivery, claims on events), notify_record.go (the record vocabulary of the trail), notify_route.go (routing and escalation), then the webhook sender in notify/webhook.go.
  6. Audit log and proofs: audit/audit.go (the hash-chain head and signing), audit/merkle.go (RFC 6962 trees over the journal), audit/sth.go (signed tree heads), audit/proof.go (ProofBundle), audit/anchor.go (what turns integrity into tamper-evidence).

agent ​

The core package: the engine, the Run API, the approval gate and the notifier. Open first:

Then, by topic: compensate.go and saga.go (undo), parallel.go (durable fan-out), session.go (multi-turn), subagent.go, replay.go, identity.go (who acted, for whom), and the approval_*.go, gate_*.go and notify_*.go families. The agenttest and storetest directories hold test helpers and the conformance suite a Store must pass.

audit ​

Turns the journal into evidence a third party can check offline. Stdlib only. Open first:

Then: grant.go and delegate.go (signed grants, delegation), earned.go, the identity_*.go and cert_*.go files (certificate-bound approvers), the notify_*.go files (verifying the notification trail), eventstore.go (the event-trail port), and the subpackages verify, crlrefresh and rfc3161.

plan ​

Handle-based flow builder that lowers to the same journal. Open first:

approvals ​

The intake an application serves so approvers can decide on gated calls. approvals.go (the handler and its package doc), limiter.go (rate limiting), page.go (the static approve page; its sources are in page).

notify ​

Webhook notifier. webhook.go (the sender and package doc), payload.go (the v1 payload), sign.go (request signing headers), tlsconf.go (client certificate reload), probe.go (testing a receiver), and the relay subpackage (relay.go, slack.go, pagerduty.go).

store ​

Each store is its own module and implements agent.Store (and the event-store port from audit).

govern ​

Governed multi-agent state on gsm. govern.go (the package doc and entry points), quorum.go (k-of-n voting), federated.go (federated events), confluence.go (the convergence certificate). Event logs for it: sqlitelog, postgreslog, redislog, each one file plus its module files.

flowedit ​

The engine behind bide edit. engine.go (the package doc and edit engine), ops.go (the closed set of edit operations), ops_structure.go (add, remove, rename and move a node, the entry, wiring order, the flow's name and types), engine_swap.go (exchange two neighbouring list items, and check it), ops_wiring.go (edges, switches, arms and else), ops_join.go (joins and loop bounds), verify.go (checks an edit changed only what it should), baseline.go (does an edit weaken the flow), save.go (preview and atomic save), server.go (the local HTTP page), view.go and render.go.

anchor ​

Where signed heads are published so the journal's operator cannot rewrite them. The SDK-free part is audit/anchorobj (anchorobj.go: the object layout, body and the checks a Reader makes; loaddir.go: reading a downloaded copy; suspect.go: the tripwire for run IDs that look like personal data). Two modules build on it, each its own module so its cloud SDK stays out of the core: anchor/awss3 (S3 Object Lock: anchor.go publishes, reader.go reads back and audits the bucket's configuration, kmskey.go checks a KMS key reference, iam holds the policies) and anchor/gcs (Cloud Storage with a locked retention policy: anchor.go, reader.go, store.go for the Store interface the package uses and its IAM permissions, sdk.go for its Cloud Storage adapter). The bide-anchor command, cmd/bide-anchor (main.go for verify, export and check; backend.go and backend_gcs.go for -backend s3|gcs), reads either.

internal/runview ​

The run viewer, the diff and config pages, and the pages bide check -diff serves; cmd/bide calls it as bide view. cli.go (flags and startup), server.go (the HTTP handlers and JSON endpoints), graph.go and svg.go (the server-drawn flow graph, shared with the editor), diff.go and config.go (the diff and config pages), attention.go (the needs-attention list), live.go (live mode), and assets (the page's HTML, CSS and JavaScript, embedded). The stylesheet's colours, fonts and spacing come from theme through themefs.go.

theme ​

The theme layer of the visual pages, and a public package (0.x) so a Go program can build and check a theme and hand it to planview or flowedit. theme.go (the theme file: parsing, strict keys, a shipped base plus overrides), check.go with color.go (contrast, colour distance, colour-blindness and polarity checks), css.go (checked themes to the one generated stylesheet), fonts.go (the fixed font list), load.go (reading a theme file), register.go (hands the stylesheet generators to internal/themeaccess, so only the module's own servers can call them), internal/themecmd (bide theme check) and themes (the shipped light, dark and high-contrast JSON). The rules and the format are in Themes and its design note.

cmd/bide ​

The bide command. main.go (dispatch), full.go (commands that need a store driver; the bide_audit_only build uses auditonly.go instead), view.go (the run viewer). Each subcommand's implementation is a package under internal, for example approvecmd, editcmd, migratecmd and notifycmd. The reference for every command is reference/cli.md.

Apache-2.0 licensed.