pi-mega-compact 0.16.3 → 0.17.1

package/dist/src/vector-cortex/conformance/triadB-reader.js

@@ -0,0 +1,95 @@
+/**
+ * conformance/triadB-reader.ts — TRIAD-B independent exact reader (VC1C).
+ *
+ * Deliberately shares NO code and NO cached-seed instance with the runner
+ * modules (l1-minhash-v2.ts / l1-lsh-v2.ts). It re-derives the minhash-v2
+ * signature and 64 bucket keys from first principles, using only the PUBLISHED
+ * (a,b) seed pairs passed in (read by the caller from
+ * conformance/.../minhash/seeds-v2.json — the table authored independently by
+ * scripts/gen-fixtures/minhash.mjs, the same process that produced the frozen
+ * fixture bytes). Because B shares no subroutine with the runner, a systematic
+ * error in the runner's splitmix64 / seed-derivation / signature arithmetic
+ * cannot satisfy both triad A and triad B.
+ *
+ * Pure compute, no deps, no storage, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+const MASK64 = 0xffffffffffffffffn;
+const P = (1n << 61n) - 1n; // 2^61 - 1
+const SLOTS = 256;
+const U64 = 8;
+const BANDS = 64;
+/** 64-bit FNV-1a over UTF-8 bytes or a raw byte buffer (own, independent loop). */
+function fnv1a64(input) {
+    let h = 0xcbf29ce484222325n;
+    for (const b of Buffer.from(input)) {
+        h = ((h ^ BigInt(b)) * 0x100000001b3n) & MASK64;
+    }
+    return h;
+}
+/**
+ * Re-derive the 2048-byte minhash-v2 signature and (optionally) the 64 LSH
+ * bucket keys for `text` within `session`, from published seed pairs only —
+ * never the runner module.
+ */
+export function independentReaderV2(text, session, seedPairs, withBuckets) {
+    // Normalization: ANSI-strip, NFC, case-fold, CRLF->LF, whitespace collapse,
+    // 32K cap — mirrored from the frozen VC1C spec.
+    let norm = (text || "")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .normalize("NFC")
+        .toLowerCase()
+        .replace(/\r\n?/g, "\n")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (norm.length > 32768)
+        norm = norm.slice(0, 32768);
+    // Five-code-point shingles (deduped, capped at 50_000).
+    const grams = [];
+    if (norm.length > 0) {
+        const cps = Array.from(norm);
+        const seen = new Set();
+        const short = cps.length < 5;
+        for (let i = 0; i < (short ? 1 : cps.length - 4); i++) {
+            const h = short ? fnv1a64(norm) : fnv1a64(cps.slice(i, i + 5).join(""));
+            if (!seen.has(h)) {
+                seen.add(h);
+                grams.push(h);
+            }
+            if (!short && seen.size >= 50000)
+                break;
+        }
+    }
+    // Signature: slot i = min over shingles of (a_i*x + b_i) mod p (exact BigInt).
+    const sig = new Array(SLOTS).fill(P);
+    for (let i = 0; i < SLOTS && grams.length > 0; i++) {
+        const pair = seedPairs[i];
+        const a = BigInt(pair.a);
+        const b = BigInt(pair.b);
+        let min = P;
+        for (const x of grams) {
+            const h = (a * x + b) % P;
+            if (h < min)
+                min = h;
+        }
+        sig[i] = min;
+    }
+    // Own 256 x u64 little-endian encoder.
+    const buf = Buffer.allocUnsafe(SLOTS * U64);
+    for (let i = 0; i < SLOTS; i++)
+        buf.writeBigUInt64LE(sig[i], i * U64);
+    const bytes = new Uint8Array(buf);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    // 64 buckets: FNV-1a over `<session>|v2|` + each 32-byte band (LE hex).
+    const buckets = [];
+    if (withBuckets) {
+        const prefix = Buffer.from(`${session}|v2|`, "utf8");
+        for (let band = 0; band < BANDS; band++) {
+            const bandBytes = Buffer.from(bytes.slice(band * 32, band * 32 + 32));
+            const out = Buffer.allocUnsafe(U64);
+            out.writeBigUInt64LE(fnv1a64(Buffer.concat([prefix, bandBytes])), 0);
+            buckets.push(`b${band}:${out.toString("hex")}`);
+        }
+    }
+    return { bytes, digest, buckets };
+}

package/dist/src/vector-cortex/eval/annotations.js

@@ -0,0 +1,41 @@
+/**
+ * vector-cortex/eval/annotations.ts — redaction metadata + JSONL serialization.
+ *
+ * Payload bytes, prompts, and exact ledger text are NEVER serialized. Before a
+ * JSONL line is written, each such field is replaced by a SHA-256 digest + byte
+ * count + redaction kind (EVAL-REDACT-002: prompt bytes never appear in JSONL).
+ * The redaction journal is itself the AnnotationV1 output.
+ *
+ * Uses node:crypto for the digest (pure local math, PREVENT-PI-004 safe).
+ */
+import { createHash } from "node:crypto";
+/** SHA-256 over bytes, unpadded base64 (conformance canonical binary form). */
+export function digestBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("base64");
+}
+/** Replace every raw content field with its digest/count metadata. */
+export function redactAnnotation(itemId, contents) {
+    const redactions = contents.map((c) => ({
+        field: c.field,
+        digest: digestBytes(c.bytes),
+        bytes: c.bytes.byteLength,
+        kind: c.kind,
+    }));
+    return {
+        itemId,
+        redactions,
+        redactedCount: redactions.length,
+    };
+}
+/**
+ * Serialize one set of raw contents to a single redacted JSONL line. Returns
+ * the annotation with its digest metadata and the JSONL text; the raw bytes
+ * never appear in the returned string.
+ */
+export function serializeRedactedJsonl(itemId, contents) {
+    const annotation = redactAnnotation(itemId, contents);
+    return {
+        annotation,
+        jsonl: `${JSON.stringify(annotation)}\n`,
+    };
+}

package/dist/src/vector-cortex/eval/metrics.js

@@ -0,0 +1,86 @@
+/**
+ * vector-cortex/eval/metrics.ts — canonical metric ordering + fixed histogram.
+ *
+ * 1. Stable sort rows by `(session, seq, event)` — session string byte order,
+ *    then integer seq ascending, then event-name byte order as tiebreak
+ *    (EVAL-ORDER-003: equal seq rows use event-name order).
+ * 2. Bucket latency values at exactly 1/5/10/25/50/100/250ms with inclusive
+ *    boundaries (EVAL-BUCKET-001); values past 250ms kept in a separate
+ *    overflow bucket. Histogram totals are permutation-stable.
+ *
+ * Pure/no side effects (PREVENT-PI-004).
+ */
+import { LATENCY_BUCKETS } from "./types.js";
+/** Inclusive-boundary bucket edges, with a sentinel past the largest edge. */
+const EDGES = LATENCY_BUCKETS;
+const OVERFLOW_INDEX = EDGES.length;
+/** Histogram cell counts aligned to EDGES, plus a trailing overflow cell. */
+export function emptyHistogram() {
+    return new Array(EDGES.length + 1).fill(0);
+}
+/** True when a sample carries a latency (`unit === "ms"`) datum. */
+export function isLatencySample(m) {
+    return m.unit === "ms";
+}
+/** Bucket a latency ms value into a cell index (0..EDGES.length, last=overflow). */
+export function bucketIndex(value) {
+    if (!Number.isFinite(value) || value < 0)
+        return OVERFLOW_INDEX;
+    for (let i = 0; i < EDGES.length; i++) {
+        if (value <= EDGES[i])
+            return i; // inclusive upper boundary
+    }
+    return OVERFLOW_INDEX;
+}
+/**
+ * Bucket latency sample values across all rows into the fixed histogram.
+ * Overflow is kept separate (counted in `overflow` and the trailing cell).
+ */
+export function bucketHistogram(rows) {
+    const cells = emptyHistogram();
+    let overflow = 0;
+    for (const m of rows) {
+        if (!isLatencySample(m))
+            continue;
+        const idx = bucketIndex(m.value);
+        cells[idx] += 1;
+        if (idx === EDGES.length)
+            overflow += 1;
+    }
+    return {
+        cells,
+        edges: [...EDGES],
+        overflow,
+        total: cells.reduce((a, b) => a + b, 0),
+    };
+}
+/**
+ * Stable sort MetricEventV1 rows by `(session, seq, event)`:
+ *  - session: UTF-8 / JS string byte order;
+ *  - seq: ascending numeric;
+ *  - event: ascending string byte order (tiebreak for equal seq).
+ * Equal content stays separate occurrences (never deduplicated here).
+ */
+export function sortCanonical(rows) {
+    const out = [...rows];
+    out.sort((a, b) => {
+        const s = a.session < b.session ? -1 : a.session > b.session ? 1 : 0;
+        if (s !== 0)
+            return s;
+        if (a.seq !== b.seq)
+            return a.seq - b.seq;
+        return a.event < b.event ? -1 : a.event > b.event ? 1 : 0;
+    });
+    return out;
+}
+/**
+ * Assisted sort plus histogram, returning both under one result.
+ * The observer (mode A) calls this before JSONL serialization.
+ */
+export function buildMetrics(rows) {
+    return {
+        rows: sortCanonical(rows),
+        histogram: bucketHistogram(rows),
+        rejects: [],
+    };
+}

package/dist/src/vector-cortex/eval/observer.js

@@ -0,0 +1,61 @@
+/**
+ * vector-cortex/eval/observer.ts — VC0A structured observer (triad mode A).
+ *
+ * Connects to the evaluation reader: accepts MetricEventV1 samples, maintains
+ * the canonical `(session, seq, event)` ordered set plus the fixed latency
+ * histogram, and emits two structured local events:
+ *   - vector_cortex_eval_sample_recorded   (one per accepted sample)
+ *   - vector_cortex_eval_redaction_rejected (when a redaction fails)
+ *
+ * Mode C (observer absent) is the responsibility of the caller: no observes(),
+ * no writes, byte-identical to the predecessor. This module never touches the
+ * network (PREVENT-PI-004) — it only manipulates in-memory rows and emits
+ * structured log lines through an injected logging callback so it stays
+ * pi-agnostic and deterministically testable.
+ */
+import { buildMetrics, sortCanonical } from "./metrics.js";
+/**
+ * Build a structured observer (mode A). Best-effort: emitting never throws
+ * into the extension path (non-fatal observability).
+ */
+export function createEvalObserver(opts) {
+    const rows = [];
+    function emit(event, fields) {
+        try {
+            opts.emit(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    }
+    return {
+        record(sample) {
+            rows.push(sample);
+            if (opts.persist) {
+                try {
+                    opts.persist(sample);
+                }
+                catch {
+                    /* non-fatal observability */
+                }
+            }
+            emit("vector_cortex_eval_sample_recorded", {
+                session: sample.session,
+                seq: sample.seq,
+                event: sample.event,
+                unit: sample.unit,
+                mode: sample.mode,
+            });
+        },
+        rejectRedaction(field, reason) {
+            emit("vector_cortex_eval_redaction_rejected", { field, reason });
+        },
+        rows() {
+            return sortCanonical(rows);
+        },
+    };
+}
+/** Aggregate metrics result from an observer's rows (canonical + histogram). */
+export function observerMetrics(result) {
+    return buildMetrics(result.rows());
+}

package/dist/src/vector-cortex/eval/persist.js

@@ -0,0 +1,67 @@
+/**
+ * vector-cortex/eval/persist.ts — redacted eval JSONL persistence (VC0A).
+ *
+ * Bridges the in-memory observer (mode A) and the dashboard reader (separate
+ * process) via a disk JSONL under the state dir. Writes are append-only and
+ * hold only MetricEventV1 metric rows plus redaction metadata — never payloads,
+ * prompts, or exact ledger text (EVAL-REDACT-002). Best-effort and non-fatal
+ * (PREVENT-PI-004: local filesystem only; no network).
+ *
+ * PREVENT-011: no `any` type.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Location of the redacted evaluation JSONL under a state dir. */
+export function evalJsonlPath(stateDir) {
+    return join(stateDir, "vector-cortex", "evaluation.jsonl");
+}
+/** Append one redacted metric row as a canonical JSON line (append-only). */
+export function appendEvalRow(stateDir, row) {
+    try {
+        const path = evalJsonlPath(stateDir);
+        mkdirSync(join(stateDir, "vector-cortex"), { recursive: true, mode: 0o700 });
+        // PER_EVAL_PERMISSION: 0600 file inherits state-dir permission policy.
+        writeFileSync(path, row.map((r) => `${JSON.stringify(r)}\n`).join(""), {
+            flag: "a",
+            mode: 0o600,
+        });
+        // guardrails-allow PREVENT-PI-004: local filesystem eval JSONL (no network)
+    }
+    catch {
+        /* non-fatal observability — never break the agent loop */
+    }
+}
+/**
+ * Read every redacted metric row from the JSONL. Malformed or truncated final
+ * lines are skipped (callers surface EVAL_JSONL_TRUNCATED); the caller decides
+ * whether that is fatal. Returns an empty array when the file is absent.
+ */
+export function readEvalRows(stateDir) {
+    const out = [];
+    let raw;
+    try {
+        raw = readFileSync(evalJsonlPath(stateDir), "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of raw.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.session === "string" &&
+                typeof parsed.seq === "number" &&
+                typeof parsed.event === "string" &&
+                typeof parsed.value === "number" &&
+                typeof parsed.unit === "string" &&
+                (parsed.mode === "A" || parsed.mode === "B" || parsed.mode === "C")) {
+                out.push(parsed);
+            }
+        }
+        catch {
+            /* malformed line — skip; EVAL_JSONL_TRUNCATED surfaced by caller */
+        }
+    }
+    return out;
+}

package/dist/src/vector-cortex/eval/reader.js

@@ -0,0 +1,29 @@
+/**
+ * vector-cortex/eval/reader.ts — evaluation reader (aggregate-only).
+ *
+ * Reader-only capability: `summarizeEvalRows` collapses a set of MetricEventV1
+ * rows into an aggregate summary for the dashboard `GET /api/vector-cortex/
+ * evaluation` endpoint. No writable capability — the observer writes via its
+ * own path; this reader never mutates. Predecessor (flag-off / mode C) emits
+ * an empty summary byte-identical to "no data".
+ *
+ * Pure + local, zero network (PREVENT-PI-004).
+ */
+import { buildMetrics } from "./metrics.js";
+/** Aggregate rows into a reader-only summary (histogram + per-mode counts). */
+export function summarizeEvalRows(rows) {
+    const byMode = { A: 0, B: 0, C: 0 };
+    for (const r of rows)
+        byMode[r.mode] += 1;
+    const metrics = buildMetrics(rows);
+    return {
+        samples: rows.length,
+        byMode,
+        histogram: {
+            edges: metrics.histogram.edges,
+            cells: metrics.histogram.cells,
+            overflow: metrics.histogram.overflow,
+            total: metrics.histogram.total,
+        },
+    };
+}

package/dist/src/vector-cortex/eval/types.js

@@ -0,0 +1,33 @@
+/**
+ * vector-cortex/eval/types.ts — MetricEventV1 / AnnotationV1 contract types
+ * and the registered EVAL conformance ID range (EVAL-001..010).
+ *
+ * Owned by VC0A (baseline observability). Consumes reviewer-accepted predecessor
+ * contracts and common contracts only. These are pure type/schema definitions —
+ * no runtime network, no side effects (PREVENT-PI-004 / PREVENT-011).
+ */
+/** Units the evaluator understands. Unknown units reject as EVAL_UNIT_UNKNOWN. */
+export const UNITS = ["ms", "bytes", "count", "ratio"];
+/**
+ * Histogram bucket edges for latency, in milliseconds, inclusive on both
+ * boundaries (EVAL-BUCKET-001): values at exactly 1ms and 250ms land in
+ * those buckets. Overflow (value > largest edge) is kept separate.
+ */
+export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250];
+/**
+ * Registered EVAL conformance ID range (EVAL-001..010). The acceptance test
+ * reads these rows from the v2 manifest and asserts their expected bytes/results.
+ * Registered BEFORE evaluation logic so the manifest/fixture seam is stable.
+ */
+export const EVAL_IDS = [
+    "EVAL-001",
+    "EVAL-002",
+    "EVAL-003",
+    "EVAL-004",
+    "EVAL-005",
+    "EVAL-006",
+    "EVAL-007",
+    "EVAL-008",
+    "EVAL-009",
+    "EVAL-010",
+];

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

@@ -0,0 +1,55 @@
+/**
+ * vector-cortex/ledger/adapter.ts — EventV2 ledger adapter (VC1A, task 5).
+ *
+ * A thin, pi-agnostic adapter combining the Mode-A codec, the canonical
+ * validator, and the VC1A emit seam so `vector_cortex_event_decoded` and
+ * `vector_cortex_event_validation_failed` are emitted by REAL code paths (not a
+ * hand-invoked reporter), gated by `VC1A_ENABLED()` inside `createLedgerReporter`.
+ *
+ * The live producer (wiring this into `extensions/mega-compact.ts` /
+ * `src/engine.ts`) is deferred to VC1C/VC1B (mirroring VC0B-I08); this sprint
+ * ships the seam + adapter as the clean single surface, with the acceptance
+ * aggregator exercising the real gated-emission path.
+ *
+ * Pure orchestration — no storage, no network, no side effects (PREVENT-PI-004).
+ */
+import { createEventCodec } from "./event-codec.js";
+import { validateEvents } from "./validator.js";
+import { createLedgerReporter } from "./emit.js";
+/** Build the ledger adapter over an injected emit callback (optional). */
+export function createLedgerAdapter(emit) {
+    const codec = createEventCodec();
+    const reporter = createLedgerReporter(emit);
+    return {
+        encode: (input) => codec.encode(input),
+        decode(event) {
+            const bytes = codec.decode(event);
+            reporter.eventDecoded({
+                session: event.sessionId,
+                seq: event.seq.toString(),
+                eventId: event.eventId,
+                bytes: bytes.length,
+                utf8Valid: event.utf8.valid,
+            });
+            return bytes;
+        },
+        validate(events) {
+            const result = validateEvents(events);
+            if (!result.ok) {
+                // Emit one event per failing occurrence with its REAL locator — a
+                // consumer of the feed can identify WHICH event failed (VC1A-I05).
+                for (const issue of result.issues) {
+                    reporter.validationFailed({
+                        session: issue.sessionId,
+                        seq: issue.seq.toString(),
+                        eventId: issue.eventId,
+                        code: issue.code,
+                    });
+                }
+            }
+            return result;
+        },
+        codec,
+        reporter,
+    };
+}

package/dist/src/vector-cortex/ledger/compat-journal.js

@@ -0,0 +1,206 @@
+/**
+ * vector-cortex/ledger/compat-journal.ts — CompatJournalV1 (VC1B, task 4).
+ *
+ * The downgrade-safety journal. From v2 activation every accepted v2 append
+ * atomically appends a record holding the original bytes, IDs, and a legacy
+ * projection or an explicit `unrepresentable` marker. The journal tracks its own
+ * lifetime state (prepared → copied → validated → switched) so the M2
+ * downgrade is resumable: a crash mid-journal never corrupts v2, and a restart
+ * resumes idempotently (the unique failure-injection contract).
+ *
+ * `active()` is true once ANY v2 append has been journaled — an old binary may
+ * only open the exported legacy copy, never v2 directly, once the journal is
+ * active (CONTRACTS §Store). Unrepresentable rows (e.g. invalid UTF-8 bytes have
+ * no lossless legacy projection) are listed on prepare and carried through the
+ * copy/validate/switch lifecycle.
+ *
+ * Durable in the same isolated occurrence-v2 SQLite DB as the ledger rows
+ * (append-only provenance: journal records are never UPDATE'd; only the
+ * singleton state row advances phase). PREVENT-002 parameterized; PREVENT-011
+ * no `any`; PREVENT-PI-004 local filesystem only; no console.log.
+ */
+import { createHash } from "node:crypto";
+/** Downgrade-phase validation failure codes (registered as conformance rows). */
+export const MIG_DOWN_FAIL = {
+    NOT_ACTIVE: "MIG_DOWN_NOT_ACTIVE",
+    PHASE_UNREACHED: "MIG_DOWN_PHASE_UNREACHED",
+    SEQ_REGRESSION: "MIG_DOWN_SEQ_REGRESSION",
+    DIGEST_MISMATCH: "MIG_DOWN_DIGEST_MISMATCH",
+    SWITCH_UNSAFE: "MIG_DOWN_SWITCH_UNSAFE",
+};
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS compat_journal_v1 (
+  session             TEXT    NOT NULL,
+  seq                 INTEGER NOT NULL,
+  event_id            TEXT    NOT NULL,
+  digest              TEXT    NOT NULL,
+  kind                TEXT    NOT NULL,
+  legacy_projection   TEXT,
+  unrepresentable     INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (session, seq)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS compat_journal_state (
+  id    INTEGER PRIMARY KEY CHECK (id = 1),
+  phase TEXT NOT NULL
+) STRICT;
+`;
+/** Ensure the journal tables exist and seed the singleton phase row. */
+export function initCompatJournal(db) {
+    db.exec(SCHEMA);
+    db.prepare(`INSERT OR IGNORE INTO compat_journal_state (id, phase) VALUES (1, 'prepared')`).run();
+}
+function phaseOf(db) {
+    const row = db
+        .prepare(`SELECT phase FROM compat_journal_state WHERE id = 1`)
+        .get();
+    return row?.phase ?? "prepared";
+}
+/** Read the durable journal phase (for the M2 migration host seam). */
+export function journalPhase(db) {
+    return phaseOf(db);
+}
+function setPhase(db, phase) {
+    db.prepare(`UPDATE compat_journal_state SET phase = @phase WHERE id = 1`).run({
+        "@phase": phase,
+    });
+}
+/**
+ * Verify a recorded digest by RECOMPUTING sha256 over the base64 source embedded
+ * in the legacy projection and comparing it to the recorded digest (Q03: real
+ * digest parity, not a `sha256:` prefix check). Returns false when the projection
+ * is absent or malformed, or the digest does not match the recomputed hash.
+ */
+export function verifyLegacyDigest(digest, legacyProjection) {
+    if (legacyProjection === null)
+        return false;
+    let rec;
+    try {
+        rec = JSON.parse(legacyProjection);
+    }
+    catch {
+        return false;
+    }
+    const source = rec.source;
+    if (typeof source !== "string")
+        return false;
+    const recomputed = `sha256:${createHash("sha256").update(Buffer.from(source, "base64")).digest("hex")}`;
+    return recomputed === digest;
+}
+/**
+ * Build the CompatJournalV1 over the isolated occurrence-v2 DB. Call
+ * `initCompatJournal` once before use. All record writes are append-only and
+ * best-effort/non-fatal so the agent loop is never broken (PREVENT-PI-004).
+ */
+export function createCompatJournal(db) {
+    return {
+        active() {
+            try {
+                const row = db
+                    .prepare(`SELECT 1 AS hit FROM compat_journal_v1 LIMIT 1`)
+                    .get();
+                return row !== undefined;
+            }
+            catch {
+                return false;
+            }
+        },
+        record(input) {
+            const { occurrence, legacyProjection } = input;
+            try {
+                const unrep = legacyProjection === null;
+                db.prepare(`INSERT INTO compat_journal_v1
+             (session, seq, event_id, digest, kind, legacy_projection, unrepresentable)
+           VALUES (@session, @seq, @event_id, @digest, @kind, @legacy, @unrep)
+           ON CONFLICT(session, seq) DO NOTHING`).run({
+                    "@session": occurrence.session,
+                    "@seq": Number(occurrence.seq),
+                    "@event_id": occurrence.eventId,
+                    "@digest": occurrence.digest,
+                    "@kind": occurrence.kind,
+                    // Q06: an unrepresentable row stores NO projection (legacy_projection
+                    // stays NULL); we never write a base64 body we cannot round-trip.
+                    "@legacy": legacyProjection,
+                    "@unrep": unrep ? 1 : 0,
+                });
+            }
+            catch {
+                /* non-fatal journal write — never break the agent loop */
+            }
+        },
+        isUnrepresentable(eventId, digest) {
+            try {
+                const row = db
+                    .prepare(`SELECT unrepresentable AS u FROM compat_journal_v1
+             WHERE event_id = @event_id AND digest = @digest
+             ORDER BY seq DESC LIMIT 1`)
+                    .get({ "@event_id": eventId, "@digest": digest });
+                return row?.u === 1;
+            }
+            catch {
+                return false;
+            }
+        },
+        prepare() {
+            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();
+            setPhase(db, "prepared");
+            return rows.filter((r) => r.unrepresentable === 1).map((r) => r.event_id);
+        },
+        copied() {
+            setPhase(db, "copied");
+        },
+        validate() {
+            const codes = [];
+            const phase = phaseOf(db);
+            if (!isRepresentableState(phase, "copied"))
+                codes.push(MIG_DOWN_FAIL.PHASE_UNREACHED);
+            if (!this.active())
+                codes.push(MIG_DOWN_FAIL.NOT_ACTIVE);
+            // Seq must be strictly increasing within a session (no regression).
+            const prev = new Map();
+            const rows = db
+                .prepare(`SELECT session, seq FROM compat_journal_v1 ORDER BY session ASC, seq ASC`)
+                .all();
+            for (const r of rows) {
+                const last = prev.get(r.session);
+                if (last !== undefined && r.seq <= last)
+                    codes.push(MIG_DOWN_FAIL.SEQ_REGRESSION);
+                prev.set(r.session, r.seq);
+            }
+            // Digests must verify: recompute sha256 over the stored source and compare
+            // to the recorded digest (Q03 — real parity, not just a `sha256:` prefix).
+            for (const r of db
+                .prepare(`SELECT digest, legacy_projection FROM compat_journal_v1 WHERE unrepresentable = 0`)
+                .all()) {
+                if (r.legacy_projection === null)
+                    continue;
+                if (!verifyLegacyDigest(r.digest, r.legacy_projection)) {
+                    codes.push(MIG_DOWN_FAIL.DIGEST_MISMATCH);
+                }
+            }
+            const ok = codes.length === 0;
+            if (ok)
+                setPhase(db, "validated");
+            return { ok, codes: dedupe(codes) };
+        },
+        switched() {
+            if (this.active())
+                setPhase(db, "switched");
+        },
+    };
+}
+/** A phase has reached at least `required` in the prepare→…→switched order. */
+function isRepresentableState(phase, required) {
+    const order = ["prepared", "copied", "validated", "switched"];
+    return order.indexOf(phase) >= order.indexOf(required);
+}
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}