pi-mega-compact 0.16.3 → 0.17.1

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

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

@@ -0,0 +1,53 @@
+/**
+ * vector-cortex/ledger/emit.ts — VC1A ledger emit seam.
+ *
+ * The single structured-event surface for the EventV2 ledger path. It mirrors
+ * the VC0B replay emit seam (`src/vector-cortex/replay/emit.ts`): the same
+ * non-fatal, structured-JSON `ts`+`event` contract (`src/log.ts` LogEntry),
+ * delivered through an injected emit callback so it stays pi-agnostic,
+ * deterministically testable, and network-free (PREVENT-PI-004).
+ *
+ * Carries only the two EventV2 events:
+ *   - vector_cortex_event_decoded          (a V2 occurrence was byte-decoded)
+ *   - vector_cortex_event_validation_failed (a V2 conformity check failed)
+ *
+ * Flag gating: this is VC1A's single real consumer of `VC1A_ENABLED()`. When the
+ * flag is OFF the reporter emits NOTHING (zero observability writes) — the
+ * VC1A mode-C byte-identical behavior — while the codec/validator still operate.
+ * The flag is read per-call so a live toggle takes effect immediately.
+ */
+import { VC1A_ENABLED } from "../../config/vector-cortex.js";
+function safe(fn) {
+    return (event, fields) => {
+        try {
+            fn(event, fields);
+        }
+        catch {
+            /* non-fatal observability — never break the agent loop */
+        }
+    };
+}
+/**
+ * Build a typed reporter over an injected emit callback. Emission is gated on
+ * `VC1A_ENABLED()` — flag OFF means zero ledger observability writes (mode-C
+ * parity). `emit` is optional: absent (or flag off) degrades to a no-op.
+ */
+export function createLedgerReporter(emit) {
+    const fire = safe((event, fields) => {
+        if (VC1A_ENABLED())
+            emit?.(event, fields);
+    });
+    return {
+        eventDecoded(fields) {
+            fire("vector_cortex_event_decoded", fields);
+        },
+        validationFailed(fields) {
+            fire("vector_cortex_event_validation_failed", fields);
+        },
+    };
+}
+/** Export the event names for consumers that match on them. */
+export const LEDGER_EVENTS = [
+    "vector_cortex_event_decoded",
+    "vector_cortex_event_validation_failed",
+];

package/dist/vector-cortex/ledger/event-codec.js

@@ -0,0 +1,72 @@
+/**
+ * vector-cortex/ledger/event-codec.ts — EventV2 byte-authority codec, Mode A
+ * (VC1A, TRIAD_RESILIENCE).
+ *
+ * A retains `originalBytes` + a SHA-256 `bytesDigest` and classifies strict
+ * UTF-8 (success) vs invalid-byte content WITHOUT replacement decoding:
+ * `TextDecoder(..., {fatal:true})` either yields text or throws — invalid input
+ * is represented only as `{valid:false, base64}` and is NEVER lossy-replaced.
+ * `canonicalNfc` is computed ONLY as a derived field for valid UTF-8 and is
+ * NEVER used for identity, digest, or byte reconstruction — `decode` returns the
+ * authoritative `originalBytes` exactly.
+ *
+ * Mode B (`./event-codecB.ts`) is a genuinely independent implementation of the
+ * same byte rule; A and B share no subroutine and must agree byte-for-byte.
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+import nodeCrypto from "node:crypto";
+/** Mode-A internal SHA-256 helper (NOT shared with mode B). */
+function digestSha256A(bytes) {
+    const hex = nodeCrypto.createHash("sha256").update(bytes).digest("hex");
+    return `sha256:${hex}`;
+}
+/** Mode-A internal base64 (NOT shared with mode B). */
+function base64EncodeA(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+/**
+ * Strict UTF-8 classification with FATAL decoding (never replaces invalid bytes
+ * with U+FFFD). Returns the decoded text, or `{valid:false, base64}`.
+ */
+export function classifyUtf8(bytes) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return { valid: true, text };
+    }
+    catch {
+        return { valid: false, base64: base64EncodeA(bytes) };
+    }
+}
+/** Build the Mode-A byte-authority codec. */
+export function createEventCodec() {
+    return {
+        encode(input) {
+            const bytes = input.bytes;
+            const bytesDigest = digestSha256A(bytes);
+            const utf8 = classifyUtf8(bytes);
+            const event = {
+                schema: "event-v2",
+                sessionId: input.sessionId,
+                seq: input.seq,
+                eventId: input.eventId,
+                role: input.role,
+                kind: input.kind,
+                originalBytes: bytes,
+                bytesDigest,
+                utf8,
+                occurredAtMs: input.occurredAtMs,
+            };
+            if (input.toolCallId !== undefined)
+                event.toolCallId = input.toolCallId;
+            // canonicalNfc is a DERIVED search key — valid UTF-8 only, never identity.
+            if (utf8.valid)
+                event.canonicalNfc = utf8.text.normalize("NFC");
+            return event;
+        },
+        decode(event) {
+            return event.originalBytes;
+        },
+        classifyUtf8,
+    };
+}

package/dist/vector-cortex/ledger/event-codecB.js

@@ -0,0 +1,76 @@
+/**
+ * vector-cortex/ledger/event-codecB.ts — EventV2 byte-authority codec, Mode B
+ * (VC1A, TRIAD_RESILIENCE).
+ *
+ * B is a GENUINELY independent raw-byte record implementation of the SAME byte
+ * rule as Mode A (`./event-codec.ts`). It shares NO subroutine with A: its own
+ * SHA-256 helper, its own base64 helper, its own strict-UTF-8 classifier, and
+ * its own raw record — the lesson from VC0B-I09 (a mode-B tested against code
+ * identical to A is a tautology). Because the digest of given bytes is a pure
+ * function, two independent implementations MUST agree byte-for-byte; the
+ * acceptance test asserts `bytesDigest` parity across the fixture corpus.
+ *
+ * B retains `originalBytes` + `bytesDigest` and classifies strict UTF-8 with no
+ * lossy replacement; `canonicalNfc` is derived for valid UTF-8 but never used
+ * for identity, digest, or reconstruction.
+ *
+ * Pure/deterministic — no console, no network, no side effects (PREVENT-PI-004).
+ */
+import nodeCrypto from "node:crypto";
+/** Mode-B internal SHA-256 helper (independent of A's — no shared subroutine). */
+function digestSha256B(bytes) {
+    const d = nodeCrypto.createHash("sha256");
+    d.update(bytes);
+    const hex = d.digest("hex");
+    return `sha256:${hex}`;
+}
+/** Mode-B internal base64 (independent of A's). */
+function base64EncodeB(bytes) {
+    let out = "";
+    const buf = Buffer.from(bytes);
+    for (let i = 0; i < buf.length; i += 3) {
+        const b0 = buf[i];
+        const b1 = i + 1 < buf.length ? buf[i + 1] : -1;
+        const b2 = i + 2 < buf.length ? buf[i + 2] : -1;
+        out += CHARS[(b0 >> 2) & 63];
+        out += CHARS[((b0 & 3) << 4) | (b1 < 0 ? 0 : (b1 >> 4) & 15)];
+        if (b1 >= 0)
+            out += CHARS[((b1 & 15) << 2) | (b2 < 0 ? 0 : (b2 >> 6) & 3)];
+        if (b2 >= 0)
+            out += CHARS[b2 & 63];
+    }
+    // Padding (independent reconstruction of standard base64).
+    const pad = (3 - (buf.length % 3)) % 3;
+    for (let i = 0; i < pad; i++)
+        out += "=";
+    return out;
+}
+const CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Mode-B strict UTF-8 classifier (fatal decode; no replacement). */
+function classifyUtf8B(bytes) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return { valid: true, text };
+    }
+    catch {
+        return { valid: false, base64: base64EncodeB(bytes) };
+    }
+}
+/** Independently digest + classify raw bytes into a B record. */
+export function recordRawBytesB(bytes) {
+    const bytesDigest = digestSha256B(bytes);
+    const utf8 = classifyUtf8B(bytes);
+    const record = { originalBytes: bytes, bytesDigest, utf8 };
+    if (utf8.valid) {
+        return { originalBytes: bytes, bytesDigest, utf8, canonicalNfc: utf8.text.normalize("NFC") };
+    }
+    return record;
+}
+/**
+ * Independent digest check: recompute the SHA-256 over an EventV2's
+ * `originalBytes` via B's OWN algorithm and compare to the stored digest.
+ * Returns the recomputed digest string (parity-checked by the caller).
+ */
+export function digestCheckB(event) {
+    return digestSha256B(event.originalBytes);
+}

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