pi-mega-compact 0.16.3 → 0.17.1

package/dist/src/config.js

@@ -109,3 +109,9 @@ export const RAG_MEMORY_GRAPH = () => ragEnabled("MEGACOMPACT_MEMORY_GRAPH");
 export const RAG_HYDE_ENABLED = () => ragEnabled("MEGACOMPACT_HYDE");
 /** Spec 1: vbrainstorm visual design migration for the dashboard. */
 export const NEW_UI = () => ragEnabled("MEGACOMPACT_NEW_UI");
+// ---------------------------------------------------------------------------
+// Vector-cortex flags + breaker constants (VC0A+). Positive sprint flags,
+// default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
+// so root consumers share one source of truth.
+// ---------------------------------------------------------------------------
+export { VC0A_ENABLED, VC0B_ENABLED, VC1A_ENABLED, VC0C_ENABLED, VC1B_ENABLED, VC1C_ENABLED, BREAKER_WINDOW_MS, BREAKER_MIN_ATTEMPTS, BREAKER_PERF_FAILURES, BREAKER_PERF_FAILURE_RATE, BREAKER_CORRECTNESS_FAILURES, BREAKER_COOLDOWN_MS, BREAKER_PROBE_COUNT, BREAKER_RETRY_BASE_MS, BREAKER_RETRY_CAP_MS, BREAKER_RETRY_JITTER, BREAKER_HYSTERESIS_FAILURE_RATE, BREAKER_HYSTERESIS_BUDGET_P95_MS, BREAKER_MIN_HEALTHY_RESIDENCE_MS, } from "./config/vector-cortex.js";

package/dist/src/dedup/l1-lsh-v2.js

@@ -0,0 +1,60 @@
+/**
+ * l1-lsh-v2.ts — Locality-Sensitive Hashing banding over MinHashV2 signatures
+ * (VC1C, M4 minhash-v2).
+ *
+ * Splits the frozen 2048-byte v2 signature (256 x u64 LE slots) into 64 bands
+ * of FOUR u64 values each. Each band yields a deterministic bucket key derived
+ * from its 4 u64 little-endian bytes (32 bytes) hashed with a 64-bit FNV-1a,
+ * scoped by session id and the frozen v2 version tag so buckets never collide
+ * across sessions or the v1 path. Deterministic: same (sessionId,
+ * signatureBytes) -> same 64 bucket keys, every run, every language.
+ *
+ * Mixed v1/v2 comparison and bucket mixing is REJECTED upstream with
+ * `MINHASH_VERSION_MISMATCH` (see minhash-v2 migration); this module only ever
+ * bands a v2 signature.
+ *
+ * Pure compute, no deps, no storage, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { MINHASH_VERSION, NUM_HASHES_V2, U64_BYTES, } from "./l1-minhash-v2.js";
+/** Number of bands (frozen). */
+export const BANDS_V2 = 64;
+/** u64 slots per band (frozen): 64 * 4 = 256 total slots. */
+export const VALUES_PER_BAND_V2 = 4;
+/** Band byte length: 4 u64 LE = 32 bytes. */
+export const BAND_BYTES_V2 = VALUES_PER_BAND_V2 * U64_BYTES;
+/** Total signature byte length this scheme expects (256 * 8 = 2048). */
+export const SIGNATURE_BYTES_EXPECTED_V2 = NUM_HASHES_V2 * U64_BYTES;
+const MASK64 = 0xffffffffffffffffn;
+/** 64-bit FNV-1a over a byte buffer. */
+function fnv1a64Bytes(buf) {
+    let h = 0xcbf29ce484222325n;
+    for (let i = 0; i < buf.length; i++) {
+        h ^= BigInt(buf[i] ?? 0);
+        h = (h * 0x100000001b3n) & MASK64;
+    }
+    return h;
+}
+/**
+ * Compute the 64 LSH bucket keys for a v2 signature within a session. `bytes`
+ * is the 2048-byte little-endian signature (see encodeSignatureV2). Each bucket
+ * key is the hex of an 8-byte little-endian FNV-1a-64 over the band's 32 bytes
+ * prefixed by `<sessionId>|v2|band-` — so the "bucket bytes" are deterministic
+ * and reproducible across languages.
+ */
+export function lshBandsV2(bytes, sessionId, version = MINHASH_VERSION) {
+    if (bytes.length !== SIGNATURE_BYTES_EXPECTED_V2) {
+        throw new Error(`lshBandsV2: expected ${SIGNATURE_BYTES_EXPECTED_V2} signature bytes, got ${bytes.length}`);
+    }
+    const keys = [];
+    const prefix = Buffer.from(`${sessionId}|v${version}|`, "utf8");
+    for (let band = 0; band < BANDS_V2; band++) {
+        const start = band * BAND_BYTES_V2;
+        const bandBytes = bytes.slice(start, start + BAND_BYTES_V2);
+        const combined = Buffer.concat([prefix, Buffer.from(bandBytes)]);
+        const h = fnv1a64Bytes(combined);
+        const out = Buffer.allocUnsafe(U64_BYTES);
+        out.writeBigUInt64LE(h, 0);
+        keys.push(`b${band}:${out.toString("hex")}`);
+    }
+    return keys;
+}

package/dist/src/dedup/l1-minhash-v2.js

@@ -0,0 +1,193 @@
+/**
+ * l1-minhash-v2.ts — MinHash V2 signatures (VC1C, M4 minhash-v2).
+ *
+ * The v1 path (l1-minhash.ts) uses 32-bit universal hashing with `p=2^31-1`
+ * and Number math, which is exact because a*x < 2^62 can overflow double
+ * precision (>= 2^53) and is reduced too eagerly. MinHashV2 freezes a v2
+ * scheme that is CROSS-LANGUAGE deterministic and byte-exact:
+ *
+ *   - normalization: the stable `normalize()` from normalize.ts (NFC, NFKC
+ *     case-fold, CRLF->LF, whitespace collapse, 32K cap);
+ *   - shingles: windows of FIVE CODE POINTS over the normalized text
+ *     (SHINGLE_CP=5), each shingle hashed to a u64 with 64-bit FNV-1a over its
+ *     UTF-8 bytes;
+ *   - 256 PUBLISHED unsigned (a_i, b_i) seed pairs, derived deterministically
+ *     via splitmix64 and listed in
+ *     conformance/vector-cortex/v2/minhash/seeds-v2.json;
+ *   - p = 2^61 - 1 (2305843009213693951), EXACT BigInt multiply/modulo — a_i*x
+ *     can reach ~2^124 so Number math would silently corrupt high-bit products;
+ *   - signature = 256 slots, slot i = min over shingles of (a_i*x + b_i) mod p;
+ *     the empty signature is all-`p` sentinel slots;
+ *   - encoding: 256 x u64 LITTLE-ENDIAN bytes (2048 bytes total);
+ *   - bands: 64 bands of FOUR u64 slots each (256 total), see l1-lsh-v2.ts.
+ *
+ * NEVER compares a v2 signature against a v1 signature — cross-version compare
+ * is rejected with `MINHASH_VERSION_MISMATCH` (see minhash-v2 migration).
+ *
+ * Pure compute, no deps, no storage, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { normalize } from "./normalize.js";
+/** MinHashV2 scheme version tag (frozen). */
+export const MINHASH_VERSION = 2;
+/** The published count of slots / seed pairs (frozen). */
+export const NUM_HASHES_V2 = 256;
+/** Five-code-point shingle length (frozen). */
+export const SHINGLE_CP = 5;
+/** p = 2^61 - 1 (Mersenne prime), as exact BigInt. */
+export const P_V2 = (1n << 61n) - 1n;
+/** Little-endian bytes per u64 signature slot. */
+export const U64_BYTES = 8;
+/** Signature byte length: 256 slots x 8 LE bytes. */
+export const SIGNATURE_BYTES_V2 = NUM_HASHES_V2 * U64_BYTES;
+/** Fixed splitmix64 initial state so the seed table is reproducible everywhere. */
+export const SEED_STATE_INIT = 0x5eedc0def001ba11n & 0xffffffffffffffffn;
+/** splitmix64 mixing constants (frozen). */
+const SM_GOLDEN = 0x9e3779b97f4a7c15n;
+const SM_M1 = 0xbf58476d1ce4e5b9n;
+const SM_M2 = 0x94d049bb133111ebn;
+const MASK64 = 0xffffffffffffffffn;
+function mix(z0) {
+    let z = z0;
+    z = (z ^ (z >> 30n)) * SM_M1;
+    z &= MASK64;
+    z = (z ^ (z >> 27n)) * SM_M2;
+    z &= MASK64;
+    return z ^ (z >> 31n);
+}
+/** Create a splitmix64 PRNG from a fixed unsigned 64-bit state. */
+export function splitmix64(state = SEED_STATE_INIT) {
+    let s = state & MASK64;
+    return () => {
+        s = (s + SM_GOLDEN) & MASK64;
+        return mix(s) & MASK64;
+    };
+}
+/**
+ * Derive the frozen 256 published (a_i, b_i) seed pairs. Each pair maps two
+ * splitmix64 draws into [1, p-1]. Deterministic and cross-language reproducible
+ * from SEED_STATE_INIT — mirrors `seeds-v2.json`.
+ *
+ * The table is frozen: computed ONCE at module load and reused for every call.
+ * Recomputing the 256 splitmix64 pairs (and re-walking all shingles) per
+ * signature/backfill row is wasteful for a large v1 index backfill, and the
+ * table is immutable by construction, so a single shared instance is safe and
+ * byte-identical. The returned sub-arrays share the frozen pair objects; they
+ * are themselves frozen so no caller can mutate the shared cache.
+ */
+export function minhashV2Seeds(count = NUM_HASHES_V2) {
+    return FROZEN_SEEDS.slice(0, count);
+}
+/** Singleton seed table, computed exactly once and frozen (see minhashV2Seeds). */
+const FROZEN_SEEDS = (() => {
+    const prng = splitmix64();
+    const pairs = [];
+    for (let i = 0; i < NUM_HASHES_V2; i++) {
+        const a = (prng() % (P_V2 - 1n)) + 1n;
+        const b = (prng() % (P_V2 - 1n)) + 1n;
+        pairs.push(Object.freeze({ a, b }));
+    }
+    return Object.freeze(pairs);
+})();
+/** 64-bit FNV-1a over a UTF-8 string (for shingle hashing). */
+function fnv1a64String(s) {
+    let h = 0xcbf29ce484222325n;
+    const bytes = Buffer.from(s, "utf8");
+    for (let i = 0; i < bytes.length; i++) {
+        h ^= BigInt(bytes[i] ?? 0);
+        h = (h * 0x100000001b3n) & MASK64;
+    }
+    return h;
+}
+/**
+ * Five-code-point shingle set (deduped, capped) of normalized text as u64
+ * hashes. Iterates over code points (not UTF-16 code units) so astral-plane
+ * characters do not split a shingle.
+ */
+export function shinglesV2(text, shingleCp = SHINGLE_CP, maxShingles = 50_000) {
+    const norm = normalize(text);
+    if (norm.length === 0)
+        return [];
+    const cps = Array.from(norm); // code points
+    const set = new Set();
+    if (cps.length < shingleCp) {
+        set.add(fnv1a64String(norm));
+    }
+    else {
+        for (let i = 0; i + shingleCp <= cps.length; i++) {
+            const sh = cps.slice(i, i + shingleCp).join("");
+            set.add(fnv1a64String(sh));
+            if (set.size >= maxShingles)
+                break;
+        }
+    }
+    return [...set];
+}
+/**
+ * Compute the 256-slot MinHashV2 signature of a text as an array of exact u64
+ * BigInt values (each in [0, p], p = sentinel when empty). Uses EXACT BigInt
+ * multiply/modulo so high-bit products (a*x ~ up to 2^124) are never corrupted.
+ */
+export function minhashV2Signature(text) {
+    const grams = shinglesV2(text);
+    const seeds = minhashV2Seeds();
+    const sig = new Array(NUM_HASHES_V2).fill(P_V2);
+    if (grams.length === 0)
+        return sig;
+    for (let i = 0; i < NUM_HASHES_V2; i++) {
+        const { a, b } = seeds[i];
+        let min = P_V2;
+        for (const x of grams) {
+            const h = (a * x + b) % P_V2;
+            if (h < min)
+                min = h;
+        }
+        sig[i] = min;
+    }
+    return sig;
+}
+/** Encode a 256-slot signature to 2048 bytes as 256 x u64 little-endian. */
+export function encodeSignatureV2(sig) {
+    if (sig.length !== NUM_HASHES_V2) {
+        throw new Error(`encodeSignatureV2: expected ${NUM_HASHES_V2} slots, got ${sig.length}`);
+    }
+    const buf = Buffer.allocUnsafe(SIGNATURE_BYTES_V2);
+    for (let i = 0; i < NUM_HASHES_V2; i++) {
+        buf.writeBigUInt64LE(sig[i], i * U64_BYTES);
+    }
+    return new Uint8Array(buf);
+}
+/**
+ * Estimated Jaccard similarity of two v2 signatures (fraction of equal slots).
+ *
+ * THIS IS v2-ONLY. Cross-version compare is rejected INTERNALLY with
+ * `MINHASH_VERSION_MISMATCH`: both inputs must be exact 256-slot v2 signatures,
+ * i.e. every slot a `bigint` in [0, P_V2] (the empty sentinel is exactly P_V2).
+ * A v1 signature is a `number[]` of u31 values, so passing a v1 array fails the
+ * bigint type/range check and is rejected — a mixed v1/v2 compare can never
+ * produce a similarity number. Never call this with v1 arrays.
+ */
+export function signatureSimilarityV2(a, b) {
+    assertV2Signature(a);
+    assertV2Signature(b);
+    const n = Math.min(a.length, b.length);
+    if (n === 0)
+        return 0;
+    let equal = 0;
+    for (let i = 0; i < n; i++)
+        if (a[i] === b[i])
+            equal++;
+    return equal / n;
+}
+/** Reject any array that is not an exact 256-slot v2 signature (bigint in [0, P_V2]). */
+function assertV2Signature(sig) {
+    if (sig.length !== NUM_HASHES_V2) {
+        throw new Error(MINHASH_VERSION_MISMATCH_MSG);
+    }
+    for (const s of sig) {
+        if (typeof s !== "bigint" || s < 0n || s > P_V2) {
+            throw new Error(MINHASH_VERSION_MISMATCH_MSG);
+        }
+    }
+}
+/** Frozen cross-version-reject message shared by the v2-only function guards. */
+const MINHASH_VERSION_MISMATCH_MSG = "MINHASH_VERSION_MISMATCH";

package/dist/src/dedup/normalize.js

@@ -30,7 +30,7 @@ export function normalize(text) {
         return "";
     let out = stripAnsi(text);
     out = out.normalize("NFC");
-    out = out.toLocaleLowerCase(); // case-fold so "Foo"/"FOO" collapse to one key
+    out = out.toLowerCase(); // case-fold so "Foo"/"FOO" collapse to one key (locale-independent: byte-exact across languages)
     out = out.replace(/\r\n?/g, "\n"); // CRLF / CR → LF
     out = out.replace(/\s+/g, " ").trim();
     if (out.length > MAX_CHARS)

package/dist/src/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/src/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/src/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;
+}