magenta-canon 0.6.0 → 0.7.0

package/README.md

@@ -236,6 +236,7 @@ magenta-canon sentinel repository        # invariant-check a git repository
 magenta-canon sentinel artifact <tgz|dir>  # invariant-check a packed artifact
 magenta-canon sentinel pack              # npm pack, then check the result
 magenta-canon sentinel witness --ledger ledger.jsonl  # witness rotation-authority check
+magenta-canon sentinel ledger ledger.jsonl  # ledger truth: sequence, chains, Merkle, checkpoints (new in 0.7.0)
 magenta-canon sentinel invariants        # list the invariant registry
 ```
 
@@ -246,6 +247,17 @@ retired-key resurrection / pre-activation refusal, and keystore↔ledger
 agreement — re-derived independently from the published wire formats, so it
 can disagree with a wrong (or compromised) server.
 
+The **Ledger Sentinel** (MC-LEDGER-001…021, new in 0.7.0) is the independent
+judge of ledger truth: contiguous receipt sequence, hash-chain and issuer
+signatures, RFC 6962 Merkle re-derivation, checkpoint monotonicity and
+equivocation refusal, corruption fail-closed vs bounded crash-tail
+quarantine, writer/lock authority (never auto-stolen), witness agreement,
+and mirror consistency. It reports five distinct outcomes — integrity /
+origin (pinned anchor only) / operational exclusivity (lock metadata only) /
+not-evaluated / violation — and is the contract any future storage backend
+(PostgreSQL, hosted) must satisfy before carrying authority
+([`docs/LEDGER_SENTINEL.md`](docs/LEDGER_SENTINEL.md), ships in the package).
+
 Sentinels are read-only, redacting (paths + fingerprints, never secret
 bodies), deterministic, network-free, and emit `magenta-sentinel-violation/1`
 evidence records; exit codes map to a scoped promotion decision (`eligible` /

package/bin/magenta-canon.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * magenta-canon — CLI entry point for the open-source reference implementation.
  *

package/dist/MANIFEST.json

@@ -3,7 +3,7 @@
   "scripts/demo-control-plane.js": "3a559f39d17c1a403988e731e053d0d071cbd41ab595fd6246910f852337ab2f",
   "scripts/intake-cli.js": "189014db22d6fccb034ed1a93ec11efe8905be820bc468366c68bb2cabaf8a97",
   "scripts/magenta-mirror.js": "cf701065f7a6e20f7f44a9b815396aeb5fe031c3f003bcd793b8014ea8801b85",
-  "scripts/magenta-sentinel.js": "0280d7584524201551c61a93beb1f2ee4964e76b0e44eb7c9d15a0f5a95cafdc",
+  "scripts/magenta-sentinel.js": "74336873d7f7c10825750e34a79988497ba793df593587f1c971b494a4d29f5f",
   "scripts/magenta-verify.js": "0bb65ef6ff1350789eecc4f0434ca94dcf3a89930f8ef1d62cc38100e18094ba",
   "scripts/mcp-gateway.js": "335923004b73511fe42ea0fc6f2e567afe8018dc95464a79027e4c2537e30de1",
   "server/agent-policy.js": "20dd9150f8244c33aaf14ecdf3a09f471210960d246cda9ab8d5abe0e8433518",
@@ -26,6 +26,7 @@
   "server/ledger.js": "9bf8f132e08d636070d2ede568b2eaf75810be245c90ecd5979d2d4de69af934",
   "server/persistence.js": "2e6b1d0b1c74babbd581780b028c2593256c5ec96c2d60f4c25159e3f54e4e3f",
   "server/sentinel/artifact-sentinel.js": "93bae917af313c9247f8062af148e7c25ccfd16d0507fa85e755c64056715f8d",
+  "server/sentinel/ledger-sentinel.js": "37d1c7040ae2506454247d40b42bad6076273b577190eeb3a6571184849b1e71",
   "server/sentinel/promotion.js": "68ac5e54eb8c07d5c75ba0d2325d595b1583557840cc46322b2053dd9924a0be",
   "server/sentinel/repository-sentinel.js": "722e973c8860cf281b29db8c4a22ec3cf473afcb088247916e8278d5e11638cf",
   "server/sentinel/rules.js": "ab24435df4f6f5b10f8b721fde37fe7fa894453648f17f04923cab56020c459f",
@@ -39,7 +40,7 @@
   "server/witness.js": "b1a8209d4dae4ffafc3ca4a158474b369250472ba80cef03bd92048282be91a4",
   "shared/canonical.js": "476cee4b5c5702e8a2a198e79c2639cf8ff84000ffb92f68a04433ed2a2f5484",
   "shared/certificates.js": "7844e71a38e1b1324586c7d054b2f5c15222b86446318d1e6dea9bab504a4a73",
-  "shared/invariants.js": "414a2aac034c9b28d0e32fc4afefb9b9ab723ed465b4aba1f8da98dab08363d4",
+  "shared/invariants.js": "7cde6f65dc014d9dd09849281734660369cbb0ea0f34faa583671efd2522d0c0",
   "shared/schema.js": "f89190990e3826e44c722d5e8f5b39fd59b4d3fb9ec047229930a17604e4646c",
   "shared/terminating-kernel.js": "8e2aa68d47d6780e4a70822482e3e410924e9d1af843f301a487da0af37ed047"
 }

package/dist/scripts/magenta-sentinel.js

@@ -43,6 +43,7 @@ const path = __importStar(require("node:path"));
 const repository_sentinel_1 = require("../server/sentinel/repository-sentinel");
 const artifact_sentinel_1 = require("../server/sentinel/artifact-sentinel");
 const witness_sentinel_1 = require("../server/sentinel/witness-sentinel");
+const ledger_sentinel_1 = require("../server/sentinel/ledger-sentinel");
 const promotion_1 = require("../server/sentinel/promotion");
 const invariants_1 = require("../shared/invariants");
 const USAGE = `magenta-sentinel — deterministic invariant evaluation (Sentinel Mesh foundation)
@@ -53,6 +54,9 @@ Usage:
   sentinel pack [--json]
   sentinel witness --ledger <file> [--keystore <file>] [--passphrase-env <VAR>]
                    [--anchor <pubkey-hex>] [--json]
+  sentinel ledger <ledger.jsonl> [--anchor <pubkey-hex>] [--keystore <file>]
+                  [--passphrase-env <VAR>] [--mirror <mirror.jsonl>]
+                  [--no-lock-inspection] [--json]
   sentinel invariants [--json]
 
 Exit: 0 eligible/diagnostic-only · 1 blocked · 2 requires review · 3 usage/unreadable
@@ -169,6 +173,36 @@ try {
         }
         process.exit(exitFor(promo));
     }
+    else if (sub === "ledger") {
+        const target = argv.find((a) => !a.startsWith("-"));
+        if (!target) {
+            console.error("sentinel ledger: missing <ledger.jsonl>\n\n" + USAGE);
+            process.exit(3);
+        }
+        const keystore = option(argv, "--keystore");
+        const mirror = option(argv, "--mirror");
+        const res = (0, ledger_sentinel_1.runLedgerSentinel)({
+            ledgerPath: path.resolve(target),
+            anchorPubkey: option(argv, "--anchor") ?? option(argv, "--expected-witness-key"),
+            keystorePath: keystore ? path.resolve(keystore) : undefined,
+            passphraseEnv: option(argv, "--passphrase-env"),
+            mirrorPath: mirror ? path.resolve(mirror) : undefined,
+            inspectLock: !flag(argv, "--no-lock-inspection"),
+        });
+        const promo = (0, promotion_1.decidePromotion)({ subject: `ledger:${res.subject_identity}`, findings: res.findings, violations: res.violations });
+        if (json)
+            console.log(JSON.stringify({ result: res, promotion: promo }, null, 2));
+        else {
+            printHuman("ledger", `${res.subject_identity.slice(0, 26)}… (${res.record_count} records: ${res.receipt_count} receipts, ${res.checkpoint_count} STH, ${res.rotation_count} rotation(s))`, res, promo);
+            for (const n of res.not_evaluated)
+                console.log(`  [NOT EVALUATED] ${n.invariant_id}: ${n.reason}`);
+            if (res.incomplete_tail_quarantined)
+                console.log("  note: incomplete trailing append quarantined (carries no authority)");
+            if (res.witness_cross_run)
+                console.log(`  witness cross-run: ${res.witness_cross_run.failed.length === 0 ? "agrees" : "DISAGREES"} (tip ${res.witness_cross_run.tip_fingerprint ?? "-"})`);
+        }
+        process.exit(exitFor(promo));
+    }
     else if (sub === "invariants") {
         if (json)
             console.log(JSON.stringify(invariants_1.INVARIANTS, null, 2));

package/dist/server/sentinel/ledger-sentinel.js

@@ -0,0 +1,408 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLedgerSentinel = exports.LEDGER_SENTINEL_VERSION = exports.LEDGER_SENTINEL_TYPE = void 0;
+/**
+ * LEDGER SENTINEL — deterministic evaluation of ledger-truth invariants
+ * (MC-LEDGER-001…021) over a durable evidence ledger.
+ *
+ * The Ledger Sentinel defines what a lawful Magenta evidence ledger looks
+ * like. The File Ledger satisfies it today; Postgres, hosted ledgers, and
+ * mirrors must satisfy the SAME family later — the implementation is never
+ * its own judge.
+ *
+ * INDEPENDENCE: this module parses the JSONL ledger itself and re-derives
+ * every claim from the published wire formats — receipt chain
+ * (chainHash(prev, execution_hash)), execution-hash recomputation, issuer
+ * signatures (Ed25519 over the canonical receipt body, verified directly
+ * with tweetnacl), RFC 6962 Merkle roots (0x00 leaf / 0x01 node domain
+ * separation, re-implemented here on node:crypto), checkpoint accounting,
+ * and tail/corruption classification. It deliberately does NOT call
+ * FileLedgerStore.replay(), LedgerStore.importState(),
+ * TransparencyLog.rebuildLeaves(), or MemStorage.
+ *
+ * Shared primitives (documented, spec-level only):
+ *  - shared/canonical.ts canonicalHash/chainHash/GENESIS_HASH — canonical
+ *    JSON hashing IS the published protocol spec; the standalone verifier
+ *    shares it for the same reason.
+ *  - tweetnacl — the Ed25519 primitive itself.
+ *  - witness-sentinel — a SIBLING in the same independent layer; the ledger
+ *    sentinel cross-runs it for epoch/rotation agreement (MC-LEDGER-019)
+ *    rather than re-implementing the witness model a third time.
+ *
+ * Read-only (MC-REL-004), redacting, deterministic, network-free.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const canonical_1 = require("../../shared/canonical");
+const invariants_1 = require("../../shared/invariants");
+const violation_1 = require("./violation");
+const witness_sentinel_1 = require("./witness-sentinel");
+exports.LEDGER_SENTINEL_TYPE = "ledger-sentinel";
+exports.LEDGER_SENTINEL_VERSION = "1.0.0";
+const SUPPORTED_RECORD_VERSION = 1;
+const KNOWN_TYPES = new Set(["header", "receipt", "sth", "rotation"]);
+// ── independent crypto (published wire formats only) ─────────────────────
+const sha256 = (b) => (0, node_crypto_1.createHash)("sha256").update(b).digest("hex");
+function fromHex(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function verifyDetachedUtf8(message, signatureHex, pubkeyHex) {
+    try {
+        return tweetnacl_1.default.sign.detached.verify(new TextEncoder().encode(message), fromHex(signatureHex), fromHex(pubkeyHex));
+    }
+    catch {
+        return false;
+    }
+}
+/** RFC 6962 (re-implemented): SHA256(0x00 || utf8(receipt_hash)) leaves,
+ *  SHA256(0x01 || left || right) nodes, odd node promoted, empty = SHA256(""). */
+function leafHash(receiptHash) {
+    return sha256(Buffer.concat([Buffer.from([0x00]), Buffer.from(receiptHash, "utf8")]));
+}
+function rootOver(leaves) {
+    if (leaves.length === 0)
+        return sha256(Buffer.alloc(0));
+    let level = leaves.slice();
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            if (i + 1 < level.length) {
+                next.push(sha256(Buffer.concat([Buffer.from([0x01]), Buffer.from(level[i], "hex"), Buffer.from(level[i + 1], "hex")])));
+            }
+            else
+                next.push(level[i]);
+        }
+        level = next;
+    }
+    return level[0];
+}
+const fp = (hex) => "key:" + (0, node_crypto_1.createHash)("sha256").update(hex, "utf8").digest("hex").slice(0, 16);
+function finding(invId, observed, expected, paths) {
+    const inv = (0, invariants_1.getInvariant)(invId);
+    return {
+        invariant_id: inv.id, invariant_version: inv.version, severity: inv.severity,
+        authority_class: inv.authorityClass, disposition: inv.disposition,
+        observed, expected, paths: paths.sort(),
+    };
+}
+function pidAliveOnThisHost(pid) {
+    try {
+        // /proc check covers Linux; zombie state counts as dead-for-writing.
+        const stat = (0, node_fs_1.readFileSync)(`/proc/${pid}/stat`, "utf8");
+        const state = stat.slice(stat.lastIndexOf(")") + 2).trim().charAt(0);
+        return state !== "Z";
+    }
+    catch {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === "EPERM" ? true : false;
+        }
+    }
+}
+function runLedgerSentinel(opts) {
+    if (!(0, node_fs_1.existsSync)(opts.ledgerPath))
+        throw new Error(`ledger-sentinel: ledger not found: ${opts.ledgerPath}`);
+    const raw = (0, node_fs_1.readFileSync)(opts.ledgerPath);
+    const subjectIdentity = `ledger:${sha256(raw)}`;
+    const text = raw.toString("utf8");
+    const findings = [];
+    const notEvaluated = [];
+    // ── parse with bounded tail quarantine (MC-LEDGER-013) ────────────────
+    const lines = text.split("\n");
+    const incompleteTail = lines.length > 0 && lines[lines.length - 1] !== "";
+    const complete = incompleteTail ? lines.slice(0, -1) : lines;
+    const records = [];
+    let recordNo = 0;
+    const MAX_RECORD_BYTES = 2 * 1024 * 1024; // file-ledger bounds records at 1MiB; 2MiB is hard refusal
+    for (const line of complete) {
+        if (line === "")
+            continue;
+        recordNo++;
+        let rec = null;
+        let framingOk = true;
+        let defect;
+        if (Buffer.byteLength(line, "utf8") > MAX_RECORD_BYTES) {
+            framingOk = false;
+            defect = `record exceeds the ${MAX_RECORD_BYTES}-byte bound`;
+        }
+        else {
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                framingOk = false;
+                defect = "not valid JSON (complete record)";
+            }
+        }
+        if (framingOk) {
+            if (rec.v !== SUPPORTED_RECORD_VERSION) {
+                framingOk = false;
+                defect = `unsupported record version ${rec.v}`;
+            }
+            else if (typeof rec.t !== "string") {
+                framingOk = false;
+                defect = "missing record type";
+            }
+            else if (!KNOWN_TYPES.has(rec.t)) {
+                framingOk = false;
+                defect = `unknown record type '${rec.t}'`;
+            }
+            else if (rec.t !== "header" && (0, canonical_1.canonicalHash)(rec.payload) !== rec.payload_hash) {
+                framingOk = false;
+                defect = "payload_hash mismatch (record altered on disk)";
+            }
+        }
+        records.push({ recordNo, t: rec?.t ?? "?", v: rec?.v ?? -1, seq: rec?.seq, payload: rec?.payload, payload_hash: rec?.payload_hash, framingOk, framingDefect: defect });
+    }
+    const badFraming = records.filter((r) => !r.framingOk);
+    for (const b of badFraming) {
+        const isUnknownType = (b.framingDefect ?? "").startsWith("unknown record type");
+        findings.push(finding(isUnknownType ? "MC-LEDGER-020" : "MC-LEDGER-003", `record #${b.recordNo}: ${b.framingDefect}`, (0, invariants_1.getInvariant)(isUnknownType ? "MC-LEDGER-020" : "MC-LEDGER-003").statement, [`record#${b.recordNo}`]));
+    }
+    // Complete-but-invalid records anywhere = corruption fails closed.
+    if (badFraming.length > 0) {
+        findings.push(finding("MC-LEDGER-012", `ledger contains ${badFraming.length} complete-but-invalid committed record(s) — must be refused, never skipped`, (0, invariants_1.getInvariant)("MC-LEDGER-012").statement, badFraming.map((b) => `record#${b.recordNo}`)));
+    }
+    const good = records.filter((r) => r.framingOk);
+    const receipts = good.filter((r) => r.t === "receipt");
+    const sths = good.filter((r) => r.t === "sth");
+    const rotations = good.filter((r) => r.t === "rotation");
+    // ── MC-LEDGER-001: contiguous sequence ────────────────────────────────
+    const seqProblems = [];
+    receipts.forEach((r, i) => {
+        if (r.seq !== i + 1)
+            seqProblems.push(`record#${r.recordNo} seq=${r.seq} expected=${i + 1}`);
+    });
+    if (seqProblems.length > 0) {
+        findings.push(finding("MC-LEDGER-001", `sequence not contiguous: ${seqProblems.join("; ")}`, "receipt sequence is exactly 1..N in ledger order", seqProblems.map((s) => s.split(" ")[0])));
+    }
+    // ── MC-LEDGER-002: duplicate receipt identity ─────────────────────────
+    const seenHashes = new Map();
+    for (const r of receipts) {
+        const h = r.payload.receipt_hash;
+        const prev = seenHashes.get(h);
+        if (prev !== undefined) {
+            findings.push(finding("MC-LEDGER-002", `duplicate receipt_hash at record#${prev} and record#${r.recordNo}`, "each receipt is unique under its canonical identity", [`record#${prev}`, `record#${r.recordNo}`]));
+        }
+        else
+            seenHashes.set(h, r.recordNo);
+    }
+    // ── MC-LEDGER-004/005/006: chain, hash, signature ─────────────────────
+    let prevHash = canonical_1.GENESIS_HASH;
+    for (const r of receipts) {
+        const rec = r.payload;
+        if (rec.previous_receipt_hash !== prevHash) {
+            findings.push(finding("MC-LEDGER-004", `record#${r.recordNo}: previous_receipt_hash does not link to predecessor`, "every receipt links to the exact predecessor (genesis first)", [`record#${r.recordNo}`]));
+        }
+        const expectedExecution = (0, canonical_1.canonicalHash)({ action_hash: rec.action_hash, decision_hash: rec.decision_hash, timestamp: rec.timestamp });
+        if (rec.execution_hash !== expectedExecution || rec.receipt_hash !== (0, canonical_1.chainHash)(rec.previous_receipt_hash, rec.execution_hash)) {
+            findings.push(finding("MC-LEDGER-005", `record#${r.recordNo}: receipt/execution hash does not re-derive from the canonical body`, "receipt_hash = chainHash(prev, execution_hash); execution_hash re-derives", [`record#${r.recordNo}`]));
+        }
+        if (typeof rec.receipt_signature === "string" && rec.receipt_signature.length > 0) {
+            const { receipt_signature, ...body } = rec;
+            if (!verifyDetachedUtf8((0, canonical_1.canonicalHash)(body), receipt_signature, rec.issuer_pubkey)) {
+                findings.push(finding("MC-LEDGER-006", `record#${r.recordNo}: issuer signature INVALID under ${fp(rec.issuer_pubkey)}`, "every receipt signature verifies under its declared issuer key", [`record#${r.recordNo}`]));
+            }
+        }
+        else {
+            findings.push(finding("MC-LEDGER-006", `record#${r.recordNo}: durable receipt carries no issuer signature`, "every committed receipt is issuer-signed", [`record#${r.recordNo}`]));
+        }
+        prevHash = rec.receipt_hash;
+    }
+    // ── MC-LEDGER-007/008/009/010: tree & checkpoints ─────────────────────
+    // Leaves in commit order; accounting uses ledger positions.
+    const leafByPosition = [];
+    const receiptCountBefore = new Map(); // recordNo -> receipts committed before it
+    {
+        let count = 0;
+        for (const r of good) {
+            receiptCountBefore.set(r.recordNo, count);
+            if (r.t === "receipt") {
+                leafByPosition.push(leafHash(r.payload.receipt_hash));
+                count++;
+            }
+        }
+    }
+    const rootBySize = new Map();
+    let lastSize = -1;
+    for (const s of sths) {
+        const sth = s.payload;
+        const before = receiptCountBefore.get(s.recordNo);
+        if (!Number.isInteger(sth.tree_size) || sth.tree_size < 0 || sth.tree_size > before) {
+            findings.push(finding("MC-LEDGER-009", `record#${s.recordNo}: STH tree_size ${sth.tree_size} exceeds the ${before} receipts committed before it`, "tree_size never exceeds receipts committed at that point", [`record#${s.recordNo}`]));
+            continue;
+        }
+        const recomputed = rootOver(leafByPosition.slice(0, sth.tree_size));
+        if (recomputed !== sth.root_hash) {
+            findings.push(finding("MC-LEDGER-007", `record#${s.recordNo}: committed root at tree_size ${sth.tree_size} does not re-derive from the ledger's receipts`, "every signed root equals the independently recomputed Merkle root", [`record#${s.recordNo}`]));
+        }
+        const existing = rootBySize.get(sth.tree_size);
+        if (existing && existing.root !== sth.root_hash) {
+            findings.push(finding("MC-LEDGER-008", `two roots committed for tree_size ${sth.tree_size} (record#${existing.recordNo} vs record#${s.recordNo}) — equivocation at rest`, "at most one root per tree size", [`record#${existing.recordNo}`, `record#${s.recordNo}`]));
+        }
+        else if (!existing)
+            rootBySize.set(sth.tree_size, { root: sth.root_hash, recordNo: s.recordNo });
+        if (sth.tree_size < lastSize) {
+            findings.push(finding("MC-LEDGER-010", `record#${s.recordNo}: checkpoint tree_size ${sth.tree_size} regresses below ${lastSize}`, "checkpoint sizes never regress in ledger order", [`record#${s.recordNo}`]));
+        }
+        lastSize = Math.max(lastSize, sth.tree_size);
+    }
+    // Rotation boundary accounting (the witness model owns the rest).
+    for (const r of rotations) {
+        const before = receiptCountBefore.get(r.recordNo);
+        if (r.payload.effective_tree_size !== before) {
+            findings.push(finding("MC-LEDGER-009", `record#${r.recordNo}: rotation boundary ${r.payload.effective_tree_size} != ${before} receipts at its position`, "rotation boundary equals the receipt count at its ledger position", [`record#${r.recordNo}`]));
+        }
+    }
+    // ── MC-LEDGER-013/014: tail semantics ─────────────────────────────────
+    // An incomplete final line is lawful quarantine (013) and carries no
+    // authority (014). Execution ordering beyond bytes: not-evaluated.
+    notEvaluated.push({
+        invariant_id: "MC-LEDGER-014",
+        reason: "execution/evidence ordering beyond the ledger bytes is runtime context; the quarantined tail (if any) was verified to carry no authority",
+    });
+    // ── MC-LEDGER-015/016: writer & lock (operational metadata) ───────────
+    const lockPath = `${opts.ledgerPath}.lock`;
+    if (opts.inspectLock === false || !(0, node_fs_1.existsSync)(lockPath)) {
+        notEvaluated.push({
+            invariant_id: "MC-LEDGER-015",
+            reason: opts.inspectLock === false ? "lock inspection disabled" : "no lock file present (offline artifact or writer cleanly absent)",
+        });
+        notEvaluated.push({ invariant_id: "MC-LEDGER-016", reason: "no lock metadata to evaluate" });
+    }
+    else {
+        try {
+            // Published lock format: {pid, hostname, created, nonce, ledger}.
+            const lock = JSON.parse((0, node_fs_1.readFileSync)(lockPath, "utf8"));
+            if (typeof lock.pid !== "number" || typeof lock.hostname !== "string" || typeof lock.created !== "string") {
+                findings.push(finding("MC-LEDGER-016", "lock file metadata malformed (missing pid/hostname/created)", "lock metadata must positively identify its holder", [lockPath]));
+            }
+            else {
+                const alive = pidAliveOnThisHost(lock.pid);
+                if (alive === false) {
+                    notEvaluated.push({
+                        invariant_id: "MC-LEDGER-016",
+                        reason: `lock holder pid ${lock.pid}@${lock.hostname} not found alive on this host — stale-lock recovery is a deliberate OPERATOR action; the sentinel never removes locks`,
+                    });
+                }
+                // A live holder is lawful single-writer state; nothing to flag.
+            }
+        }
+        catch {
+            findings.push(finding("MC-LEDGER-016", "lock file is not valid JSON (forged or damaged lock metadata)", "lock metadata must positively identify its holder", [lockPath]));
+        }
+    }
+    // Configuration authority is runtime context.
+    notEvaluated.push({ invariant_id: "MC-LEDGER-017", reason: "configuration (env) is runtime context, not ledger bytes" });
+    notEvaluated.push({ invariant_id: "MC-LEDGER-018", reason: "file-ledger subjects carry OS-lock semantics; fencing tokens apply to future stores" });
+    // ── MC-LEDGER-019: witness agreement (cross-run the sibling sentinel) ──
+    let witnessCross = null;
+    if (badFraming.length === 0) {
+        try {
+            const w = (0, witness_sentinel_1.runWitnessSentinel)({
+                ledgerPath: opts.ledgerPath,
+                keystorePath: opts.keystorePath,
+                passphraseEnv: opts.passphraseEnv,
+                anchorPubkey: opts.anchorPubkey,
+                detectedAt: opts.detectedAt,
+                detector: opts.detector,
+            });
+            witnessCross = { failed: w.failed, tip_fingerprint: w.tip_fingerprint };
+            if (w.failed.length > 0) {
+                findings.push(finding("MC-LEDGER-019", `witness authority model disagrees with this ledger: ${w.failed.join(", ")}`, "ledger and witness views of the same bytes agree", w.failed));
+            }
+        }
+        catch (e) {
+            findings.push(finding("MC-LEDGER-019", `witness cross-run refused the subject: ${e.message}`, "ledger and witness views of the same bytes agree", ["witness-cross-run"]));
+        }
+    }
+    else {
+        notEvaluated.push({ invariant_id: "MC-LEDGER-019", reason: "framing corruption present; witness cross-run skipped (subject already refused)" });
+    }
+    // ── MC-LEDGER-021: mirror consistency ─────────────────────────────────
+    if (!opts.mirrorPath) {
+        notEvaluated.push({ invariant_id: "MC-LEDGER-021", reason: "no mirror file supplied" });
+    }
+    else if (!(0, node_fs_1.existsSync)(opts.mirrorPath)) {
+        throw new Error(`ledger-sentinel: mirror not found: ${opts.mirrorPath}`);
+    }
+    else {
+        const mirrorLines = (0, node_fs_1.readFileSync)(opts.mirrorPath, "utf8").split("\n").filter((l) => l !== "");
+        for (let i = 0; i < mirrorLines.length; i++) {
+            let m;
+            try {
+                m = JSON.parse(mirrorLines[i]);
+            }
+            catch {
+                continue;
+            }
+            if (typeof m.tree_size !== "number" || typeof m.root_hash !== "string")
+                continue;
+            if (m.tree_size > leafByPosition.length) {
+                findings.push(finding("MC-LEDGER-021", `mirror observed tree_size ${m.tree_size} beyond this ledger's ${leafByPosition.length} receipts (mirror ahead or ledger truncated)`, "mirrored checkpoints never contradict committed history", [`mirror#${i + 1}`]));
+                continue;
+            }
+            const localRoot = rootOver(leafByPosition.slice(0, m.tree_size));
+            if (localRoot !== m.root_hash) {
+                findings.push(finding("MC-LEDGER-021", `mirror root at tree_size ${m.tree_size} contradicts the ledger's recomputed root`, "mirrored (size, root) pairs match committed history", [`mirror#${i + 1}`]));
+            }
+            else if (!rootBySize.has(m.tree_size)) {
+                // The mirror observed a checkpoint this ledger no longer carries —
+                // a committed STH was deleted even though the receipts survive.
+                findings.push(finding("MC-LEDGER-021", `mirror observed a checkpoint at tree_size ${m.tree_size} that is absent from the ledger's committed STH history (checkpoint deletion)`, "every mirrored checkpoint exists in committed history", [`mirror#${i + 1}`]));
+            }
+        }
+    }
+    // ── MC-LEDGER-011: deterministic replay (self-attested here; the cross-
+    //    implementation agreement is pinned by tests against the store and
+    //    verifier — a finding appears only if THIS run detects divergence). ──
+    // (No runtime check beyond the above: every derived quantity used a single
+    //  pass over the same bytes; tests prove three-way agreement.)
+    const ledgerInvariants = (0, invariants_1.ratifiedInvariants)().filter((i) => i.domain === "ledger").map((i) => i.id);
+    const notEvalIds = new Set(notEvaluated.map((n) => n.invariant_id));
+    const failed = Array.from(new Set(findings.map((f) => f.invariant_id))).sort();
+    const evaluated = ledgerInvariants.filter((id) => !notEvalIds.has(id) || failed.includes(id)).sort();
+    const passed = evaluated.filter((id) => !failed.includes(id)).sort();
+    const violations = findings.map((f) => (0, violation_1.buildViolationRecord)({
+        sentinelType: exports.LEDGER_SENTINEL_TYPE,
+        sentinelVersion: exports.LEDGER_SENTINEL_VERSION,
+        subjectType: "artifact",
+        subjectIdentity,
+        finding: f,
+        detectedAt: opts.detectedAt,
+        detector: opts.detector,
+    }));
+    const describe = (r) => r ? `#${r.recordNo}:${r.t}${r.t === "receipt" ? `(seq ${r.seq})` : ""}` : null;
+    return {
+        sentinel_type: exports.LEDGER_SENTINEL_TYPE,
+        sentinel_version: exports.LEDGER_SENTINEL_VERSION,
+        subject_type: "artifact",
+        subject_identity: subjectIdentity,
+        ledger_format: `magenta-file-ledger/v${SUPPORTED_RECORD_VERSION}`,
+        record_count: records.length,
+        receipt_count: receipts.length,
+        checkpoint_count: sths.length,
+        rotation_count: rotations.length,
+        first_record: describe(records[0]),
+        last_record: describe(records[records.length - 1]),
+        evaluated_invariants: evaluated,
+        not_evaluated: notEvaluated,
+        passed,
+        failed,
+        findings,
+        violations,
+        incomplete_tail_quarantined: incompleteTail,
+        witness_cross_run: witnessCross,
+    };
+}
+exports.runLedgerSentinel = runLedgerSentinel;

package/dist/shared/invariants.js

@@ -486,18 +486,408 @@ exports.INVARIANTS = [
         name: "reserved-postgres-ledger-invariants",
         version: 1,
         domain: "ledger",
-        statement: "RESERVED: single-writer, fsync-equivalent durability, replay-equals-" +
-            "file semantics for the Postgres ledger. Ratification happens in the " +
-            "Postgres lane.",
+        statement: "RESERVED (superseded): ledger truth — ratified as MC-LEDGER-001…021 by " +
+            "the Ledger Sentinel lane. Any future storage implementation (Postgres, " +
+            "hosted, mirror) must satisfy that family; it does not define its own.",
         severity: "high",
         enforcementPhase: ["runtime"],
         authorityClass: "none",
         disposition: "report",
         evidenceRequirements: [],
-        remediation: "n/a (reserved)",
-        owner: "postgres-lane",
-        status: "reserved",
+        remediation: "n/a (superseded)",
+        owner: "ledger-sentinel",
+        status: "superseded",
         enforcedBy: [],
+        supersededBy: "MC-LEDGER-001",
+    }),
+    // ── Ledger truth (ratified by the Ledger Sentinel lane). The contract every
+    //    storage implementation — File Ledger today, Postgres/hosted/mirrors
+    //    later — must satisfy. The implementation is never its own judge. ──
+    inv({
+        id: "MC-LEDGER-001",
+        name: "contiguous-receipt-sequence",
+        version: 1,
+        domain: "ledger",
+        statement: "Committed receipt records carry sequence numbers exactly 1..N in ledger " +
+            "order — no gaps, no regressions, no duplicates, no unexplained holes.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "expected vs observed seq"],
+        remediation: "Refuse the ledger; restore from a verified copy.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "server/file-ledger-store.ts replay"],
+        supersedes: "MC-LEDGER-RSV-001",
+    }),
+    inv({
+        id: "MC-LEDGER-002",
+        name: "no-duplicate-receipt-identity",
+        version: 1,
+        domain: "ledger",
+        statement: "No two committed receipt records may share a receipt_hash; each durable " +
+            "receipt is unique under its canonical identity.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["duplicate receipt_hash", "record numbers"],
+        remediation: "Refuse the ledger; investigate replay/duplication.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel"],
+    }),
+    inv({
+        id: "MC-LEDGER-003",
+        name: "record-framing-integrity",
+        version: 1,
+        domain: "ledger",
+        statement: "Every committed ledger record is well-formed: supported version, known " +
+            "type, valid JSON framing, and payload_hash equal to the canonical hash " +
+            "of its payload. Altered records are refused, never repaired.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "framing defect class"],
+        remediation: "Refuse the ledger; restore from a verified copy.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "server/file-ledger-store.ts replay"],
+    }),
+    inv({
+        id: "MC-LEDGER-004",
+        name: "receipt-chain-continuity",
+        version: 1,
+        domain: "ledger",
+        statement: "Every receipt's previous_receipt_hash equals the preceding receipt's " +
+            "receipt_hash (genesis for the first) — removal, reordering, or " +
+            "insertion breaks the chain and is refused.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "expected vs observed predecessor hash"],
+        remediation: "Refuse the ledger; audit against mirrors.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "scripts/magenta-verify.ts"],
+    }),
+    inv({
+        id: "MC-LEDGER-005",
+        name: "receipt-hash-correctness",
+        version: 1,
+        domain: "ledger",
+        statement: "Every receipt_hash re-derives as chainHash(previous_receipt_hash, " +
+            "execution_hash), and execution_hash re-derives from the receipt's own " +
+            "action_hash, decision_hash, and timestamp.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "expected vs observed hash"],
+        remediation: "Refuse the ledger.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "scripts/magenta-verify.ts"],
+    }),
+    inv({
+        id: "MC-LEDGER-006",
+        name: "issuer-signature-validity",
+        version: 1,
+        domain: "ledger",
+        statement: "Every receipt's issuer signature verifies (Ed25519 over the canonical " +
+            "receipt body without the signature) under its declared issuer key. " +
+            "Recomputing hashes alone can never bypass signature validation.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "issuer",
+        disposition: "require-independent-review",
+        evidenceRequirements: ["record number", "issuer key fingerprint"],
+        remediation: "Treat as forged evidence; freeze and review.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "scripts/magenta-verify.ts"],
+    }),
+    inv({
+        id: "MC-LEDGER-007",
+        name: "merkle-root-rederivation",
+        version: 1,
+        domain: "ledger",
+        statement: "Every committed STH root_hash equals the independently recomputed " +
+            "RFC 6962 Merkle root over the first tree_size receipt leaves. No signed " +
+            "root may describe a different ledger.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "witness",
+        disposition: "require-independent-review",
+        evidenceRequirements: ["STH record number", "expected vs observed root"],
+        remediation: "Refuse the ledger; audit against mirrors.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "scripts/magenta-verify.ts", "file-ledger replay"],
+    }),
+    inv({
+        id: "MC-LEDGER-008",
+        name: "no-equivocation-at-rest",
+        version: 1,
+        domain: "ledger",
+        statement: "At most one root_hash may exist per tree_size across all committed " +
+            "checkpoints — two roots for one size is equivocation and is refused.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "witness",
+        disposition: "freeze-authority-class",
+        evidenceRequirements: ["tree_size", "both conflicting roots", "record numbers"],
+        remediation: "Freeze ledger authority; independent review against mirrors.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "file-ledger appendSth/replay", "magenta-mirror"],
+    }),
+    inv({
+        id: "MC-LEDGER-009",
+        name: "tree-size-accounting",
+        version: 1,
+        domain: "ledger",
+        statement: "Checkpoint and rotation accounting is exact: an STH's tree_size never " +
+            "exceeds the receipts committed before it, and a rotation's " +
+            "effective_tree_size equals the receipt count at its ledger position. " +
+            "Non-receipt records never contribute leaves.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "claimed vs actual size"],
+        remediation: "Refuse the ledger.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "file-ledger replay"],
+    }),
+    inv({
+        id: "MC-LEDGER-010",
+        name: "checkpoint-monotonicity",
+        version: 1,
+        domain: "ledger",
+        statement: "Committed checkpoint tree sizes never regress in ledger order: the " +
+            "authoritative head moves forward only.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "witness",
+        disposition: "require-independent-review",
+        evidenceRequirements: ["record numbers", "sizes in violation"],
+        remediation: "Treat as rollback; freeze and review.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "magenta-mirror (rollback refusal)"],
+    }),
+    inv({
+        id: "MC-LEDGER-011",
+        name: "deterministic-replay",
+        version: 1,
+        domain: "ledger",
+        statement: "Identical ledger bytes must replay — by any correct, independent " +
+            "implementation — to identical receipts, Merkle roots, checkpoint sets, " +
+            "and epoch interpretation. Divergent replay between the store, the " +
+            "verifier, and the sentinel is itself a violation.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["diverging surface", "differing values"],
+        remediation: "Treat the ledger as ambiguous; refuse until resolved.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "cross-implementation agreement tests"],
+    }),
+    inv({
+        id: "MC-LEDGER-012",
+        name: "corruption-fails-closed",
+        version: 1,
+        domain: "ledger",
+        statement: "A complete-but-invalid committed record anywhere in the ledger is " +
+            "refused: no skipping damaged records, no fresh blank universe, no " +
+            "memory fallback, no silent auto-discard of authoritative records.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "corruption class"],
+        remediation: "Operator restores from a verified copy; never auto-repair.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "file-ledger LedgerCorruptionError"],
+    }),
+    inv({
+        id: "MC-LEDGER-013",
+        name: "bounded-tail-quarantine",
+        version: 1,
+        domain: "ledger",
+        statement: "Only a provably incomplete FINAL append (no newline termination / " +
+            "truncated JSON at end-of-file) may be quarantined as a crash tail. A " +
+            "complete final record that is invalid fails closed like any other " +
+            "corruption.",
+        severity: "high",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "report",
+        evidenceRequirements: ["tail byte offset", "incompleteness proof"],
+        remediation: "Quarantine the tail; committed prefix remains authoritative.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "file-ledger tail quarantine"],
+    }),
+    inv({
+        id: "MC-LEDGER-014",
+        name: "commit-before-authority",
+        version: 1,
+        domain: "ledger",
+        statement: "No authority attaches to an incomplete append: a crash before durable " +
+            "commit leaves no authoritative record, and where the protocol requires " +
+            "evidence-first semantics, execution must not outrun the durable record. " +
+            "(Execution ordering beyond the ledger bytes is reported not-evaluated " +
+            "in offline inspection — never silently passed.)",
+        severity: "critical",
+        enforcementPhase: ["runtime", "ci"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["tail/ordering evidence where available"],
+        remediation: "Re-drive the action through the gate; never backfill evidence.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel (tail)", "gate-first invariant (runtime)"],
+    }),
+    inv({
+        id: "MC-LEDGER-015",
+        name: "single-writer-exclusivity",
+        version: 1,
+        domain: "ledger",
+        statement: "Exactly one live writer may hold a ledger's write authority at a time; " +
+            "a second concurrent writer is refused. (Evaluable only with operational " +
+            "lock metadata; offline bundles report not-evaluated.)",
+        severity: "critical",
+        enforcementPhase: ["runtime", "ci"],
+        authorityClass: "operator",
+        disposition: "freeze-authority-class",
+        evidenceRequirements: ["lock holder identity", "liveness evidence"],
+        remediation: "Stop the rogue writer; verify ledger integrity afterward.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["file-ledger O_EXCL lock", "ledger-sentinel (lock inspection)"],
+    }),
+    inv({
+        id: "MC-LEDGER-016",
+        name: "no-stale-lock-auto-theft",
+        version: 1,
+        domain: "ledger",
+        statement: "A ledger lock is never stolen automatically: recovery requires positive " +
+            "dead-holder evidence and a deliberate operator action.",
+        severity: "critical",
+        enforcementPhase: ["runtime", "ci"],
+        authorityClass: "operator",
+        disposition: "require-independent-review",
+        evidenceRequirements: ["lock metadata", "holder liveness determination"],
+        remediation: "Verify the holder is dead, then remove the lock manually.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["file-ledger lock semantics", "ledger-sentinel (lock inspection)"],
+    }),
+    inv({
+        id: "MC-LEDGER-017",
+        name: "single-ledger-authority",
+        version: 1,
+        domain: "ledger",
+        statement: "Exactly one evidence authority may be configured: durable ledger and " +
+            "legacy state-file authority are mutually exclusive, and a configured-" +
+            "but-unavailable ledger fails startup rather than falling back. " +
+            "(Configuration is runtime context; offline inspection reports " +
+            "not-evaluated.)",
+        severity: "critical",
+        enforcementPhase: ["runtime"],
+        authorityClass: "operator",
+        disposition: "freeze-authority-class",
+        evidenceRequirements: ["conflicting configuration surfaces"],
+        remediation: "Fix the configuration; never run with ambiguous authority.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["server/witness.ts config guards", "server/ledger.ts"],
+    }),
+    inv({
+        id: "MC-LEDGER-018",
+        name: "writer-fencing-contract",
+        version: 1,
+        domain: "ledger",
+        statement: "CONTRACT for future storage implementations (Postgres, hosted): write " +
+            "authority must be fenced (token/lease) such that a paused or partitioned " +
+            "old writer cannot commit after a new writer is authorized. The File " +
+            "Ledger satisfies the same intent via OS-exclusive locks; subjects " +
+            "without fencing metadata report not-evaluated.",
+        severity: "critical",
+        enforcementPhase: ["runtime"],
+        authorityClass: "operator",
+        disposition: "freeze-authority-class",
+        evidenceRequirements: ["fencing token/lease evidence"],
+        remediation: "Implement fencing before granting write authority.",
+        owner: "postgres-lane (future) / ledger-sentinel (contract)",
+        status: "ratified",
+        enforcedBy: ["contract — enforced when a fencing-capable store exists"],
+    }),
+    inv({
+        id: "MC-LEDGER-019",
+        name: "ledger-witness-agreement",
+        version: 1,
+        domain: "ledger",
+        statement: "The ledger's committed rotation placement and epoch interpretation must " +
+            "agree with the witness authority model (MC-WIT-001…011) for the same " +
+            "bytes; disagreement between the ledger view and the witness view is a " +
+            "violation of the whole subject.",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "witness",
+        disposition: "require-independent-review",
+        evidenceRequirements: ["witness-sentinel finding refs"],
+        remediation: "Freeze and review; audit against mirrors.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel (cross-runs witness-sentinel)"],
+    }),
+    inv({
+        id: "MC-LEDGER-020",
+        name: "authority-record-typing",
+        version: 1,
+        domain: "ledger",
+        statement: "Every committed record carries a known, validated authority type " +
+            "(header, receipt, sth, rotation — and future typed Sentinel records). " +
+            "An unknown type bearing authority-shaped content is refused, not " +
+            "ignored.",
+        severity: "high",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "none",
+        disposition: "block-release",
+        evidenceRequirements: ["record number", "unknown type"],
+        remediation: "Refuse the ledger; classify the record first.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel", "file-ledger replay (fail closed on unknown)"],
+    }),
+    inv({
+        id: "MC-LEDGER-021",
+        name: "mirror-consistency",
+        version: 1,
+        domain: "ledger",
+        statement: "No checkpoint observed by an external mirror may contradict the " +
+            "ledger's committed history: every mirrored (tree_size, root_hash) must " +
+            "match the ledger's root at that size. (Evaluated only when a mirror " +
+            "file is supplied; otherwise not-evaluated.)",
+        severity: "critical",
+        enforcementPhase: ["ci", "runtime"],
+        authorityClass: "witness",
+        disposition: "freeze-authority-class",
+        evidenceRequirements: ["mirrored vs committed root at the conflicting size"],
+        remediation: "Treat as equivocation; freeze and review.",
+        owner: "ledger-sentinel",
+        status: "ratified",
+        enforcedBy: ["ledger-sentinel (--mirror)", "magenta-mirror check"],
     }),
     inv({
         id: "MC-WIT-RSV-001",

package/docs/FILE_LEDGER.md

@@ -109,3 +109,12 @@ 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`).
+
+## Independent evaluation (Ledger Sentinel)
+
+The File Ledger no longer judges itself: `magenta-canon sentinel ledger
+<ledger.jsonl>` re-derives sequence, hash-chain, Merkle, checkpoint,
+corruption-refusal, and writer-authority truth from the bytes with an
+independent implementation (MC-LEDGER-001…021 — see
+`docs/LEDGER_SENTINEL.md`). The same invariant family is the contract the
+future PostgreSQL ledger must satisfy before it carries authority.

package/docs/LEDGER_SENTINEL.md

@@ -0,0 +1,96 @@
+# Ledger Sentinel
+
+The Ledger Sentinel determines whether a Magenta evidence ledger is
+**structurally, cryptographically, sequentially, and operationally lawful** —
+independently of the implementation that wrote it. It ratifies and enforces
+**MC-LEDGER-001…021**, the ledger-truth contract that every storage
+implementation must satisfy: the File Ledger today; Postgres, hosted ledgers,
+and mirrors later. **The implementation is never its own judge.**
+
+Safe claim: *Magenta Canon can independently evaluate whether a ledger
+preserves sequence, hash-chain integrity, Merkle consistency, checkpoint
+monotonicity, witness epoch correctness, corruption refusal, and configured
+writer authority.* It is **not** continuous production monitoring.
+
+## Usage
+
+```bash
+magenta-canon sentinel ledger ledger.jsonl \
+  [--anchor <pubkey-hex>]            # pinned witness anchor (origin assurance)
+  [--keystore <file>]                # witness keystore (authority agreement depth)
+  [--passphrase-env <VAR>]           # env-var NAME only; never a literal, never echoed
+  [--mirror <mirror.jsonl>]          # external mirror records (MC-LEDGER-021)
+  [--no-lock-inspection]             # skip operational lock metadata
+  [--json]
+```
+
+Exit codes (shared sentinel contract): `0` eligible/diagnostic-only · `1`
+blocked · `2` requires independent review · `3` usage error / unreadable
+subject.
+
+## What it evaluates (MC-LEDGER-001…021)
+
+| Group | Invariants |
+|---|---|
+| Sequence & uniqueness | 001 contiguous receipt sequence · 002 no duplicate receipt identity · 003 record framing integrity (version/type/payload_hash) |
+| Hash chain | 004 previous-hash continuity from genesis · 005 receipt/execution-hash re-derivation · 006 issuer-signature validity (recomputed hashes can never bypass signatures) |
+| Tree & checkpoints | 007 Merkle-root re-derivation (RFC 6962, re-implemented) · 008 no equivocation at rest (one root per size) · 009 exact tree-size/boundary accounting · 010 checkpoint monotonicity · 011 deterministic replay (store ↔ verifier ↔ sentinel agreement) |
+| Durability & corruption | 012 corruption fails closed (no skip, no blank universe, no memory fallback) · 013 bounded tail quarantine (only a provably incomplete FINAL append) · 014 commit-before-authority |
+| Writer authority | 015 single-writer exclusivity · 016 no stale-lock auto-theft (recovery = positive dead-holder evidence + operator action) · 017 single ledger authority (config) · 018 writer-fencing contract (the rule future Postgres/hosted stores must implement) |
+| Cross-surface | 019 ledger/witness agreement (cross-runs the Witness & Rotation Sentinel on the same bytes) · 020 authority-record typing (unknown types refused, not ignored) · 021 mirror consistency (mirrored checkpoints can neither contradict nor be missing from committed history) |
+
+## Assurance honesty — five distinct outcomes
+
+The sentinel never collapses these into one green light:
+
+1. **Integrity proven** — sequence/chain/Merkle/framing re-derived from bytes.
+2. **Origin proven** — only with an independently pinned `--anchor` (witness
+   cross-run); a subject can never vouch for its own origin.
+3. **Operational exclusivity proven** — only when live lock metadata is
+   present; offline bundles report not-evaluated.
+4. **Not evaluated** — runtime-context invariants (configuration, execution
+   ordering, fencing) and absent optional inputs (mirror, keystore, anchor)
+   are reported explicitly, never silently passed.
+5. **Violation confirmed** — a deterministic `magenta-sentinel-violation/1`
+   record binding invariant, subject hash, record number, expected vs
+   observed, severity, authority class, and disposition.
+
+Lock semantics mirror the File Ledger's: a **live** holder is lawful
+single-writer state; a **dead** holder is reported as an operator decision —
+the sentinel never removes a lock (MC-LEDGER-016); forged/malformed lock
+metadata is a finding.
+
+## Independence boundary (documented per shared primitive)
+
+The sentinel parses the JSONL itself and re-derives every claim. It does
+**not** call `FileLedgerStore.replay()`, `LedgerStore.importState()`,
+`TransparencyLog.rebuildLeaves()`, or `MemStorage`. Shared primitives:
+
+- `shared/canonical.ts` (`canonicalHash`/`chainHash`) — canonical JSON
+  hashing is the published protocol spec; the standalone verifier shares it
+  for the same reason.
+- `tweetnacl` — the Ed25519 primitive.
+- the **Witness & Rotation Sentinel** — a sibling in the same independent
+  layer, cross-run for epoch agreement (MC-LEDGER-019) instead of
+  re-implementing the witness model a third time.
+- RFC 6962 Merkle hashing is **re-implemented** in the sentinel (not imported
+  from `transparency-log.ts`); cross-implementation agreement is pinned by
+  tests against the real store (MC-LEDGER-011).
+
+## Relationship to the rest of the trust loop
+
+- **Verifier** proves a published evidence *bundle*; the Ledger Sentinel
+  proves the durable *ledger* behind it, including operational properties a
+  bundle cannot carry.
+- **Witness Sentinel** owns rotation-authority truth; the Ledger Sentinel
+  defers to it and converts disagreement into MC-LEDGER-019.
+- **Mirror** supplies the external observations for MC-LEDGER-021
+  (equivocation, rollback, and checkpoint deletion against an outside record).
+
+## The future Postgres contract
+
+When the Postgres ledger is built it must satisfy **this same family** —
+including MC-LEDGER-018 (fenced write authority: a paused or partitioned old
+writer must be unable to commit after a new writer is authorized). Postgres
+will be validated against the already-existing Ledger Sentinel; it does not
+get to define ledger truth for itself.

package/docs/NPM_PACKAGING.md

@@ -3,21 +3,23 @@
 How Magenta Canon is packaged as an installable CLI, what ships in the tarball,
 what deliberately does not, and how to verify the package locally.
 
-> **Status: published on npm.** The current published release is **`0.5.0`**
-> (durable witness identity + authorized rotation continuity), carried on
-> **both** the `latest` and `next` dist-tags (published and registry-verified
-> 2026-06-12 — see `reports/PUBLICATION_PACKET_0.5.0.md`). This refresh
-> prepares **`0.6.0`** — the **executable Sentinel Mesh foundation**:
-> Magenta Canon 0.6.0 introduces an executable Sentinel Mesh that protects
-> repository state, npm artifacts, dependency boundaries, release promotion,
-> witness identity, and cryptographically authorized witness-key rotation
-> (`magenta-canon sentinel` — repository / artifact / pack / witness /
-> invariants). It does **not** include a production runtime kill switch, a
-> hosted Sentinel service, a Postgres Ledger Sentinel, an independent hosted
-> mirror, founder/root custody persistence, multi-tenancy, automated
-> third-party threat-intelligence intake, or complete Sentinel Mesh
-> coverage. `0.6.0` is **not yet published**; publishing remains an
-> explicitly-authorized step done on an authenticated machine.
+> **Status: published on npm.** The current published release is **`0.6.0`**
+> (the executable Sentinel Mesh foundation), carried on **both** the
+> `latest` and `next` dist-tags (published 2026-06-12; registry shasum
+> `20da40e742d47d1f4cf38beced1b17495bc6f300`, 64 files, owner-verified live
+> install). This refresh prepares **`0.7.0`** — the **Ledger Sentinel**:
+> Magenta Canon 0.7.0 adds an independent Ledger Sentinel
+> (`magenta-canon sentinel ledger`) that evaluates sequence, hash-chain
+> integrity, issuer signatures, Merkle consistency, checkpoint monotonicity,
+> corruption handling, writer authority, witness agreement, and mirror
+> consistency — the ledger-truth contract (MC-LEDGER-001…021) that any
+> future storage backend (PostgreSQL, hosted) must satisfy before carrying
+> authority. It does **not** yet provide continuous hosted monitoring,
+> Postgres storage, hosted independent mirror infrastructure, trust-root/
+> issuer persistence, production execution kill switches, multi-tenant
+> hosted services, or automatic multi-model threat ingestion. `0.7.0` is
+> **not yet published**; publishing remains an explicitly-authorized step
+> done on an authenticated machine.
 >
 > **Verdict-semantics migration (0.3.0):** scripts that grepped
 > `RESULT: VERIFIED` must match the new verdicts — `RESULT: INTEGRITY
@@ -28,7 +30,7 @@ what deliberately does not, and how to verify the package locally.
 
 ## Release posture
 
-The **`latest`** dist-tag tracks the current release (`0.4.0`), so a plain
+The **`latest`** dist-tag tracks the current release (`0.6.0`), so a plain
 `npm i magenta-canon` resolves the current reference implementation; the **`next`**
 tag points at the same version. It remains a **proven reference implementation**,
 not production-hosted infrastructure yet — production durability and an
@@ -64,7 +66,8 @@ npm dist-tag add magenta-canon@<version> next
 | `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` — **published**; `latest`/`next` aligned |
 | `0.5.0` | **durable witness identity + authorized rotation continuity** (Durable Witness PR 3, #35): encrypted witness keystore (`MAGENTA_WITNESS_KEYFILE`/`MAGENTA_WITNESS_PASSPHRASE`; scrypt N=2^16 with bounded params → AES-256-GCM with header-bound AAD, `O_EXCL` create, atomic replace); **rotation records committed into the evidence ledger** (`magenta-rotation/1`: old-key authorization + new-key countersignature + `effective_tree_size` epoch boundary + chain hash) — *key material alone never grants authority; a validated, durably committed rotation record does*; epoch-aware replay in server **and** standalone verifier (historical STHs validate against their epoch's key; rollback/substitution/forked chains refused); deterministic crash reconciliation at boot (recover committed fact / abandon orphan / fail closed — never silent activation); single-authority config matrix (keystore × env-keys × `MAGENTA_STATE_FILE` exclusions); ships `docs/WITNESS_IDENTITY.md`. **Limitation (documented):** witness identity only — founder/receipt-issuer custody is a separate forthcoming lane (issuer key still regenerates on restart in file-ledger mode; pre-restart evidence keeps verifying). **Migration:** none required — 0.4.0 env-key and memory modes are unchanged; the keystore is opt-in and mutually exclusive with `MAGENTA_WITNESS_SECRET`/`PUBLIC` and `MAGENTA_STATE_FILE`. **Also in this release (repo hygiene, #37/#38):** the legacy RealityOS heartbeat adapter is **deprecated and removed** — excluded from the supported product architecture, never required for Magenta verification or distribution (`docs/LEGACY_REALITYOS_HEARTBEAT.md`); a tracked legacy dev identity was removed with a secret-hygiene CI gate added (`reports/INCIDENT_TRACKED_DEV_IDENTITY.md`) — **published**; `latest`/`next` aligned |
-| `0.6.0` | the **executable Sentinel Mesh foundation** (PRs #40/#41): versioned **Invariant Registry** (`magenta-invariants/1`, `shared/invariants.ts` — 37 ratified invariants across repository/artifact/dependency/release/authority/witness domains, permanent IDs, reserved IDs for future lanes); deterministic **Repository Sentinel** (tracked private-key material incl. escaped-JSON forms, identity/keystore/state paths, heartbeat-revival surfaces, `.gitignore` protections); deterministic **Artifact Sentinel** (tarball / extracted dir / `npm pack`: secrets, forbidden file classes, compiled entrypoints, `MANIFEST.json` sha256 equality, version consistency, approved-dependency set, install scripts, native binaries — hardened in-memory tar reader, traversal-inert, bomb/malformation refusal); canonical **violation records** (`magenta-sentinel-violation/1`, deterministic `record_hash`, volatile fields excluded, assurance honestly `unsigned-local-diagnostic`); **scoped release-promotion eligibility** (`eligible / blocked / requires-independent-review / diagnostic-only`; authority-class violations always escalate to human review); and the **Witness & Rotation Sentinel** (MC-WIT-001…011: pinned-anchor continuity — honestly `not-evaluated` without an independently supplied anchor; rotation-chain completeness; old-key authorization + new-key countersignature validation; exact epoch boundaries; key-version & fork detection; epoch-correct STH validation; **substitution / resurrection / rollback / pre-activation** distinguished in evidence; keystore↔ledger authority agreement) — independently re-derived from the published wire formats, never wrapping server code. New CLI: `magenta-canon sentinel repository | artifact | pack | witness | invariants`. **Not included:** production runtime kill switch, hosted Sentinel service, Postgres Ledger Sentinel, independent hosted mirror, founder/root custody persistence, multi-tenant hosted control plane, automated third-party threat-intel intake, complete Sentinel Mesh coverage. **Migration:** none required — no behavior changes to gateway/verifier/ledger/witness paths; the sentinel surface is additive — **not yet published** |
+| `0.6.0` | the **executable Sentinel Mesh foundation** (PRs #40/#41): versioned **Invariant Registry** (`magenta-invariants/1`, `shared/invariants.ts` — 37 ratified invariants across repository/artifact/dependency/release/authority/witness domains, permanent IDs, reserved IDs for future lanes); deterministic **Repository Sentinel** (tracked private-key material incl. escaped-JSON forms, identity/keystore/state paths, heartbeat-revival surfaces, `.gitignore` protections); deterministic **Artifact Sentinel** (tarball / extracted dir / `npm pack`: secrets, forbidden file classes, compiled entrypoints, `MANIFEST.json` sha256 equality, version consistency, approved-dependency set, install scripts, native binaries — hardened in-memory tar reader, traversal-inert, bomb/malformation refusal); canonical **violation records** (`magenta-sentinel-violation/1`, deterministic `record_hash`, volatile fields excluded, assurance honestly `unsigned-local-diagnostic`); **scoped release-promotion eligibility** (`eligible / blocked / requires-independent-review / diagnostic-only`; authority-class violations always escalate to human review); and the **Witness & Rotation Sentinel** (MC-WIT-001…011: pinned-anchor continuity — honestly `not-evaluated` without an independently supplied anchor; rotation-chain completeness; old-key authorization + new-key countersignature validation; exact epoch boundaries; key-version & fork detection; epoch-correct STH validation; **substitution / resurrection / rollback / pre-activation** distinguished in evidence; keystore↔ledger authority agreement) — independently re-derived from the published wire formats, never wrapping server code. New CLI: `magenta-canon sentinel repository | artifact | pack | witness | invariants`. **Not included:** production runtime kill switch, hosted Sentinel service, Postgres Ledger Sentinel, independent hosted mirror, founder/root custody persistence, multi-tenant hosted control plane, automated third-party threat-intel intake, complete Sentinel Mesh coverage. **Migration:** none required — no behavior changes to gateway/verifier/ledger/witness paths; the sentinel surface is additive — **published**; `latest`/`next` aligned |
+| `0.7.0` | the **Ledger Sentinel** (PR #43): MC-LEDGER-RSV-001 ratified into **MC-LEDGER-001…021** — the ledger-truth contract every storage implementation must satisfy (File Ledger today; PostgreSQL/hosted/mirrors later; *the implementation is never its own judge*). Independent evaluation (`magenta-canon sentinel ledger <ledger.jsonl>`): contiguous receipt sequence; duplicate-identity refusal; framing integrity; previous-hash continuity from genesis; receipt/execution-hash re-derivation; issuer-signature validity (recomputed hashes never bypass signatures); **own RFC 6962 Merkle re-derivation**; equivocation-at-rest freeze; exact tree-size/boundary accounting; checkpoint monotonicity; deterministic replay (store↔verifier↔sentinel agreement); corruption fails closed; **bounded crash-tail quarantine** (only a provably incomplete final append); commit-before-authority; single-writer/lock inspection (**never auto-stolen**); single-ledger-authority + **writer-fencing contract** for future stores; witness cross-run agreement; authority-record typing; mirror consistency incl. checkpoint-deletion exposure. Five distinct assurance outcomes (integrity / origin / operational exclusivity / not-evaluated / violation). Ships `docs/LEDGER_SENTINEL.md`. **Not included:** continuous hosted monitoring, Postgres storage, hosted independent mirror, trust-root/issuer persistence, production kill switches, multi-tenancy, automatic multi-model threat ingestion. **Migration:** none — additive CLI surface — **not yet published** |
 
 
 **Verified on macOS / Linux / Windows (current release `0.1.11`; `0.1.12` re-proven via installed-tarball smoke):**
@@ -263,26 +266,27 @@ 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.6.0`)
+## Verifying the release artifact (checklist — current target `0.7.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.6.0.tgz
-tar -tzf magenta-canon-0.6.0.tgz             # 64 files; no .ts, no .map, no tests, no server/routes.ts, no ledger/lock/keystore files
+npm pack                                     # prepack rebuilds dist/; expect magenta-canon-0.7.0.tgz
+tar -tzf magenta-canon-0.7.0.tgz             # 66 files; no .ts, no .map, no tests, no server/routes.ts, no ledger/lock/keystore files
 ```
 
 Then in an empty directory:
 
 ```bash
-npm init -y && npm i ../path/to/magenta-canon-0.6.0.tgz
+npm init -y && npm i ../path/to/magenta-canon-0.7.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
 npx magenta-canon demo                       # allow / block / VERIFIED / tamper FAILED
 npx magenta-canon sentinel artifact node_modules/magenta-canon   # PROMOTION: ELIGIBLE
+npx magenta-canon sentinel ledger <your-ledger.jsonl>            # ledger truth (new in 0.7.0)
 npx magenta-canon sentinel invariants        # the live invariant registry
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magenta-canon",
-  "version": "0.6.0",
+  "version": "0.7.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.",
@@ -45,6 +45,7 @@
     "docs/NPM_PACKAGING.md",
     "docs/FILE_LEDGER.md",
     "docs/WITNESS_IDENTITY.md",
+    "docs/LEDGER_SENTINEL.md",
     "public/canon/schemas/constitutional-spine.schema.json",
     "public/canon/spine/constitutional-spine.v1.json",
     "README.md",