ledger

An append-only state engine for portable application truth.

Ledger defines a minimal contract for authored entries, staged truth, committed history, deterministic replay, and derived projection. It composes Seal for authenticity and Armour for protected payloads without turning storage into authority.

Install package View source

Ledger stores truth, replays state, and keeps projection derived. It does not require a central database to be trusted.

Ledger is not the app. It is the state engine the app projects from.

Truth: committed entries
Type: concord-ledger
Replay: deterministic
Result: derived projection

The Primitive

The primitive

Ledger defines a minimal state-engine contract. It authors entries, stages them, commits them into append-only history, and replays that history into projection. It does not define app commands, hosting, or storage ownership. It emits truth and derives state.

Append-only truth

Committed history is immutable. New facts are appended, never rewritten.

Deterministic replay

The same committed truth replays into the same projection under the same rules.

Explicit composition

Seal authenticates entries. Armour protects payloads. Ledger composes both without blurring them.

Storage-agnostic

Storage persists committed and staged truth. It does not become the source of authority.

The Ledger Format

The ledger format

A ledger container is plain JSON. It holds committed truth only. Staged truth lives separately in runtime state and persistence snapshots.

proof.json

{
  "format": "concord-ledger",
  "version": "1",
  "metadata": {
    "createdAt": "2026-03-18T00:00:00.000Z"
  },
  "commits": {
    "commit_001": {
      "parent": null,
      "timestamp": "2026-03-18T00:00:00.000Z",
      "entries": ["entry_001"],
      "metadata": null
    }
  },
  "entries": {
    "entry_001": {
      "entryId": "entry_001",
      "kind": "todo.item.created",
      "authoredAt": "2026-03-18T00:00:00.000Z",
      "author": "sam",
      "meta": null,
      "payload": {
        "type": "plain",
        "data": {
          "id": "todo_123",
          "title": "Buy milk"
        }
      },
      "seal": {
        "type": "seal-proof",
        "version": "2",
        "algorithm": "Ed25519"
      }
    }
  },
  "head": "commit_001"
}

The container stores committed truth only. Projection is always recomputed from replay.

Surfaces

One truth model. Multiple layers.

Ledger sits between deep protocol rules and higher-level Concord runtime ergonomics. It keeps the state engine explicit across every surface that builds on it.

State engine package

Use @ternent/ledger directly when you need append, commit, replay, verify, export, and import over portable truth.

Concord runtime layer

Concord builds app-facing command and plugin ergonomics above the same ledger truth model. It should not reimplement ledger mechanics.

Portable storage adapters

Ledger stays storage-agnostic so committed truth can live in local files, Solid, Drive, or other persistence layers.

Example Use

Append truth. Replay state.

Build an entry, optionally protect its payload, seal it, commit it, and replay the ledger into derived state. The history stays portable. The projection can always be rebuilt.

1
Author an entry
Create a ledger-owned truth record for an application fact, such as a todo item being created.
2
Protect and seal it
Encrypt the payload when needed, then seal the resulting entry so authenticity binds to stored truth.
3
Commit it
Move staged entries into committed append-only history in deterministic order.
4
Replay it
Recompute projection from committed truth, with optional decryption when capability is present.

Truth is committed once. Projection is rebuilt whenever needed.

For Developers

For developers

The Ledger package is the state engine layer between protocol primitives and Concord runtime ergonomics. It owns authored truth records, replay, verification, and persistence boundaries without becoming an app framework.

State engine

Replay pipeline

Persistence boundary

JavaScript

Append and replay directly

import { createLedger } from "@ternent/ledger"

const ledger = await createLedger({
  identity,
  protocol,
  seal,
  armour,
  storage,
  projector,
})

await ledger.create()

await ledger.append({
  kind: "todo.item.created",
  payload: {
    id: "todo_123",
    title: "Buy milk"
  }
})

await ledger.commit({
  metadata: { reason: "user-action" }
})

const projection = await ledger.replay()

Use the package directly when you want explicit control over append, commit, replay, and verification without jumping straight to app-level runtime abstractions.

View source

Ready

Start with truth. Build projection on top.

Append facts, commit them deterministically, replay projection anywhere, and keep storage from becoming authority.