pi-mega-compact 0.17.0 → 0.17.1

package/dist/src/vector-cortex/migrations/minhash-v2.js

@@ -0,0 +1,209 @@
+/**
+ * vector-cortex/migrations/minhash-v2.ts — M4 MinHashV2 copy/validate/switch
+ * migration (VC1C).
+ *
+ * M4 versions the L1 dedup signature store: v2 signatures/buckets are written
+ * BESIDE v1, backfilled by checkpoint id, verified, and only then switched as
+ * the active version. It follows the same copy/validate/switch + resume
+ * contract as M2 but for the minhash index:
+ *
+ *   - batch: writes v2 signatures + buckets for a set of checkpoint IDs, each
+ *     tagged with the frozen version 2; never touches v1 rows.
+ *   - backfill: resumable by checkpoint id — an interrupted run resumes without
+ *     duplicate v2 signatures or active-pointer drift.
+ *   - verify: counts per checkpoint match v1 and every v2 digest re-hashes.
+ *   - switch: atomically flips the ACTIVE VERSION pointer from v1 to v2; until
+ *     a verified switch, v1 remains active (interruption keeps old authority).
+ *
+ * Cross-version compare is REJECTED: a mixed v1-v2 similarity/bucket query
+ * returns `MINHASH_VERSION_MISMATCH` (never compares v1/v2 signatures).
+ *
+ * Pure logic over an injected M4Host (deterministic + testable; no console).
+ * PREVENT-002/011/PI-004 honored.
+ */
+import { createHash } from "node:crypto";
+import { MINHASH_VERSION, minhashV2Signature, encodeSignatureV2, } from "../../dedup/l1-minhash-v2.js";
+import { lshBandsV2, BANDS_V2, SIGNATURE_BYTES_EXPECTED_V2, } from "../../dedup/l1-lsh-v2.js";
+import { createConformanceReporter, } from "../conformance/emit.js";
+/** M4 failure codes. */
+export const M4_FAIL = {
+    VERSION_MISMATCH: "MINHASH_VERSION_MISMATCH",
+    BACKFILL_PARTIAL: "M4_BACKFILL_PARTIAL",
+    COUNT_MISMATCH: "M4_COUNT_MISMATCH",
+    DIGEST_MISMATCH: "M4_DIGEST_MISMATCH",
+};
+/** Reject a cross-version compare. Returns the frozen mismatch code. */
+export function crossVersionError() {
+    return M4_FAIL.VERSION_MISMATCH;
+}
+/**
+ * Compute v2 signature + buckets for one checkpoint (the authoritative bytes).
+ * Pure and cross-language deterministic.
+ */
+export function computeV2Row(host, checkpointId) {
+    const sessionId = host.sessionOf(checkpointId);
+    const source = host.sourceOf(checkpointId);
+    const sig = minhashV2Signature(source);
+    const bytes = encodeSignatureV2(sig);
+    const buckets = lshBandsV2(new Uint8Array(bytes), sessionId);
+    return {
+        checkpointId,
+        sessionId,
+        version: MINHASH_VERSION,
+        signatureBytes: new Uint8Array(bytes),
+        digest: `sha256:${sha256Hex(bytes)}`,
+        buckets,
+    };
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Backfill v2 signatures/buckets for all v1 checkpoint ids (resumable): rows
+ * already persisted with matching v2 digest/version are left untouched (no
+ * duplicates), and the active pointer stays at v1 until a verified switch.
+ * Returns the rows written this call (delta), never duplicates.
+ *
+ * An EXISTING row is re-computed and digest-verified before it is skipped; if
+ * the persisted row is corrupt (wrong version, wrong length, or a digest that
+ * no longer re-hashes its signatureBytes — e.g. a crash mid-write that left a
+ * truncated/bad row for an already-present id), it is recomputed and rewritten
+ * so corruption self-heals instead of being frozen by a later `m4Verify` failure.
+ */
+export function m4Backfill(host, reporter = createConformanceReporter()) {
+    const wanted = host.v1CheckpointIds();
+    const existing = new Map(host.storedV2().map((r) => [r.checkpointId, r]));
+    const writes = [];
+    for (const id of wanted) {
+        const row = computeV2Row(host, id);
+        const stored = existing.get(id);
+        if (stored !== undefined && v2RowMatches(stored, row))
+            continue; // healthy, no dup
+        writes.push(row); // absent, or stored row is corrupt -> (re)compute authoritative bytes
+    }
+    if (writes.length > 0) {
+        host.putV2(writes);
+        reporter.backfilled({
+            written: writes.length,
+            checkpointIds: writes.map((r) => r.checkpointId),
+        });
+    }
+    return writes;
+}
+/** True when a persisted row already matches the authoritative recompute. */
+function v2RowMatches(stored, fresh) {
+    return (stored.version === MINHASH_VERSION &&
+        stored.checkpointId === fresh.checkpointId &&
+        stored.sessionId === fresh.sessionId &&
+        stored.signatureBytes.length === fresh.signatureBytes.length &&
+        stored.digest === fresh.digest &&
+        bucketsMatch(stored));
+}
+/**
+ * Re-derive the 64 bucket keys from the row's signatureBytes + sessionId and
+ * compare every value to the stored buckets. This closes a defensive
+ * verification gap: a persisted row whose signatureBytes + digest are correct
+ * but whose bucket VALUES were written wrong (a writer defect, or a partial
+ * bucket write that still held 64 entries) would otherwise pass digest+count
+ * checks and be treated as healthy — yet the buckets are exactly the data the
+ * live LSH-dedup path queries. Buckets are deterministic from sigBytes +
+ * sessionId, so a mismatch is always a real storage/author defect.
+ */
+function bucketsMatch(row) {
+    // A wrong-length signature can't be banded (lshBandsV2 throws); the caller
+    // already reports it as a count/version mismatch, so fail closed here too.
+    if (row.signatureBytes.length !== SIGNATURE_BYTES_EXPECTED_V2)
+        return false;
+    if (row.buckets.length !== BANDS_V2)
+        return false;
+    const expected = lshBandsV2(new Uint8Array(row.signatureBytes), row.sessionId);
+    for (let i = 0; i < BANDS_V2; i++) {
+        if (expected[i] !== row.buckets[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Verify the backfilled v2 index: every v1 checkpoint has exactly one v2 row
+ * (reset -> resumable partial counts), each stored row's digest re-hashes, and
+ * each row has all 64 buckets. Never mutates.
+ */
+export function m4Verify(host) {
+    const codes = [];
+    const wanted = new Set(host.v1CheckpointIds());
+    const stored = host.storedV2();
+    const counts = new Map();
+    for (const r of stored) {
+        counts.set(r.checkpointId, (counts.get(r.checkpointId) ?? 0) + 1);
+        if (r.version !== MINHASH_VERSION)
+            codes.push(M4_FAIL.VERSION_MISMATCH);
+        if (r.signatureBytes.length !== 2048)
+            codes.push(M4_FAIL.COUNT_MISMATCH);
+        if (r.buckets.length !== BANDS_V2)
+            codes.push(M4_FAIL.COUNT_MISMATCH);
+        if (r.digest !== `sha256:${sha256Hex(r.signatureBytes)}`) {
+            codes.push(M4_FAIL.DIGEST_MISMATCH);
+        }
+        // Bucket VALUE verification: re-derive all 64 keys from signatureBytes +
+        // sessionId and compare them. Digest + count alone would let a row with
+        // correct sigBytes/digest but wrong bucket values pass; the buckets are the
+        // data the live LSH-dedup path queries, so a drifts here is a real defect.
+        if (!bucketsMatch(r))
+            codes.push(M4_FAIL.COUNT_MISMATCH);
+    }
+    // Every v1 checkpoint backfilled exactly once (count parity, no dup rows).
+    for (const id of wanted) {
+        const c = counts.get(id) ?? 0;
+        if (c === 0)
+            codes.push(M4_FAIL.BACKFILL_PARTIAL);
+        if (c > 1)
+            codes.push(M4_FAIL.COUNT_MISMATCH);
+    }
+    // No orphan v2 rows without a v1 checkpoint.
+    for (const id of counts.keys()) {
+        if (!wanted.has(id))
+            codes.push(M4_FAIL.COUNT_MISMATCH);
+    }
+    const ok = codes.length === 0;
+    return { ok, codes: dedupe(codes) };
+}
+/**
+ * Switch the active version to v2. Only call after `m4Verify` reports ok; a
+ * crash/return before switch leaves v1 active (interruption keeps old
+ * authority, resumable idempotently).
+ */
+export function m4Switch(host) {
+    host.switchToV2();
+}
+/** Full M4 lifecycle: backfill -> verify -> switch; returns verify result. */
+export function migrateMinhashV2(host, reporter = createConformanceReporter()) {
+    m4Backfill(host, reporter);
+    const v = m4Verify(host);
+    if (v.ok)
+        m4Switch(host);
+    return v;
+}
+/** Registered M4 conformance ID range (M4-001..008 + named M4-*). */
+export const M4_IDS = [
+    "M4-001",
+    "M4-002",
+    "M4-003",
+    "M4-004",
+    "M4-005",
+    "M4-006",
+    "M4-007",
+    "M4-008",
+];
+/** Registered named M4 conformance IDs. */
+export const M4_NAMED = [
+    "M4-HIGHBIT-001",
+    "M4-VERSION-002",
+    "M4-RESUME-003",
+];
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}

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;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * vector-cortex/conformance/runner.ts — v2 conformance runner (VC1C).
+ *
+ * Dispatches a conformance case STRICTLY by domain/version (no inference, no
+ * partial output on unknown) and compares both the canonical success bytes and
+ * the expected failure code. Owns `DowngradeReport`.
+ *
+ * The runner is triad-shaped (mode A client):
+ *   A = this manifest runner over the real algorithms;
+ *   B = an independent exact fixture reader (invertible digest recheck);
+ *   C = reject any unknown domain/version WITHOUT partial output.
+ *
+ * Downgrade export: `exporter` produces a new legacy copy that never edits
+ * authority data; the resulting `DowngradeReport` is deterministic — a second
+ * run yields a byte-identical report digest (CONF-DOWN-003).
+ *
+ * No network, no side effects on authority (PREVENT-PI-004 / PREVENT-011).
+ */
+import { CONF_FAIL } from "./manifest.js";
+import { createConformanceReporter, } from "./emit.js";
+const UNKNOWN_DOMAIN = "CONF_UNKNOWN_DOMAIN";
+const UNKNOWN_VERSION = "CONF_UNKNOWN_VERSION";
+/**
+ * The runner-pinned expectation mismatch code: a dispatched handler returned an
+ * outcome that contradicts the manifest entry's frozen expectation (the wrong
+ * failure code, or a success/failure parity error). This is the runner's own
+ * cross-check (task 5: "compare both success bytes and expected failure code"),
+ * distinct from the domain's own failure codes.
+ */
+const EXPECTATION_MISMATCH = "CONF_EXPECTATION_MISMATCH";
+export { UNKNOWN_DOMAIN, UNKNOWN_VERSION, EXPECTATION_MISMATCH };
+/**
+ * Run one conformance case by dispatching strictly on `(domain, algorithmTuple)`.
+ * If no handler is registered for the exact domain/algorithms, returns
+ * `CONF_UNKNOWN_DOMAIN`/`CONF_UNKNOWN_VERSION` WITHOUT partial output.
+ *
+ * After dispatch the runner cross-checks the handler's outcome against the
+ * manifest entry's frozen expectation (task 5):
+ *   - failure expected (`entry.failureCode` set): the handler must return
+ *     `ok:false` with that exact code, else `CONF_EXPECTATION_MISMATCH`;
+ *   - success expected (`entry.expected === "ok"`): the handler must return
+ *     `ok:true`, and when the manifest pins an `expectedOutputDigest` the
+ *     handler's `outputDigest` must match it, else `CONF_DIGEST_DRIFT`.
+ */
+export function runConformanceCase(entry, handlers, fixture, reporter = createConformanceReporter()) {
+    const key = `${entry.domain}::${entry.algorithmTuple.join(";")}`;
+    const handler = handlers.get(key);
+    let result;
+    if (!handler) {
+        if (entry.domain === "") {
+            result = { ok: false, code: UNKNOWN_DOMAIN, algorithm: entry.algorithm };
+        }
+        else {
+            result = { ok: false, code: UNKNOWN_VERSION, algorithm: entry.algorithm };
+        }
+    }
+    else {
+        const out = handler.run(entry, fixture);
+        if (out.ok) {
+            // Success expected? The manifest entry pins the expected success bytes.
+            if (entry.expected !== "ok") {
+                result = { ok: false, code: EXPECTATION_MISMATCH, algorithm: entry.algorithm };
+            }
+            else if (entry.expectedOutputDigest !== undefined &&
+                out.outputDigest !== entry.expectedOutputDigest) {
+                result = { ok: false, code: CONF_FAIL.DIGEST_DRIFT, algorithm: entry.algorithm };
+            }
+            else {
+                result = { ok: true, outputDigest: out.outputDigest, algorithm: entry.algorithm };
+            }
+        }
+        else {
+            // Failure expected? The manifest entry pins the exact failure code.
+            if (entry.failureCode !== undefined && out.code === entry.failureCode) {
+                result = { ok: false, code: out.code, algorithm: entry.algorithm };
+            }
+            else {
+                result = { ok: false, code: EXPECTATION_MISMATCH, algorithm: entry.algorithm };
+            }
+        }
+    }
+    reporter.caseChecked({
+        id: entry.id,
+        domain: entry.domain,
+        algorithm: entry.algorithm,
+        ok: result.ok,
+        ...(result.ok ? { outputDigest: result.outputDigest } : { code: result.code }),
+    });
+    return result;
+}
+/**
+ * Build a dispatch key for a (domain, algorithmTuple) pair. Callers register
+ * handlers under this key.
+ */
+export function handlerKey(domain, algorithmTuple) {
+    return `${domain}::${algorithmTuple.join(";")}`;
+}
+/**
+ * Run a downgrade export and recompute its report digest deterministically.
+ * A second invocation produces a byte-identical report (CONF-DOWN-003).
+ */
+export function runDowngradeExport(exporter, reporter = createConformanceReporter()) {
+    const report = exporter.exportOnce();
+    reporter.downgradeWritten({
+        exportedCopyId: report.exportedCopyId,
+        copiedCount: report.copiedCount,
+        unrepresentableIds: report.unrepresentableIds,
+        reportDigest: report.reportDigest,
+    });
+    return report;
+}