Skip to main content

The Ledger of Reality#

Every meaningful event inside ANNIE — an intent proposed, an intent approved, an intent denied, a ceremony signed, a halt triggered — is recorded in a single append-only ledger. The ledger is the source of truth. Everything else is a cache.

What it does#

Each entry in the ledger references the hash of the entry before it. Together they form a chain. Tampering with any historical entry breaks every entry that follows. You cannot quietly revise the past.

The chain is more than an audit log. It is a temporal branching memory. Every intent your agent generates exists as a branch on this tree. When the system needs to roll back — because a downstream check failed, or because the hardware reported an exception, or because the operator pulled the cord — it does not reverse the world. It amputates the branch and continues from the last sealed safe state.

The cost of being wrong drops from “irrecoverable damage” to “a pruned subtree.”

Why it matters#

Most production AI systems treat their action history as logging. Logging is for forensics — you read it after something has gone wrong. The Ledger of Reality is for prevention — it is consulted continuously, every transition cryptographically anchored to the previous one.

Three properties follow from this:

  1. Replay. Any ANNIE deployment can be re-executed from its ledger and must produce the same approvals and denials. If it does not, the deployment is in an undefined state and must be quarantined.
  2. Independent verification. A customer, an auditor, or a regulator can verify the ledger without trusting us. The annie verify command, shipped with every install, walks the chain and reports tampering at row-level granularity.
  3. Time-bounded rollback. Because every state is a hash-addressed point on the tree, returning to a known-good past is a pointer move, not a reconstruction.

How you observe it#

The ledger lives on disk inside the ANNIE data directory. You do not read it by hand — you query it through:

  • annie verify — walks the entire ceremony log, checks structural integrity, monotonic timestamps, signature presence on signing events, and known event kinds. Exits 0 with a PASS report or non-zero with row-level FAIL details.
  • annie log tail — streams recent events for live observation.
  • annie log export — produces a portable, signed archive suitable for external audit.

Every entry carries an index, a session identifier, a hash of the previous entry, a self-seal hash, and an event payload digest. These are the fields you can rely on across releases. The internal byte layout is a deliberate implementation detail and not part of the public contract.

What it does not do#

The Ledger of Reality records what the system decided. It does not record what the underlying language model was thinking, nor does it second-guess the formal logic that produced the decision. A ledger entry tells you: “at time T, intent I was evaluated against rule set R and the result was D.” It does not editorialize.

This separation matters. Audit surfaces that mix decisions with interpretation become political artifacts. Pure decision logs do not.

Previous Functional-Safety Framing Holographic Tombstones Next