pi-mega-compact 0.16.3 → 0.17.1

package/src/vector-cortex/ledger/types.ts

@@ -0,0 +1,141 @@
+/**
+ * vector-cortex/ledger/types.ts — EventV2 / EventCodec byte-authority contract
+ * types, validation result codes, and the registered EVT conformance ID range.
+ *
+ * Owned by VC1A (canonical byte events). Consumes only reviewer-accepted
+ * predecessor contracts and [common contracts](../../CONTRACTS.md §EventV2),
+ * which are NORMATIVE here. `originalBytes` and its SHA-256 digest are the byte
+ * authority; strict UTF-8 classification is never lossy; `canonicalNfc` is a
+ * DERIVED comparison/search key only (never identity, digest, or reconstruction).
+ *
+ * Pure type/schema definitions + a short pure digest/classify predicate runtime
+ * (validator codes). No network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** SHA-256 digest over the authoritative `originalBytes`, `sha256:<hex>`. */
+export type BytesDigest = `sha256:${string}`;
+
+/**
+ * EventV2 — the neutral byte-authority ledger occurrence. `schema:"event-v2"`
+ * is the discriminant tag of the union. Two events whose bytes differ by NFC
+ * normalization are DISTINCT identities (different `originalBytes`, different
+ * `bytesDigest`); their `canonicalNfc` (derived) may coincide but never drives
+ * equality, hashing, or byte reconstruction.
+ */
+export interface EventV2 {
+  schema: "event-v2";
+  sessionId: string;
+  seq: bigint;
+  eventId: string;
+  role: "policy" | "user" | "assistant" | "tool";
+  kind: string;
+  /** Authoritative original event bytes (byte authority). */
+  originalBytes: Uint8Array;
+  /** DigitalObjectIdentifier over originalBytes (authoritative digest). */
+  bytesDigest: BytesDigest;
+  /**
+   * Strict UTF-8 classification (NO lossy replacement). Invalid input is
+   * represented only as `{valid:false, base64}`.
+   */
+  utf8: { valid: true; text: string } | { valid: false; base64: string };
+  /** DERIVED NFC comparison/search key, valid UTF-8 only. Never identity. */
+  canonicalNfc?: string;
+  /** On a tool RESULT, references exactly one earlier CALL in this session. */
+  toolCallId?: string;
+  /** Wall-clock occurrence timestamp (monotonic for ordering; not the sort key). */
+  occurredAtMs: bigint;
+}
+
+/** Inputs to the byte-authority encoder. `bytes` is the sole byte source. */
+export interface EventEncodeInput {
+  sessionId: string;
+  seq: bigint;
+  eventId: string;
+  role: "policy" | "user" | "assistant" | "tool";
+  kind: string;
+  bytes: Uint8Array;
+  toolCallId?: string;
+  occurredAtMs: bigint;
+}
+
+/**
+ * EventCodec — byte-authority contract (normative, [CONTRACTS §EventV2]).
+ * `encode` computes the SHA-256 digest + strict UTF-8 classification + derived
+ * NFC; `decode` returns the authoritative `originalBytes` unchanged. Decoding
+ * never reconstructs bytes from normalized text — only from originalBytes.
+ */
+export interface EventCodec {
+  encode(input: EventEncodeInput): EventV2;
+  decode(event: EventV2): Uint8Array;
+  /**
+   * Strict UTF-8 classification: `fatal` decode succeeds, or the raw bytes are
+   * reported as `{valid:false, base64}` — never replacement-decode to U+FFFD.
+   */
+  classifyUtf8(bytes: Uint8Array): { valid: true; text: string } | { valid: false; base64: string };
+}
+
+/** Canonical validator failure codes (VC1A). */
+export type ValidationCode =
+  /** sha256(originalBytes) !== bytesDigest (authority corruption). */
+  | "EVT_DIGEST_MISMATCH"
+  /** The stored `utf8` discriminant contradicts a strict re-classification. */
+  | "EVT_UTF8_TAG_INVALID"
+  /** Duplicate (sessionId, seq, eventId) occurrence. */
+  | "EVT_DUPLICATE_ID";
+
+/**
+ * Deterministic validation result. `ok:false` carries the deduplicated failure
+ * codes (fixed priority order) AND the per-occurrence `issues` with real
+ * locators (sessionId/seq/eventId) so consumers can identify WHICH event failed.
+ */
+export type ValidationResult =
+  | { ok: true; ordered: readonly EventV2[] }
+  | { ok: false; codes: readonly ValidationCode[]; issues: readonly ValidationIssue[] };
+
+/** A single flagged validation issue (code + the offending occurrence locator). */
+export interface ValidationIssue {
+  readonly code: ValidationCode;
+  readonly sessionId: string;
+  readonly seq: bigint;
+  readonly eventId: string;
+}
+
+/**
+ * Registered EVT conformance ID range (EVT-001..030). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest bytes or
+ * exactly its listed failure code. Mirrors CUT_IDS / M3_IDS in replay/types.ts.
+ * EVT-001..015 are owned by VC1A (codec/validator); EVT-016..030 are owned by
+ * VC1B (occurrence ledger, see ledger/store.ts).
+ */
+export const EVT_IDS = [
+  "EVT-001",
+  "EVT-002",
+  "EVT-003",
+  "EVT-004",
+  "EVT-005",
+  "EVT-006",
+  "EVT-007",
+  "EVT-008",
+  "EVT-009",
+  "EVT-010",
+  "EVT-011",
+  "EVT-012",
+  "EVT-013",
+  "EVT-014",
+  "EVT-015",
+  "EVT-016",
+  "EVT-017",
+  "EVT-018",
+  "EVT-019",
+  "EVT-020",
+  "EVT-021",
+  "EVT-022",
+  "EVT-023",
+  "EVT-024",
+  "EVT-025",
+  "EVT-026",
+  "EVT-027",
+  "EVT-028",
+  "EVT-029",
+  "EVT-030",
+] as const;

package/src/vector-cortex/ledger/validator.ts

@@ -0,0 +1,124 @@
+/**
+ * vector-cortex/ledger/validator.ts — EventV2 canonical validation (VC1A).
+ *
+ * Canonical ordering is `(sessionId, seq, eventId bytewise UTF-8)`: the sort is
+ * by the eventId's UTF-8 BYTES (unsigned) — NOT by JS string code-unit order —
+ * so multi-byte eventIds sort bytewise. Deterministic failure detection with a
+ * fixed priority order:
+ *   1. EVT_DIGEST_MISMATCH   — sha256(originalBytes) !== bytesDigest
+ *   2. EVT_UTF8_TAG_INVALID  — stored `utf8` discriminant contradicting a strict
+ *                              fatal re-classification of originalBytes
+ *   3. EVT_DUPLICATE_ID      — duplicate (sessionId, seq, eventId) occurrence
+ *
+ * The unique failure injection requirement: flip ONE stored byte while retaining
+ * the SHA-256 signature — the digest recomputation diverges and the validator
+ * returns EVT_DIGEST_MISMATCH (never a lossy replacement text, which is not
+ * produced anywhere in this module).
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+
+import nodeCrypto from "node:crypto";
+import { classifyUtf8 } from "./event-codec.js";
+import type { BytesDigest, EventV2, ValidationCode, ValidationIssue, ValidationResult } from "./types.js";
+
+/** Mode-A digest recompute (validator uses the codec's canonical digest rule). */
+function digestOf(bytes: Uint8Array): BytesDigest {
+  const hex = nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+  return `sha256:${hex}`;
+}
+
+/** Bytewise UTF-8 comparator for eventId tiebreak (unsigned bytes, not code units). */
+function compareEventIdBytes(a: string, b: string): number {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  const n = Math.min(ab.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    if (ab[i] !== bb[i]) return ab[i] < bb[i] ? -1 : 1;
+  }
+  if (ab.length !== bb.length) return ab.length < bb.length ? -1 : 1;
+  return 0;
+}
+
+/** Comparator: `(sessionId, seq, eventId bytewise UTF-8)`. */
+export function compareEvents(a: EventV2, b: EventV2): number {
+  if (a.sessionId !== b.sessionId) return a.sessionId < b.sessionId ? -1 : 1;
+  if (a.seq !== b.seq) return a.seq < b.seq ? -1 : 1;
+  return compareEventIdBytes(a.eventId, b.eventId);
+}
+
+/** Ascending (sessionId, seq, eventId-bytes) sort. Returns a new array. */
+export function sortEvents(events: readonly EventV2[]): EventV2[] {
+  return [...events].sort(compareEvents);
+}
+
+/** Recompute the digest and compare to the stored one (authority corruption). */
+function digestMismatch(event: EventV2): boolean {
+  return digestOf(event.originalBytes) !== event.bytesDigest;
+}
+
+/** The stored utf8 discriminant must match a strict fatal re-classification. */
+function utf8TagMismatch(event: EventV2): boolean {
+  const cls = classifyUtf8(event.originalBytes);
+  const stored = event.utf8;
+  if (stored.valid !== cls.valid) return true;
+  if (!stored.valid) {
+    // Both invalid: never compare decoded text; only the (valid, base64) shape.
+    return false;
+  }
+  if (!cls.valid) return true; // unreachable given `stored.valid === cls.valid`
+  // Both valid: compare the strict-decoded TEXT (no NFC — the tag stores raw text).
+  return stored.text !== cls.text;
+}
+
+/**
+ * Validate a batch of events. Returns `{ok:true, ordered}` when every event
+ * passes digest + UTF-8-tag consistency and no duplicate occurrence exists;
+ * otherwise `{ok:false, codes}` with the failure codes in fixed priority order,
+ * deduplicated, and an explicit issue list for diagnostics.
+ */
+export function validateEvents(events: readonly EventV2[]): ValidationResult {
+  const issues: ValidationIssue[] = [];
+
+  // Fixed priority order: DIGEST_MISMATCH, UTF8_TAG_INVALID, DUPLICATE_ID.
+  for (const e of events) {
+    if (digestMismatch(e)) {
+      issues.push({ code: "EVT_DIGEST_MISMATCH", sessionId: e.sessionId, seq: e.seq, eventId: e.eventId });
+    }
+  }
+  for (const e of events) {
+    if (utf8TagMismatch(e)) {
+      issues.push({ code: "EVT_UTF8_TAG_INVALID", sessionId: e.sessionId, seq: e.seq, eventId: e.eventId });
+    }
+  }
+
+  // Unambiguous (sessionId, seq, eventId) occurrence key (seq stringified — a
+  // bigint cannot be JSON-serialized directly).
+  const key = (e: EventV2): string => JSON.stringify([e.sessionId, e.seq.toString(), e.eventId]);
+  const seen = new Set<string>();
+  for (const e of sortEvents(events)) {
+    const k = key(e);
+    if (seen.has(k)) {
+      issues.push({ code: "EVT_DUPLICATE_ID", sessionId: e.sessionId, seq: e.seq, eventId: e.eventId });
+    }
+    seen.add(k);
+  }
+
+  if (issues.length === 0) {
+    return { ok: true, ordered: sortEvents(events) };
+  }
+  // Surface the per-occurrence issues (real locators) alongside the deduped
+  // codes so the adapter/observability feed can name WHICH event failed.
+  return { ok: false, codes: dedupe(issues.map((i) => i.code)), issues };
+}
+
+function dedupe(codes: ValidationCode[]): ValidationCode[] {
+  const out: ValidationCode[] = [];
+  for (const c of codes) {
+    if (!out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+/** Export the canonical ordering comparator for consumers (replay etc.). */
+export { compareEventIdBytes };

package/src/vector-cortex/migrations/effective-cut-v2.ts

@@ -0,0 +1,149 @@
+/**
+ * vector-cortex/migrations/effective-cut-v2.ts — M3 copy/validate/switch
+ * migration (VC0B).
+ *
+ * Freezes the v2 effective replay cut: `min(boundarySafeSeq, committedSeq,
+ * capturedHighWater)` with pair retreat and anchor floor. The migration copies
+ * the candidate into the staged slot, validates the STAGED pointer against the
+ * minima and pair/anchor invariants (plus copy-match), and ONLY THEN atomically
+ * switches the active pointer. The three phases are exposed separately so a
+ * crash between validate and switch retains the OLD pointer and a restart
+ * resumes idempotently (the unique failure-injection contract).
+ *
+ * This is an internal developer seam: no dashboard/API change is necessary. It
+ * operates against the EXISTING host state via an injected M3Host interface —
+ * the future v2 compat-journal is owned by VC1B and is not introduced here.
+ */
+
+import { computeEffectiveCutV2 } from "../replay/cut.js";
+import type { ReplayToolPair, ReplayRetreatCode } from "../replay/types.js";
+
+/** Migration failure codes (registered in M3-001..010 as conformance rows). */
+export const M3_FAIL = {
+  MISSING_HOST: "M3_HOST_MISSING",
+  INVALID_MINIMA: "M3_MINIMA_VIOLATED",
+  PAIR_SPLIT: "M3_PAIR_SPLIT",
+  ANCHOR_CROSSED: "M3_ANCHOR_CROSSED",
+  COPY_MISMATCH: "M3_COPY_MISMATCH",
+} as const;
+export type M3FailureCode = (typeof M3_FAIL)[keyof typeof M3_FAIL];
+
+/** Live seq inputs that parameterize the effective cut. */
+export interface M3CutInput {
+  readonly requestedSeq: bigint;
+  readonly boundarySafeSeq: bigint;
+  readonly committedSeq: bigint;
+  readonly capturedHighWater: bigint;
+  readonly anchorFloor: bigint;
+  readonly pairs: readonly ReplayToolPair[];
+}
+
+/**
+ * Host state the migration reads/writes. copy/validate are read-only over host;
+ * switch is the only mutating step (atomically activates the staged pointer).
+ */
+export interface M3Host {
+  /** Actively used cut pointer (legacy prior). Never changes before switch. */
+  readonly oldPointer: bigint | null;
+  /** Persist the staged (new) cut pointer WITHOUT activating it. */
+  writeStaged(pointer: bigint): void;
+  /** The currently staged (new) pointer, persisted across restarts. */
+  stagedPointer(): bigint | null;
+  /** Contiguous durable authority high-water (min source). */
+  committedSeq(): bigint;
+  /** Atomic switch: activate the staged pointer and freeze the prior one. */
+  switchPointer(pointer: bigint): void;
+}
+
+export interface M3ValidateResult {
+  readonly ok: boolean;
+  readonly codes: readonly M3FailureCode[];
+  readonly retreats: readonly { code: ReplayRetreatCode; fromSeq: bigint; toSeq: bigint }[];
+  readonly effectiveSeq: bigint;
+}
+
+/** Pure effective-cut computation (min-of-three + retreat + floor). */
+export function m3Compute(input: M3CutInput): bigint {
+  return computeEffectiveCutV2(input).cut.effectiveSeq;
+}
+
+/**
+ * Phase 1 — copy: compute the candidate effective cut and stage it via the host
+ * (without activating). Returns the staged seq.
+ */
+export function m3Copy(host: M3Host, input: M3CutInput): bigint {
+  const effective = m3Compute(input);
+  host.writeStaged(effective);
+  return effective;
+}
+
+/**
+ * Phase 2 — validate: the host's STAGED pointer must equal the freshly computed
+ * effective cut (copy-match), respect the minima, not split a pair, and never
+ * fall below the anchor floor. Failure codes:
+ *   M3_HOST_MISSING     — no staged pointer at all
+ *   M3_COPY_MISMATCH    — staged != freshly computed effective
+ *   M3_MINIMA_VIOLATED  — effective exceeds a source minimum (or requested)
+ *   M3_PAIR_SPLIT       — effective splits a tool call/result pair
+ *   M3_ANCHOR_CROSSED   — effective is below the anchor floor
+ */
+export function m3Validate(host: M3Host, input: M3CutInput): M3ValidateResult {
+  const codes: M3FailureCode[] = [];
+  const { cut, retreats } = computeEffectiveCutV2(input);
+  const expected = cut.effectiveSeq;
+
+  const staged = host.stagedPointer();
+  if (staged === null) {
+    codes.push(M3_FAIL.MISSING_HOST);
+  } else {
+    if (staged !== expected) codes.push(M3_FAIL.COPY_MISMATCH);
+    if (
+      staged > input.boundarySafeSeq ||
+      staged > host.committedSeq() ||
+      staged > input.capturedHighWater ||
+      staged > input.requestedSeq
+    ) {
+      codes.push(M3_FAIL.INVALID_MINIMA);
+    }
+    for (const p of input.pairs) {
+      if (p.callSeq <= staged && staged < p.resultSeq) {
+        codes.push(M3_FAIL.PAIR_SPLIT);
+        break;
+      }
+    }
+    if (staged < input.anchorFloor) codes.push(M3_FAIL.ANCHOR_CROSSED);
+  }
+
+  return {
+    ok: codes.length === 0,
+    codes,
+    retreats,
+    effectiveSeq: expected,
+  };
+}
+
+/**
+ * Phase 3 — switch: atomic activation of the staged pointer. Only call after
+ * m3Validate reports ok; the host performs the durable pointer flip.
+ */
+export function m3Switch(host: M3Host, input: M3CutInput): bigint {
+  const effective = m3Compute(input);
+  host.switchPointer(effective);
+  return effective;
+}
+
+/**
+ * Run the full copy-validate-switch migration against a host. On validation
+ * failure the switch is NOT performed and the host retains its previous pointer
+ * (crash-safety / copy-validate-switch).
+ */
+export function migrateEffectiveCutV2(
+  host: M3Host,
+  input: M3CutInput,
+): { ok: boolean; codes: readonly M3FailureCode[]; effectiveSeq: bigint } {
+  m3Copy(host, input);
+  const v = m3Validate(host, input);
+  if (!v.ok) return { ok: false, codes: v.codes, effectiveSeq: v.effectiveSeq };
+  m3Switch(host, input);
+  return { ok: true, codes: [], effectiveSeq: v.effectiveSeq };
+}

package/src/vector-cortex/migrations/minhash-v2.ts

@@ -0,0 +1,263 @@
+/**
+ * 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,
+  type ConformanceReporter,
+} 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",
+} as const;
+export type M4MigrationCode = (typeof M4_FAIL)[keyof typeof M4_FAIL];
+
+/** A v2 signature row stored beside v1 (keyed by checkpoint id). */
+export interface V2SignatureRow {
+  readonly checkpointId: string;
+  readonly sessionId: string;
+  readonly version: number; // MINHASH_VERSION
+  readonly signatureBytes: Uint8Array; // 2048 LE bytes
+  readonly digest: string; // sha256: over signatureBytes
+  readonly buckets: readonly string[]; // 64 band keys
+}
+
+/** The host the migration reads from / writes to (capability-shaped). */
+export interface M4Host {
+  /** Full set of v1 checkpoint ids the index should cover. */
+  readonly v1CheckpointIds: () => readonly string[];
+  /** Session id a checkpoint belongs to (for bucket scoping). */
+  readonly sessionOf: (checkpointId: string) => string;
+  /** The raw source text for a checkpoint (to recompute a v2 signature). */
+  readonly sourceOf: (checkpointId: string) => string;
+  /** Persisted v2 rows already written (for resume/dedup + active pointer). */
+  readonly storedV2: () => readonly V2SignatureRow[];
+  /** The currently ACTIVE version (1 until a verified switch). */
+  readonly activeVersion: () => number;
+  /** Idempotent write of v2 rows (never mutates v1 rows). */
+  readonly putV2: (rows: readonly V2SignatureRow[]) => void;
+  /** Atomically switch the active version pointer to v2. */
+  readonly switchToV2: () => void;
+}
+
+/** An M4 migration failure result. */
+export interface M4ValidateResult {
+  readonly ok: boolean;
+  readonly codes: readonly M4MigrationCode[];
+}
+
+/** Reject a cross-version compare. Returns the frozen mismatch code. */
+export function crossVersionError(): M4MigrationCode {
+  return M4_FAIL.VERSION_MISMATCH;
+}
+
+/**
+ * Compute v2 signature + buckets for one checkpoint (the authoritative bytes).
+ * Pure and cross-language deterministic.
+ */
+export function computeV2Row(host: M4Host, checkpointId: string): V2SignatureRow {
+  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: Uint8Array): string {
+  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: M4Host,
+  reporter: ConformanceReporter = createConformanceReporter(),
+): readonly V2SignatureRow[] {
+  const wanted = host.v1CheckpointIds();
+  const existing = new Map(host.storedV2().map((r) => [r.checkpointId, r]));
+  const writes: V2SignatureRow[] = [];
+  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: V2SignatureRow, fresh: V2SignatureRow): boolean {
+  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: V2SignatureRow): boolean {
+  // 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] as string) !== (row.buckets[i] as string)) 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: M4Host): M4ValidateResult {
+  const codes: M4MigrationCode[] = [];
+  const wanted = new Set(host.v1CheckpointIds());
+  const stored = host.storedV2();
+  const counts = new Map<string, number>();
+  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: M4Host): void {
+  host.switchToV2();
+}
+
+/** Full M4 lifecycle: backfill -> verify -> switch; returns verify result. */
+export function migrateMinhashV2(
+  host: M4Host,
+  reporter: ConformanceReporter = createConformanceReporter(),
+): M4ValidateResult {
+  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",
+] as const;
+
+/** Registered named M4 conformance IDs. */
+export const M4_NAMED = [
+  "M4-HIGHBIT-001",
+  "M4-VERSION-002",
+  "M4-RESUME-003",
+] as const;
+
+function dedupe(codes: M4MigrationCode[]): M4MigrationCode[] {
+  const out: M4MigrationCode[] = [];
+  for (const c of codes) if (!out.includes(c)) out.push(c);
+  return out;
+}