pi-mega-compact 0.16.3 → 0.17.1

package/dist/src/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/src/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/src/vector-cortex/migrations/minhash-v2.js

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

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

@@ -0,0 +1,139 @@
+/**
+ * vector-cortex/migrations/occurrence-v2.ts — M2 copy/validate/switch migration
+ * for the occurrence-v2 ledger + compat journal (VC1B).
+ *
+ * M2 converts the neutral v2 ledger into a lossless legacy export so an OLD
+ * binary may keep reading after a downgrade. It follows the compat-journal
+ * copy/validate/switch contract: COPY the v2 rows + journal records into the
+ * staged legacy export, VALIDATE the staged export (seq monotonicity + digest
+ * parity + unrepresentable rows listed), and ONLY THEN atomically SWITCH
+ * authority to the export. Each phase is exposed separately so a crash between
+ * validate and switch retains the OLD authority and a restart resumes
+ * idempotently (the unique failure-injection contract — terminate after
+ * `validated` and before `switched`, restart switches once without duplicate
+ * rows).
+ *
+ * Runs against an injected M2Host so the migration is deterministic and
+ * testable. Never mutates v2; the export is a NEW copy (silent direct downgrade
+ * is rejected). Registered conformance rows: M2-001..015 + MIG-DOWN-001.
+ * PREVENT-002/011/PI-004 honored; no console.log.
+ */
+import { MIG_DOWN_FAIL, verifyLegacyDigest } from "../ledger/compat-journal.js";
+/** M2 failure codes (downgrade export). */
+export const M2_FAIL = {
+    ...MIG_DOWN_FAIL,
+    COPY_MISSING: "M2_COPY_MISSING",
+    UNREPRESENTABLE_UNLISTED: "M2_UNREPRESENTABLE_UNLISTED",
+};
+/** The freshly computed legacy export from the v2 journal (expected bytes). */
+export function computeLegacyExport(host) {
+    return host.journalRows();
+}
+/** Phase 1 — copy: stage the legacy export without activating. Returns rows. */
+export function m2Copy(host) {
+    const rows = computeLegacyExport(host);
+    host.writeStagedLegacy(rows);
+    return rows;
+}
+/**
+ * Phase 2 — validate: the staged export must equal the freshly computed one
+ * (copy-match), the journal must be active and have reached the `copied`
+ * phase, seq must be monotonic per session, digests must be well-formed, and
+ * every unrepresentable row must be listed. Advances to `validated` only when
+ * every check passes (so a crash here leaves authority unchanged).
+ */
+export function m2Validate(host) {
+    const codes = [];
+    const staged = host.stagedLegacy();
+    const expected = computeLegacyExport(host);
+    if (staged === null) {
+        codes.push(M2_FAIL.COPY_MISSING);
+    }
+    else {
+        const sameRows = staged.length === expected.length &&
+            staged.every((r, i) => r.session === expected[i].session &&
+                r.seq === expected[i].seq &&
+                r.eventId === expected[i].eventId &&
+                r.unrepresentable === expected[i].unrepresentable);
+        if (!sameRows)
+            codes.push(M2_FAIL.COPY_MISSING);
+        // Seq monotonic per session (no regression).
+        const prev = new Map();
+        for (const r of staged) {
+            const last = prev.get(r.session);
+            if (last !== undefined && r.seq <= last)
+                codes.push(M2_FAIL.SEQ_REGRESSION);
+            prev.set(r.session, r.seq);
+        }
+        // Digests on representable rows must verify: recompute sha256 over the stored
+        // source and compare to the recorded digest (Q03 — real parity).
+        for (const r of staged) {
+            if (!r.unrepresentable && !verifyLegacyDigest(r.digest, r.legacyProjection)) {
+                codes.push(M2_FAIL.DIGEST_MISMATCH);
+            }
+        }
+        // Every unrepresentable row is explicitly flagged (MIG-DOWN-003).
+        for (const r of expected) {
+            if (r.unrepresentable) {
+                const flag = staged.find((s) => s.session === r.session && s.seq === r.seq && s.unrepresentable);
+                if (!flag)
+                    codes.push(M2_FAIL.UNREPRESENTABLE_UNLISTED);
+            }
+        }
+    }
+    if (!host.journalActive())
+        codes.push(M2_FAIL.NOT_ACTIVE);
+    if (host.phase() !== "copied")
+        codes.push(M2_FAIL.PHASE_UNREACHED);
+    if (codes.length === 0) {
+        const v = host.validateStaged();
+        if (!v.ok) {
+            // Q05: narrow the host's string codes through a runtime type guard instead
+            // of an unchecked cast — unknown codes are dropped, never mis-typed.
+            for (const c of v.codes)
+                if (isM2MigrationCode(c))
+                    codes.push(c);
+        }
+    }
+    const ok = codes.length === 0;
+    return { ok, codes: dedupe(codes) };
+}
+/**
+ * Phase 3 — switch: atomic activation of the legacy export as the openable
+ * authority. Only call after m2Validate reports ok; the journal advances to
+ * `switched` and v2 becomes read-only-archival. Idempotent on resume.
+ */
+export function m2Switch(host) {
+    host.switchLegacy();
+}
+/** Registered M2 conformance ID range (M2-001..015). */
+export const M2_IDS = [
+    "M2-001",
+    "M2-002",
+    "M2-003",
+    "M2-004",
+    "M2-005",
+    "M2-006",
+    "M2-007",
+    "M2-008",
+    "M2-009",
+    "M2-010",
+    "M2-011",
+    "M2-012",
+    "M2-013",
+    "M2-014",
+    "M2-015",
+];
+/** Registered MIG-DOWN conformance ID (MIG-DOWN-001). */
+export const MIG_DOWN_IDS = ["MIG-DOWN-001"];
+/** Runtime narrowing: is `code` a known M2 migration failure code? */
+function isM2MigrationCode(code) {
+    return Object.values(M2_FAIL).includes(code);
+}
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}

package/dist/src/vector-cortex/replay/cut.js

@@ -0,0 +1,123 @@
+/**
+ * vector-cortex/replay/cut.ts — ReplayCutV2 effective-cut calculator (VC0B).
+ *
+ * M3 effective-cut rule: effective = min(boundarySafeSeq, committedSeq,
+ * capturedHighWater), capped by requestedSeq, then retreated to the call
+ * boundary whenever the candidate intersects a tool call/result pair, then
+ * clamped to the recent-anchor floor. On a tie among the min sources we choose
+ * the LOWER source order and record CUT_LOWEST_SOURCE_ORDER. This is the
+ * successor to the legacy capped-replay effective cut — the defect at
+ * docs/vector-cortex/SPRINT_PLAN.md M3 ("capped replay effective cut must
+ * respect boundary/commit/capture minima") is fixed here.
+ *
+ * Pure/deterministic — no network, no side effects (PREVENT-PI-004).
+ */
+const MIN_SOURCES = ["boundary", "committed", "captured"];
+/**
+ * min-of-three, capped by requestedSeq, with deterministic lower-source
+ * tie-breaking. Returns the min value and every source that tied for it.
+ * On a tie the LOWER source order wins; `sources[0]` is the winning source.
+ */
+function minOfCapped(requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater) {
+    const values = [
+        ["boundary", boundarySafeSeq],
+        ["committed", committedSeq],
+        ["captured", capturedHighWater],
+    ];
+    const minVal = values.reduce((a, [, v]) => (v < a ? v : a), requestedSeq);
+    const floors = values.filter(([, v]) => v === minVal).map(([s]) => s);
+    // If a source value exceeds requestedSeq it is capped away; the min is
+    // positioned at requestedSeq only when every source is above the request.
+    const value = floors.length > 0 ? minVal : requestedSeq;
+    return { value, sources: floors.length > 0 ? floors : ["boundary"] };
+}
+/** True when a cut at seq `e` does NOT split any tool call/result pair. */
+export function cutIsPairSafe(e, pairs) {
+    for (const p of pairs) {
+        // Cutting at e keeps events with seq <= e. A pair is split when the call
+        // (callSeq) is kept but the result (resultSeq) is dropped.
+        if (p.callSeq <= e && e < p.resultSeq)
+            return false;
+    }
+    return true;
+}
+/**
+ * Retreat `e` upward-locked toward the call boundary of any pair it splits.
+ * Returns the largest pair-safe e <= start, never below `floor`.
+ *
+ * `splitResolved` is true when a CUT_TOOL_PAIR_SPLIT retreat occurred; when a
+ * retreat would cross the floor the cut clamps AT the floor and the reason
+ * becomes CUT_ANCHOR_FLOOR (the floor is assumed pair-safe for legal inputs).
+ */
+function retreatAgainstPairs(start, pairs, floor) {
+    let e = start;
+    let split = false;
+    let floorClamped = false;
+    for (;;) {
+        let hit = false;
+        for (const p of pairs) {
+            if (p.callSeq <= e && e < p.resultSeq) {
+                hit = true;
+                const target = p.callSeq - 1n;
+                if (target < floor) {
+                    // No-progress guard (VC0B-I12): the retreat target lies below the
+                    // floor. If the floor itself still splits a pair we must not loop
+                    // back onto it (that hangs the synchronous agent loop) — clamp AT
+                    // the floor once and stop. The floor is taken as the legal cut.
+                    e = floor;
+                    floorClamped = true;
+                }
+                else {
+                    e = target;
+                }
+                split = true;
+                break;
+            }
+        }
+        // Terminate when no pair splits e, OR when we have already clamped to the
+        // floor (the floor is an absolute lower bound; we never retreat past it
+        // even if it is not itself pair-safe).
+        if (!hit || floorClamped)
+            return { effective: e, split, floorClamped };
+    }
+}
+/**
+ * Compute the v2 effective cut. Pure with respect to the provided inputs.
+ */
+export function computeEffectiveCutV2(input) {
+    const { requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater, anchorFloor, pairs } = input;
+    const retreats = [];
+    // Step 1 — min-of-three (capped by requestedSeq) with lower-source tie-break.
+    const min = minOfCapped(requestedSeq, boundarySafeSeq, committedSeq, capturedHighWater);
+    let effective = min.value;
+    // Tie among the min sources: resolved to the LOWER source order — record it.
+    if (min.sources.length > 1) {
+        retreats.push({
+            code: "CUT_LOWEST_SOURCE_ORDER",
+            fromSeq: effective,
+            toSeq: effective,
+        });
+    }
+    // Step 2 — pair retreat (never below the anchor floor).
+    const retreat = retreatAgainstPairs(effective, pairs, anchorFloor);
+    if (retreat.split && retreat.floorClamped) {
+        retreats.push({ code: "CUT_ANCHOR_FLOOR", fromSeq: effective, toSeq: retreat.effective });
+    }
+    else if (retreat.split) {
+        retreats.push({ code: "CUT_TOOL_PAIR_SPLIT", fromSeq: effective, toSeq: retreat.effective });
+    }
+    effective = retreat.effective;
+    // Step 3 — final anchor-floor clamp (safety; legal floors are already >=).
+    if (effective < anchorFloor) {
+        retreats.push({ code: "CUT_ANCHOR_FLOOR", fromSeq: effective, toSeq: anchorFloor });
+        effective = anchorFloor;
+    }
+    const cut = {
+        requestedSeq,
+        boundarySafeSeq,
+        committedSeq,
+        capturedHighWater,
+        effectiveSeq: effective,
+    };
+    return { cut, retreats };
+}