Lesson 10 — The .ledger Class
Series: index · prev: 09 · next: 11 — HTTP 3.0 & HTTP colors
Where Lesson 09's gate protects the toolchain, the .ledger gives per-file
integrity for artifacts. A .ledger is a tamper-evident chain of records, one
per file, binding three things:
- a QR insignia (an SVG QR encoding the record's identity),
- a SHA-256 of the file, chained to the previous record's hash,
- an ISO-8601 UTC timestamp.
Full spec: ../ledger/LEDGER.md.
Two ways to produce one
1. Standalone — build a ledger over any set of files:
# Python
python3 ledger/ledger.py build --out /tmp/demo.ledger \
--insignia-dir /tmp/insignia --root . \
examples/symmetry/src/core/Message.sleela
# or the C++ tool
cd ledger && make ledger_tool
./ledger_tool build --out /tmp/demo.ledger --insignia-dir /tmp/insignia --root . ledger_core.h
2. By the compiler — Nordshrift emits <artifact>.sleela.ledger (and a
.qr.svg) next to each .sleela artifact automatically. You saw that line in
Lesson 05.
Verifying a ledger
python3 ledger/ledger.py verify /tmp/demo.ledger
# ledger: OK — N records, chain intact
The verifier recomputes each record's hash and checks every prev link. Edit or
reorder any record and it fails closed:
ledger: record 1 record_hash MISMATCH
ledger: record 2 prev-link BROKEN
A record, up close
{"seq":1,"path":"...Demo.sleela","sha256":"ea85…8f01","prev":"0000…0000",
"timestamp_utc":"2026-09-20T18:24:01Z","timestamp_kind":"utc-iso8601",
"qr_svg":"...Demo.sleela.qr.svg","record_hash":"5c9c…d012"}
Each record_hash is a SHA-256 over the record's canonical bytes (excluding the
hash itself); the next record's prev points at it — that's the chain.
Honest scope
The timestamp is a UTC ISO-8601 clock reading — the international format — not an RFC-3161 notarized token (that needs network the offline build lacks); the format reserves a field where a real token would attach. The C and Python implementations produce byte-identical SHA-256 and QR SVG, and each verifies the other's ledgers.