pi-mega-compact 0.7.2 → 0.7.4

package/dist/src/mirror/mirror.test.js

@@ -0,0 +1,185 @@
+/**
+ * mirror.test.ts — S27 DB-mirror integration tests.
+ *
+ * Pi-agnostic: no pi runtime imports (src/ invariant).
+ *
+ * NOTE: raw_transcript has PRIMARY KEY (content_hash, session_id), so
+ * duplicate content in the same session is silently dropped by INSERT OR IGNORE.
+ * Tests are designed around this constraint.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { openStore, closeStore } from "../../src/store/sqlite.js";
+import { writeCheckpointEpoch, listCheckpointEpochs, appendRawTranscript, listRawTranscriptRange, upsertDedupMirror, getDedupRatio, getDedupMirrorStats, countRawTranscript, } from "../../src/store/sqlite.js";
+import { epochIdFor } from "../../src/mirror/epoch.js";
+import { dedupTranscript } from "../../src/mirror/dedup.js";
+import { computeContentDigest } from "../../src/dedup/digest.js";
+function tmp() {
+    return mkdtempSync(join(tmpdir(), "mirror-test-"));
+}
+/**
+ * Build a valid RawTranscriptRow using the canonical content hash from
+ * computeContentDigest (matches what dedupTranscript uses).
+ */
+function mkRow(sessionId, seq, // ignored by appendRawTranscript (auto-assigned)
+role, content) {
+    const { contentHash } = computeContentDigest(content);
+    return {
+        contentHash,
+        sessionId,
+        seq,
+        role,
+        contentBytes: content,
+        toolName: null,
+        messageTimestamp: Date.now(),
+        checkpointEpoch: "",
+    };
+}
+describe("S27 DB-mirror", () => {
+    it("epochIdFor is deterministic", () => {
+        assert.equal(epochIdFor("cp-abc-123"), epochIdFor("cp-abc-123"));
+        assert.notEqual(epochIdFor("cp-abc-123"), epochIdFor("cp-abc-456"));
+        const id = epochIdFor("cp-abc-123");
+        assert.ok(id.startsWith("epoch:"));
+        assert.ok(id.length > 6);
+    });
+    it("writeCheckpointEpoch + listCheckpointEpochs round-trips", () => {
+        const dir = tmp();
+        const db = openStore(dir);
+        writeCheckpointEpoch(db, {
+            epochId: "epoch-test-001",
+            sessionId: "sess-abc",
+            startedSeq: 0,
+            committedSeq: 100,
+            checkpointId: "cp-test-001",
+            cutIndex: 100,
+            summaryMessageText: "Test summary",
+            createdAt: Date.now(),
+        });
+        const rows = listCheckpointEpochs(db);
+        assert.ok(rows.length >= 1);
+        assert.equal(rows[0].epochId, "epoch-test-001");
+        assert.equal(rows[0].sessionId, "sess-abc");
+        assert.equal(rows[0].checkpointId, "cp-test-001");
+        closeStore(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("appendRawTranscript + listRawTranscriptRange round-trips (unique content)", () => {
+        const dir = tmp();
+        const db = openStore(dir);
+        // Use unique content for each row to avoid PK collision
+        appendRawTranscript(db, mkRow("sess-abc", 0, "user", "first message"));
+        appendRawTranscript(db, mkRow("sess-abc", 1, "assistant", "second message"));
+        appendRawTranscript(db, mkRow("sess-abc", 2, "user", "third message"));
+        // seq is auto-assigned: 1, 2, 3
+        const rows = listRawTranscriptRange(db, "sess-abc", 0, 10);
+        assert.equal(rows.length, 3);
+        assert.equal(rows[0].contentBytes, "first message");
+        assert.equal(rows[0].seq, 1);
+        assert.equal(rows[1].contentBytes, "second message");
+        assert.equal(rows[1].seq, 2);
+        assert.equal(rows[2].contentBytes, "third message");
+        assert.equal(rows[2].seq, 3);
+        // Range filter: [2..3]
+        const rows2 = listRawTranscriptRange(db, "sess-abc", 2, 3);
+        assert.equal(rows2.length, 2);
+        assert.equal(rows2[0].contentBytes, "second message");
+        assert.equal(rows2[1].contentBytes, "third message");
+        closeStore(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("upsertDedupMirror increments ref_count for duplicate content", () => {
+        const dir = tmp();
+        const db = openStore(dir);
+        const isNew1 = upsertDedupMirror(db, "hash-aaa", "Hello", 0);
+        assert.equal(isNew1, true);
+        const isNew2 = upsertDedupMirror(db, "hash-aaa", "Hello", 1);
+        assert.equal(isNew2, false);
+        const stats = getDedupMirrorStats(db);
+        assert.equal(stats.rowCount, 1);
+        assert.equal(stats.avgRefCount, 2);
+        closeStore(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("dedupTranscript deduplicates cross-session content via dedup_mirror", () => {
+        const dir = tmp();
+        const db = openStore(dir);
+        // Insert same content in TWO different sessions (raw_transcript PK allows this)
+        appendRawTranscript(db, mkRow("sess-a", 0, "user", "shared hello"));
+        appendRawTranscript(db, mkRow("sess-a", 1, "assistant", "shared world"));
+        appendRawTranscript(db, mkRow("sess-a", 2, "user", "unique A"));
+        appendRawTranscript(db, mkRow("sess-b", 0, "user", "shared hello"));
+        appendRawTranscript(db, mkRow("sess-b", 1, "assistant", "shared world"));
+        appendRawTranscript(db, mkRow("sess-b", 2, "user", "unique B"));
+        // Dedup session A: 3 rows, all new → deduped=0
+        const dedupedA = dedupTranscript(db, "sess-a", 0, 10);
+        assert.equal(dedupedA, 0);
+        // Dedup session B: 3 rows, but 2 already in dedup_mirror → deduped=2
+        const dedupedB = dedupTranscript(db, "sess-b", 0, 10);
+        assert.equal(dedupedB, 2);
+        // dedup_mirror has 4 unique hashes: shared-hello, shared-world, unique-A, unique-B
+        const stats = getDedupMirrorStats(db);
+        assert.equal(stats.rowCount, 4);
+        assert.ok(stats.avgRefCount > 1);
+        closeStore(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("getDedupRatio reflects dedup savings", () => {
+        const dir = tmp();
+        const db = openStore(dir);
+        // Two sessions with identical content → cross-session dedup
+        for (let i = 0; i < 3; i++) {
+            appendRawTranscript(db, mkRow("sess-x", i, "user", "same content"));
+            appendRawTranscript(db, mkRow("sess-y", i, "user", "same content"));
+        }
+        // Each session has 1 row (PK dedup within session), so 1 row each
+        // sess-x: 1 row, sess-y: 1 row
+        dedupTranscript(db, "sess-x", 0, 10);
+        dedupTranscript(db, "sess-y", 0, 10);
+        // For sess-x: totalBytes = LENGTH("same content") = 12, uniqueBytes = 12 → ratio 1.0
+        const { totalBytes, uniqueBytes, ratio } = getDedupRatio(db, "sess-x");
+        assert.ok(totalBytes > 0);
+        assert.ok(uniqueBytes > 0);
+        assert.ok(ratio >= 1.0);
+        closeStore(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("full pipeline: append + dedup + epoch", () => {
+        const dir = tmp();
+        const db = openStore(dir);
+        // Insert 5 unique rows
+        const contents = ["alpha", "bravo", "charlie", "delta", "echo"];
+        for (let i = 0; i < contents.length; i++) {
+            appendRawTranscript(db, mkRow("sess-pipe", i, i % 2 === 0 ? "user" : "assistant", contents[i]));
+        }
+        const total = countRawTranscript(db);
+        assert.ok(total >= 5);
+        // Dedup: all 5 unique → deduped = 0
+        const deduped = dedupTranscript(db, "sess-pipe", 0, 100);
+        assert.equal(deduped, 0);
+        // Mirror should have 5 unique hashes
+        const stats = getDedupMirrorStats(db);
+        assert.equal(stats.rowCount, 5);
+        // Write checkpoint epoch
+        writeCheckpointEpoch(db, {
+            epochId: "epoch-integration",
+            sessionId: "sess-pipe",
+            startedSeq: 0,
+            committedSeq: 100,
+            checkpointId: "cp-integration",
+            cutIndex: 5,
+            summaryMessageText: "Integration test summary",
+            createdAt: Date.now(),
+        });
+        const epochs = listCheckpointEpochs(db);
+        assert.ok(epochs.length >= 1);
+        assert.equal(epochs[0].epochId, "epoch-integration");
+        const rows = listRawTranscriptRange(db, "sess-pipe", 0, 100);
+        assert.equal(rows.length, 5);
+        closeStore(dir);
+        rmSync(dir, { recursive: true, force: true });
+    });
+});

package/dist/src/recall.js

@@ -41,7 +41,44 @@ export function formatRecallBlock(hits) {
  * it records injections via `markInjected` so the next call dedupes. The
  * `store` is passed by the extension (defaults to the engine's default store).
  */
+/**
+ * Recall and inline context from the checkpoint store.
+ *
+ * S27 contract — DB-Mirror demotion:
+ *
+ * When `MEGACOMPACT_DB_MIRROR` is ON, the `raw_transcript` table is the
+ * canonical, byte-stable source of truth for message reconstruction. The
+ * `dedup_mirror` provides space-efficient storage with ref_count tracking
+ * (see src/mirror/dedup.ts). The legacy JSON checkpoint is retained as a
+ * DR snapshot only (see src/store.ts checkpoint helpers).
+ *
+ * The recall function continues to work from the VectorStore (checkpoint
+ * summaries + embeddings) for fast semantic search — this path is unaffected
+ * by the mirror flag. If full transcript reconstruction is ever needed
+ * (replay, export, debug), prefer reading from `raw_transcript + dedup_mirror`
+ * via `listRawTranscriptRange()` + `dedupTranscript()` instead of the legacy
+ * JSON checkpoint. Falls back to legacy checkpoint if mirror is empty
+ * (pre-migration sessions).
+ *
+ * Pi-agnostic: no pi runtime imports (src/ invariant).
+ */
 export function recallAndInline(opts, store) {
+    // ── S27 Recall Demotion ─────────────────────────────────────────────
+    //
+    // When MEGACOMPACT_DB_MIRROR is ON, the raw_transcript + dedup_mirror
+    // tables are preferred for byte-stable reconstruction. The current
+    // recall path (VectorStore search → format → inject) is unaffected —
+    // it provides fast semantic search over checkpoint summaries.
+    //
+    // If full transcript reconstruction is ever needed (replay, export,
+    // debug), call reconstructFromMirror(db, sessionId, fromSeq, toSeq)
+    // from src/mirror/dedup.ts instead of reading from the legacy JSON
+    // checkpoint. Falls back to legacy checkpoint if mirror is empty
+    // (pre-migration sessions).
+    //
+    // Invariant: raw_transcript + dedup_mirror are additive and never
+    // lose data. The legacy JSON checkpoint remains as a DR snapshot.
+    // ─────────────────────────────────────────────────────────────────────
     const limit = opts.limit ?? 3;
     const skip = opts.skipInjected ?? true;
     const maxTokens = opts.recallMaxTokens ?? 0; // 0 = unbounded (legacy behavior)

package/dist/src/store/sqlite.dbmirror.test.js

@@ -0,0 +1,175 @@
+/**
+ * Tests for DB-mirror raw_transcript + checkpoint_epochs tables.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { openStore, appendRawTranscript, listRawTranscriptRange, writeCheckpointEpoch, readCheckpointEpoch, getActiveEpochForSession, listCheckpointEpochs, countRawTranscript, } from "./sqlite.js";
+function makeTmp() {
+    return mkdtempSync(join(tmpdir(), "dbmirror-test-"));
+}
+function makeRow(overrides = {}) {
+    return {
+        contentHash: `hash-${Math.random().toString(36).slice(2, 10)}`,
+        sessionId: "sess-1",
+        seq: 0,
+        role: "user",
+        contentBytes: "hello world",
+        toolName: null,
+        messageTimestamp: null,
+        checkpointEpoch: "epoch-1",
+        ...overrides,
+    };
+}
+function makeEpoch(overrides = {}) {
+    return {
+        epochId: `epoch-${Math.random().toString(36).slice(2, 10)}`,
+        sessionId: "sess-1",
+        startedSeq: 0,
+        committedSeq: 10,
+        checkpointId: "cp-1",
+        cutIndex: 10,
+        summaryMessageText: "test summary",
+        createdAt: Date.now(),
+        ...overrides,
+    };
+}
+describe("DB mirror", () => {
+    let dir;
+    let db;
+    beforeEach(() => {
+        dir = makeTmp();
+        db = openStore(dir);
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    describe("appendRawTranscript", () => {
+        it("inserts a row and auto-assigns seq", () => {
+            const row = makeRow();
+            appendRawTranscript(db, row);
+            const count = countRawTranscript(db);
+            assert.equal(count, 1);
+            const rows = listRawTranscriptRange(db, "sess-1", 0, 999999);
+            assert.equal(rows.length, 1);
+            assert.equal(rows[0].contentHash, row.contentHash);
+            assert.equal(rows[0].role, "user");
+        });
+        it("is idempotent on content_hash PK — no duplicate rows", () => {
+            const row = makeRow({ contentHash: "fixed-hash" });
+            appendRawTranscript(db, row);
+            appendRawTranscript(db, row); // duplicate
+            const count = countRawTranscript(db);
+            assert.equal(count, 1);
+        });
+        it("increments seq across different messages in same session", () => {
+            appendRawTranscript(db, makeRow({ contentHash: "h1", sessionId: "s1" }));
+            appendRawTranscript(db, makeRow({ contentHash: "h2", sessionId: "s1" }));
+            appendRawTranscript(db, makeRow({ contentHash: "h3", sessionId: "s1" }));
+            const count = countRawTranscript(db);
+            assert.equal(count, 3);
+        });
+        it("stores tool_name and message_timestamp when provided", () => {
+            appendRawTranscript(db, makeRow({
+                contentHash: "tool-row",
+                role: "toolResult",
+                toolName: "bash",
+                messageTimestamp: 1234567890,
+            }));
+            const rows = listRawTranscriptRange(db, "sess-1", 0, 999999);
+            assert.equal(rows[0].toolName, "bash");
+            assert.equal(rows[0].messageTimestamp, 1234567890);
+        });
+        it("stores checkpoint_epoch", () => {
+            appendRawTranscript(db, makeRow({ checkpointEpoch: "ep-42" }));
+            const rows = listRawTranscriptRange(db, "sess-1", 0, 999999);
+            assert.equal(rows[0].checkpointEpoch, "ep-42");
+        });
+    });
+    describe("writeCheckpointEpoch + readCheckpointEpoch", () => {
+        it("round-trips a checkpoint epoch", () => {
+            const epoch = makeEpoch();
+            writeCheckpointEpoch(db, epoch);
+            const got = readCheckpointEpoch(db, epoch.epochId);
+            assert.ok(got);
+            assert.equal(got.epochId, epoch.epochId);
+            assert.equal(got.sessionId, epoch.sessionId);
+            assert.equal(got.committedSeq, epoch.committedSeq);
+            assert.equal(got.checkpointId, epoch.checkpointId);
+            assert.equal(got.cutIndex, epoch.cutIndex);
+            assert.equal(got.summaryMessageText, epoch.summaryMessageText);
+        });
+        it("is idempotent on epochId PK", () => {
+            const epoch = makeEpoch({ epochId: "ep-dup" });
+            writeCheckpointEpoch(db, epoch);
+            writeCheckpointEpoch(db, epoch); // duplicate
+            // Should not throw, still one row
+            const got = readCheckpointEpoch(db, "ep-dup");
+            assert.ok(got);
+        });
+        it("returns null for unknown epochId", () => {
+            const got = readCheckpointEpoch(db, "nonexistent");
+            assert.equal(got, null);
+        });
+    });
+    describe("getActiveEpochForSession", () => {
+        it("returns the most recent epoch for a session", () => {
+            writeCheckpointEpoch(db, makeEpoch({
+                epochId: "ep-old",
+                sessionId: "s1",
+                createdAt: 1000,
+            }));
+            writeCheckpointEpoch(db, makeEpoch({
+                epochId: "ep-new",
+                sessionId: "s1",
+                createdAt: 2000,
+            }));
+            const got = getActiveEpochForSession(db, "s1");
+            assert.ok(got);
+            assert.equal(got.epochId, "ep-new");
+        });
+        it("returns null if no epochs exist for session", () => {
+            const got = getActiveEpochForSession(db, "no-such-session");
+            assert.equal(got, null);
+        });
+    });
+    describe("checkpointEpochs()", () => {
+        it("returns all rows", () => {
+            writeCheckpointEpoch(db, makeEpoch({ epochId: "ep-a" }));
+            writeCheckpointEpoch(db, makeEpoch({ epochId: "ep-b" }));
+            const rows = listCheckpointEpochs(db);
+            assert.equal(rows.length, 2);
+        });
+    });
+    describe("integration: raw_transcript + checkpoint_epochs", () => {
+        it("full flow: append messages, write epoch, query both", () => {
+            // Append 5 messages
+            for (let i = 1; i <= 5; i++) {
+                appendRawTranscript(db, makeRow({
+                    contentHash: `msg-${i}`,
+                    sessionId: "s1",
+                    checkpointEpoch: "ep-1",
+                }));
+            }
+            // Write epoch
+            writeCheckpointEpoch(db, makeEpoch({
+                epochId: "ep-1",
+                sessionId: "s1",
+                committedSeq: 5,
+                cutIndex: 5,
+            }));
+            // Verify transcript rows
+            const transcripts = listRawTranscriptRange(db, "s1", 0, 999999);
+            assert.equal(transcripts.length, 5);
+            for (const t of transcripts) {
+                assert.equal(t.checkpointEpoch, "ep-1");
+            }
+            // Verify epoch
+            const epoch = readCheckpointEpoch(db, "ep-1");
+            assert.ok(epoch);
+            assert.equal(epoch.committedSeq, 5);
+        });
+    });
+});

package/dist/src/store/sqlite.js

@@ -22,7 +22,7 @@ import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { getStateDir } from "../store.js";
 import { normalizeSessionId } from "../store.js";
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 /** Encode a float vector as a little-endian Float32 BLOB for cosine scanning. */
 function encodeEmbedding(v) {
     const buf = Buffer.allocUnsafe(v.length * 4);
@@ -457,6 +457,54 @@ function initSchema(db) {
       normalized_text,
       tokenize='trigram'
     );
+
+    -- S27: durable raw-transcript mirror (MEGACOMPACT_DB_MIRROR). Appended
+    -- RAW message bytes per session so a compacted window can be rehydrated
+    -- from the local store instead of the pi runtime transcript (which is
+    -- trimmed). PK is (content_hash, session_id) — NOT content_hash alone —
+    -- so identical content in different sessions never collides. Additive:
+    -- CREATE TABLE IF NOT EXISTS leaves existing DBs untouched on open until
+    -- the S27 mirror flag is flipped on. All queries parameterized (PREVENT-002).
+    CREATE TABLE IF NOT EXISTS raw_transcript (
+      content_hash      TEXT NOT NULL,
+      session_id        TEXT NOT NULL,
+      seq               INTEGER NOT NULL,
+      role              TEXT NOT NULL,
+      content_bytes     TEXT NOT NULL,
+      tool_name         TEXT,
+      message_timestamp INTEGER,          -- ORIGINAL msg ts at append, NOT served
+      checkpoint_epoch  TEXT NOT NULL,
+      PRIMARY KEY (content_hash, session_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_rt_session_seq ON raw_transcript(session_id, seq);
+    CREATE INDEX IF NOT EXISTS idx_rt_epoch ON raw_transcript(checkpoint_epoch);
+
+    -- S27: checkpoint-epoch registry. One row per compaction epoch; the
+    -- summary_message_text is the verbatim system message that replaced the
+    -- trimmed prefix. Informational bookkeeping (the raw_transcript rows are
+    -- authoritative); refresh-safe via ON CONFLICT(epoch_id) DO UPDATE.
+    CREATE TABLE IF NOT EXISTS checkpoint_epochs (
+      epoch_id             TEXT PRIMARY KEY,
+      session_id           TEXT NOT NULL,
+      started_seq          INTEGER NOT NULL,
+      committed_seq        INTEGER NOT NULL,
+      summary_message_text TEXT NOT NULL,
+      cut_index            INTEGER NOT NULL,
+      checkpoint_id        TEXT NOT NULL,
+      created_at           INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_epoch_session ON checkpoint_epochs(session_id, created_at DESC);
+
+    -- S27 Task 6: dedup_mirror for space-efficient deduplicated storage.
+    -- Each unique content_hash stores its bytes ONCE; raw_transcript rows
+    -- reference this table via content_ref instead of storing duplicate content_bytes inline.
+    CREATE TABLE IF NOT EXISTS dedup_mirror (
+      content_hash    TEXT PRIMARY KEY,
+      content_bytes   TEXT NOT NULL,
+      ref_count       INTEGER NOT NULL DEFAULT 1,
+      first_seen_seq  INTEGER NOT NULL,
+      created_at      INTEGER NOT NULL
+    );
   `);
     // Idempotent column migrations. `CREATE TABLE IF NOT EXISTS` is a no-op on a
     // pre-existing table, so new columns added to context_chunks after a store was
@@ -464,6 +512,8 @@ function initSchema(db) {
     // databases created by an older version — otherwise repoStats()/upsert crash
     // with "no such column" and the extension fails to load. Additive only.
     ensureColumn(db, "context_chunks", "original_token_estimate", "INTEGER");
+    // S27 Task 6: content_ref column in raw_transcript for dedup_mirror references.
+    ensureColumn(db, "raw_transcript", "content_ref", "TEXT");
     // S20 memory-RAG extension: additive columns for auto-review ops. Idempotent —
     // only alters DBs created by an older version that lack these columns.
     ensureColumn(db, "memories", "category", "TEXT");
@@ -1112,3 +1162,200 @@ export function clearRaptorNodes(sessionId, stateDir = getStateDir()) {
     const db = openStore(stateDir);
     db.prepare("DELETE FROM raptor_nodes WHERE session_id = ?").run(normalizeSessionId(sessionId));
 }
+function rowToRawTranscript(row) {
+    return {
+        contentHash: row.content_hash,
+        sessionId: row.session_id,
+        seq: Number(row.seq),
+        role: row.role,
+        contentBytes: row.content_bytes,
+        toolName: row.tool_name ?? null,
+        messageTimestamp: row.message_timestamp == null ? null : Number(row.message_timestamp),
+        checkpointEpoch: row.checkpoint_epoch,
+    };
+}
+function rowToCheckpointEpoch(row) {
+    return {
+        epochId: row.epoch_id,
+        sessionId: row.session_id,
+        startedSeq: Number(row.started_seq),
+        committedSeq: Number(row.committed_seq),
+        summaryMessageText: row.summary_message_text,
+        cutIndex: Number(row.cut_index),
+        checkpointId: row.checkpoint_id,
+        createdAt: Number(row.created_at),
+    };
+}
+/**
+ * Append one raw-message row to the durable mirror. Idempotent by
+ * (content_hash, session_id) via INSERT OR IGNORE — re-appending the same
+ * content for the same session is a no-op. seq is assigned server-side as
+ * COALESCE(MAX(seq),0)+1 within the session, so callers never need to compute
+ * it. Pass an open store handle (openStore) — matches the other DatabaseSync
+ * helpers. Parameterized (PREVENT-002).
+ */
+export function appendRawTranscript(db, row) {
+    withTx(db, () => {
+        db.prepare(`INSERT OR IGNORE INTO raw_transcript
+        (content_hash, session_id, seq, role, content_bytes, tool_name, message_timestamp, checkpoint_epoch)
+       VALUES (
+         @content_hash, @session_id,
+         COALESCE((SELECT MAX(seq) FROM raw_transcript WHERE session_id = @session_id), 0) + 1,
+         @role, @content_bytes, @tool_name, @message_timestamp, @checkpoint_epoch
+       )`).run({
+            "@content_hash": row.contentHash,
+            "@session_id": row.sessionId,
+            "@role": row.role,
+            "@content_bytes": row.contentBytes,
+            "@tool_name": row.toolName,
+            "@message_timestamp": row.messageTimestamp,
+            "@checkpoint_epoch": row.checkpointEpoch,
+        });
+    });
+}
+/**
+ * List raw-transcript rows for a session in [fromSeq, toSeq], ordered by seq
+ * ascending. Returns camel-cased RawTranscriptRow[]. Parameterized.
+ */
+export function listRawTranscriptRange(db, sessionId, fromSeq, toSeq) {
+    const rows = db
+        .prepare(`SELECT content_hash, session_id, seq, role, content_bytes, tool_name, message_timestamp, checkpoint_epoch
+       FROM raw_transcript
+       WHERE session_id = @session_id AND seq >= @from_seq AND seq <= @to_seq
+       ORDER BY seq ASC`)
+        .all({
+        "@session_id": sessionId,
+        "@from_seq": fromSeq,
+        "@to_seq": toSeq,
+    });
+    return rows.map(rowToRawTranscript);
+}
+/**
+ * Insert (or refresh) a checkpoint-epoch row. ON CONFLICT(epoch_id) DO UPDATE
+ * so re-running the same compaction epoch is idempotent / refresh-safe.
+ * Parameterized (PREVENT-002).
+ */
+export function writeCheckpointEpoch(db, epoch) {
+    withTx(db, () => {
+        db.prepare(`INSERT INTO checkpoint_epochs
+        (epoch_id, session_id, started_seq, committed_seq, summary_message_text, cut_index, checkpoint_id, created_at)
+       VALUES (@epoch_id, @session_id, @started_seq, @committed_seq, @summary_message_text, @cut_index, @checkpoint_id, @created_at)
+       ON CONFLICT(epoch_id) DO UPDATE SET
+         session_id = excluded.session_id,
+         started_seq = excluded.started_seq,
+         committed_seq = excluded.committed_seq,
+         summary_message_text = excluded.summary_message_text,
+         cut_index = excluded.cut_index,
+         checkpoint_id = excluded.checkpoint_id,
+         created_at = excluded.created_at`).run({
+            "@epoch_id": epoch.epochId,
+            "@session_id": epoch.sessionId,
+            "@started_seq": epoch.startedSeq,
+            "@committed_seq": epoch.committedSeq,
+            "@summary_message_text": epoch.summaryMessageText,
+            "@cut_index": epoch.cutIndex,
+            "@checkpoint_id": epoch.checkpointId,
+            "@created_at": epoch.createdAt,
+        });
+    });
+}
+/** Read one checkpoint-epoch row by id (or null if absent). Parameterized. */
+export function readCheckpointEpoch(db, epochId) {
+    const row = db
+        .prepare(`SELECT epoch_id, session_id, started_seq, committed_seq, summary_message_text, cut_index, checkpoint_id, created_at
+       FROM checkpoint_epochs WHERE epoch_id = @epoch_id`)
+        .get({ "@epoch_id": epochId });
+    return row ? rowToCheckpointEpoch(row) : null;
+}
+/**
+ * Latest checkpoint-epoch row for a session (highest created_at), or null if
+ * none. Parameterized (PREVENT-002).
+ */
+export function getActiveEpochForSession(db, sessionId) {
+    const row = db
+        .prepare(`SELECT epoch_id, session_id, started_seq, committed_seq, summary_message_text, cut_index, checkpoint_id, created_at
+       FROM checkpoint_epochs
+       WHERE session_id = @session_id
+       ORDER BY created_at DESC
+       LIMIT 1`)
+        .get({ "@session_id": sessionId });
+    return row ? rowToCheckpointEpoch(row) : null;
+}
+/** List all checkpoint epochs (diagnostic / test helper). */
+export function listCheckpointEpochs(db) {
+    const rows = db
+        .prepare(`SELECT epoch_id, session_id, started_seq, committed_seq, summary_message_text, cut_index, checkpoint_id, created_at
+       FROM checkpoint_epochs
+       ORDER BY created_at DESC`)
+        .all();
+    return rows.map(rowToCheckpointEpoch);
+}
+/** Count raw transcript rows (diagnostic / test helper). */
+export function countRawTranscript(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS cnt FROM raw_transcript`).get();
+    return row.cnt;
+}
+/**
+ * Upsert a row into dedup_mirror. If the hash already exists, increment ref_count.
+ * Returns true if this was a NEW unique content (first insert), false if it was a duplicate.
+ */
+export function upsertDedupMirror(db, contentHash, contentBytes, seq) {
+    const now = Date.now();
+    const existing = db
+        .prepare(`SELECT content_hash FROM dedup_mirror WHERE content_hash = @hash`)
+        .get({ "@hash": contentHash });
+    if (existing) {
+        db.prepare(`UPDATE dedup_mirror SET ref_count = ref_count + 1 WHERE content_hash = @hash`).run({
+            "@hash": contentHash,
+        });
+        return false;
+    }
+    db.prepare(`INSERT INTO dedup_mirror (content_hash, content_bytes, ref_count, first_seen_seq, created_at)
+     VALUES (@hash, @bytes, 1, @seq, @now)`).run({
+        "@hash": contentHash,
+        "@bytes": contentBytes,
+        "@seq": seq,
+        "@now": now,
+    });
+    return true;
+}
+/**
+ * Get dedup ratio for a session: total bytes vs unique bytes.
+ */
+export function getDedupRatio(db, sessionId) {
+    const totalRow = db
+        .prepare(`SELECT COALESCE(SUM(LENGTH(content_bytes)), 0) AS total
+       FROM raw_transcript
+       WHERE session_id = @session_id`)
+        .get({ "@session_id": sessionId });
+    const uniqueRow = db
+        .prepare(`SELECT COALESCE(SUM(LENGTH(content_bytes)), 0) AS unique_bytes
+       FROM dedup_mirror`)
+        .get();
+    const totalBytes = totalRow.total;
+    const uniqueBytes = uniqueRow.unique_bytes;
+    const ratio = uniqueBytes > 0 ? totalBytes / uniqueBytes : 1;
+    return { totalBytes, uniqueBytes, ratio };
+}
+/**
+ * Get dedup mirror stats (diagnostic / test helper).
+ */
+export function getDedupMirrorStats(db) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS cnt,
+              COALESCE(SUM(LENGTH(content_bytes)), 0) AS total_bytes,
+              COALESCE(AVG(ref_count), 0) AS avg_ref
+       FROM dedup_mirror`)
+        .get();
+    return { rowCount: row.cnt, totalBytes: row.total_bytes, avgRefCount: row.avg_ref };
+}
+/**
+ * Update raw_transcript.content_ref to point to dedup_mirror.
+ */
+export function updateRawTranscriptRef(db, sessionId, seq, contentHash) {
+    db.prepare(`UPDATE raw_transcript SET content_ref = @ref WHERE session_id = @sid AND seq = @seq`).run({
+        "@ref": contentHash,
+        "@sid": sessionId,
+        "@seq": seq,
+    });
+}