pi-mega-compact 0.16.2 → 0.17.0

package/dist/src/vector-cortex/ledger/sqlite.js

@@ -0,0 +1,200 @@
+/**
+ * vector-cortex/ledger/sqlite.ts — occurrence-v2 SQLite store, Mode A (VC1B).
+ *
+ * A self-contained, isolated SQLite store (`node:sqlite` `DatabaseSync`) over its
+ * OWN database file — NOT the host `sqlite.db` — so the neutral v2 ledger is a
+ * true independent authority, not a host table. Holds the canonical occurrence
+ * rows plus per-session monotonic seq and the durable contiguous high-water.
+ *
+ * The defect M2 fixes: the host `raw_transcript` table keys on
+ * `(content_hash, session_id)`, so repeated equal bytes at a later turn are
+ * silently dropped. Here the ledger keys occurrences by `(event_id, digest)`
+ * ONLY — equal bytes at a distinct seq/event-id are preserved as separate
+ * occurrences (M2-DUP-001).
+ *
+ * Append enforces, per occurrence: (1) strictly monotonic per-session seq
+ * (EVT_SEQ_REGRESSION otherwise); (2) a tool RESULT names exactly one earlier
+ * call (EVT_TOOL_CALL_MISSING otherwise); (3) exact `(event_id,digest)`
+ * re-appends are acknowledged idempotently, never duplicated.
+ *
+ * Mode A of the VC1B triad: transactional SQLite append. Mode B (`./spool.ts`)
+ * is an independent fsync spool; mode C leaves the host transcript unchanged.
+ *
+ * PREVENT-002: every query is parameterized. PREVENT-011: no `any`.
+ * PREVENT-PI-004: local filesystem only, no network. No console.log.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS occurrence_v2 (
+  session       TEXT    NOT NULL,
+  seq           INTEGER NOT NULL,
+  event_id      TEXT    NOT NULL,
+  digest        TEXT    NOT NULL,
+  kind          TEXT    NOT NULL,
+  tool_call_id  TEXT,
+  source_bytes  BLOB,
+  PRIMARY KEY (session, seq),
+  UNIQUE (session, event_id, digest)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS ledger_high_water (
+  session TEXT PRIMARY KEY,
+  seq     INTEGER NOT NULL
+) STRICT;
+`;
+/** Default digest for a row when the caller omits one (sha256 over bytes). */
+export function ledgerDigest(bytes) {
+    const hex = createHash("sha256").update(bytes).digest("hex");
+    return `sha256:${hex}`;
+}
+/** Open (or reuse) the isolated occurrence-v2 ledger DB handle. */
+export function openOccurrenceStore(dbPath) {
+    const dir = dirname(dbPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec(SCHEMA);
+    return db;
+}
+function rowToOccurrence(row) {
+    return {
+        session: row.session,
+        seq: BigInt(row.seq),
+        eventId: row.event_id,
+        digest: row.digest,
+        kind: row.kind,
+        toolCallId: row.tool_call_id ?? undefined,
+        sourceBytes: row.source_bytes ? Buffer.from(row.source_bytes) : new Uint8Array(0),
+    };
+}
+/** Current durable contiguous high-water for a session (0 when none). */
+export function ledgerHighWater(db, session) {
+    const row = db
+        .prepare(`SELECT seq FROM ledger_high_water WHERE session = @session`)
+        .get({ "@session": session });
+    return row ? BigInt(row.seq) : 0n;
+}
+/** Read all accepted occurrences for a session in ascending (seq,eventId). */
+export function readSessionOccurrences(db, session) {
+    const rows = db
+        .prepare(`SELECT session, seq, event_id, digest, kind, tool_call_id, source_bytes
+       FROM occurrence_v2 WHERE session = @session
+       ORDER BY seq ASC, event_id ASC`)
+        .all({ "@session": session });
+    return rows.map(rowToOccurrence);
+}
+/** Occurrences at or above `fromSeq` (inclusive), ascending. */
+export function readFromSeq(db, session, fromSeq) {
+    const rows = db
+        .prepare(`SELECT session, seq, event_id, digest, kind, tool_call_id, source_bytes
+       FROM occurrence_v2 WHERE session = @session AND seq >= @from
+       ORDER BY seq ASC, event_id ASC`)
+        .all({ "@session": session, "@from": Number(fromSeq) });
+    return rows.map(rowToOccurrence);
+}
+/** Count accepted occurrences for a session. */
+export function countOccurrences(db, session) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS cnt FROM occurrence_v2 WHERE session = @session`)
+        .get({ "@session": session });
+    return row.cnt;
+}
+/** Whether a `(event_id, digest)` pair is already accepted in a session. */
+export function hasOccurrence(db, session, eventId, digest) {
+    const row = db
+        .prepare(`SELECT 1 AS hit FROM occurrence_v2
+       WHERE session = @session AND event_id = @event_id AND digest = @digest LIMIT 1`)
+        .get({ "@session": session, "@event_id": eventId, "@digest": digest });
+    return row !== undefined;
+}
+/** The stored occurrence matching a `(event_id, digest)` pair, or undefined. */
+function findOccurrence(db, session, eventId, digest) {
+    const row = db
+        .prepare(`SELECT session, seq, event_id, digest, kind, tool_call_id, source_bytes
+       FROM occurrence_v2
+       WHERE session = @session AND event_id = @event_id AND digest = @digest LIMIT 1`)
+        .get({ "@session": session, "@event_id": eventId, "@digest": digest });
+    return row ? rowToOccurrence(row) : undefined;
+}
+/** Whether a prior call row with the given eventId exists in the session. */
+function hasCallRef(db, session, eventId) {
+    const row = db
+        .prepare(`SELECT 1 AS hit FROM occurrence_v2
+       WHERE session = @session AND event_id = @event_id LIMIT 1`)
+        .get({ "@session": session, "@event_id": eventId });
+    return row !== undefined;
+}
+/**
+ * Append one occurrence within a transaction. Enforces monotonic seq, tool-call
+ * reference completeness, and `(event_id,digest)` idempotent ack. Returns the
+ * accepted row or a deterministic failure code.
+ */
+export function appendOccurrence(db, input) {
+    const digest = input.digest ?? ledgerDigest(input.sourceBytes);
+    const occurrence = {
+        session: input.session,
+        seq: input.seq,
+        eventId: input.eventId,
+        digest,
+        kind: input.kind,
+        toolCallId: input.toolCallId,
+        sourceBytes: input.sourceBytes,
+    };
+    // (3) exact (event_id,digest) re-append is acknowledged idempotently, WITHOUT
+    // inserting a new row. Return the EXISTING stored occurrence (its real seq) —
+    // not the caller's input — so a journal record written from this result carries
+    // the existing seq, which always corresponds to a real occurrence_v2 row (Q01:
+    // never a phantom journal row at a seq with no backing occurrence).
+    const existing = findOccurrence(db, input.session, input.eventId, digest);
+    if (existing) {
+        return { ok: true, occurrence: existing };
+    }
+    // (1) monotonic seq: must be exactly the next expected seq (highWater+1).
+    const hw = ledgerHighWater(db, input.session);
+    if (input.seq !== hw + 1n) {
+        return { ok: false, code: "EVT_SEQ_REGRESSION", rejected: occurrence };
+    }
+    // (2) a tool RESULT names exactly one earlier call in the same session.
+    if (input.toolCallId !== undefined && input.toolCallId !== "") {
+        if (!hasCallRef(db, input.session, input.toolCallId)) {
+            return { ok: false, code: "EVT_TOOL_CALL_MISSING", rejected: occurrence };
+        }
+    }
+    // Accept: insert the row and advance the per-session high-water atomically.
+    db.exec("SAVEPOINT mc_ledger");
+    try {
+        db.prepare(`INSERT INTO occurrence_v2 (session, seq, event_id, digest, kind, tool_call_id, source_bytes)
+       VALUES (@session, @seq, @event_id, @digest, @kind, @tool_call_id, @source_bytes)`).run({
+            "@session": input.session,
+            "@seq": Number(input.seq),
+            "@event_id": input.eventId,
+            "@digest": digest,
+            "@kind": input.kind,
+            "@tool_call_id": input.toolCallId ?? null,
+            "@source_bytes": Buffer.from(input.sourceBytes),
+        });
+        db.prepare(`INSERT INTO ledger_high_water (session, seq) VALUES (@session, @seq)
+       ON CONFLICT(session) DO UPDATE SET seq = excluded.seq`).run({ "@session": input.session, "@seq": Number(input.seq) });
+        db.exec("RELEASE mc_ledger");
+    }
+    catch (e) {
+        db.exec("ROLLBACK TO mc_ledger");
+        db.exec("RELEASE mc_ledger");
+        throw e;
+    }
+    return { ok: true, occurrence };
+}
+/** Append a batch; each occurrence reports its own result. */
+export function appendOccurrenceBatch(db, inputs) {
+    return inputs.map((input) => appendOccurrence(db, input));
+}
+/** Diagnostic: total accepted occurrences across all sessions. */
+export function countAllOccurrences(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS cnt FROM occurrence_v2`).get();
+    return row.cnt;
+}

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