magenta-canon 0.3.0 → 0.4.0

package/README.md

@@ -170,6 +170,26 @@ npx magenta-canon verify bundle.json --expected-witness-key witness.pub
 
 Full walkthrough: [`docs/MCP_GATEWAY.md`](docs/MCP_GATEWAY.md).
 
+### Durable evidence (file ledger) — new in 0.4.0
+
+By default evidence lives in memory (the demo's fresh-universe behavior). For
+evidence that **survives a process restart**, point the gateway/control plane
+at an append-only file ledger and pin the witness identity:
+
+```bash
+MAGENTA_LEDGER_FILE=/var/lib/magenta/ledger.jsonl \
+MAGENTA_WITNESS_SECRET=<hex> MAGENTA_WITNESS_PUBLIC=<hex> \
+  <your magenta process>
+```
+
+Every receipt and signed tree head is fsync-committed before it is reported
+recorded; on restart the ledger is strictly replayed (chain, issuer
+signatures, Merkle roots, checkpoint history) or startup fails loudly. One
+exclusive writer per ledger; corruption is refused, never repaired silently.
+This is single-writer local/reference durability — see
+[`docs/FILE_LEDGER.md`](docs/FILE_LEDGER.md) for the format, lock recovery,
+crash-tail policy, backup guidance, and limitations.
+
 ### From the repo vs. as a CLI
 
 - **From a repo checkout** (above): `npm install` then `npm run demo`.

package/dist/MANIFEST.json

@@ -1,6 +1,6 @@
 {
   "package.json": "8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
-  "scripts/demo-control-plane.js": "3357c8de8e3fe32e73e0be99a3bb02179dff3ee041854d4ee6f8d135e4d8dcbf",
+  "scripts/demo-control-plane.js": "6d58bd7e816029b3c23b8c3b5f8812a5bd8ae1f4b5d6a70851eeaf6cb577dbc1",
   "scripts/intake-cli.js": "189014db22d6fccb034ed1a93ec11efe8905be820bc468366c68bb2cabaf8a97",
   "scripts/magenta-mirror.js": "cf701065f7a6e20f7f44a9b815396aeb5fe031c3f003bcd793b8014ea8801b85",
   "scripts/magenta-verify.js": "f79c60944bef65926530c2d0fd5cc35df10319c5831764b035e547b6bfebe715",
@@ -9,6 +9,7 @@
   "server/agent-record.js": "790bbfa2a10601c2bdcd98873e6e41babdf96d1df7c7ca34f19791de4c8b860f",
   "server/crypto.js": "ebbcb2929e7b3651e4ec04c9fbf3dcb656e3ae0d30bf8864f3642f72f3be2f39",
   "server/execution-receipts.js": "171a506df7d1e99f3370de9a41c1a4f0b21b38d1f02edc78d9c44e68c93dbee4",
+  "server/file-ledger-store.js": "92dc58d313be183e53817455ee9fd4ab7cb2f3a171343de66f5db26e0f139d79",
   "server/intake/categories.js": "e9860eee0e2e0fe96c7ade165e5e068fae0874de2c7d39ff796efc91e713013b",
   "server/intake/engine.js": "abb8feacd925520cbf01acc2e932d9ebb037a3d016b053b7b10deaf8f545a605",
   "server/intake/gateway-intake.js": "40514fa489b031c29725e9b837e83998217bbc1ae84cf9259154a16b1faae2e8",
@@ -20,11 +21,13 @@
   "server/intake/rationale.js": "3ea64a1430828ae5a06b41f4e93d06cdd667850d6a2ff9a1e266f98bdfc6c404",
   "server/intake/types.js": "014891c6c8360648d6954b3185ae92d56be625484bf2f0d0f71dac271a59e23b",
   "server/intake/witness.js": "588ad166f4870d65a6ed334c70aaa2deb1d6d96ec97d889902a9eda7528bd34f",
+  "server/ledger-store.js": "fc8a46f925908764bac7a076cffa08053af4c1f93237bee408eb0ed1e61eeca2",
+  "server/ledger.js": "9bf8f132e08d636070d2ede568b2eaf75810be245c90ecd5979d2d4de69af934",
   "server/persistence.js": "2e6b1d0b1c74babbd581780b028c2593256c5ec96c2d60f4c25159e3f54e4e3f",
-  "server/storage.js": "4f1660e9542dcb157148f561efd757d8aa452730c3a09064d3b1314feb16e8c9",
-  "server/transparency-log.js": "42d0d9fd3de9c60389ca882b546d9784e6ef0003895898dd5958d763d54f2f6b",
+  "server/storage.js": "7a7556a6d15d736f028698b6094072daa71eed2230427594edac9d29b531081a",
+  "server/transparency-log.js": "826dbae845726853b0736d10546a2c65596357530b82af0d1a781ac368c69a79",
   "server/trust-bootstrap.js": "57a53a3ee9cd630ada2867e8b087a34b069ba26f86a696d3ead74888dd7e8d5f",
-  "server/witness.js": "e94384a35a4cfce39990e580eb5b572ef9a2d4c4d9bad1a2ed9b5382aba64b1b",
+  "server/witness.js": "1963401588a48817f7e478d3824a4752d8a3f438f277ba4443158abcedfd6a47",
   "shared/canonical.js": "476cee4b5c5702e8a2a198e79c2639cf8ff84000ffb92f68a04433ed2a2f5484",
   "shared/certificates.js": "7844e71a38e1b1324586c7d054b2f5c15222b86446318d1e6dea9bab504a4a73",
   "shared/schema.js": "f89190990e3826e44c722d5e8f5b39fd59b4d3fb9ec047229930a17604e4646c",

package/dist/scripts/demo-control-plane.js

@@ -33,6 +33,7 @@ const node_crypto_1 = require("node:crypto");
 const storage_1 = require("../server/storage");
 const witness_1 = require("../server/witness");
 const agent_record_1 = require("../server/agent-record");
+const witness_2 = require("../server/witness");
 const trust_bootstrap_1 = require("../server/trust-bootstrap");
 const PORT = Number(process.env.PORT ?? 0);
 const HOST = "127.0.0.1";
@@ -164,6 +165,13 @@ const server = (0, node_http_1.createServer)(async (req, res) => {
         sendJson(res, 500, { error: "internal_error", message: e instanceof Error ? e.message : String(e) });
     }
 });
+// File-ledger restart support: rebuild the witness's derived leaf view from
+// any receipts the durable store replayed (no-op in the default memory mode).
+void (async () => {
+    const restored = await storage_1.storage.getExecutionReceipts();
+    if (restored.length > 0)
+        (0, witness_2.rebuildWitnessFromReceipts)([...restored].reverse().map((r) => r.receipt_hash));
+})();
 server.listen(PORT, HOST, () => {
     const addr = server.address();
     const port = typeof addr === "object" && addr ? addr.port : PORT;

package/dist/server/file-ledger-store.js

@@ -0,0 +1,411 @@
+"use strict";
+/**
+ * FILE LEDGER STORE — Durable Witness PR 2.
+ *
+ * Append-only, fsync-committed, exclusively-locked file implementation of the
+ * LedgerStore contract (server/ledger-store.ts). This is the first lane where
+ * Magenta evidence survives a real process restart:
+ *
+ *   action → receipt appended → write + fsync → "committed" returned
+ *   → restart → strict replay → same chain, same Merkle root, same STH
+ *   history → evidence still verifies (or startup FAILS LOUDLY).
+ *
+ * THE COMMIT GUARANTEE: a receipt or STH checkpoint is reported committed
+ * only after its record has been written and fsync'd. The in-memory view
+ * advances only after the durable write succeeds. A failed write surfaces an
+ * error, leaves the in-memory state unchanged, and never silently degrades
+ * to memory-only mode.
+ *
+ * FILE FORMAT — canonical JSON Lines (auditable with `less`):
+ *   {"v":1,"t":"header","genesis":"<64hex>","created":"<iso>"}
+ *   {"v":1,"t":"receipt","seq":<n>,"payload":{...receipt...},"payload_hash":"<canonicalHash(payload)>"}
+ *   {"v":1,"t":"sth","payload":{...sth...},"payload_hash":"<canonicalHash(payload)>"}
+ * One record per line, no pretty-printing, bounded line size (MAX_LINE bytes).
+ * Unknown versions/types and malformed committed records FAIL CLOSED. The
+ * store never reinterprets, repairs, re-sorts, or silently drops history.
+ *
+ * CRASH-TAIL POLICY (strict, two distinct cases):
+ *   - INCOMPLETE FINAL TAIL (no terminating newline, or the final
+ *     newline-terminated fragment is not parseable JSON): provably never a
+ *     committed record (commit = full line + "\n" + fsync). It is QUARANTINED
+ *     to `<ledger>.tail-quarantine-<ts>` and truncated, with a loud audit log.
+ *   - COMPLETE BUT INVALID RECORD (parses, but bad hash / broken chain /
+ *     duplicate / conflicting STH / bad signature), anywhere including last:
+ *     CORRUPTION → startup refuses with line number and reason. No automatic
+ *     truncation, no blank universe, no backup auto-selection.
+ *
+ * EXCLUSIVE WRITER: `<ledger>.lock` created with O_EXCL, containing
+ * {pid, hostname, created, nonce, ledger}. A second writer fails before
+ * accepting any traffic. A stale lock is REPORTED with its contents and the
+ * exact operator recovery step — never auto-deleted on a PID heuristic.
+ *
+ * APPEND-ONLY SEMANTICS FOR LIFECYCLE METHODS: clearReceipts/clearSths
+ * (test-isolation hooks on the memory store) THROW here — a durable evidence
+ * ledger refuses destructive clears. restoreReceipts accepts only a snapshot
+ * matching the current committed tail (the mutation-rollback path after a
+ * FAILED append is a no-op by construction); restoring any other state would
+ * rewrite history and throws.
+ *
+ * SNAPSHOT COHERENCE: all writes are synchronous under the single-threaded
+ * event loop, so reads can never observe a torn receipt/STH combination;
+ * snapshotReceipts() copies, exactly like the memory store.
+ *
+ * Scope honesty: single-writer, single-host, reference-grade durability.
+ * NOT multi-tenant, NOT hosted production infrastructure — that is the
+ * PostgresLedgerStore lane (architecture §2.2 option A).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileLedgerStore = exports.LedgerLockedError = exports.LedgerCorruptionError = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const node_crypto_1 = require("node:crypto");
+const canonical_1 = require("../shared/canonical");
+const crypto_1 = require("./crypto");
+const transparency_log_1 = require("./transparency-log");
+const FORMAT_VERSION = 1;
+const MAX_LINE = 1024 * 1024; // 1 MiB per record — bounded, fail-closed
+class LedgerCorruptionError extends Error {
+    line;
+    constructor(line, reason) {
+        super(`file-ledger: CORRUPTION at record ${line}: ${reason} — startup refused. ` +
+            `History is never repaired automatically; restore from a verified backup or investigate the record.`);
+        this.line = line;
+    }
+}
+exports.LedgerCorruptionError = LedgerCorruptionError;
+class LedgerLockedError extends Error {
+    constructor(lockPath, holder) {
+        super(`file-ledger: ledger is locked by another writer (${holder}). ` +
+            `If that process is dead, verify it first, then remove the lock file manually: ${lockPath}. ` +
+            `This is a deliberate operator action and is never done automatically.`);
+    }
+}
+exports.LedgerLockedError = LedgerLockedError;
+const realFileOps = {
+    appendAndSync(fd, data) {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+    },
+};
+const HEX64 = /^[0-9a-f]{64}$/;
+class FileLedgerStore {
+    filePath;
+    genesis;
+    ops;
+    receipts = [];
+    index = new Map();
+    lastHash;
+    sths = [];
+    sthBySize = new Map(); // tree_size -> root_hash (one root per size)
+    leaves = []; // replay-validation view only
+    fd;
+    lockPath;
+    lockNonce;
+    closed = false;
+    constructor(filePath, genesis = canonical_1.GENESIS_HASH, ops = realFileOps) {
+        this.filePath = filePath;
+        this.genesis = genesis;
+        this.ops = ops;
+        this.lastHash = genesis;
+        if (!path.isAbsolute(filePath)) {
+            throw new Error(`file-ledger: MAGENTA_LEDGER_FILE must be an absolute path (got '${filePath}') — relative paths change meaning with the working directory.`);
+        }
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            throw new Error(`file-ledger: parent directory does not exist: ${dir} — create it deliberately (the ledger never invents directories).`);
+        }
+        // ── exclusive writer lock (atomic O_EXCL; never auto-stolen) ────────────
+        this.lockPath = `${filePath}.lock`;
+        this.lockNonce = (0, node_crypto_1.randomBytes)(8).toString("hex");
+        try {
+            const lockFd = fs.openSync(this.lockPath, "wx", 0o600);
+            fs.writeSync(lockFd, JSON.stringify({
+                pid: process.pid, hostname: os.hostname(),
+                created: new Date().toISOString(), nonce: this.lockNonce, ledger: filePath,
+            }));
+            fs.fsyncSync(lockFd);
+            fs.closeSync(lockFd);
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                let holder = "unreadable lock file";
+                try {
+                    const lk = JSON.parse(fs.readFileSync(this.lockPath, "utf8"));
+                    const alive = (() => { try {
+                        process.kill(lk.pid, 0);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    } })();
+                    holder = `pid ${lk.pid}@${lk.hostname}, created ${lk.created}, pid ${alive ? "STILL RUNNING" : "not found on this host (possibly stale — verify before removing)"}`;
+                }
+                catch { /* malformed lock also fails closed */ }
+                throw new LedgerLockedError(this.lockPath, holder);
+            }
+            throw e;
+        }
+        // ── open + strict replay ────────────────────────────────────────────────
+        try {
+            const existed = fs.existsSync(filePath);
+            this.fd = fs.openSync(filePath, existed ? "r+" : "ax", 0o600);
+            if (!existed) {
+                this.writeRecord({ v: FORMAT_VERSION, t: "header", genesis, created: new Date().toISOString() });
+            }
+            else {
+                this.replay();
+                // position for appends
+                const end = fs.fstatSync(this.fd).size;
+                fs.closeSync(this.fd);
+                this.fd = fs.openSync(filePath, "a");
+                void end;
+            }
+        }
+        catch (e) {
+            this.releaseLock();
+            throw e;
+        }
+    }
+    // ── durable append protocol: serialize → append → fsync → THEN update memory
+    writeRecord(rec) {
+        if (this.closed)
+            throw new Error("file-ledger: store is closed");
+        const line = JSON.stringify(rec) + "\n";
+        if (Buffer.byteLength(line) > MAX_LINE) {
+            throw new Error(`file-ledger: record exceeds the ${MAX_LINE}-byte line bound — refused`);
+        }
+        this.ops.appendAndSync(this.fd, line); // throws on append/flush/fsync failure
+    }
+    async appendReceipt(receipt) {
+        // Candidate validation (the PR-1 contract activates here):
+        const r = receipt;
+        if (typeof r.receipt_hash !== "string" || !HEX64.test(r.receipt_hash)) {
+            throw new Error("file-ledger: receipt_hash missing/malformed — refused");
+        }
+        if (this.index.has(receipt.receipt_hash)) {
+            throw new Error(`file-ledger: duplicate receipt_hash ${receipt.receipt_hash.slice(0, 16)}… — append-only ledger refuses duplicates`);
+        }
+        if (r.previous_receipt_hash !== this.lastHash) {
+            throw new Error(`file-ledger: previous_receipt_hash does not match the committed tail — refused (expected ${this.lastHash.slice(0, 16)}…)`);
+        }
+        const payload = { ...receipt };
+        this.writeRecord({
+            v: FORMAT_VERSION, t: "receipt", seq: this.receipts.length + 1,
+            payload, payload_hash: (0, canonical_1.canonicalHash)(payload),
+        });
+        // Only after the durable write: advance the committed view.
+        this.receipts.push(receipt);
+        this.index.set(receipt.receipt_hash, receipt);
+        this.lastHash = receipt.receipt_hash;
+        this.leaves.push((0, transparency_log_1.hashLeaf)(receipt.receipt_hash));
+    }
+    appendSth(sth) {
+        if (typeof sth.tree_size !== "number" || sth.tree_size < 0) {
+            throw new Error("file-ledger: STH tree_size malformed — refused");
+        }
+        const existing = this.sthBySize.get(sth.tree_size);
+        if (existing !== undefined && existing !== sth.root_hash) {
+            throw new Error(`file-ledger: conflicting STH at tree_size ${sth.tree_size} — equivocation refused`);
+        }
+        const payload = { ...sth };
+        this.writeRecord({ v: FORMAT_VERSION, t: "sth", payload, payload_hash: (0, canonical_1.canonicalHash)(payload) });
+        this.sths.push(sth);
+        this.sthBySize.set(sth.tree_size, sth.root_hash);
+    }
+    // ── reads (same copy semantics as the memory store) ───────────────────────
+    async getReceiptsNewestFirst(limit) {
+        const out = [...this.receipts].reverse();
+        return limit ? out.slice(0, limit) : out;
+    }
+    async getReceiptByHash(receiptHash) {
+        return this.index.get(receiptHash);
+    }
+    async getLastReceiptHash() {
+        return this.lastHash;
+    }
+    latestSth() {
+        return this.sths[this.sths.length - 1];
+    }
+    allSths() {
+        return this.sths.slice();
+    }
+    snapshotReceipts() {
+        return { receipts: [...this.receipts], index: new Map(this.index), lastReceiptHash: this.lastHash };
+    }
+    // ── append-only refusals ───────────────────────────────────────────────────
+    clearReceipts() {
+        throw new Error("file-ledger: append-only evidence ledger refuses destructive clearReceipts() — use a fresh ledger file for a fresh universe");
+    }
+    clearSths() {
+        throw new Error("file-ledger: append-only evidence ledger refuses destructive clearSths()");
+    }
+    restoreReceipts(snapshot) {
+        // The mutation-rollback path restores the snapshot taken BEFORE a failed
+        // append; a failed durable append never advanced state, so an identical
+        // tail is a no-op. Anything else would rewrite committed history.
+        if (snapshot.lastReceiptHash === this.lastHash && snapshot.receipts.length === this.receipts.length)
+            return;
+        throw new Error("file-ledger: restoreReceipts would rewrite committed append-only history — refused");
+    }
+    /** Release the writer lock and close the file. Idempotent. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            fs.closeSync(this.fd);
+        }
+        catch { /* already closed */ }
+        this.releaseLock();
+    }
+    releaseLock() {
+        try {
+            const lk = JSON.parse(fs.readFileSync(this.lockPath, "utf8"));
+            if (lk.nonce === this.lockNonce)
+                fs.unlinkSync(this.lockPath);
+        }
+        catch { /* lock already gone or not ours — leave it */ }
+    }
+    // ── strict startup replay ──────────────────────────────────────────────────
+    replay() {
+        const raw = fs.readFileSync(this.filePath, "utf8");
+        let body = raw;
+        // Incomplete final tail: bytes after the last newline can never be a
+        // committed record (commit = line + "\n" + fsync). Quarantine + truncate.
+        const lastNl = raw.lastIndexOf("\n");
+        const tail = raw.slice(lastNl + 1);
+        if (tail.length > 0) {
+            this.quarantineTail(tail, lastNl + 1);
+            body = raw.slice(0, lastNl + 1);
+        }
+        else if (lastNl >= 0) {
+            // The final newline-terminated line might still be a torn write that
+            // happens to end in "\n"? No: writes are single appendAndSync calls of
+            // full lines; a torn final line is only possible WITHOUT its newline.
+            // A complete line that fails to parse is corruption (handled below).
+        }
+        const lines = body.length ? body.split("\n").slice(0, -1) : [];
+        let recNo = 0;
+        let headerSeen = false;
+        let witnessKey;
+        for (const line of lines) {
+            recNo++;
+            if (Buffer.byteLength(line) > MAX_LINE)
+                throw new LedgerCorruptionError(recNo, "record exceeds line bound");
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                // A complete (newline-terminated) record that does not parse, with or
+                // without records after it, is corruption — never auto-truncated.
+                throw new LedgerCorruptionError(recNo, "committed record is not valid JSON");
+            }
+            if (rec.v !== FORMAT_VERSION)
+                throw new LedgerCorruptionError(recNo, `unsupported format version ${rec.v}`);
+            if (rec.t === "header") {
+                if (recNo !== 1)
+                    throw new LedgerCorruptionError(recNo, "header record not first");
+                if (rec.genesis !== this.genesis)
+                    throw new LedgerCorruptionError(recNo, `genesis mismatch (file ${rec.genesis}, expected ${this.genesis})`);
+                headerSeen = true;
+                continue;
+            }
+            if (!headerSeen)
+                throw new LedgerCorruptionError(recNo, "missing header record");
+            if (!rec.payload || typeof rec.payload !== "object")
+                throw new LedgerCorruptionError(recNo, "missing payload");
+            if (rec.payload_hash !== (0, canonical_1.canonicalHash)(rec.payload))
+                throw new LedgerCorruptionError(recNo, "payload_hash mismatch (record altered on disk)");
+            if (rec.t === "receipt") {
+                const rc = rec.payload;
+                const rr = rec.payload;
+                if (rec.seq !== this.receipts.length + 1)
+                    throw new LedgerCorruptionError(recNo, `sequence mismatch (got ${rec.seq}, expected ${this.receipts.length + 1})`);
+                if (typeof rr.receipt_hash !== "string" || !HEX64.test(rr.receipt_hash))
+                    throw new LedgerCorruptionError(recNo, "receipt_hash malformed");
+                if (this.index.has(rc.receipt_hash))
+                    throw new LedgerCorruptionError(recNo, "duplicate receipt_hash");
+                if (rr.previous_receipt_hash !== this.lastHash)
+                    throw new LedgerCorruptionError(recNo, "previous_receipt_hash breaks the chain");
+                // receipt_hash recomputation (chain layer)
+                if (typeof rr.execution_hash === "string" &&
+                    (0, canonical_1.chainHash)(rr.previous_receipt_hash, rr.execution_hash) !== rc.receipt_hash) {
+                    throw new LedgerCorruptionError(recNo, "receipt_hash does not recompute from previous_receipt_hash + execution_hash");
+                }
+                // issuer signature (Ed25519 over canonical body minus receipt_signature)
+                if (typeof rr.receipt_signature === "string" && typeof rr.issuer_pubkey === "string") {
+                    const bodyNoSig = {};
+                    for (const k of Object.keys(rr))
+                        if (k !== "receipt_signature")
+                            bodyNoSig[k] = rr[k];
+                    if (!(0, crypto_1.verify)((0, canonical_1.canonicalHash)(bodyNoSig), rr.receipt_signature, rr.issuer_pubkey)) {
+                        throw new LedgerCorruptionError(recNo, "issuer signature invalid");
+                    }
+                }
+                this.receipts.push(rc);
+                this.index.set(rc.receipt_hash, rc);
+                this.lastHash = rc.receipt_hash;
+                this.leaves.push((0, transparency_log_1.hashLeaf)(rc.receipt_hash));
+                continue;
+            }
+            if (rec.t === "sth") {
+                const sth = rec.payload;
+                if (!(0, transparency_log_1.verifySTH)(sth))
+                    throw new LedgerCorruptionError(recNo, "STH signature invalid");
+                if (witnessKey === undefined)
+                    witnessKey = sth.witness_pubkey;
+                else if (sth.witness_pubkey !== witnessKey)
+                    throw new LedgerCorruptionError(recNo, "witness key changed mid-ledger (rotation records are a later lane)");
+                if (sth.tree_size > this.leaves.length)
+                    throw new LedgerCorruptionError(recNo, `STH tree_size ${sth.tree_size} exceeds receipts seen (${this.leaves.length})`);
+                const existing = this.sthBySize.get(sth.tree_size);
+                if (existing !== undefined && existing !== sth.root_hash)
+                    throw new LedgerCorruptionError(recNo, `conflicting STH roots at tree_size ${sth.tree_size} (equivocation at rest)`);
+                if ((0, transparency_log_1.merkleRoot)(this.leaves.slice(0, sth.tree_size)) !== sth.root_hash) {
+                    throw new LedgerCorruptionError(recNo, "STH root_hash does not recompute from the receipt chain");
+                }
+                this.sths.push(sth);
+                this.sthBySize.set(sth.tree_size, sth.root_hash);
+                continue;
+            }
+            throw new LedgerCorruptionError(recNo, `unknown record type '${rec.t}'`);
+        }
+        if (lines.length > 0 && !headerSeen)
+            throw new LedgerCorruptionError(1, "missing header record");
+    }
+    quarantineTail(tail, offset) {
+        const qPath = `${this.filePath}.tail-quarantine-${Date.now()}`;
+        fs.writeFileSync(qPath, tail, { mode: 0o600 });
+        fs.truncateSync(this.filePath, offset);
+        // Loud, deterministic, auditable — an operator can inspect the quarantined bytes.
+        console.error(`[file-ledger] AUDIT: incomplete uncommitted tail (${Buffer.byteLength(tail)} bytes at offset ${offset}) ` +
+            `quarantined to ${qPath} and truncated. This tail never completed its commit (no terminating newline); ` +
+            `committed history is unaffected.`);
+    }
+}
+exports.FileLedgerStore = FileLedgerStore;

package/dist/server/ledger-store.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * LEDGER STORE — the durable-evidence seam (Durable Witness PR 1).
+ *
+ * This interface is the storage contract for Magenta's evidence ledger: the
+ * ordered execution-receipt chain and the signed-tree-head (STH) checkpoint
+ * history. It exists so durability can be added behind a seam (FileLedgerStore,
+ * PostgresLedgerStore — see docs/roadmaps/DURABLE_WITNESS_ARCHITECTURE.md)
+ * without rewriting the transparency log, witness, receipts, verifier,
+ * gateway, or any public API surface.
+ *
+ * WHAT THE STORE IS NOT (semantics stay in their existing layers):
+ *   - it does NOT generate keys, sign anything, or compute receipt hashes;
+ *   - it does NOT decide authorization or policy outcomes;
+ *   - it does NOT verify evidence;
+ *   - it does NOT repair, re-sort, or rewrite history — it preserves exactly
+ *     what was appended, in the order it was appended, and propagates errors
+ *     rather than suppressing them.
+ *
+ * Merkle LEAVES deliberately do NOT live here: they are a derivable view of
+ * the receipt sequence (architecture §2.2) and remain in TransparencyLog,
+ * rebuilt from receipts on boot when persistence is enabled.
+ *
+ * SYNC/ASYNC BOUNDARY (deliberate, staged):
+ *   - Receipt operations are Promise-based — every existing call site already
+ *     awaits them (IStorage has been async since inception), so a future
+ *     PostgresLedgerStore slots in without caller churn.
+ *   - STH operations are synchronous today because TransparencyLog.append()
+ *     is synchronous and is called fire-and-forget from witnessReceipt().
+ *     EVOLUTION POINT (PR 4, Postgres lane): when STH writes become durable,
+ *     witnessing moves behind an async ledger service; the interface gains
+ *     async STH variants THEN, alongside the fail-closed integration the
+ *     architecture prescribes — not speculatively now.
+ *
+ * ATOMIC APPEND CONTRACT (normative for future durable implementations):
+ *   - A receipt is either durably committed exactly once, or not recorded at
+ *     all; "recorded" means COMMITTED (the durable store must not acknowledge
+ *     before its transaction/fsync boundary).
+ *   - Sequence is allocated by the store (array position today; DB identity /
+ *     file offset later) — never by an external in-memory counter.
+ *   - `receipt_hash` is unique: a durable store MUST reject a duplicate
+ *     append (constraint violation), and MUST verify the incoming receipt's
+ *     `previous_receipt_hash` equals the current tail before committing.
+ *   - One STH per tree_size: a durable store MUST make equivocation at rest a
+ *     constraint violation (tree_size as primary key).
+ *   - Partial failure must surface as an error to the caller; the store never
+ *     silently retries into an inconsistent state, and a failed append leaves
+ *     the tail unchanged so a retry is safe.
+ *   MemoryLedgerStore intentionally does NOT enforce the duplicate/previous-
+ *   hash checks above: it byte-for-byte preserves the behavior the in-memory
+ *   ledger has always had (push, index, advance tail), because PR 1 is
+ *   non-semantic. The contract text governs PR 2+ implementations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryLedgerStore = void 0;
+const canonical_1 = require("../shared/canonical");
+/**
+ * In-memory implementation — behavior-identical to the state previously held
+ * inline by MemStorage (receipts) and TransparencyLog (sthHistory).
+ * Deterministic order, no I/O, no environment variables, no background work.
+ */
+class MemoryLedgerStore {
+    receipts = [];
+    index = new Map();
+    lastHash;
+    sths = [];
+    constructor(genesisHash = canonical_1.GENESIS_HASH) {
+        this.lastHash = genesisHash;
+        this.genesis = genesisHash;
+    }
+    genesis;
+    async appendReceipt(receipt) {
+        // Exact historical semantics: push, index by hash, advance tail.
+        this.receipts.push(receipt);
+        this.index.set(receipt.receipt_hash, receipt);
+        this.lastHash = receipt.receipt_hash;
+    }
+    async getReceiptsNewestFirst(limit) {
+        const out = [...this.receipts].reverse();
+        return limit ? out.slice(0, limit) : out;
+    }
+    async getReceiptByHash(receiptHash) {
+        return this.index.get(receiptHash);
+    }
+    async getLastReceiptHash() {
+        return this.lastHash;
+    }
+    appendSth(sth) {
+        this.sths.push(sth);
+    }
+    latestSth() {
+        return this.sths[this.sths.length - 1];
+    }
+    allSths() {
+        return this.sths.slice();
+    }
+    clearReceipts() {
+        this.receipts = [];
+        this.index = new Map();
+        this.lastHash = this.genesis;
+    }
+    clearSths() {
+        this.sths = [];
+    }
+    snapshotReceipts() {
+        return {
+            receipts: [...this.receipts],
+            index: new Map(this.index),
+            lastReceiptHash: this.lastHash,
+        };
+    }
+    restoreReceipts(snapshot) {
+        this.receipts = snapshot.receipts;
+        this.index = snapshot.index;
+        this.lastHash = snapshot.lastReceiptHash;
+    }
+}
+exports.MemoryLedgerStore = MemoryLedgerStore;

package/dist/server/ledger.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedLedgerStore = void 0;
+/**
+ * LEDGER COMPOSITION POINT — selects the process-wide evidence-ledger store.
+ *
+ * Modes (explicit, never accidental):
+ *   - MEMORY (default): no env var set. MemStorage and TransparencyLog each
+ *     construct their own MemoryLedgerStore — the historical behavior.
+ *   - FILE: MAGENTA_LEDGER_FILE=/absolute/path/to/magenta-ledger.jsonl
+ *     ONE FileLedgerStore instance owns BOTH halves (receipts + STH
+ *     checkpoints) in one append-only file under one writer lock — receipts
+ *     and checkpoints can never split across two state universes.
+ *
+ * NO AMBIGUOUS DUAL AUTHORITY: the legacy whole-state dump
+ * (MAGENTA_STATE_FILE) also persists receipt state. Setting both variables is
+ * a configuration error and FAILS STARTUP — evidence must have exactly one
+ * durable authority. Migration from a legacy state file is a documented,
+ * deliberate operator action (docs/FILE_LEDGER.md), not an automatic merge.
+ *
+ * NO SILENT FALLBACK: if MAGENTA_LEDGER_FILE is set but the ledger cannot be
+ * opened (bad path, lock held, corruption), the error propagates and the
+ * process fails to start. A configured durable ledger never degrades to a
+ * blank in-memory universe.
+ */
+const file_ledger_store_1 = require("./file-ledger-store");
+function resolveSharedLedgerStore() {
+    const file = process.env.MAGENTA_LEDGER_FILE;
+    if (!file)
+        return undefined;
+    if (process.env.MAGENTA_STATE_FILE) {
+        throw new Error("ledger: MAGENTA_LEDGER_FILE and MAGENTA_STATE_FILE are both set — refusing to start with two " +
+            "independent persistence authorities over receipt state. Unset one (see docs/FILE_LEDGER.md for migration).");
+    }
+    return new file_ledger_store_1.FileLedgerStore(file);
+}
+/** Shared durable store when file mode is configured; undefined in memory mode. */
+exports.sharedLedgerStore = resolveSharedLedgerStore();

package/dist/server/storage.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetStorage = exports.storage = exports.MemStorage = void 0;
 const crypto_1 = require("crypto");
 const canonical_1 = require("../shared/canonical");
+const ledger_store_1 = require("./ledger-store");
+const ledger_1 = require("./ledger");
 const schema_1 = require("../shared/schema");
 // Genesis hash for first audit entry
 const GENESIS_HASH = "GENESIS";
@@ -52,9 +54,10 @@ class MemStorage {
     revocationChain;
     revokedPubkeys;
     lastRevocationHash;
-    executionReceipts;
-    receiptIndex;
-    lastReceiptHash;
+    // Durable Witness PR 1: the evidence-ledger receipt chain lives behind the
+    // LedgerStore seam (see server/ledger-store.ts). MemoryLedgerStore preserves
+    // the exact historical in-memory semantics.
+    ledger;
     usedNonces; // nonce -> timestamp
     secretKeyStore; // pubkey -> secretKey (server-side only)
     policyBundles; // keyed by `${policy_id}:${version}`
@@ -103,9 +106,9 @@ class MemStorage {
         this.revocationChain = [];
         this.revokedPubkeys = new Set();
         this.lastRevocationHash = canonical_1.GENESIS_HASH;
-        this.executionReceipts = [];
-        this.receiptIndex = new Map();
-        this.lastReceiptHash = canonical_1.GENESIS_HASH;
+        // FILE mode (MAGENTA_LEDGER_FILE) shares ONE durable store with the
+        // witness; MEMORY mode keeps the historical per-owner in-memory store.
+        this.ledger = ledger_1.sharedLedgerStore ?? new ledger_store_1.MemoryLedgerStore(canonical_1.GENESIS_HASH);
         this.usedNonces = new Map();
         this.secretKeyStore = new Map();
         this.policyBundles = new Map();
@@ -147,9 +150,7 @@ class MemStorage {
         this.revocationChain = [];
         this.revokedPubkeys = new Set();
         this.lastRevocationHash = canonical_1.GENESIS_HASH;
-        this.executionReceipts = [];
-        this.receiptIndex = new Map();
-        this.lastReceiptHash = canonical_1.GENESIS_HASH;
+        this.ledger.clearReceipts();
         this.usedNonces = new Map();
         this.secretKeyStore = new Map();
         this.policyBundles = new Map();
@@ -1037,19 +1038,16 @@ class MemStorage {
     // SOVEREIGN TRUST ARCHITECTURE: Execution Receipts
     // ========================================================================
     async appendExecutionReceipt(receipt) {
-        this.executionReceipts.push(receipt);
-        this.receiptIndex.set(receipt.receipt_hash, receipt);
-        this.lastReceiptHash = receipt.receipt_hash;
+        return this.ledger.appendReceipt(receipt);
     }
     async getExecutionReceipts(limit) {
-        const receipts = [...this.executionReceipts].reverse();
-        return limit ? receipts.slice(0, limit) : receipts;
+        return this.ledger.getReceiptsNewestFirst(limit);
     }
     async getExecutionReceipt(receiptHash) {
-        return this.receiptIndex.get(receiptHash);
+        return this.ledger.getReceiptByHash(receiptHash);
     }
     async getLastReceiptHash() {
-        return this.lastReceiptHash;
+        return this.ledger.getLastReceiptHash();
     }
     // ========================================================================
     // SOVEREIGN TRUST ARCHITECTURE: Nonce Replay Protection
@@ -1142,9 +1140,14 @@ class MemStorage {
             certificates: new Map(this.certificates),
             rootCertPubkey: this.rootCertPubkey,
             secretKeyStore: new Map(this.secretKeyStore),
-            executionReceipts: [...this.executionReceipts],
-            receiptIndex: new Map(this.receiptIndex),
-            lastReceiptHash: this.lastReceiptHash,
+            ...(() => {
+                const l = this.ledger.snapshotReceipts();
+                return {
+                    executionReceipts: l.receipts,
+                    receiptIndex: l.index,
+                    lastReceiptHash: l.lastReceiptHash,
+                };
+            })(),
             policyBundles: new Map(this.policyBundles),
         };
     }
@@ -1164,9 +1167,11 @@ class MemStorage {
         this.certificates = snapshot.certificates;
         this.rootCertPubkey = snapshot.rootCertPubkey;
         this.secretKeyStore = snapshot.secretKeyStore;
-        this.executionReceipts = snapshot.executionReceipts;
-        this.receiptIndex = snapshot.receiptIndex;
-        this.lastReceiptHash = snapshot.lastReceiptHash;
+        this.ledger.restoreReceipts({
+            receipts: snapshot.executionReceipts,
+            index: snapshot.receiptIndex,
+            lastReceiptHash: snapshot.lastReceiptHash,
+        });
         this.policyBundles = snapshot.policyBundles;
     }
     // ========================================================================
@@ -1215,9 +1220,14 @@ class MemStorage {
             revocationChain: this.revocationChain,
             revokedPubkeys: Array.from(this.revokedPubkeys),
             lastRevocationHash: this.lastRevocationHash,
-            executionReceipts: this.executionReceipts,
-            receiptIndex: Array.from(this.receiptIndex),
-            lastReceiptHash: this.lastReceiptHash,
+            ...(() => {
+                const l = this.ledger.snapshotReceipts();
+                return {
+                    executionReceipts: l.receipts,
+                    receiptIndex: Array.from(l.index),
+                    lastReceiptHash: l.lastReceiptHash,
+                };
+            })(),
             usedNonces: Array.from(this.usedNonces),
             secretKeyStore: Array.from(this.secretKeyStore),
             policyBundles: Array.from(this.policyBundles),
@@ -1263,9 +1273,11 @@ class MemStorage {
         this.revocationChain = s.revocationChain;
         this.revokedPubkeys = new Set(s.revokedPubkeys);
         this.lastRevocationHash = s.lastRevocationHash;
-        this.executionReceipts = s.executionReceipts;
-        this.receiptIndex = new Map(s.receiptIndex);
-        this.lastReceiptHash = s.lastReceiptHash;
+        this.ledger.restoreReceipts({
+            receipts: s.executionReceipts,
+            index: new Map(s.receiptIndex),
+            lastReceiptHash: s.lastReceiptHash,
+        });
         this.usedNonces = new Map(s.usedNonces);
         this.secretKeyStore = new Map(s.secretKeyStore);
         this.policyBundles = new Map(s.policyBundles);

package/dist/server/transparency-log.js

@@ -37,6 +37,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifyConsistency = exports.verifySTH = exports.TransparencyLog = exports.verifyInclusion = exports.inclusionProof = exports.merkleRoot = exports.hashLeaf = void 0;
 const crypto_1 = require("crypto");
+const ledger_store_1 = require("./ledger-store");
 const crypto_2 = require("./crypto");
 // ----------------------------------------------------------------------------
 // Merkle primitives (RFC 6962 domain separation: 0x00 leaves, 0x01 nodes)
@@ -111,8 +112,12 @@ function sthMessage(tree_size, root_hash, timestamp, witness_pubkey) {
     return `magenta-sth-v1|${tree_size}|${root_hash}|${timestamp}|${witness_pubkey}`;
 }
 class TransparencyLog {
+    /** Merkle leaves are a DERIVED view of the receipt sequence (rebuilt from
+     *  receipts on boot when persistence is enabled) — they deliberately stay
+     *  in-memory here rather than in the LedgerStore (architecture §2.2). */
     leaves = [];
-    sthHistory = [];
+    /** STH checkpoint history lives behind the LedgerStore seam (PR 1). */
+    store;
     witnessPub;
     witnessSec;
     /**
@@ -120,10 +125,11 @@ class TransparencyLog {
      *   or a second host). If omitted, a fresh independent key is generated — the
      *   point is that it is NOT the trust root key.
      */
-    constructor(witnessKey) {
+    constructor(witnessKey, store) {
         const kp = witnessKey ?? (0, crypto_2.generateKeyPair)();
         this.witnessPub = kp.publicKey;
         this.witnessSec = kp.secretKey;
+        this.store = store ?? new ledger_store_1.MemoryLedgerStore();
     }
     get witnessPublicKey() {
         return this.witnessPub;
@@ -133,7 +139,7 @@ class TransparencyLog {
         const leaf = hashLeaf(receiptHash);
         this.leaves.push(leaf);
         const sth = this.signTreeHead();
-        this.sthHistory.push(sth);
+        this.store.appendSth(sth);
         return { index: this.leaves.length - 1, sth };
     }
     signTreeHead() {
@@ -146,7 +152,7 @@ class TransparencyLog {
     }
     /** The latest signed tree head (what you mirror to an external auditor). */
     latestSTH() {
-        return this.sthHistory[this.sthHistory.length - 1];
+        return this.store.latestSth();
     }
     /** Inclusion proof for a given leaf index, against the current root. */
     proveInclusion(index) {
@@ -162,14 +168,35 @@ class TransparencyLog {
     size() {
         return this.leaves.length;
     }
+    /**
+     * Rebuild the DERIVED leaf view from replayed receipt hashes (file-ledger
+     * restart). Does NOT sign anything — the durable store already holds the
+     * committed STH history. Asserts the rebuilt view matches the latest
+     * committed checkpoint (boot-time corruption detection).
+     */
+    rebuildLeaves(receiptHashes) {
+        if (this.leaves.length > 0) {
+            throw new Error("transparency-log: rebuildLeaves on a non-empty log — refusing to overwrite the live view");
+        }
+        this.leaves = receiptHashes.map(hashLeaf);
+        const latest = this.store.latestSth();
+        if (latest && latest.witness_pubkey !== this.witnessPub) {
+            throw new Error("transparency-log: the durable ledger's STH history was signed by a DIFFERENT witness key than this " +
+                "process holds — a restart regenerated the witness identity. Pin MAGENTA_WITNESS_SECRET/MAGENTA_WITNESS_PUBLIC " +
+                "to the original key (witness continuity is required for origin verification); refusing to continue incoherently.");
+        }
+        if (latest && merkleRoot(this.leaves.slice(0, latest.tree_size)) !== latest.root_hash) {
+            throw new Error("transparency-log: rebuilt leaf view does not match the committed STH root — ledger/receipt divergence");
+        }
+    }
     /** Clear the log (fresh universe / test isolation). Keeps the witness key. */
     reset() {
         this.leaves = [];
-        this.sthHistory = [];
+        this.store.clearSths();
     }
     /** For export/persistence: the raw leaves and STH history. */
     exportState() {
-        return { leaves: this.leaves.slice(), sthHistory: this.sthHistory.slice(), witnessPub: this.witnessPub };
+        return { leaves: this.leaves.slice(), sthHistory: this.store.allSths(), witnessPub: this.witnessPub };
     }
 }
 exports.TransparencyLog = TransparencyLog;

package/dist/server/witness.js

@@ -18,6 +18,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rebuildWitnessFromReceipts = exports.witnessReceipt = exports.resetWitnessLog = exports.witnessLog = void 0;
 const transparency_log_1 = require("./transparency-log");
+const ledger_1 = require("./ledger");
 function loadWitnessKey() {
     const secretKey = process.env.MAGENTA_WITNESS_SECRET;
     const publicKey = process.env.MAGENTA_WITNESS_PUBLIC;
@@ -25,7 +26,7 @@ function loadWitnessKey() {
         return { publicKey, secretKey };
     return undefined;
 }
-exports.witnessLog = new transparency_log_1.TransparencyLog(loadWitnessKey());
+exports.witnessLog = new transparency_log_1.TransparencyLog(loadWitnessKey(), ledger_1.sharedLedgerStore);
 /** Reset the witness log (fresh universe / test isolation). Keeps the witness key. */
 function resetWitnessLog() {
     exports.witnessLog.reset();
@@ -56,6 +57,13 @@ exports.witnessReceipt = witnessReceipt;
 function rebuildWitnessFromReceipts(receiptHashes) {
     if (exports.witnessLog.size() > 0)
         return; // already populated this process
+    if (exports.witnessLog.latestSTH() !== undefined) {
+        // Durable store already replayed committed STH history (file-ledger
+        // restart): rebuild ONLY the derived leaf view. Re-signing here would
+        // append duplicate checkpoints on every boot.
+        exports.witnessLog.rebuildLeaves(receiptHashes);
+        return;
+    }
     for (const h of receiptHashes) {
         try {
             exports.witnessLog.append(h);

package/docs/FILE_LEDGER.md

@@ -0,0 +1,111 @@
+# File Ledger — durable local evidence (`MAGENTA_LEDGER_FILE`)
+
+The file ledger makes Magenta's evidence survive a process restart:
+
+```
+action → receipt appended → write + fsync → "committed" returned
+→ restart → strict replay → same chain, same Merkle root, same STH history
+→ evidence still verifies (or startup FAILS LOUDLY)
+```
+
+**Scope honesty:** single-writer, single-host, reference-grade durability for
+operators running the lean gateway/control plane. It is NOT multi-tenant and
+NOT hosted production infrastructure — that is the PostgreSQL ledger lane.
+
+## Modes
+
+| Mode | Selection | Behavior |
+|---|---|---|
+| **Memory** (default) | no env var | historical behavior; evidence lives for the process lifetime |
+| **File** | `MAGENTA_LEDGER_FILE=/absolute/path/magenta-ledger.jsonl` | one durable append-only ledger owns BOTH receipts and STH checkpoints, under one writer lock |
+
+Rules:
+- The path MUST be absolute. The parent directory must already exist (the
+  ledger never invents directories). Files are created `0600` where supported.
+- A configured but unopenable ledger (bad path, lock held, corruption)
+  **fails startup**. There is no silent fallback to a blank in-memory universe.
+- `MAGENTA_LEDGER_FILE` together with the legacy whole-state dump
+  (`MAGENTA_STATE_FILE`) is a **configuration error** — evidence has exactly
+  one durable authority. To migrate from a legacy state file: boot once with
+  only `MAGENTA_STATE_FILE` and export your evidence bundle, then start a
+  fresh file ledger and keep the legacy file as a read-only archive. (The
+  legacy dump remains supported for non-ledger state; it is simply never
+  combined with the file ledger.)
+- **Pin the witness identity**: set `MAGENTA_WITNESS_SECRET` /
+  `MAGENTA_WITNESS_PUBLIC` when using file mode. A restart that regenerates
+  the witness key cannot continue a ledger signed under the old key — boot
+  refuses with a clear error. Durable receipts with a discontinuous witness
+  identity would break origin verification, so this is enforced, not advised.
+- The demo (`npx magenta-canon demo`) keeps using a fresh in-memory universe.
+
+## File format (auditable with `less`)
+
+Canonical JSON Lines, one record per line, 1 MiB line bound:
+
+```
+{"v":1,"t":"header","genesis":"<64hex>","created":"<iso>"}
+{"v":1,"t":"receipt","seq":1,"payload":{…receipt…},"payload_hash":"<canonicalHash(payload)>"}
+{"v":1,"t":"sth","payload":{…signed tree head…},"payload_hash":"…"}
+```
+
+Unknown versions or record types fail closed. Records are never rewritten,
+re-sorted, repaired, or silently dropped.
+
+## The commit guarantee
+
+A receipt or STH is reported committed only after its record is written and
+`fsync`'d. The in-memory view advances only after the durable write succeeds.
+A failed write surfaces an error, leaves state unchanged (retry is safe), and
+never degrades to memory-only mode. Append enforces the ledger contract:
+duplicate `receipt_hash` refused; `previous_receipt_hash` must equal the
+committed tail; conflicting STH at an existing tree size refused
+(equivocation), and the file ledger refuses destructive `clear*` operations.
+
+## Exclusive writer lock
+
+`<ledger>.lock` is created atomically (`O_EXCL`) containing
+`{pid, hostname, created, nonce, ledger}`. A second writer fails before
+serving any traffic.
+
+**Stale-lock recovery (deliberate operator action — never automatic):**
+1. Read the lock file; identify the holder pid/host/created.
+2. Verify that process is genuinely dead (`ps`, host check).
+3. Remove the lock file manually.
+4. Start the new process; replay validates the whole ledger before serving.
+
+A malformed lock file also fails closed and is left in place for inspection.
+
+## Startup replay (strict)
+
+Every committed record is re-validated: payload hash, receipt chain linkage,
+`receipt_hash` recomputation, **issuer signatures**, duplicates, sequence
+numbers, **STH signatures**, one-root-per-tree-size, **recomputed Merkle
+roots**, and witness-key coherence. Any invalid committed record refuses
+startup with the record number and reason. History is never repaired
+automatically; never start a blank universe; never silently pick a backup.
+
+## Crash-tail policy (two distinct cases)
+
+- **Incomplete final tail** (no terminating newline — provably never
+  committed, since commit = full line + `\n` + fsync): quarantined to
+  `<ledger>.tail-quarantine-<timestamp>` and truncated, with a loud audit
+  log line. Committed history is unaffected.
+- **Complete but invalid record** (parses, but bad hash / broken chain /
+  bad signature / conflicting STH), anywhere including last: **corruption —
+  startup refuses.** No automatic truncation.
+
+## Backup
+
+Copy the ledger file while the process is stopped (or accept that a live copy
+may carry an uncommitted tail, which replay will quarantine). Restoring an
+OLD backup re-exposes an earlier tree — external mirrors will flag the
+regression; reconcile with your mirror operator before serving (see
+`docs/STH_MIRROR.md`).
+
+## Limitations / path to PostgreSQL
+
+Single writer; no tenant separation; locks are advisory at the filesystem
+level; sync writes briefly block the event loop per append (fine at
+reference-grade volumes). The hosted, transactional, lease-protected,
+fail-closed implementation is the PostgreSQL ledger lane
+(`docs/roadmaps/DURABLE_WITNESS_ARCHITECTURE.md`).

package/docs/NPM_PACKAGING.md

@@ -5,7 +5,7 @@ what deliberately does not, and how to verify the package locally.
 
 > **Status: published on npm.** The current published release is **`0.1.13`**,
 > carried on **both** the `latest` and `next` dist-tags (CJ published `0.1.13`
-> and explicitly aligned both tags). This refresh prepares **`0.3.0`** — the
+> and explicitly aligned both tags). This refresh prepares **`0.4.0`** — the
 > **truth-hardened verifier** (spec v1.1): layered verdicts (`ORIGIN AND
 > INTEGRITY VERIFIED` / `INTEGRITY VERIFIED` / `INCOMPLETE EVIDENCE` /
 > `VERIFICATION FAILED`), independently pinned witness keys
@@ -56,7 +56,9 @@ npm dist-tag add magenta-canon@<version> next
 | `0.1.12` | the **full trust loop** release: external STH mirror (`mirror` CLI: append/verify/check/--self-test) + mirror-feed operator helper (`mirror-feed`) + operational runbook; supply-chain remediation (`npm audit` 15→**0**, runtime deps 19→17, `ws` removed, `@anthropic-ai/sdk` demoted to dev with a lazy key-gated bridge, express transitives patched via overrides, drizzle-orm 0.45.2, tarball narrowed); intake/gateway test-hygiene; plus the Windows ESM subprocess-path fix + first Windows CI job — **published** |
 | `0.1.13` | **security hardening** (no API change): constant-time `INTERNAL_API_KEY` comparison; trust-key custody regression tests (root/intermediate never transit, actor key never persisted, key-returning routes fail closed) pinning the design Socket's AI heuristic flagged on `server/routes.ts`; threat-model docs (`SECURITY_MODEL.md` "Trust-key custody") + Socket dependency-alert mapping (`SUPPLY_CHAIN_REVIEW.md` §8) |
 | `0.2.0` | the **lean precompiled artifact** (supply-chain cleanroom, PRs #23–#25): minimal in-process demo control plane (the hosted Express/Passport/Postgres plane no longer ships); explicit `files` whitelist; org-storage and org-schema splits keep `pg`/drizzle out of the lean closure; **precompiled CommonJS `dist/`** built by `npm run build:lean` at `prepack` (deterministic, sha256 `MANIFEST.json`); runtime deps 17 → **2** (`tweetnacl`, `zod`); consumer install 111 → **3** packages; **zero install scripts**; no runtime `tsx`/`esbuild`/TypeScript; closure + precompile regression guards in `scripts/lean-closure.test.ts` — **published**; `latest`/`next` aligned |
-| `0.3.0` | **verifier truth hardening** (spec v1.1, PR #27): layered verdicts; `--expected-witness-key` (independently pinned witness identity — a bundle's own key can no longer masquerade as trusted); `INCOMPLETE EVIDENCE` for zero-receipt bundles; `--require-receipt`/`--require-action-hash`/`--min-receipts` claim pinning; **receipt issuer signatures enforced**; `--json` machine output; 21-test adversarial battery; demo now pins the witness key and earns `ORIGIN AND INTEGRITY VERIFIED`. Plus: Durable Witness architecture report, MVAR v1 receipt-standard DRAFT + schema/vectors, public verifier-page design — **not yet published** |
+| `0.3.0` | **verifier truth hardening** (spec v1.1, PR #27): layered verdicts; `--expected-witness-key` (independently pinned witness identity — a bundle's own key can no longer masquerade as trusted); `INCOMPLETE EVIDENCE` for zero-receipt bundles; `--require-receipt`/`--require-action-hash`/`--min-receipts` claim pinning; **receipt issuer signatures enforced**; `--json` machine output; 21-test adversarial battery; demo now pins the witness key and earns `ORIGIN AND INTEGRITY VERIFIED`. Plus: Durable Witness architecture report, MVAR v1 receipt-standard DRAFT + schema/vectors, public verifier-page design — **published**; `latest`/`next` aligned |
+| `0.4.0` | **durable file ledger** (Durable Witness PRs 1–2, #32/#33): `LedgerStore` seam; `FileLedgerStore` — append-only canonical-JSONL evidence ledger (`MAGENTA_LEDGER_FILE`), fsync-before-committed, exclusive writer lock with documented stale-lock recovery, strict boot replay (payload hashes, chain, issuer signatures, STH signatures, one-root-per-tree-size, recomputed Merkle roots), crash-tail quarantine vs corruption refusal, **witness-continuity enforcement** (regenerated witness identity refuses to continue an existing ledger), dual-authority prevention vs legacy `MAGENTA_STATE_FILE`; two-real-process restart proof (`ORIGIN AND INTEGRITY VERIFIED` after `SIGKILL`); ships `docs/FILE_LEDGER.md` — **not yet published** |
+
 
 **Verified on macOS / Linux / Windows (current release `0.1.11`; `0.1.12` re-proven via installed-tarball smoke):**
 `npx magenta-canon demo` completes the full
@@ -254,21 +256,21 @@ MCP gateway, and a **local-file external STH mirror foundation** with an
 operator runbook. **Not** included: hosted mirror service, automated network
 publishing, production multi-tenant SaaS, production durability guarantees.
 
-## Verifying the release artifact (checklist — current target `0.3.0`)
+## Verifying the release artifact (checklist — current target `0.4.0`)
 
 From a clean checkout of the release commit:
 
 ```bash
 npm ci && npm run check && npm test          # 0 tsc errors; full suite green
 npm run build:lean && npm run build:lean     # deterministic: dist/MANIFEST.json identical
-npm pack                                     # prepack rebuilds dist/; expect magenta-canon-0.3.0.tgz
-tar -tzf magenta-canon-0.3.0.tgz             # ~50 files; no .ts, no .map, no tests, no server/routes.ts
+npm pack                                     # prepack rebuilds dist/; expect magenta-canon-0.4.0.tgz
+tar -tzf magenta-canon-0.4.0.tgz             # 53 files; no .ts, no .map, no tests, no server/routes.ts, no ledger/lock files
 ```
 
 Then in an empty directory:
 
 ```bash
-npm init -y && npm i ../path/to/magenta-canon-0.3.0.tgz
+npm init -y && npm i ../path/to/magenta-canon-0.4.0.tgz
 ls node_modules                              # exactly: magenta-canon tweetnacl zod
 npx magenta-canon verify --self-test         # all verdict levels incl. tamper VERIFICATION FAILED
 npx magenta-canon mirror --self-test         # [PASS] x3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magenta-canon",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "A verifiable MCP accountability gateway for AI-agent tool calls: allows authorized calls, blocks unauthorized calls, records both, and produces cryptographic evidence anyone can verify.",
@@ -43,6 +43,7 @@
     "docs/MCP_GATEWAY.md",
     "docs/SECURITY_MODEL.md",
     "docs/NPM_PACKAGING.md",
+    "docs/FILE_LEDGER.md",
     "public/canon/schemas/constitutional-spine.schema.json",
     "public/canon/spine/constitutional-spine.v1.json",
     "README.md",