Architecture

Agent reasoning                     (not ours)
      │  "I want to do X"
      ▼
┌──────────────────────────────┐
│           CTRLRun            │
│  normalize → decide →        │
│  approve → reserve →         │
│  execute → resolve → record  │
└──────────────────────────────┘
      │
      ▼
Real-world effect                   (not ours either)

function call (kwargs)
      │
      ▼
   ACTION  ──────────── canonicalize ──► action_hash
      │
      ▼
   POLICY  ──► ALLOW / APPROVE / DENY        (unknown → DENY)
      │              │            │
      │              ▼            └──► receipt(denied)
      │        approval request
      │              │
      │        human grants (bound to action_hash)
      │              │
      ▼              ▼
   consume approval + reserve effect         (one transaction)
      │
      ▼
   EXECUTING ──► executor runs
      │
      ├── returns            ──► COMMITTED
      ├── raises NotExecuted ──► FAILED     (retry permitted)
      └── raises anything    ──► AMBIGUOUS  (retry refused; human resolves)
      │
      ▼
   RECEIPT + events

effects(
  effect_key TEXT PRIMARY KEY,
  state TEXT NOT NULL,
  action_id TEXT NOT NULL,        -- current/last attempt
  attempt INTEGER NOT NULL DEFAULT 1,
  lease_expires_at TEXT,
  result_json TEXT, error TEXT,
  created_at TEXT, updated_at TEXT
);
approvals(
  approval_id TEXT PRIMARY KEY,
  action_hash TEXT NOT NULL,
  status TEXT NOT NULL,           -- pending|granted|denied|expired|consumed
  action_json TEXT NOT NULL,
  approver TEXT, created_at TEXT, granted_at TEXT, expires_at TEXT, consumed_at TEXT
);
receipts(receipt_id TEXT PRIMARY KEY, action_id TEXT, effect_key TEXT, result TEXT, json TEXT, ts TEXT);
events(event_id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT, type TEXT, action_id TEXT, effect_key TEXT, approval_id TEXT, data_json TEXT);
delegations(                      -- v0.3; a new table, which is why v0.3 needed no migration
  delegation_id TEXT PRIMARY KEY, -- "dlg_" + 32 hex
  parent_id TEXT NOT NULL,        -- a root grant's id, or another delegation_id
  depth INTEGER NOT NULL,         -- recorded, never trusted: evaluation walks to the root
  grant_json TEXT NOT NULL,       -- the child grant; `state.py` stores the string, `authority.py` parses it
  created_by_agent TEXT NOT NULL, created_by_user TEXT,
  created_via TEXT NOT NULL,      -- api|cli: an act, or an assertion at a terminal
  created_at TEXT NOT NULL, revoked_at TEXT, revoked_by TEXT
);
schema_version(                   -- v0.6; SPEC-v0.6 §3. Applied migration ids, RECORDED and
  migration_id TEXT PRIMARY KEY,  -- never inferred: `PRAGMA table_info` answers "what is
  applied_at TEXT NOT NULL,       -- there", which is not "what has been applied", and the two
  ctrlrun_version TEXT NOT NULL   -- diverge the moment a migration does a backfill or a repair
);
receipt_chain(                    -- v0.6; SPEC-v0.6 §6.3. One row. The chain head, so that
  id INTEGER PRIMARY KEY CHECK (id = 1),  -- truncation at the END is detectable: deleting the
  seq INTEGER NOT NULL,           -- last N receipts leaves an internally consistent chain, and
  hash TEXT NOT NULL              -- only a head naming a seq no row carries catches it
);
-- and `receipts` gains `seq`, `prev_hash` and `hash`, NULL for every row written before the
-- chain existed. `0002_receipt_chain` does not backfill them (SPEC-v0.6 §3.7).