deadreckon
reference · 14

The filesystem & the receipts

Everything lives in plain files under ~/.deadreckon — run state, spend, traces, provenance, events — auditable on disk, not scrolled in a chat.

maps to as-built §5§14

plain files, all the way down · auditable on disk
Everything is a file under ~/.deadreckon A directory tree of the deadreckon home. config.toml holds your keys and defaults. A run in progress lives under runstate/scope/runs/id with its state.json, the working tree, per-turn snapshots, the gate nonce and signed acceptance marker, and four append-only receipt streams: spend.jsonl, traces.jsonl, provenance.jsonl, and events.jsonl, plus checkpoints and the live narrative. Accepted runs are promoted under library/scope/id with a manifest.json. Locks, plans, chains, and the learning history sit alongside. ~/.deadreckon/ all run state lives here └─ config.toml BYOK keys, defaults, fallback chain └─ runstate/<scope>/runs/<id>/ a run in progress └─ state.json the run state machine └─ working/ the tree being edited └─ snapshots/turn-N/ full tree, every turn └─ gate/nonce the secret only dr-gate reads └─ proofs/turn-acceptance.json the signed marker └─ spend.jsonl cost, per call └─ traces.jsonl every turn + tool call └─ provenance.jsonl file ↔ turn ↔ tool ↔ model └─ events.jsonl the run timeline └─ checkpoints/ · narrative/ flight recorder · live story └─ library/<scope>/<id>/ promoted, durable artifacts └─ manifest.json what was built, from what └─ locks/ · plans/ · chains/ · learning/ task locks, orchestration, history
No database, no daemon. The four receipts (spend, traces, provenance, events) are append-only JSONL you can read with your eyes.

There is no database and no background daemon. Everything deadreckon knows lives in plain files under ~/.deadreckon/, which means you can inspect, diff, back up, or delete any of it with ordinary tools.

A run in progress lives under runstate/<scope>/runs/<id>/: its state.json, the working/ tree, per-turn snapshots/, the gate's nonce and signed acceptance marker, and the live checkpoints/ and narrative/. When a run is accepted it is promoted to library/<scope>/<id>/ with a manifest.json. Task locks, orchestration plans, chains, and learning history sit alongside.

The four receipts are append-only JSONL, the audit trail:

  • spend.jsonl: what each call cost.
  • traces.jsonl: every turn and tool call.
  • provenance.jsonl: which call touched which file.
  • events.jsonl: the run's timeline of milestones.

That's the whole tour. A harness around your agent, a gate it can't fake, runs that survive anything, and an audit trail in plain files. Head back to the map to revisit any part.

source