pi-mega-compact 0.17.0 → 0.18.0

package/src/dedup/l1-minhash-v2.ts

@@ -0,0 +1,221 @@
+/**
+ * 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 as const;
+
+/** The published count of slots / seed pairs (frozen). */
+export const NUM_HASHES_V2 = 256 as const;
+
+/** Five-code-point shingle length (frozen). */
+export const SHINGLE_CP = 5 as const;
+
+/** 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 as const;
+
+/** 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 = 0x5eedc0de_f001_ba11n & 0xffffffffffffffffn;
+
+/** splitmix64 mixing constants (frozen). */
+const SM_GOLDEN = 0x9e3779b97f4a7c15n;
+const SM_M1 = 0xbf58476d1ce4e5b9n;
+const SM_M2 = 0x94d049bb133111ebn;
+const MASK64 = 0xffffffffffffffffn;
+
+function mix(z0: bigint): bigint {
+  let z = z0;
+  z = (z ^ (z >> 30n)) * SM_M1;
+  z &= MASK64;
+  z = (z ^ (z >> 27n)) * SM_M2;
+  z &= MASK64;
+  return z ^ (z >> 31n);
+}
+
+/** A splitmix64 PRNG yielding unsigned 64-bit values as BigInt. */
+export type SplitMix64 = () => bigint;
+
+/** Create a splitmix64 PRNG from a fixed unsigned 64-bit state. */
+export function splitmix64(state: bigint = SEED_STATE_INIT): SplitMix64 {
+  let s = state & MASK64;
+  return () => {
+    s = (s + SM_GOLDEN) & MASK64;
+    return mix(s) & MASK64;
+  };
+}
+
+export interface MinHashSeedPair {
+  readonly a: bigint;
+  readonly b: bigint;
+}
+
+/**
+ * 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: number = NUM_HASHES_V2,
+): readonly MinHashSeedPair[] {
+  return FROZEN_SEEDS.slice(0, count);
+}
+
+/** Singleton seed table, computed exactly once and frozen (see minhashV2Seeds). */
+const FROZEN_SEEDS: readonly MinHashSeedPair[] = (() => {
+  const prng = splitmix64();
+  const pairs: MinHashSeedPair[] = [];
+  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: string): bigint {
+  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: string,
+  shingleCp: number = SHINGLE_CP,
+  maxShingles = 50_000,
+): bigint[] {
+  const norm = normalize(text);
+  if (norm.length === 0) return [];
+  const cps = Array.from(norm); // code points
+  const set = new Set<bigint>();
+  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: string): bigint[] {
+  const grams = shinglesV2(text);
+  const seeds = minhashV2Seeds();
+  const sig = new Array<bigint>(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] as MinHashSeedPair;
+    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: readonly bigint[]): Uint8Array {
+  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] as bigint, 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: readonly bigint[], b: readonly bigint[]): number {
+  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: readonly bigint[]): void {
+  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/src/dedup/normalize.ts

@@ -33,7 +33,7 @@ export function normalize(text: string): string {
   if (!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) out = out.slice(0, MAX_CHARS);

package/src/store/sqlite/game-scores.ts

@@ -15,7 +15,8 @@
 import { getStateDir } from "../../store.js";
 import { openStore } from "./utils.js";
 import type { SQLInputValue } from "node:sqlite";
-import { GameMetric, METRICS } from "../../game/scoring.js";
+import type { GameMetric } from "../../game/scoring.js";
+import { METRICS } from "../../game/scoring.js";
 
 // Process-local monotonic sequence appended into the low 3 digits of `ts` so
 // back-to-back inserts within the same millisecond get distinct PK values

package/src/vector-cortex/conformance/emit.ts

@@ -0,0 +1,56 @@
+/**
+ * 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";
+
+export type ConformanceEmit = (event: string, fields: Record<string, unknown>) => void;
+
+/** The three-event reporter surface consumed by the runtime seams. */
+export interface ConformanceReporter {
+  readonly backfilled: (fields: Record<string, unknown>) => void;
+  readonly caseChecked: (fields: Record<string, unknown>) => void;
+  readonly downgradeWritten: (fields: Record<string, unknown>) => void;
+}
+
+/** A flag-gated no-op reporter (zero emissions, default when none injected). */
+export const NOOP_CONFORMANCE_REPORTER: ConformanceReporter = {
+  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?: ConformanceEmit): ConformanceReporter {
+  const fire = (event: string, fields: Record<string, unknown>): void => {
+    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/src/vector-cortex/conformance/manifest.ts

@@ -0,0 +1,298 @@
+/**
+ * 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",
+} as const;
+export type ConfFailureCode = (typeof CONF_FAIL)[keyof typeof CONF_FAIL];
+
+/** A normalized FixtureManifestV2 entry. */
+export interface FixtureManifestEntry {
+  readonly id: string;
+  readonly domain: string;
+  readonly path: string;
+  readonly algorithm: string;
+  readonly expected: string;
+  readonly inputDigest: string;
+  readonly expectedDigest: string;
+  readonly expectedOutputDigest?: string;
+  readonly failureCode?: string;
+  readonly algorithmTuple: readonly string[];
+}
+
+/** The parsed, normalized v2 manifest. */
+export interface FixtureManifestV2 {
+  readonly version: string;
+  readonly owner: readonly string[];
+  readonly fixtureEntries: readonly FixtureManifestEntry[];
+  /** id -> entry index for O(1) lookup. */
+  readonly byId: ReadonlyMap<string, FixtureManifestEntry>;
+}
+
+/** Result of a canonical manifest validation. */
+export type ManifestValidateResult =
+  | { ok: true; entryCount: number }
+  | { ok: false; codes: readonly ConfFailureCode[]; issues: readonly string[] };
+
+/** Walk a directory tree returning relative POSIX paths (sorted). */
+function walk(dir: string, base: string, acc: string[] = []): string[] {
+  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: unknown): string {
+  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 as Record<string, unknown>)
+    .map((k) => k.normalize("NFC"))
+    .sort();
+  const parts = keys.map(
+    (k) => `${JSON.stringify(k)}:${canonicalValue((value as Record<string, unknown>)[k])}`,
+  );
+  return `{${parts.join(",")}}`;
+}
+
+function canonicalJson(value: unknown): Buffer {
+  return Buffer.from(`${canonicalValue(value)}\n`, "utf8");
+}
+
+function sha256Hex(bytes: Uint8Array): string {
+  return sha256("sha256").update(bytes).digest("hex");
+}
+
+/** parse a manifest.json (must be a valid v2 manifest object). */
+function parseManifest(raw: string): {
+  version: string;
+  owner: string;
+  fixtures: Array<{
+    id: string;
+    path: string;
+    sha256: string;
+    algorithm: string;
+    expected: string;
+    domain?: string;
+    outputDigest?: string;
+  }>;
+} {
+  const obj = JSON.parse(raw) as {
+    version?: unknown;
+    owner?: unknown;
+    fixtures?: unknown;
+  };
+  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 as Array<{
+      id: string;
+      path: string;
+      sha256: string;
+      algorithm: string;
+      expected: string;
+      domain?: string;
+      outputDigest?: string;
+    }>,
+  };
+}
+
+/**
+ * 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: string): FixtureManifestV2 {
+  const manifestRaw = readFileSync(join(fixtureRoot, "manifest.json"), "utf8");
+  const manifest = parseManifest(manifestRaw);
+  const byId = new Map<string, FixtureManifestEntry>();
+  const entries: FixtureManifestEntry[] = [];
+  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: FixtureManifestEntry = {
+      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: string): string {
+  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: string): string {
+  let raw: string;
+  try {
+    raw = readFileSync(absPath, "utf8");
+  } catch {
+    return "";
+  }
+  let parsed: unknown;
+  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: string): ManifestValidateResult {
+  const codes: ConfFailureCode[] = [];
+  const issues: string[] = [];
+  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: string;
+    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: string): boolean {
+  const v = validateCanonicalV2(fixtureRoot);
+  return v.ok;
+}
+
+function exists(p: string): boolean {
+  try {
+    statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function dedupeCodes(codes: ConfFailureCode[]): ConfFailureCode[] {
+  const out: ConfFailureCode[] = [];
+  for (const c of codes) if (!out.includes(c)) out.push(c);
+  return out;
+}