pi-mega-compact 0.13.1 → 0.13.2

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

@@ -1,4 +1,8 @@
 import { ACHIEVEMENT_DEFS } from "../../game/scoring.js";
+import { CORE_DDL } from "./schema/core.js";
+import { TURNS_DDL } from "./schema/turns.js";
+import { GAME_DDL } from "./schema/game.js";
+import { PLAN_V2_DDL } from "./schema/plan-v2.js";
 const SCHEMA_VERSION = 5;
 /**
  * Add `column` (with `decl`, e.g. "INTEGER") to `table` if it does not already
@@ -14,447 +18,10 @@ export function ensureColumn(db, table, column, decl) {
     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);
-    -- S42D/QA perf: session-scoped timestamp ordering so the S25 RAPTOR
-    -- freshness guard's MAX(timestamp) (run on every RAPTOR search) is
-    -- index-satisfied rather than a full partition scan as checkpoints grow.
-    CREATE INDEX IF NOT EXISTS idx_chunks_session_ts
-      ON context_chunks(session_id, timestamp DESC);
-    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
-      conversation_id         TEXT,       -- S43: groups turns across resumes (/clear → new root)
-      last_turn_id            INTEGER     -- S43: most recent turn id (stable fork refs)
-    );
-
-    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);
-
-    -- S42D: structured RAPTOR build history. One row per tree build; the
-    -- freshness check (buildHistory.ts) uses completed_at + leaf_count to skip
-    -- unnecessary rebuilds when the tree is recent and the chunk count is stable.
-    CREATE TABLE IF NOT EXISTS raptor_build_history (
-      build_id        TEXT PRIMARY KEY,
-      session_id      TEXT NOT NULL,
-      state_dir       TEXT NOT NULL,
-      started_at      INTEGER NOT NULL,
-      completed_at    INTEGER NOT NULL,
-      node_count      INTEGER NOT NULL,
-      leaf_count      INTEGER NOT NULL,
-      depth           INTEGER NOT NULL,
-      config_json     TEXT NOT NULL,    -- serialized BuildOptions
-      coherence_score REAL,            -- avg intra-cluster cosine (post-build)
-      timed_out       INTEGER NOT NULL DEFAULT 0
-    );
-    CREATE INDEX IF NOT EXISTS idx_raptor_build_session ON raptor_build_history(session_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);
-
-    -- S43 (per-turn vector tracking): the relational spine for per-turn +
-    -- per-conversation memories. One row per turn_end; links turns to the
-    -- epoch that compacted them (epoch_id) and to the checkpoints/cluster
-    -- summaries that were RECALLED during that turn (turn_recall).
-    -- conversation_id groups turns across pi session resumes (/clear starts a
-    -- new conversation root; a fork carries parent_conversation_id).
-    CREATE TABLE IF NOT EXISTS turns (
-      id              INTEGER PRIMARY KEY AUTOINCREMENT, -- global turn id
-      conversation_id TEXT NOT NULL,
-      session_id      TEXT NOT NULL,
-      turn_index      INTEGER NOT NULL,                   -- per-session turn (event.turnIndex)
-      role            TEXT,                                -- 'user' | 'assistant' | 'tool' (turn's last role)
-      started_at      INTEGER NOT NULL,
-      ended_at        INTEGER,                             -- set at turn_end
-      ctx_tokens      INTEGER,                             -- runtime.lastCtxTokens snapshot
-      ctx_percent     REAL,                                -- runtime.lastCtxPercent
-      pressure_band   TEXT,                                -- 'low'|'mid'|'high'|'critical'
-      model_id        TEXT,
-      epoch_id        TEXT,                                -- FK checkpoint_epochs (set when a compact closes this turn's epoch)
-      UNIQUE(session_id, turn_index)
-    );
-    CREATE INDEX IF NOT EXISTS idx_turns_conv ON turns(conversation_id, turn_index);
-    CREATE INDEX IF NOT EXISTS idx_turns_session ON turns(session_id, turn_index);
-    CREATE INDEX IF NOT EXISTS idx_turns_epoch ON turns(epoch_id) WHERE epoch_id IS NOT NULL;
-
-    -- S43: recall provenance — which checkpoints/cluster summaries were
-    -- injected at which turn, their score, and the path that sourced them.
-    -- This is the per-turn vector data that makes memory quality measurable
-    -- per turn and enables recall-to-point (replay these checkpoint_ids into a
-    -- forked session). source: 'flat' | 'raptor' | 'cross-repo' | 'memory'.
-    CREATE TABLE IF NOT EXISTS turn_recall (
-      id            INTEGER PRIMARY KEY AUTOINCREMENT,
-      turn_id       INTEGER NOT NULL,
-      checkpoint_id TEXT NOT NULL,
-      score         REAL NOT NULL,
-      source        TEXT NOT NULL,
-      raptor_level  INTEGER,                              -- set for RAPTOR cluster hits
-      UNIQUE(turn_id, checkpoint_id)
-    );
-    CREATE INDEX IF NOT EXISTS idx_turn_recall_turn ON turn_recall(turn_id);
-    CREATE INDEX IF NOT EXISTS idx_turn_recall_cp ON turn_recall(checkpoint_id);
-
-    -- S43: conversation branch/fork registry. A row per fork: the child
-    -- conversation inherits the parent's recall state at fork_turn_id as its
-    -- starting injected-set. The root conversation has no row here.
-    CREATE TABLE IF NOT EXISTS conversation_branches (
-      conversation_id        TEXT PRIMARY KEY,
-      parent_conversation_id TEXT NOT NULL,
-      fork_turn_id           INTEGER NOT NULL,             -- FK turns.id at the branch point
-      created_at             INTEGER NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS idx_conv_branch_parent ON conversation_branches(parent_conversation_id);
-
-    -- 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;
-
-    -- v0.8.8 Perf dashboard: append-only local instrumentation samples (one row
-    -- per turn / provider round-trip / 5s cpu-mem tick / snapshot-recompute).
-    -- Drives the dashboard Perf tab. Local SQLite (PREVENT-PI-004); parameterized
-    -- accessors in perf-samples.ts (PREVENT-002).
-    CREATE TABLE IF NOT EXISTS perf_samples (
-      id    INTEGER PRIMARY KEY AUTOINCREMENT,
-      ts    INTEGER NOT NULL,
-      kind  TEXT NOT NULL,
-      value REAL NOT NULL,
-      meta  TEXT
-    );
-    CREATE INDEX IF NOT EXISTS idx_perf_samples_ts ON perf_samples(ts);
-    CREATE INDEX IF NOT EXISTS idx_perf_samples_kind_ts ON perf_samples(kind, ts);
-
-    -- A1 PLAN_V2 Phase 2: Message Separation tables (SCHEMA_VERSION 3).
-    -- Stable conversation thread: user + assistant turns ONLY. Tool results are
-    -- stored in tool_results to keep the conversation thread cache-predictable.
-    -- Parameterized queries only (PREVENT-002). CREATE TABLE IF NOT EXISTS is
-    -- a no-op on re-open — no migration needed.
-    CREATE TABLE IF NOT EXISTS conversation_thread (
-      id              INTEGER PRIMARY KEY AUTOINCREMENT,
-      conversation_id TEXT NOT NULL,
-      role            TEXT NOT NULL CHECK(role IN ('user','assistant')),
-      content         TEXT NOT NULL,
-      turn_index      INTEGER NOT NULL,
-      timestamp       INTEGER NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS idx_conv_thread_conv_turn
-      ON conversation_thread(conversation_id, turn_index);
-
-    -- Volatile tool results: appended at END so they never disrupt the
-    -- conversation thread prefix (the prompt-cache-friendly prefix).
-    CREATE TABLE IF NOT EXISTS tool_results (
-      id              INTEGER PRIMARY KEY AUTOINCREMENT,
-      conversation_id TEXT NOT NULL,
-      tool_call_id    TEXT NOT NULL,
-      tool_result     TEXT NOT NULL,
-      turn_index      INTEGER NOT NULL,
-      timestamp       INTEGER NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS idx_tool_results_conv_turn
-      ON tool_results(conversation_id, turn_index);
-
-    -- A2 PLAN_V2 Phase 3: Vector-Aware Cache Striping (SCHEMA_VERSION 4).
-    -- Cache stripe assignments: maps each context chunk to a cache stability
-    -- tier (stripe). Layer 0=permanent, 1=epoch, 2=topic, 3=thread, 4=volatile.
-    -- stability is the composite score (0.0-1.0) from computeStabilityScore.
-    -- Primary key is (chunk_id, epoch_id) so the same chunk can be reassigned
-    -- across epochs without conflict. See cache-stripe.ts for scoring details.
-    -- Parameterized queries only (PREVENT-002). IF NOT EXISTS is a no-op on re-open.
-    CREATE TABLE IF NOT EXISTS cache_stripes (
-      chunk_id      TEXT NOT NULL,
-      stripe        INTEGER NOT NULL,
-      stability     REAL NOT NULL,
-      assigned_at   INTEGER NOT NULL,
-      epoch_id      TEXT,
-      PRIMARY KEY (chunk_id, epoch_id)
-    );
-    CREATE INDEX IF NOT EXISTS idx_cs_stripe_stability
-      ON cache_stripes(stripe, stability DESC);
-
-    -- Embedding computation cache: avoids re-embedding content every time
-    -- stability scores are recomputed across epochs. Keyed by content_hash
-    -- (SHA-256 64-hex-char string). Embeddings are serialized via
-    -- Float64Array-to-Buffer to match the embedding_blob convention.
-    CREATE TABLE IF NOT EXISTS embedding_cache (
-      content_hash  TEXT PRIMARY KEY,
-      embedding     BLOB NOT NULL,
-      computed_at   INTEGER NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS idx_emb_cache_computed
-      ON embedding_cache(computed_at DESC);
-
-    -- A2 PLAN_V2 Phase 2 (SCHEMA_VERSION 5): Context Health metrics. One row
-    -- per turn recorded during compactSession. drift_score / output_quality /
-    -- error_score / cache_health / cache_poison / composite are the core signal
-    -- columns; repetition_ratio / coherence_score / prefix_hash are optional
-    -- enrichment. Parameterized accessors in context-health.ts (PREVENT-002).
-    CREATE TABLE IF NOT EXISTS context_health (
-      id              INTEGER PRIMARY KEY AUTOINCREMENT,
-      ts              INTEGER NOT NULL,
-      turn_index      INTEGER NOT NULL,
-      session_id      TEXT NOT NULL,
-      drift_score     REAL,
-      output_quality  REAL,
-      error_score     REAL,
-      cache_health    REAL,
-      cache_poison    REAL,
-      composite       REAL,
-      model_id        TEXT,
-      repetition_ratio REAL,
-      coherence_score REAL,
-      prefix_hash     TEXT
-    );
-    CREATE INDEX IF NOT EXISTS idx_ctx_health_ts
-      ON context_health(ts);
-    CREATE INDEX IF NOT EXISTS idx_ctx_health_session
-      ON context_health(session_id, ts);
-
-    -- A2 PLAN_V2 Phase 2 (SCHEMA_VERSION 5): Cache poison advisory events.
-    -- Emitted when cache corruption / inconsistency is detected at a given
-    -- layer during compactSession. Drives the R13 advisory channel redesign.
-    -- Parameterized accessors in context-health.ts (PREVENT-002).
-    CREATE TABLE IF NOT EXISTS cache_poison_events (
-      id          INTEGER PRIMARY KEY AUTOINCREMENT,
-      ts          INTEGER NOT NULL,
-      turn_index  INTEGER NOT NULL,
-      session_id  TEXT NOT NULL,
-      layer       INTEGER,
-      detail      TEXT,
-      severity    TEXT
-    );
-    CREATE INDEX IF NOT EXISTS idx_cache_poison_ts
-      ON cache_poison_events(ts);
-  `);
+    db.exec(CORE_DDL);
+    db.exec(TURNS_DDL);
+    db.exec(GAME_DDL);
+    db.exec(PLAN_V2_DDL);
     // 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

package/dist/src/store/turns/contract-compliance.test/_helpers.js

@@ -0,0 +1,21 @@
+/** Helper: create a valid TurnEntry. */
+export function makeTurn(overrides = {}) {
+    return {
+        conversationId: "conv_test1234",
+        sessionId: "sess_abc",
+        turnIndex: 0,
+        role: "assistant",
+        endedAt: Date.now(),
+        ...overrides,
+    };
+}
+/** Helper: create a valid TurnRecallEntry. */
+export function makeRecall(turnId, overrides = {}) {
+    return {
+        turnId,
+        checkpointId: "ckpt_001",
+        score: 0.85,
+        source: "checkpoint",
+        ...overrides,
+    };
+}

package/dist/src/store/turns/sqlite-store/admin.js

@@ -0,0 +1,171 @@
+/**
+ * admin.ts — TurnAdmin method bodies (extracted from sqlite-store.ts). All
+ * queries use bound parameters (PREVENT-002). DELETE/UPDATE only here (the
+ * append-only rule applies to turns/turn_recall writes outside migrations).
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeSessionId, rowToEntry, rowToFork } from "./rows.js";
+export function prune(ctx, policy) {
+    const { db } = ctx;
+    const beforeSize = dbSizeBytes(ctx);
+    const cutoff = Date.now() - policy.maxTurnAgeMs;
+    // Find conversations with turns to potentially prune
+    const convRows = db
+        .prepare("SELECT DISTINCT conversation_id FROM turns")
+        .all();
+    let turnsRemoved = 0;
+    let recallRemoved = 0;
+    for (const { conversation_id } of convRows) {
+        // Count total turns in this conversation
+        const total = db
+            .prepare("SELECT COUNT(*) as cnt FROM turns WHERE conversation_id = ?")
+            .get(conversation_id);
+        // Keep at least keepMinPerConversation — delete only the oldest
+        const canDelete = Math.max(0, total.cnt - policy.keepMinPerConversation);
+        if (canDelete === 0)
+            continue;
+        // Find old turns to delete
+        const oldTurns = db
+            .prepare(`SELECT id FROM turns WHERE conversation_id = ? AND ended_at < ?
+           ORDER BY ended_at ASC LIMIT ?`)
+            .all(conversation_id, cutoff, canDelete);
+        if (oldTurns.length === 0)
+            continue;
+        const ids = oldTurns.map((t) => t.id);
+        const placeholders = ids.map(() => "?").join(",");
+        // Delete recall for those turns
+        const delRecall = db
+            .prepare(`DELETE FROM turn_recall WHERE turn_id IN (${placeholders})`)
+            .run(...ids);
+        recallRemoved += Number(delRecall.changes);
+        // Delete the turns
+        const delTurns = db
+            .prepare(`DELETE FROM turns WHERE id IN (${placeholders})`)
+            .run(...ids);
+        turnsRemoved += Number(delTurns.changes);
+    }
+    // Count preserved branches
+    const branchesPreserved = db
+        .prepare("SELECT COUNT(*) as cnt FROM conversation_forks")
+        .get().cnt;
+    if (policy.vacuumAfterPrune && (turnsRemoved > 0 || recallRemoved > 0)) {
+        vacuum(ctx);
+    }
+    const afterSize = dbSizeBytes(ctx);
+    return {
+        turnsRemoved,
+        recallRemoved,
+        branchesPreserved,
+        freedBytes: Math.max(0, beforeSize - afterSize),
+    };
+}
+export function vacuum(ctx) {
+    ctx.db.exec("VACUUM");
+}
+export function checkpoint(ctx) {
+    const { db } = ctx;
+    // Query turns in row-id order (ended_at ASC with unique constraint)
+    const turnRows = db
+        .prepare("SELECT * FROM turns ORDER BY ended_at ASC")
+        .all();
+    const turns = turnRows.map(rowToEntry);
+    // Build mapping: row_id → 1-based position in turns array
+    const rowIdToPos = new Map();
+    for (let i = 0; i < turnRows.length; i++) {
+        rowIdToPos.set(turnRows[i].id, i + 1);
+    }
+    const recallRows = db
+        .prepare("SELECT * FROM turn_recall ORDER BY turn_id ASC")
+        .all();
+    // Replace recall's turnId with the 1-based position of the referenced turn
+    // in the turns array. This makes the TurnId stable across restore.
+    const recall = recallRows.map((r) => {
+        const originalTurnId = r.turn_id;
+        const stableTurnId = rowIdToPos.get(originalTurnId) ?? originalTurnId;
+        return {
+            turnId: String(stableTurnId),
+            checkpointId: r.checkpoint_id,
+            score: r.score,
+            source: r.source,
+            raptorLevel: r.raptor_level ?? undefined,
+        };
+    });
+    const forks = db
+        .prepare("SELECT * FROM conversation_forks ORDER BY created_at ASC")
+        .all().map(rowToFork);
+    return {
+        version: 1,
+        exportedAt: Date.now(),
+        turns,
+        recall,
+        forks,
+    };
+}
+export function restore(ctx, from) {
+    const { db } = ctx;
+    clear(ctx);
+    const insertTurn = db.prepare(`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at,
+	                               ctx_tokens, ctx_percent, pressure_band, model, epoch_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertRecall = db.prepare(`INSERT INTO turn_recall (turn_id, checkpoint_id, score, source, raptor_level)
+       VALUES (?, ?, ?, ?, ?)`);
+    const insertFork = db.prepare(`INSERT INTO conversation_forks (parent_conversation_id, child_conversation_id, fork_turn_index, created_at)
+       VALUES (?, ?, ?, ?)`);
+    db.exec("BEGIN TRANSACTION");
+    try {
+        // Map: 1-based position → new auto-increment row ID
+        const posToNewId = new Map();
+        for (let i = 0; i < from.turns.length; i++) {
+            const t = from.turns[i];
+            insertTurn.run(t.conversationId, normalizeSessionId(t.sessionId), t.turnIndex, t.role, t.endedAt, t.ctxTokens ?? null, t.ctxPercent ?? null, t.pressureBand ?? null, t.model ?? null, t.epochId ?? null);
+            const row = db
+                .prepare("SELECT id FROM turns WHERE conversation_id = ? AND turn_index = ?")
+                .get(t.conversationId, t.turnIndex);
+            if (row)
+                posToNewId.set(i + 1, row.id);
+        }
+        // Recall's turnId is now the 1-based position from checkpoint().
+        // Map it to the new row ID.
+        for (const r of from.recall) {
+            const targetTurnId = posToNewId.get(Number(r.turnId)) ?? Number(r.turnId);
+            insertRecall.run(targetTurnId, r.checkpointId, r.score, r.source, r.raptorLevel ?? null);
+        }
+        for (const f of from.forks) {
+            insertFork.run(f.parentConversationId, f.childConversationId, f.forkTurnIndex, f.createdAt);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+}
+export function clear(ctx) {
+    const { db } = ctx;
+    db.exec("DELETE FROM turn_recall");
+    db.exec("DELETE FROM conversation_forks");
+    db.exec("DELETE FROM turns");
+    db.exec("DELETE FROM session_conversations");
+    // Reset autoincrement
+    db.exec("DELETE FROM sqlite_sequence WHERE name IN ('turns','turn_recall','conversation_forks')");
+}
+export function stampTurnsEpoch(ctx, sessionId, epochId) {
+    const { db } = ctx;
+    const sid = normalizeSessionId(sessionId);
+    const res = db
+        .prepare("UPDATE turns SET epoch_id = ? WHERE session_id = ? AND epoch_id IS NULL")
+        .run(epochId, sid);
+    return Number(res.changes ?? 0);
+}
+function dbSizeBytes(ctx) {
+    if (ctx.opts.inMemory)
+        return 0;
+    try {
+        const path = ctx.opts.dbPath ?? join(ctx.stateDir, "turns.db");
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/src/store/turns/sqlite-store/ctx.js

@@ -0,0 +1 @@
+export {};