pi-mega-compact 0.7.8 → 0.8.0

package/dist/src/store/sqlite/meta.js

@@ -0,0 +1,82 @@
+/**
+ * meta.ts — `meta` table key/value helpers + cumulative counters
+ * (tokens_saved, dedup stats, compact count, recall injected, cache-hit tokens).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+/** Read a string-valued meta key (or undefined). Used for cumulative counters. */
+export function getMeta(key, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value;
+}
+/**
+ * Cumulative "tokens saved" — the sum of stored checkpoint token estimates across
+ * all compactions in this store (one per repo). Persisted in the SQLite `meta`
+ * table so it survives session restarts and travels with the repo's state dir,
+ * mirroring how `storageDedupRate` is cumulative. Incremented in VectorStore.add()
+ * when a new (non-deduped) checkpoint is persisted.
+ */
+export function getTokensSaved(stateDir = getStateDir()) {
+    const raw = getMeta("tokens_saved", stateDir);
+    const n = raw == null ? 0 : Number(raw);
+    return Number.isFinite(n) ? n : 0;
+}
+/** Add `delta` (>=0) to the cumulative tokens-saved counter. */
+export function addTokensSaved(delta, stateDir = getStateDir()) {
+    if (!(delta > 0))
+        return;
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO meta(key, value) VALUES('tokens_saved', ?)
+     ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + ? AS TEXT)`).run(String(delta), delta);
+}
+/** Read a store-wide integer counter from the meta table (0 if absent). */
+export function getMetaNumber(key, stateDir = getStateDir()) {
+    const raw = getMeta(key, stateDir);
+    const n = raw == null ? 0 : Number(raw);
+    return Number.isFinite(n) ? n : 0;
+}
+/** Atomically add `delta` to an integer meta counter. */
+function incMeta(key, delta, stateDir = getStateDir()) {
+    if (!(delta > 0))
+        return;
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + ? AS TEXT)`).run(key, String(delta), delta);
+}
+/** Read the cumulative store-wide dedup counters. */
+export function getDedupStats(stateDir = getStateDir()) {
+    return {
+        attempts: getMetaNumber("dedup_attempts", stateDir),
+        deduped: getMetaNumber("deduped", stateDir),
+    };
+}
+/** Increment the store-wide dedup counters for one add() call. */
+export function bumpDedupStats(deduped, stateDir = getStateDir()) {
+    incMeta("dedup_attempts", 1, stateDir);
+    if (deduped)
+        incMeta("deduped", 1, stateDir);
+}
+// --- Live dashboard counters (schemaless meta key/value — NO migration) -----
+// These reuse the private `incMeta` atomically-incrementing integer counter so
+// all cumulative tallies live in the same `meta` table as tokens_saved etc.
+export function incCompactCount(stateDir = getStateDir()) {
+    incMeta("compact_count", 1, stateDir);
+}
+export function getCompactCount(stateDir = getStateDir()) {
+    return getMetaNumber("compact_count", stateDir);
+}
+export function incRecallInjected(n, stateDir = getStateDir()) {
+    if (n > 0)
+        incMeta("recall_injected", n, stateDir);
+}
+export function getRecallInjected(stateDir = getStateDir()) {
+    return getMetaNumber("recall_injected", stateDir);
+}
+export function incCacheHitTokens(delta, stateDir = getStateDir()) {
+    if (delta > 0)
+        incMeta("cache_hit_tokens_saved", delta, stateDir);
+}
+export function getCacheHitTokensSaved(stateDir = getStateDir()) {
+    return getMetaNumber("cache_hit_tokens_saved", stateDir);
+}

package/dist/src/store/sqlite/model-snapshots.js

@@ -0,0 +1,47 @@
+/**
+ * model-snapshots.ts — `model_snapshots` table (active model/provider per repo).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+/** Persist the active model/provider for a repo (latest row wins per repo). */
+export function recordModelSnapshot(repoRoot, snap, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO model_snapshots
+       (repo_root, provider, provider_name, model_id, model_name, input_rate,
+        output_rate, context_window, max_tokens, reasoning, captured_at)
+     VALUES (@repo_root, @provider, @provider_name, @model_id, @model_name,
+             @input_rate, @output_rate, @context_window, @max_tokens, @reasoning, @captured_at)`).run({
+        repo_root: repoRoot,
+        provider: snap.provider,
+        provider_name: snap.providerName,
+        model_id: snap.modelId,
+        model_name: snap.modelName,
+        input_rate: snap.inputRate,
+        output_rate: snap.outputRate,
+        context_window: snap.contextWindow,
+        max_tokens: snap.maxTokens,
+        reasoning: snap.reasoning ? 1 : 0,
+        captured_at: Date.now(),
+    });
+}
+/** Most recent model/provider snapshot for a repo, or undefined. */
+export function latestModelSnapshot(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare(`SELECT * FROM model_snapshots ORDER BY captured_at DESC LIMIT 1`)
+        .get();
+    if (!row)
+        return undefined;
+    return {
+        provider: row.provider,
+        providerName: row.provider_name,
+        modelId: row.model_id,
+        modelName: row.model_name,
+        inputRate: row.input_rate,
+        outputRate: row.output_rate,
+        contextWindow: row.context_window,
+        maxTokens: row.max_tokens,
+        reasoning: row.reasoning === 1,
+        capturedAt: row.captured_at,
+    };
+}

package/dist/src/store/sqlite/raptor.js

@@ -0,0 +1,57 @@
+/**
+ * raptor.ts — Sprint 13 RAPTOR node persistence.
+ */
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { openStore, jsonText, encodeEmbedding, decodeEmbedding } from "./utils.js";
+/** Persist a single RAPTOR node (upsert by (session_id, id)). */
+export function upsertRaptorNode(node, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO raptor_nodes(id, session_id, level, parent_id, children, summary, embedding_blob, quality_marker, token_estimate, built_at)
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(session_id, id) DO UPDATE SET
+       level=excluded.level, parent_id=excluded.parent_id, children=excluded.children,
+       summary=excluded.summary, embedding_blob=excluded.embedding_blob,
+       quality_marker=excluded.quality_marker, token_estimate=excluded.token_estimate,
+       built_at=excluded.built_at`).run(node.id, node.sessionId, node.level, node.parentId, jsonText(node.children), node.summary, encodeEmbedding(node.embedding), node.qualityMarker, node.tokenEstimate, node.builtAt);
+}
+/** Persist an entire built RAPTOR tree for a session (shadow or live). */
+export function saveRaptorTree(sessionId, tree, builtAt, stateDir = getStateDir()) {
+    for (const node of tree.nodes.values()) {
+        upsertRaptorNode({
+            id: node.id,
+            sessionId,
+            level: node.level,
+            parentId: node.parentId,
+            children: node.children,
+            summary: node.summary,
+            embedding: node.embedding,
+            qualityMarker: node.qualityMarker,
+            tokenEstimate: node.tokenEstimate,
+            builtAt,
+        }, stateDir);
+    }
+}
+/** Load all RAPTOR nodes for a session. */
+export function listRaptorNodes(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db
+        .prepare("SELECT * FROM raptor_nodes WHERE session_id = ? ORDER BY level ASC, id ASC")
+        .all(normalizeSessionId(sessionId));
+    return rows.map((row) => ({
+        id: row.id,
+        sessionId: row.session_id,
+        level: row.level,
+        parentId: row.parent_id ?? null,
+        children: row.children ? JSON.parse(row.children) : [],
+        summary: row.summary ?? "",
+        embedding: decodeEmbedding(row.embedding_blob),
+        qualityMarker: row.quality_marker ?? "low",
+        tokenEstimate: row.token_estimate ?? 0,
+        builtAt: Number(row.built_at ?? 0),
+    }));
+}
+/** Delete all RAPTOR nodes for a session (rollback/cleanup). */
+export function clearRaptorNodes(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    db.prepare("DELETE FROM raptor_nodes WHERE session_id = ?").run(normalizeSessionId(sessionId));
+}

package/dist/src/store/sqlite/raw-transcript.js

@@ -0,0 +1,134 @@
+import { withTx } from "./utils.js";
+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;
+}

package/dist/src/store/sqlite/schema.js

@@ -0,0 +1,294 @@
+import { ACHIEVEMENT_DEFS } from "../../game/scoring.js";
+const SCHEMA_VERSION = 2;
+/**
+ * Add `column` (with `decl`, e.g. "INTEGER") to `table` if it does not already
+ * exist. Idempotent: checks PRAGMA table_info first, so it is safe to run on
+ * every open. Table/column/decl are code-controlled constants (never user
+ * input), so the unavoidable identifier interpolation here does not violate
+ * PREVENT-002 (no external data reaches this SQL).
+ */
+export function ensureColumn(db, table, column, decl) {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (cols.some((c) => c.name === column))
+        return;
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${decl}`);
+}
+export function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS context_chunks (
+      id                  TEXT NOT NULL,
+      session_id         TEXT NOT NULL,
+      region_hash        TEXT,
+      content_hash       TEXT,
+      content_hash2      TEXT,
+      content_hash_version INTEGER,
+      normalized_text    TEXT,
+      summary            TEXT,
+      topic_summary      TEXT,
+      summary_hash       TEXT,
+      key_decisions      TEXT,           -- JSON array
+      next_steps         TEXT,           -- JSON array
+      files_modified     TEXT,           -- JSON array
+      embedding_blob     BLOB,           -- float32 vector
+      token_estimate     INTEGER,
+      original_token_estimate INTEGER,    -- dropped region size (tokens saved = orig − stored)
+      timestamp          INTEGER,
+      dedup_status       TEXT DEFAULT 'active',
+      compressed_original BLOB           -- optional DR copy
+    );
+    -- Primary key is (session_id, id): checkpoint ids are unique per session
+    -- (chkpt_001 per session), not globally, so a bare id PK would collide
+    -- across sessions on the nextCheckpointId sequence.
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_chunks_pk
+      ON context_chunks(session_id, id);
+    CREATE INDEX IF NOT EXISTS idx_chunks_session ON context_chunks(session_id);
+    CREATE INDEX IF NOT EXISTS idx_chunks_region ON context_chunks(region_hash);
+    CREATE INDEX IF NOT EXISTS idx_chunks_content ON context_chunks(content_hash);
+    -- Partial UNIQUE (QA #1): null content_hash rows never violate the constraint;
+    -- ON CONFLICT DO NOTHING makes backfill + L0 inserts safe.
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_content_hash
+      ON context_chunks(session_id, content_hash) WHERE content_hash IS NOT NULL;
+
+    -- Sprint 11: MinHash signature + LSH bucket tables for L1 near-dup dedup.
+    CREATE TABLE IF NOT EXISTS minhash_signatures (
+      chunk_id          TEXT NOT NULL,
+      session_id        TEXT NOT NULL,
+      signature_version INTEGER NOT NULL,
+      signatures        TEXT NOT NULL,   -- JSON array of 256 uint32
+      PRIMARY KEY (chunk_id, signature_version)
+    );
+    CREATE INDEX IF NOT EXISTS idx_minhash_session ON minhash_signatures(session_id);
+
+    CREATE TABLE IF NOT EXISTS dedup_lsh_buckets (
+      bucket_key        TEXT NOT NULL,
+      chunk_id          TEXT NOT NULL,
+      session_id        TEXT NOT NULL,
+      signature_version INTEGER NOT NULL,
+      PRIMARY KEY (bucket_key, chunk_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_lsh_bucket ON dedup_lsh_buckets(bucket_key, session_id);
+
+    CREATE TABLE IF NOT EXISTS session_state (
+      session_id               TEXT PRIMARY KEY,
+      injected_checkpoint_ids TEXT,      -- JSON array
+      stored_region_hashes    TEXT       -- JSON array
+    );
+
+    CREATE TABLE IF NOT EXISTS meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT
+    );
+
+    -- Sprint 13 (RAPTOR): hierarchical summary tree nodes. children are a JSON
+    -- array of child node ids (or raw leaf ids at the bottom); embedding_blob
+    -- is the node centroid. Additive; retrieval ignores this table until
+    -- Sprint 14 promotes RAPTOR out of shadow mode.
+    CREATE TABLE IF NOT EXISTS raptor_nodes (
+      id            TEXT NOT NULL,
+      session_id   TEXT NOT NULL,
+      level        INTEGER NOT NULL,
+      parent_id    TEXT,
+      children     TEXT,           -- JSON array of child ids
+      summary      TEXT,
+      embedding_blob BLOB,         -- float32 centroid
+      quality_marker TEXT DEFAULT 'low',
+      token_estimate INTEGER,
+      built_at     INTEGER,        -- S25: epoch ms when the tree was built (freshness guard)
+      PRIMARY KEY (session_id, id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_raptor_session ON raptor_nodes(session_id);
+    CREATE INDEX IF NOT EXISTS idx_raptor_parent ON raptor_nodes(parent_id);
+
+    -- Foundation for future features (resume sessions, daily log, lessons
+    -- learned). Scaffolded now so all store data lives in SQLite from day one;
+    -- population is minimal (touchSession / logDaily on compact) and the full
+    -- UI/recall for these lands in later sprints.
+
+    -- Per-session registry (resume + per-repo session history).
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id    TEXT PRIMARY KEY,
+      repo          TEXT,
+      started_at    INTEGER,
+      ended_at      INTEGER,
+      last_compacted_at INTEGER,
+      status        TEXT DEFAULT 'active'
+    );
+
+    -- Append-only daily activity log (the "daily log" feature seed).
+    CREATE TABLE IF NOT EXISTS daily_log (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      day           TEXT NOT NULL,     -- YYYY-MM-DD
+      session_id    TEXT,
+      event         TEXT,             -- e.g. 'compact'
+      detail        TEXT,
+      tokens_saved  INTEGER DEFAULT 0,
+      ts            INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_daily_log_day ON daily_log(day);
+
+    -- Active model/provider for cost estimation + the future multi-repo
+    -- dashboard (Phase 5b). One row per (repo, model change); latest wins.
+    CREATE TABLE IF NOT EXISTS model_snapshots (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo_root     TEXT NOT NULL,
+      provider      TEXT NOT NULL,
+      provider_name TEXT,
+      model_id      TEXT NOT NULL,
+      model_name    TEXT,
+      input_rate    REAL,          -- USD per input token (Model.cost.input)
+      output_rate   REAL,          -- USD per output token (Model.cost.output)
+      context_window INTEGER,
+      max_tokens    INTEGER,
+      reasoning     INTEGER DEFAULT 0,
+      captured_at   INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_model_repo ON model_snapshots(repo_root);
+
+    -- Lessons learned (future recall/browse feature seed).
+    CREATE TABLE IF NOT EXISTS lessons (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id    TEXT,
+      repo          TEXT,
+      lesson        TEXT,
+      ts            INTEGER
+    );
+
+    -- Durable "save to memory" store (taken over from memory extensions).
+    -- One row per saved memory; scoped by repo so memory travels with the
+    -- clone. All params are parameterized (PREVENT-002).
+    CREATE TABLE IF NOT EXISTS memories (
+      id                INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo              TEXT,
+      kind              TEXT DEFAULT 'note',   -- note | fact | decision | preference
+      content           TEXT NOT NULL,
+      tags              TEXT,                   -- JSON array of strings
+      created_at        INTEGER,
+      last_recalled_at  INTEGER,
+      -- S20 memory-RAG extension (auto-review add/replace/remove ops).
+      category          TEXT,                   -- typed bucket, e.g. decision | fact | preference
+      target            TEXT,                   -- optional subject/scope this memory targets
+      last_referenced   INTEGER,               -- last time memory was referenced by recall (epoch s)
+      source_turn       INTEGER                -- conversation turn that produced this memory
+    );
+    CREATE INDEX IF NOT EXISTS idx_memories_repo ON memories(repo);
+
+    -- FTS5 trigram virtual table (Sprint 9+ pg_trgm-equivalent verification).
+    CREATE VIRTUAL TABLE IF NOT EXISTS context_chunks_trgm USING fts5(
+      id UNINDEXED,
+      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
+    );
+
+    -- S30 game mode: global toggle state (single row, id=1). Holds the
+    -- game-mode on/off switch, the active visual-effect theme id, and the TUI
+    -- widget display mode. Global across all repos; written by /mega-game and
+    -- the dashboard settings strip (S32). Local SQLite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS game_state (
+      id                 INTEGER PRIMARY KEY CHECK(id = 1),
+      game_mode_on       INTEGER NOT NULL DEFAULT 0,
+      theme              TEXT NOT NULL DEFAULT 'transparent',
+      tui_display_mode   TEXT NOT NULL DEFAULT 'full'
+                          CHECK(tui_display_mode IN ('full','minimal'))
+    );
+    -- S33 game mode: per-repo leaderboard metrics. One row per recorded event
+    -- (turn_end / session_compact); leaderboard() derives rankings. 'repos' is
+    -- derived (COUNT DISTINCT, never recorded). Local SQLite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS game_scores (
+      repo_root TEXT NOT NULL,
+      metric    TEXT NOT NULL CHECK(metric IN ('cache','dedupe','turns','repos','mega_cache')),
+      ts        INTEGER NOT NULL,
+      value     REAL NOT NULL,
+      meta      TEXT,
+      PRIMARY KEY(repo_root, metric, ts)
+    ) WITHOUT ROWID;
+    CREATE INDEX IF NOT EXISTS idx_game_scores_metric_ts ON game_scores(metric, ts);
+
+    -- S35 game mode: achievements (9 rows, seeded idempotently on first open).
+    -- hidden=1 AND unlocked_at IS NULL => render NOTHING (no teaser). Local SQLite.
+    CREATE TABLE IF NOT EXISTS game_achievements (
+      id          TEXT PRIMARY KEY,
+      title       TEXT NOT NULL,
+      description TEXT NOT NULL,
+      hidden      INTEGER NOT NULL DEFAULT 0 CHECK(hidden IN (0,1)),
+      icon        TEXT,
+      unlocked_at INTEGER NULL
+    ) WITHOUT ROWID;
+  `);
+    // 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
+    // first created (e.g. original_token_estimate in v0.4.2) must be ALTERed in for
+    // 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");
+    ensureColumn(db, "memories", "target", "TEXT");
+    ensureColumn(db, "memories", "last_referenced", "INTEGER");
+    ensureColumn(db, "memories", "source_turn", "INTEGER");
+    // S25: RAPTOR freshness-guard timestamp. Additive; old DBs have NULL → 0 →
+    // treated as stale → flat fallback (safe).
+    ensureColumn(db, "raptor_nodes", "built_at", "INTEGER");
+    // S35: idempotent seed of the 9 achievement rows. ON CONFLICT(id) DO
+    // NOTHING so a re-open never clobbers an already-unlocked row's
+    // unlocked_at. No user input reaches this SQL (PREVENT-002 safe).
+    const seedAch = db.prepare(`INSERT INTO game_achievements (id, title, description, hidden, icon)
+     VALUES (?, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING`);
+    for (const d of ACHIEVEMENT_DEFS) {
+        seedAch.run(d.id, d.title, d.description, d.hidden ? 1 : 0, d.icon);
+    }
+    const v = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get();
+    if (!v) {
+        db.prepare("INSERT INTO meta(key, value) VALUES(?, ?)").run("schema_version", String(SCHEMA_VERSION));
+    }
+}

package/dist/src/store/sqlite/session-state.js

@@ -0,0 +1,28 @@
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { openStore, jsonText } from "./utils.js";
+function loadSessionStateRow(sid, db) {
+    const row = db.prepare("SELECT * FROM session_state WHERE session_id = ?").get(sid);
+    if (!row) {
+        return { injectedCheckpointIds: [], storedRegionHashes: [] };
+    }
+    return {
+        injectedCheckpointIds: row.injected_checkpoint_ids ? JSON.parse(row.injected_checkpoint_ids) : [],
+        storedRegionHashes: row.stored_region_hashes ? JSON.parse(row.stored_region_hashes) : [],
+    };
+}
+export function loadSessionState(sessionId, stateDir = getStateDir()) {
+    return loadSessionStateRow(normalizeSessionId(sessionId), openStore(stateDir));
+}
+export function saveSessionState(sessionId, state, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    db.prepare(`INSERT INTO session_state(session_id, injected_checkpoint_ids, stored_region_hashes)
+     VALUES(@sid, @inj, @reg)
+     ON CONFLICT(session_id) DO UPDATE SET
+       injected_checkpoint_ids=excluded.injected_checkpoint_ids,
+       stored_region_hashes=excluded.stored_region_hashes`).run({
+        sid,
+        inj: jsonText(state.injectedCheckpointIds),
+        reg: jsonText(state.storedRegionHashes),
+    });
+}