pi-mega-compact 0.13.0 → 0.13.2

package/src/store/sqlite/schema.ts

@@ -1,8 +1,17 @@
 /**
  * schema.ts — table creation, migrations, `ensureColumn`, PRAGMA setup.
+ *
+ * Thin pointer: the table DDL is grouped by concern in ./schema/* (core /
+ * turns / game / plan-v2) and composed here by initSchema. The schema_version
+ * seeding, idempotent column migrations, and achievement seeding stay in this
+ * file. Public API (initSchema / ensureColumn) is unchanged for callers.
  */
 import type { DatabaseSync } from "node:sqlite";
 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;
 
@@ -27,447 +36,10 @@ export function ensureColumn(
 }
 
 export function initSchema(db: DatabaseSync): void {
-	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/src/store/turns/contract-compliance.test/_helpers.ts

@@ -0,0 +1,38 @@
+/**
+ * _helpers.ts — shared fixtures for the TurnStore compliance suite.
+ *
+ * Extracted from contract-compliance.test.ts so the suite stays under the
+ * 500-line hard limit. Backend test files (sqlite-store.test.ts,
+ * memory-store.test.ts) import runComplianceSuite from the parent shell;
+ * the sub-suite files import these helpers.
+ */
+import type { TurnEntry, TurnRecallEntry, TurnStore } from "../types.js";
+
+/** Factory function — backend test files provide the concrete constructor. */
+export type StoreFactory = (options: import("../types.js").TurnStoreOptions) => TurnStore;
+
+/** Helper: create a valid TurnEntry. */
+export function makeTurn(overrides: Partial<TurnEntry> = {}): TurnEntry {
+	return {
+		conversationId: "conv_test1234",
+		sessionId: "sess_abc",
+		turnIndex: 0,
+		role: "assistant",
+		endedAt: Date.now(),
+		...overrides,
+	};
+}
+
+/** Helper: create a valid TurnRecallEntry. */
+export function makeRecall(
+	turnId: string,
+	overrides: Partial<TurnRecallEntry> = {},
+): TurnRecallEntry {
+	return {
+		turnId,
+		checkpointId: "ckpt_001",
+		score: 0.85,
+		source: "checkpoint",
+		...overrides,
+	};
+}