The Behavioral Ledger

The behavioral ledger is your cell’s flight recorder. Every time a machine runs, the ledger records what happened, in order, as an append-only chain of signed events. Nothing a machine does is invisible, and nothing already recorded can be quietly changed. This is what lets you trust a machine’s behavior after the fact: not because you watched it, but because the record proves it.

If a cell is where your machines live, the ledger is their memory. It is one of the four things every cell holds (machines, history, credentials, settings), and the history is the ledger.

What the ledger records

Each run produces a sequence of events:

Event	When	What it captures
ExecStart	A run begins	Which machine, which version, the inputs, the governing policy
StepRecord	Each step runs	The step name and type, model used, tokens, duration, cost, and output
PolicyDecision	A directive is governed	The trust, economic, and consent decisions made before an effect ran
ExecEnd	A run finishes	Final state, measures (success or failure, cost, latency, domain metrics)

Because every reasoning step, every governed action, and every control-flow decision becomes an event, the ledger is a complete account of a run. You can answer “what did this machine do, what did it cost, what did it decide, and why” without adding a single log statement.

How it stays honest

The ledger is append-only and tamper-evident. Two mechanisms make that true.

The hash chain

Events are linked like blocks in a chain. Each event carries three fields:

• event_index — its position in the run, starting at 0
• event_hash — a SHA-384 hash over the event’s canonical contents plus the previous event’s hash
• prev_hash — the event_hash of the event before it

The first event links to a fixed genesis value (sha384:0000…0). Every event after it folds in the one before. Change any field of any past event, even a single character of output, and that event’s hash changes, which breaks the link to every event that followed. Tampering is not just discouraged; it is detectable at the exact event where it happened.

Hashing uses a canonical encoding (tagged _canon: v1) so the same event always produces the same hash regardless of field order or formatting. The encoding is versioned independently of the data, so it can evolve without invalidating old records.

The signature

The hash chain proves the record is internally consistent. Signatures prove who produced it. Every event is signed by your cell’s identity key, and the signature covers the event_hash. Together they establish three things:

1. Authorship — this cell produced this event.
2. Integrity — the event has not changed since it was signed.
3. Order and origin — combined with the chain, these events happened in this sequence, from this cell.

This is what makes a ledger portable. When one cell hands a run’s history to another, the receiving cell can verify the chain and the signatures using the originating cell’s public key, and trust the record without trusting the messenger.

What you can do with it

The ledger is queryable history, not a write-only log:

• Inspect any run step by step, including the model, tokens, and output of each step.
• Replay production traces to understand or debug what a machine did.
• Audit governance by reading the policy decisions that gated every effect.
• Measure cost, latency, and outcomes across runs.
• Verify integrity with a single command (see Verifying Integrity).

Cryptographic agility and the long term

mashin is built to outlast the cryptography it ships with. Every cell identity, every signature, and every attestation carries an explicit algorithm tag, so the record says not just “this is signed” but “this is signed with this algorithm.” That tag is what makes migration possible without rewriting history.

A few properties worth knowing:

• Signing is post-quantum by default. New cells sign ledger events with ML-DSA-65, the NIST FIPS 204 post-quantum signature standard, so every event a cell signs is post-quantum from the first event. A cell identity is hybrid: it keeps an Ed25519 key (used as the cell’s stable identifier and for establishing encrypted connections) alongside the ML-DSA-65 signing key. Both algorithms are tagged on every signature.
• Existing records stay verifiable. Because the algorithm travels with each signature, a cell that signed earlier events with Ed25519 keeps those events verifiable after adopting post-quantum signing. Nothing is rewritten.
• The hash chain uses SHA-384. Hash functions are not meaningfully weakened by quantum computers, so the chain’s tamper-evidence was already quantum-resistant; SHA-384 raises the collision-resistance margin for history that must stay verifiable for years. (Content hashes used for addressing remain SHA-256.)

The practical guarantee: a record written today stays verifiable tomorrow, it is signed with post-quantum cryptography by default, and adopting newer algorithms never breaks what came before.

How this maps to the platform’s guarantees

The ledger is not a feature bolted onto execution; it is how several of mashin’s runtime invariants are kept:

• Every execution is bracketed by an ExecStart and ExecEnd event (the execution contract).
• Every governance decision is recorded, append-only (decision completeness).
• The chain is tamper-evident through the hash flow (trace integrity).
• Every run produces measures (measurement is first-class).

You do not have to opt into any of this. Running a machine produces its ledger.

Related

• Verifying Integrity — check a run, machine, release, or package with mashin verify
• Cells — where the ledger lives
• Governance — the decisions the ledger records