Reasoning Ledger Records

Why I Built a Ledger That Can't Stop Anything

The hardest constraint to swallow when designing a reasoning ledger is that it must be powerless. Not advisory, not "softly enforced" — genuinely unable to block, veto, or gate the action it records. If the ledger can stop a deployment, it becomes part of the mechanism instead of an independent witness, and suddenly its own records can't be trusted as neutral fact.

Enforcement still has to happen somewhere real. It belongs at the policy and tool boundary, not inside the witness. The ledger's job is simpler and more important: it preserves that the boundary was evaluated and what it returned.

The Record That Survived a Dozen Design Debates

This started as a schema dump — here are the fields, copy them, done. That felt wrong immediately. Field lists are the least durable thing I could hand you. Names drift, implementations differ, and copying a record shape without its reasoning just produces cargo-cult structure that nobody maintains.

The durable thing is the set of design tensions that decide what belongs in the record and what doesn't. Get those right and you can derive the fields yourself. Get them wrong and no schema saves you.

Here's the baseline record we started with, which turned out to be incomplete in instructive ways:

reasoning_ledger:
  decision: "Approve deployment"
  timestamp: 2026-03-14T09:22:00Z
  evidence:
    - artifact: ADR-014
      authority: architecture-review
      version: 3
    - artifact: security-policy
      authority: security-team
      version: 7
  tools:
    - GitHub
    - CI pipeline
  approvals:
    - release manager
  outcome: approved

Every principle below is, in effect, a thing this record does not yet say.

Key Tensions That Shape the Record

Supersession is a new event, never a rewrite. A superseded decision becomes a new record pointing back at the old one. "We decided A, and later decided B instead" is two events with a relationship between them, not one field that changed value. Rewriting the March record when you change course in August destroys your ability to answer whether the March decision was reasonable given what was known then. Compaction can always produce a clean current-state projection later, but once you rewrite historical evidence, you cannot reconstruct it.

The ledger reports policy evaluation, not policy enforcement. A ledger entry can contain a policy_evaluated result showing that a check ran and what it concluded. But it never contains the enforcement decision as its own authority. It reports; it does not rule.

Evidence versions matter more than evidence names. Pinning to version 3 of an ADR instead of just "ADR-014" means the paper trail survives when the document gets updated. The authority and version fields together are what make evidence auditable over time.

Tool context is decision context. Recording that GitHub and the CI pipeline were involved isn't metadata — it's part of what made the decision possible. Those tools are part of the evidence chain, not just the execution path.

What This Means for Real Systems

If you're building an AI workflow where decisions need to be traceable, the ledger pattern pays off fast. You're not trying to prevent bad decisions — you're trying to make every decision, good or bad, fully examinable after the fact. That changes what you put in the record and what you leave out.

The strongest ideas here came from the comment thread after Part 4, and I've tried to credit where each tension landed. The field list is still the weakest part of this design — treat it as a starting point, not a destination.