pi-mega-compact 0.16.3 → 0.17.1

package/dist/src/vector-cortex/resilience/spool-core.js

@@ -0,0 +1,347 @@
+/**
+ * vector-cortex/resilience/spool-core.ts — VC0C durable spool implementation (VC0C).
+ *
+ * Implementation file behind the `spool.ts` factory barrel. See spool.ts for the
+ * public surface; this file owns the TRIAD_RESILIENCE §spool append/fsync/ack
+ * protocol.
+ *
+ * Implements TRIAD_RESILIENCE.md §Spool protocol as the mode-B independent,
+ * deterministic, local disk spool that derives directly from authority:
+ *
+ *   - One spool file per session: `spool-<session>.spool` under a state dir.
+ *   - Header records schema, session, first sequence, and the prior durable
+ *     contiguous high-water.
+ *   - Frames are length-prefixed binary records carrying seq + eventId +
+ *     original bytes + SHA-256 + CRC32C (Castagnoli). A frame is FSYNC'd to disk
+ *     before the writer acknowledges `SPOOLED`; only a durable ledger commit
+ *     (after `drain` inserts into authority and the ledger is fsynced) returns
+ *     `SPOOL_COMMITTED` and advances the contiguous high-water.
+ *   - `drain` strictly sorts frames by `(seq, eventId)`, rejects gaps/conflicts,
+ *     inserts idempotently by `(eventId, digest)`, appends an fsynced ack frame,
+ *     then advances contiguous high-water. A duplicate with the same id+digest is
+ *     acknowledged (`SPOOL_IDEMPOTENT_ACK`); the same id with a DIFFERENT digest
+ *     is `SPOOL_MANUAL_HALT`.
+ *   - Crash before an ack safely replays: on reopen, frames after the last ack
+ *     are re-drained (the ack frame carries the committed seq).
+ *   - A derived builder may never read beyond the durable contiguous authority
+ *     high-water; during an authority outage the high-water freezes (drain cannot
+ *     commit) even while the spool keeps accepting frames.
+ *
+ * LOCAL ONLY: filesystem + node:crypto, zero network (PREVENT-PI-004); no `any`
+ * (PREVENT-011); synchronous durable writes (fsyncSync) per the spec.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { basename, join } from "node:path";
+export const SPOOL_SCHEMA = "spool-v1";
+/** Sentinel eventId of an acknowledgement frame (carries the committed seq). */
+export const ACK_EVENT_ID = "__ack__";
+/** Fixed on-disk width of the digest field: "sha256:" + 64 hex chars = 71 bytes. */
+export const DIGEST_FIELD_LEN = "sha256:".length + 64;
+/** CRC32C (Castagnoli) table — seeded once. */
+const CRC_TABLE = (() => {
+    const t = new Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0x82f63b78 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32c(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function createSpool(opts) {
+    mkdirSync(opts.dir, { recursive: true });
+    const bySession = new Map();
+    return {
+        session(session) {
+            let s = bySession.get(session);
+            if (!s) {
+                s = new SessionSpoolImpl(join(opts.dir, `spool-${basename(session)}.spool`), session, opts);
+                bySession.set(session, s);
+            }
+            return s;
+        },
+    };
+}
+/**
+ * Durably manages one session's spool file. Fully synchronous: every append is
+ * fsynced before acknowledging; every committed drain appends+fsyncs an ack
+ * frame. Reopen parses the header + frames, stops at a torn trailing frame
+ * (crash mid-write => unacknowledged tail), and drains only frames strictly
+ * beyond the recovered contiguous high-water — crash before ack safely replays.
+ */
+class SessionSpoolImpl {
+    session;
+    file;
+    outage;
+    reporter;
+    header;
+    frames = [];
+    ackedSeq;
+    frontierFrozen = false;
+    constructor(file, session, opts) {
+        this.file = file;
+        this.session = session;
+        this.outage = opts.authorityOutage ?? (() => false);
+        this.reporter = opts.reporter;
+        mkdirSync(join(file, ".."), { recursive: true });
+        if (existsSync(file)) {
+            const parsed = this.readExisting();
+            this.header = parsed.header;
+            this.frames = parsed.frames;
+            this.ackedSeq = parsed.highWater;
+        }
+        else {
+            this.header = { schema: SPOOL_SCHEMA, session, firstSeq: 1, priorHighWater: "0" };
+            this.ackedSeq = 0n;
+            this.writeHeader();
+        }
+    }
+    writeHeader() {
+        const fd = openSync(this.file, "a");
+        try {
+            writeSync(fd, Buffer.from(encodeHeader(this.header), "utf8"));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /** Reopen: parse header + frames; recover the last contiguous ack high-water. */
+    readExisting() {
+        const raw = readFileSync(this.file);
+        const nl = raw.indexOf(10);
+        if (nl < 0) {
+            return { header: { schema: SPOOL_SCHEMA, session: this.session, firstSeq: 1, priorHighWater: "0" }, frames: [], highWater: 0n };
+        }
+        const header = parseHeader(raw.subarray(0, nl).toString("utf8"));
+        let highWater = BigInt(header.priorHighWater);
+        const frames = [];
+        let off = nl + 1;
+        for (;;) {
+            if (off >= raw.length)
+                break;
+            const f = tryParseFrame(raw.subarray(off));
+            if (!f)
+                break; // torn/unacknowledged tail — stop, replay from last ack
+            const frame = { ...f, session: this.session };
+            if (frame.eventId === ACK_EVENT_ID) {
+                highWater = frame.seq; // ack frame carries the committed seq
+            }
+            else {
+                frames.push(frame);
+            }
+            const len = raw.readUInt32LE(off);
+            off += 4 + len;
+        }
+        // Only frames strictly beyond the recovered high-water need re-drain.
+        const unacked = frames.filter((f) => f.seq > highWater);
+        return { header, frames: unacked, highWater };
+    }
+    append(input) {
+        const digest = input.digest ?? `sha256:${sha256Hex(input.bytes)}`;
+        const frame = {
+            session: this.session,
+            seq: input.seq,
+            eventId: input.eventId,
+            digest,
+            bytes: input.bytes,
+            crc32c: crc32c(input.bytes),
+        };
+        const framed = encodeFrame(frame);
+        // Fsync BEFORE acknowledging SPOOLED.
+        const fd = openSync(this.file, "a");
+        try {
+            writeSync(fd, framed, 0, framed.length);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        this.frames.push(frame);
+        return { verdict: "SPOOLED", seq: input.seq };
+    }
+    drain(insert) {
+        const tail = this.frames;
+        if (tail.length === 0)
+            return { verdict: "SPOOL_COMMITTED", committedSeq: this.ackedSeq };
+        // Strictly sort by (seq, eventId). NOTE: we do NOT clear this.frames up front
+        // (VC0C-Q04) — the queue is only cleared once every insert has succeeded and
+        // the ack is durably appended. If any insert throws (rather than returning a
+        // conflict), the unacked tail must be retained for a later retry, not dropped.
+        const sorted = [...tail].sort(compareFrames);
+        let committed = this.ackedSeq;
+        for (const f of sorted) {
+            if (f.seq !== committed + 1n) {
+                // Gap: requeue everything beyond the last committed seq and halt.
+                this.frames = sorted.filter((x) => x.seq > committed);
+                return { verdict: "SPOOL_MANUAL_HALT", committedSeq: committed, reason: `TRI_SPOOL_GAP expected ${committed + 1n} got ${f.seq}` };
+            }
+            let outcome;
+            try {
+                outcome = insert(this.session, f.seq, f.eventId, f.digest, f.bytes);
+            }
+            catch {
+                // Authority insert THREW (e.g. a transient authority write error). This is
+                // NON-FATAL: requeue the unacked tail and halt, mirroring the manual-halt
+                // path, instead of propagating (a propagating throw would lose the frames
+                // and leave a retry seeing SPOOL_COMMITTED-with-nothing-processed).
+                this.frames = sorted.filter((x) => x.seq > committed);
+                return { verdict: "SPOOL_MANUAL_HALT", committedSeq: committed, reason: "TRI_SPOOL_INSERT_THROW" };
+            }
+            if (outcome === "committed" || outcome === "idempotent") {
+                committed = f.seq;
+            }
+            else {
+                this.frames = sorted.filter((x) => x.seq > committed);
+                return { verdict: "SPOOL_MANUAL_HALT", committedSeq: committed, reason: "TRI_SPOOL_CONFLICT conflicting digest" };
+            }
+        }
+        // All frames committed: clear the in-memory queue, then durably commit by
+        // appending+fsyncing an ack frame and advancing the high-water.
+        this.frames = [];
+        this.appendAck(committed);
+        this.ackedSeq = committed;
+        return { verdict: "SPOOL_COMMITTED", committedSeq: committed };
+    }
+    appendAck(seq) {
+        const frame = {
+            session: this.session,
+            seq,
+            eventId: ACK_EVENT_ID,
+            digest: `sha256:${sha256Hex(new Uint8Array(0))}`,
+            bytes: new Uint8Array(0),
+            crc32c: crc32c(new Uint8Array(0)),
+        };
+        const framed = encodeFrame(frame);
+        const fd = openSync(this.file, "a");
+        try {
+            writeSync(fd, framed, 0, framed.length);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    highWater() {
+        // The contiguous authority high-water advances ONLY on a durable ack
+        // (appendAck after a successful drain commit). During authority outage drain
+        // cannot commit, so ackedSeq naturally freezes here — an explicit outage
+        // branch would return the same value and was dead code (VC0C-Q05). The
+        // freeze/outage SIGNAL is the `frozen()`/`frontierFrozen` flag, not this
+        // scalar; frames appended during outage remain in the unacked tail.
+        return this.ackedSeq;
+    }
+    frozen() {
+        return this.frontierFrozen || this.outage();
+    }
+    freezeFrontier() {
+        const firstFreeze = !this.frontierFrozen && !this.outage();
+        this.frontierFrozen = true;
+        // Emit vector_cortex_frontier_frozen only on an actual freeze transition
+        // (once per outage; flag-gated + non-fatal inside the reporter). No event on
+        // an already-frozen or authority-outage-covered frontier. flag OFF => no-op.
+        if (firstFreeze) {
+            this.reporter?.frontierFrozen({
+                session: this.session,
+                committedSeq: String(this.ackedSeq),
+                frozenHighWater: String(this.ackedSeq),
+            });
+        }
+        return this.ackedSeq;
+    }
+}
+function compareFrames(a, b) {
+    if (a.seq !== b.seq)
+        return a.seq < b.seq ? -1 : 1;
+    return a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0;
+}
+function encodeHeader(h) {
+    return `${JSON.stringify(h)}\n`;
+}
+function parseHeader(line) {
+    const raw = JSON.parse(line);
+    if (raw.schema !== SPOOL_SCHEMA)
+        throw new Error("TRI_SPOOL_SCHEMA");
+    return raw;
+}
+/**
+ * Encode one binary frame: [u32 len][seq i64][eventId UTF-8 NUL][bytes][NUL][digest][u32 crc32c].
+ * The digest field is DIGEST_FIELD_LEN bytes ("sha256:" + 64 hex = 71) — sizing it
+ * to fit the FULL digest string is load-bearing for read-side verification
+ * (VC0C-Q03): a 64-byte cap silently truncated Buffer.write, so the stored digest
+ * could never match the recomputed value and every frame would be rejected on read.
+ * body length = 8 + eventId.length + 1 + bytes.length + 1 + DIGEST_FIELD_LEN + 4.
+ */
+function encodeFrame(f) {
+    const idBuf = Buffer.from(f.eventId, "utf8");
+    const bodyLen = 8 + idBuf.length + 1 + f.bytes.length + 1 + DIGEST_FIELD_LEN + 4;
+    const body = Buffer.alloc(bodyLen);
+    let o = 0;
+    body.writeBigInt64LE(BigInt(f.seq), o);
+    o += 8;
+    idBuf.copy(body, o);
+    o += idBuf.length;
+    body[o] = 0;
+    o += 1;
+    Buffer.from(f.bytes).copy(body, o);
+    o += f.bytes.length;
+    body[o] = 0;
+    o += 1;
+    body.write(f.digest, o, "utf8");
+    o += DIGEST_FIELD_LEN;
+    body.writeUInt32LE(f.crc32c, o);
+    o += 4;
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32LE(bodyLen, 0);
+    return Buffer.concat([lenBuf, body]);
+}
+/**
+ * Parse a length-prefixed frame; returns null for a torn/truncated tail OR a
+ * CRYPTOGRAPHIC INTEGRITY MISMATCH (VC0C-Q03). The stored SHA-256 digest and
+ * CRC32C are recomputed over the parsed bytes and compared — a same-length bit
+ * flip must not survive reopen and be drained/committed. A mismatch is treated
+ * like a torn tail: `readExisting` stops there and the frame is NOT accepted —
+ * it remains unacknowledged, so replay/requeue preserves it rather than
+ * silently committing corrupted bytes.
+ */
+function tryParseFrame(buf) {
+    if (buf.length < 4)
+        return null;
+    const len = buf.readUInt32LE(0);
+    if (buf.length < 4 + len)
+        return null; // torn
+    const body = buf.subarray(4, 4 + len);
+    let o = 0;
+    const seq = body.readBigInt64LE(o);
+    o += 8;
+    const idEnd = body.indexOf(0, o);
+    if (idEnd < 0)
+        return null;
+    const eventId = body.subarray(o, idEnd).toString("utf8");
+    o = idEnd + 1;
+    const bytesStart = o;
+    const nul2 = body.indexOf(0, o);
+    if (nul2 < 0)
+        return null;
+    const bytes = new Uint8Array(body.subarray(bytesStart, nul2));
+    o = nul2 + 1;
+    const digest = body.subarray(o, o + DIGEST_FIELD_LEN).toString("utf8");
+    const storedCrc = body.readUInt32LE(o + DIGEST_FIELD_LEN);
+    // Recompute and verify — write-only integrity would let a same-length bit flip
+    // drain/commit silently. Return null (treat as torn/corrupt) on mismatch.
+    if (digest !== `sha256:${sha256Hex(bytes)}` || storedCrc !== crc32c(bytes)) {
+        return null;
+    }
+    return { session: "", seq, eventId, digest, bytes, crc32c: storedCrc };
+}

package/dist/src/vector-cortex/resilience/spool.js

@@ -0,0 +1,12 @@
+/**
+ * vector-cortex/resilience/spool.ts — VC0C durable spool barrel (VC0C).
+ *
+ * Thin barrel over the append/fsync/ack spool implementation in `spool-core.ts`
+ * (delegate-shell + impl-file split keeps the frequently-touched file small).
+ * Re-exports the public `createSpool` factory, the mode-B spool/session types,
+ * and the SHA-256 / CRC32C helpers for the safety adapter and tests.
+ *
+ * Full protocol semantics live in spool-core.ts (TRIAD_RESILIENCE §spool).
+ * Local-only, no network (PREVENT-PI-004), no `any` (PREVENT-011).
+ */
+export { createSpool, SPOOL_SCHEMA, ACK_EVENT_ID, crc32c, sha256Hex } from "./spool-core.js";

package/dist/src/vector-cortex/resilience/types.js

@@ -0,0 +1,32 @@
+/**
+ * vector-cortex/resilience/types.ts — VC0C breaker/triad contracts (VC0C).
+ *
+ * Owns `Mode`, `TriadResult<T>`, `BreakerRecord`, `KillDecision`, and the
+ * `Breaker` circuit-breaker seam from CONTRACTS.md §TriadResult and breaker
+ * seam, plus the durable spool record shapes. Pure type/schema definitions +
+ * small pure predicates (no storage, no console, no network, no side effects —
+ * PREVENT-PI-004 / PREVENT-011). The live state machine lives in
+ * `breaker.ts`/`spool.ts`; the safety adapter selects A→B→C in
+ * `extensions/mega-runtime/vector-cortex-safety.ts`.
+ *
+ * Triad semantics (TRIAD_RESILIENCE.md): A is optimized/learned; B is
+ * deterministic/local and derives directly from authority; C is continuity, not
+ * semantic completeness — it uses only the exact current transcript and reports
+ * that limitation.
+ */
+/**
+ * Registered TRI conformance ID range (TRI-001..030). The acceptance test reads
+ * these rows from the v2 `resilience/` domain and asserts each returns its
+ * manifest bytes or exactly its listed failure code. TRI-001..015 are owned by
+ * VC0C (window/probe/hysteresis/cooldown transitions); TRI-016..030 span the
+ * spool protocol (frame, drain, gap, digest conflict, ack crash, frozen
+ * frontier). Mirrors EVT_IDS / CUT_IDS / M3_IDS.
+ */
+export const TRI_IDS = [
+    "TRI-001", "TRI-002", "TRI-003", "TRI-004", "TRI-005",
+    "TRI-006", "TRI-007", "TRI-008", "TRI-009", "TRI-010",
+    "TRI-011", "TRI-012", "TRI-013", "TRI-014", "TRI-015",
+    "TRI-016", "TRI-017", "TRI-018", "TRI-019", "TRI-020",
+    "TRI-021", "TRI-022", "TRI-023", "TRI-024", "TRI-025",
+    "TRI-026", "TRI-027", "TRI-028", "TRI-029", "TRI-030",
+];

package/dist/vector-cortex/conformance/emit.js

@@ -0,0 +1,46 @@
+/**
+ * vector-cortex/conformance/emit.ts — VC1C observability seam.
+ *
+ * Emits the three VC1C structured events, all gated on `MEGACOMPACT_VC1C`
+ * (mode C parity: flag OFF => zero emissions). Every event is a JSON line with
+ * `ts` + `event` (ENGINEERING_PRACTICES §8); the emitters below capture the
+ * event name + fields and are never fatal on consumer failure (non-fatal
+ * observability, never breaks the agent loop).
+ *
+ *   vector_cortex_minhash_v2_backfilled     — M4 backfill wrote v2 rows
+ *   vector_cortex_conformance_case_checked  — a v2 conformance case dispatched
+ *   vector_cortex_downgrade_copy_written    — a downgrade legacy copy written
+ *
+ * No network, no side effects beyond the supplied emit callback
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+import { VC1C_ENABLED } from "../../config/vector-cortex.js";
+/** A flag-gated no-op reporter (zero emissions, default when none injected). */
+export const NOOP_CONFORMANCE_REPORTER = {
+    backfilled: () => { },
+    caseChecked: () => { },
+    downgradeWritten: () => { },
+};
+/**
+ * Flag-gated emit: no-op when VC1C is off or no emitter is supplied. The
+ * returned reporter is itself flag-gated (`VC1C_ENABLED`), so wiring it into a
+ * runtime seam yields zero emissions when `MEGACOMPACT_VC1C=0` (byte-identical
+ * to the predecessor).
+ */
+export function createConformanceReporter(emit) {
+    const fire = (event, fields) => {
+        if (!VC1C_ENABLED())
+            return;
+        try {
+            emit?.(event, { ...fields, ts: new Date().toISOString() });
+        }
+        catch {
+            /* non-fatal observability */
+        }
+    };
+    return {
+        backfilled: (fields) => fire("vector_cortex_minhash_v2_backfilled", fields),
+        caseChecked: (fields) => fire("vector_cortex_conformance_case_checked", fields),
+        downgradeWritten: (fields) => fire("vector_cortex_downgrade_copy_written", fields),
+    };
+}

package/dist/vector-cortex/conformance/manifest.js

@@ -0,0 +1,235 @@
+/**
+ * vector-cortex/conformance/manifest.ts — FixtureManifestV2 (VC1C).
+ *
+ * Owns the v2 conformance manifest: reads the authoritative
+ * `conformance/vector-cortex/v2/manifest.json` plus the on-disk fixture tree
+ * and validates it canonically. Each FixtureManifestV2 entry carries:
+ *   id, domain, inputDigest, expectedDigest, failureCode, algorithmTuple.
+ *
+ * Canonical validation rejects a mismatched corpus with the frozen codes:
+ *   CONF_EXTRA_FIXTURE   — a file on disk that the manifest does not list;
+ *   CONF_MISSING_FIXTURE — a manifest entry with no file on disk;
+ *   CONF_DIGEST_DRIFT    — on-disk bytes do not match the manifest SHA-256.
+ *
+ * Key ordering rule (canonical JSON): object keys are sorted by UTF-8 bytes;
+ * a manifest that is not canonical (or a fixture whose canonical re-serialization
+ * differs) is itself a digest-drift / noncanonical condition. The invariant:
+ * canonical valid manifests converge to ONE digest (the corpus is a single
+ * reproducible byte image).
+ *
+ * Pure FS reads + pure predicates; no network, no side effects on authority
+ * data (PREVENT-PI-004 / PREVENT-011).
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { createHash as sha256 } from "node:crypto";
+import { join, relative, sep } from "node:path";
+/** Frozen VC1C conformance failure codes (the "reject unknown / extra / drifted"). */
+export const CONF_FAIL = {
+    EXTRA_FIXTURE: "CONF_EXTRA_FIXTURE",
+    MISSING_FIXTURE: "CONF_MISSING_FIXTURE",
+    DIGEST_DRIFT: "CONF_DIGEST_DRIFT",
+    NONCANONICAL: "CONF_NONCANONICAL",
+    UNKNOWN_DOMAIN: "CONF_UNKNOWN_DOMAIN",
+};
+/** Walk a directory tree returning relative POSIX paths (sorted). */
+function walk(dir, base, acc = []) {
+    for (const name of readdirSync(dir)) {
+        const p = join(dir, name);
+        const st = statSync(p);
+        if (st.isDirectory())
+            walk(p, base, acc);
+        else
+            acc.push(relative(base, p).split(sep).join("/"));
+    }
+    return acc.sort();
+}
+/**
+ * Canonical JSON bytes for a value (UTF-8, NFC keys, sorted, shortest numbers).
+ * Matches the stricter `canonicalNumber` in scripts/vector-cortex-conformance.mjs:
+ * a non-finite number or -0 has no canonical shortest representation and is
+ * rejected, so the two "canonical" serializers can never diverge for the same
+ * value (thereby preserving the "converge to one digest" invariant).
+ */
+function canonicalValue(value) {
+    if (value === null || typeof value !== "object") {
+        if (typeof value === "number") {
+            if (!Number.isFinite(value) || Object.is(value, -0)) {
+                throw new Error(`non-canonical number: ${value}`);
+            }
+            if (Number.isInteger(value) && Number.isSafeInteger(value))
+                return String(value);
+            return JSON.stringify(value);
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map((v) => canonicalValue(v)).join(",")}]`;
+    const keys = Object.keys(value)
+        .map((k) => k.normalize("NFC"))
+        .sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalValue(value[k])}`);
+    return `{${parts.join(",")}}`;
+}
+function canonicalJson(value) {
+    return Buffer.from(`${canonicalValue(value)}\n`, "utf8");
+}
+function sha256Hex(bytes) {
+    return sha256("sha256").update(bytes).digest("hex");
+}
+/** parse a manifest.json (must be a valid v2 manifest object). */
+function parseManifest(raw) {
+    const obj = JSON.parse(raw);
+    if (obj === null || typeof obj !== "object" || !Array.isArray(obj.fixtures)) {
+        throw new Error("CONF_MANIFEST_INVALID: manifest.fixtures must be an array");
+    }
+    return {
+        version: typeof obj.version === "string" ? obj.version : "2",
+        owner: typeof obj.owner === "string" ? obj.owner : "",
+        fixtures: obj.fixtures,
+    };
+}
+/**
+ * Read + normalize the v2 manifest and on-disk tree into a FixtureManifestV2.
+ * `fixtureRoot` is the conformance v2 root directory (injected by callers so
+ * `src/` stays runtime-independent of a hardcoded path).
+ */
+export function readFixtureManifestV2(fixtureRoot) {
+    const manifestRaw = readFileSync(join(fixtureRoot, "manifest.json"), "utf8");
+    const manifest = parseManifest(manifestRaw);
+    const byId = new Map();
+    const entries = [];
+    for (const fx of manifest.fixtures) {
+        const expectedDigest = String(fx.sha256 ?? "");
+        const domain = fx.domain ?? domainOf(fx.path);
+        const inputDigest = canonicalFileDigest(join(fixtureRoot, fx.path));
+        const entry = {
+            id: fx.id,
+            domain,
+            path: fx.path,
+            algorithm: fx.algorithm,
+            expected: fx.expected,
+            inputDigest,
+            expectedDigest,
+            expectedOutputDigest: typeof fx.outputDigest === "string" && fx.outputDigest.length > 0
+                ? fx.outputDigest
+                : undefined,
+            failureCode: fx.expected === "ok" ? undefined : fx.expected,
+            algorithmTuple: String(fx.algorithm).split(";").filter(Boolean).map((s) => s.trim()),
+        };
+        entries.push(entry);
+        byId.set(fx.id, entry);
+    }
+    return {
+        version: manifest.version,
+        owner: manifest.owner.split(",").map((s) => s.trim()).filter(Boolean),
+        fixtureEntries: entries,
+        byId,
+    };
+}
+/** The v2 domain a fixture path belongs to (first path segment). */
+export function domainOf(path) {
+    return path.split("/")[0] ?? "";
+}
+/**
+ * SHA-256 over the canonical JSON bytes of a fixture file. A missing file
+ * returns "" so `validateCanonicalV2` can report CONF_MISSING_FIXTURE instead of
+ * throwing ENOENT part-way through manifest normalization.
+ */
+function canonicalFileDigest(absPath) {
+    let raw;
+    try {
+        raw = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return "";
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        parsed = raw; // non-JSON (e.g. seeds as bytes) — digest raw
+    }
+    return sha256Hex(canonicalJson(parsed));
+}
+/**
+ * Validate the on-disk v2 corpus against the manifest. Rejects an extra,
+ * missing, or digest-drifted fixture file with the frozen codes. Also verifies
+ * the manifest itself is canonical (sorted keys, shortest numbers) — a
+ * noncanonical manifest is reported as NONCANONICAL.
+ */
+export function validateCanonicalV2(fixtureRoot) {
+    const codes = [];
+    const issues = [];
+    const manifestRaw = readFileSync(join(fixtureRoot, "manifest.json"), "utf8");
+    try {
+        const canonicalBytes = canonicalJson(JSON.parse(manifestRaw));
+        if (Buffer.from(manifestRaw, "utf8").toString("hex") !== canonicalBytes.toString("hex")) {
+            codes.push(CONF_FAIL.NONCANONICAL);
+            issues.push("manifest.json is not canonical");
+        }
+    }
+    catch {
+        codes.push(CONF_FAIL.NONCANONICAL);
+        issues.push("manifest.json is not valid JSON");
+    }
+    const manifest = readFixtureManifestV2(fixtureRoot);
+    const listedPaths = new Set(manifest.fixtureEntries.map((e) => e.path));
+    // Extra-file detection: every file under the root (except manifest) listed.
+    const onDisk = walk(fixtureRoot, fixtureRoot).filter((p) => p !== "manifest.json");
+    for (const p of onDisk) {
+        if (!listedPaths.has(p)) {
+            codes.push(CONF_FAIL.EXTRA_FIXTURE);
+            issues.push(`extra fixture: ${p}`);
+        }
+    }
+    // Missing + digest-drift for every listed fixture.
+    for (const entry of manifest.fixtureEntries) {
+        const abs = join(fixtureRoot, entry.path);
+        if (!exists(abs)) {
+            codes.push(CONF_FAIL.MISSING_FIXTURE);
+            issues.push(`missing fixture: ${entry.path}`);
+            continue;
+        }
+        const raw = readFileSync(abs, "utf8");
+        let canonicalHex;
+        try {
+            canonicalHex = sha256Hex(canonicalJson(JSON.parse(raw)));
+        }
+        catch {
+            canonicalHex = sha256Hex(Buffer.from(raw, "utf8"));
+        }
+        if (canonicalHex !== entry.expectedDigest) {
+            codes.push(CONF_FAIL.DIGEST_DRIFT);
+            issues.push(`digest drift for ${entry.path}: expected ${entry.expectedDigest} got ${canonicalHex}`);
+        }
+    }
+    // The canonical-key ordering invariant: a canonical valid manifest is a single
+    // reproducible digest. (Extra-file presence also breaks purity but is the
+    // extra/missing covers it.) Noncanonical keys are caught above.
+    if (codes.length === 0) {
+        return { ok: true, entryCount: manifest.fixtureEntries.length };
+    }
+    return { ok: false, codes: dedupeCodes(codes), issues };
+}
+/** True if the manifest+corpus is canonical (converges to one digest). */
+export function canonicalManifestsConverge(fixtureRoot) {
+    const v = validateCanonicalV2(fixtureRoot);
+    return v.ok;
+}
+function exists(p) {
+    try {
+        statSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function dedupeCodes(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}