pi-mega-compact 0.16.3 → 0.17.1

package/dist/vector-cortex/ledger/store.js

@@ -0,0 +1,184 @@
+/**
+ * vector-cortex/ledger/store.ts — VC1B capability-separated ledger contracts.
+ *
+ * Owns `LedgerReader` / `LedgerWriter` / `LedgerAdmin` and `CompatJournalV1`.
+ * The ledger is append-only, seq is monotonic per session, a tool RESULT names
+ * exactly one earlier call in the same session, and duplicates are identified by
+ * `(eventId, digest)` only (two occurrences may share bytes at distinct seq).
+ *
+ * Capability gating mirrors the host `asReader/asWriter/asAdmin` pattern: a
+ * consumer receives ONLY what it needs. Dashboard GET receives `LedgerReader`;
+ * only ingestion receives `LedgerWriter`; only the migration coordinator
+ * receives `LedgerAdmin`. This keeps the neutral byte-authority ledger closed to
+ * anything but the sanctioned channels (CONTRACTS §Store and migration
+ * contracts).
+ *
+ * Pure type/schema definitions + small pure predicates. No storage, no console,
+ * no network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+import { VC1B_ENABLED } from "../../config/vector-cortex.js";
+import { openOccurrenceStore, appendOccurrence, ledgerHighWater, readSessionOccurrences, readFromSeq, countOccurrences, hasOccurrence, } from "./sqlite.js";
+import { initCompatJournal, createCompatJournal, journalPhase, } from "./compat-journal.js";
+import { m2Copy, m2Validate, m2Switch, } from "../migrations/occurrence-v2.js";
+/** The token that gates closures to a single capability (PREVENT-011-free). */
+const _capability = Symbol("mc-ledger-capability");
+/**
+ * Create the capability-separated occurrence-v2 ledger over its OWN isolated
+ * SQLite DB. `emit` is optional; occurrence-appended and compat-switch-committed
+ * events are only emitted when VC1B_ENABLED() and an emitter is supplied (mode-C
+ * parity: flag OFF / no emitter => zero observability writes).
+ *
+ * Normalization: `stateDir` gives the standard daemon location
+ * `<stateDir>/vector-cortex/occurrence-v2.db`; a bare `dbPath` overrides it
+ * (tests/rehearsal isolate the ledger). The compat journal shares the same DB
+ * so a v2 append + its journal record commit atomically.
+ */
+export function createLedgerStore(opts, emit) {
+    const dbPath = "dbPath" in opts
+        ? opts.dbPath
+        : `${opts.stateDir}/vector-cortex/occurrence-v2.db`;
+    const db = openOccurrenceStore(dbPath);
+    initCompatJournal(db);
+    const compat = createCompatJournal(db);
+    const fire = (event, fields) => {
+        if (!VC1B_ENABLED())
+            return;
+        try {
+            emit?.(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    };
+    const asReader = () => ({
+        kind: "LedgerReader",
+        [_capability]: "reader",
+        highWater: (session) => ledgerHighWater(db, session),
+        readSession: (session) => readSessionOccurrences(db, session),
+        readFrom: (session, fromSeq) => readFromSeq(db, session, fromSeq),
+        count: (session) => countOccurrences(db, session),
+        hasOccurrence: (session, eventId, digest) => hasOccurrence(db, session, eventId, digest),
+    });
+    const asWriter = () => ({
+        kind: "LedgerWriter",
+        [_capability]: "writer",
+        append(input) {
+            // The occurrence insert and its compat-journal record commit atomically
+            // inside one nested savepoint (CONTRACTS §Store: atomically appends).
+            db.exec("SAVEPOINT mc_ledger_app");
+            try {
+                const result = appendOccurrence(db, input);
+                if (result.ok) {
+                    compat.record({
+                        occurrence: result.occurrence,
+                        legacyProjection: legacyProjectionOf(result.occurrence),
+                    });
+                }
+                if (result.ok) {
+                    db.exec("RELEASE mc_ledger_app");
+                    fire("vector_cortex_occurrence_appended", {
+                        session: result.occurrence.session,
+                        seq: result.occurrence.seq.toString(),
+                        eventId: result.occurrence.eventId,
+                        digest: result.occurrence.digest,
+                        kind: result.occurrence.kind,
+                    });
+                }
+                else {
+                    db.exec("ROLLBACK TO mc_ledger_app");
+                    db.exec("RELEASE mc_ledger_app");
+                }
+                return result;
+            }
+            catch (e) {
+                db.exec("ROLLBACK TO mc_ledger_app");
+                db.exec("RELEASE mc_ledger_app");
+                throw e;
+            }
+        },
+        appendBatch(inputs) {
+            const out = [];
+            for (const input of inputs)
+                out.push(this.append(input));
+            return out;
+        },
+    });
+    const asAdmin = () => ({
+        kind: "LedgerAdmin",
+        [_capability]: "admin",
+        compat,
+        migrateOccurrenceV2() {
+            // copy => validate => switch; resumable & idempotent. The M2 host wraps
+            // the live DB + journal so every phase transition advances the SAME
+            // singleton journal state machine (prepared→copied→validated→switched).
+            const unrepresentable = compat.prepare().length;
+            const mig = migrateHost(db, compat);
+            m2Copy(mig);
+            const v = m2Validate(mig);
+            if (v.ok) {
+                m2Switch(mig);
+                fire("vector_cortex_compat_switch_committed", {
+                    session: "all",
+                    unrepresentable,
+                });
+            }
+            return { ok: v.ok, codes: v.codes };
+        },
+    });
+    return { reader: asReader, writer: asWriter, admin: asAdmin, close: () => db.close() };
+}
+/**
+ * Lossless legacy projection for a v2 occurrence: its identity envelope plus
+ * base64 source bytes. Returns null (→ journal `unrepresentable` marker) when the
+ * source bytes do not form valid UTF-8, which the legacy pipeline cannot round-trip
+ * losslessly — those rows are listed rather than silently coerced (MIG-DOWN-003).
+ */
+function legacyProjectionOf(occ) {
+    const source = Buffer.from(occ.sourceBytes);
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(source);
+    }
+    catch {
+        return null;
+    }
+    return JSON.stringify({
+        session: occ.session,
+        eventId: occ.eventId,
+        kind: occ.kind,
+        digest: occ.digest,
+        source: source.toString("base64"),
+    });
+}
+/** Build an M2Host over the live ledger DB + journal (for migrateOccurrenceV2). */
+function migrateHost(db, journal) {
+    let staged = null;
+    return {
+        db,
+        phase: () => journalPhase(db),
+        journalActive: () => journal.active(),
+        journalRows: () => journalRowsOf(db),
+        writeStagedLegacy: (rows) => {
+            staged = rows;
+            journal.copied();
+        },
+        stagedLegacy: () => staged,
+        validateStaged: () => journal.validate(),
+        switchLegacy: () => journal.switched(),
+    };
+}
+/** Read the journaled occurrences as legacy-export rows. */
+function journalRowsOf(db) {
+    const rows = db
+        .prepare(`SELECT session, seq, event_id, digest, kind, legacy_projection, unrepresentable
+       FROM compat_journal_v1 ORDER BY session ASC, seq ASC`)
+        .all();
+    return rows.map((r) => ({
+        session: r.session,
+        seq: BigInt(r.seq),
+        eventId: r.event_id,
+        digest: r.digest,
+        kind: r.kind,
+        legacyProjection: r.legacy_projection,
+        unrepresentable: r.unrepresentable === 1,
+    }));
+}

package/dist/vector-cortex/ledger/types.js

@@ -0,0 +1,52 @@
+/**
+ * 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).
+ */
+/**
+ * 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",
+];

package/dist/vector-cortex/ledger/validator.js

@@ -0,0 +1,117 @@
+/**
+ * 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";
+/** Mode-A digest recompute (validator uses the codec's canonical digest rule). */
+function digestOf(bytes) {
+    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, b) {
+    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, b) {
+    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) {
+    return [...events].sort(compareEvents);
+}
+/** Recompute the digest and compare to the stored one (authority corruption). */
+function digestMismatch(event) {
+    return digestOf(event.originalBytes) !== event.bytesDigest;
+}
+/** The stored utf8 discriminant must match a strict fatal re-classification. */
+function utf8TagMismatch(event) {
+    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) {
+    const issues = [];
+    // 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) => JSON.stringify([e.sessionId, e.seq.toString(), e.eventId]);
+    const seen = new Set();
+    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) {
+    const out = [];
+    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/dist/vector-cortex/migrations/effective-cut-v2.js

@@ -0,0 +1,103 @@
+/**
+ * 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";
+/** 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",
+};
+/** Pure effective-cut computation (min-of-three + retreat + floor). */
+export function m3Compute(input) {
+    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, input) {
+    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, input) {
+    const codes = [];
+    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, input) {
+    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, input) {
+    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/dist/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;
+}