pi-mega-compact 0.13.0 → 0.13.2

package/src/store/sqlite/schema/core.ts

@@ -0,0 +1,233 @@
+/**
+ * core.ts — core table DDL (extracted from schema.ts). Executed via db.exec in
+ * initSchema. CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS are
+ * idempotent no-ops on re-open. No user input reaches this SQL (PREVENT-002).
+ */
+
+export const CORE_DDL = `
+    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);
+`;

package/src/store/sqlite/schema/game.ts

@@ -0,0 +1,66 @@
+/**
+ * game.ts — game-mode + perf-samples DDL (extracted from schema.ts). Executed
+ * via db.exec in initSchema. No user input reaches this SQL (PREVENT-002).
+ */
+
+export const GAME_DDL = `
+    -- 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);
+`;

package/src/store/sqlite/schema/plan-v2.ts

@@ -0,0 +1,108 @@
+/**
+ * plan-v2.ts — PLAN_V2 Phase 2/3 message-separation, cache-striping, and
+ * context-health DDL (extracted from schema.ts). Executed via db.exec in
+ * initSchema. No user input reaches this SQL (PREVENT-002).
+ */
+
+export const PLAN_V2_DDL = `
+    -- 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);
+`;

package/src/store/sqlite/schema/turns.ts

@@ -0,0 +1,60 @@
+/**
+ * turns.ts — S43 per-turn vector tracking DDL (extracted from schema.ts).
+ * The relational spine for per-turn + per-conversation memories. Executed via
+ * db.exec in initSchema. No user input reaches this SQL (PREVENT-002).
+ */
+
+export const TURNS_DDL = `
+    -- 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);
+`;