pi-mega-compact 0.8.24 → 0.8.26

package/src/store/sqlite/raptor.ts

@@ -2,106 +2,160 @@
  * raptor.ts — Sprint 13 RAPTOR node persistence.
  */
 import { getStateDir, normalizeSessionId } from "../../store.js";
-import { openStore, jsonText, encodeEmbedding, decodeEmbedding } from "./utils.js";
+import {
+	openStore,
+	withTx,
+	jsonText,
+	encodeEmbedding,
+	decodeEmbedding,
+} from "./utils.js";
 
 export interface StoredRaptorNode {
-  id: string;
-  sessionId: string;
-  level: number;
-  parentId: string | null;
-  children: string[];
-  summary: string;
-  embedding: number[];
-  qualityMarker: string;
-  tokenEstimate: number;
-  /** S25: epoch ms when the tree containing this node was built. */
-  builtAt: number;
+	id: string;
+	sessionId: string;
+	level: number;
+	parentId: string | null;
+	children: string[];
+	summary: string;
+	embedding: number[];
+	qualityMarker: string;
+	tokenEstimate: number;
+	/** S25: epoch ms when the tree containing this node was built. */
+	builtAt: number;
 }
 
 /** Persist a single RAPTOR node (upsert by (session_id, id)). */
-export function upsertRaptorNode(node: StoredRaptorNode, stateDir: string = getStateDir()): void {
-  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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+export function upsertRaptorNode(
+	node: StoredRaptorNode,
+	stateDir: string = getStateDir(),
+): void {
+	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(@id, @session_id, @level, @parent_id, @children, @summary, @embedding_blob, @quality_marker, @token_estimate, @built_at)
      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,
-  );
+	).run({
+		id: node.id,
+		session_id: node.sessionId,
+		level: node.level,
+		parent_id: node.parentId,
+		children: jsonText(node.children),
+		summary: node.summary,
+		embedding_blob: encodeEmbedding(node.embedding),
+		quality_marker: node.qualityMarker,
+		token_estimate: node.tokenEstimate,
+		built_at: node.builtAt,
+	});
 }
 
 /** Persist an entire built RAPTOR tree for a session (shadow or live). */
 export function saveRaptorTree(
-  sessionId: string,
-  tree: {
-    nodes: Map<string, {
-      id: string;
-      level: number;
-      parentId: string | null;
-      children: string[];
-      summary: string;
-      embedding: number[];
-      qualityMarker: string;
-      tokenEstimate: number;
-    }>
-  },
-  builtAt: number,
-  stateDir: string = getStateDir(),
+	sessionId: string,
+	tree: {
+		nodes: Map<
+			string,
+			{
+				id: string;
+				level: number;
+				parentId: string | null;
+				children: string[];
+				summary: string;
+				embedding: number[];
+				qualityMarker: string;
+				tokenEstimate: number;
+			}
+		>;
+	},
+	builtAt: number,
+	stateDir: string = getStateDir(),
 ): void {
-  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,
-    );
-  }
+	const nsid = normalizeSessionId(sessionId);
+	const db = openStore(stateDir);
+	withTx(db, () => {
+		db.prepare("DELETE FROM raptor_nodes WHERE session_id = ?").run(nsid);
+		for (const node of tree.nodes.values()) {
+			upsertRaptorNode(
+				{
+					id: node.id,
+					sessionId: nsid,
+					level: node.level,
+					parentId: node.parentId,
+					children: node.children,
+					summary: node.summary,
+					embedding: node.embedding,
+					qualityMarker: node.qualityMarker,
+					tokenEstimate: node.tokenEstimate,
+					builtAt,
+				},
+				stateDir,
+			);
+		}
+	});
+}
+
+/** Safe JSON array parse — returns [] on corrupt input. */
+function safeJsonArray(raw: unknown): string[] {
+	if (typeof raw !== "string" || !raw) return [];
+	try { return JSON.parse(raw) as string[]; }
+	catch { return []; }
 }
 
 /** Load all RAPTOR nodes for a session. */
-export function listRaptorNodes(sessionId: string, stateDir: string = getStateDir()): StoredRaptorNode[] {
-  const db = openStore(stateDir);
-  const rows = db
-    .prepare("SELECT * FROM raptor_nodes WHERE session_id = ? ORDER BY level ASC, id ASC")
-    .all(normalizeSessionId(sessionId)) as any[];
-  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),
-  }));
+export function listRaptorNodes(
+	sessionId: string,
+	stateDir: string = getStateDir(),
+): StoredRaptorNode[] {
+	const db = openStore(stateDir);
+	const rows = db
+		.prepare(
+			"SELECT * FROM raptor_nodes WHERE session_id = ? ORDER BY level ASC, id ASC",
+		)
+		.all(normalizeSessionId(sessionId)) as any[];
+	return rows.map((row) => ({
+		id: row.id,
+		sessionId: row.session_id,
+		level: row.level,
+		parentId: row.parent_id ?? null,
+		children: safeJsonArray(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: string, stateDir: string = getStateDir()): void {
-  const db = openStore(stateDir);
-  db.prepare("DELETE FROM raptor_nodes WHERE session_id = ?").run(normalizeSessionId(sessionId));
+export function clearRaptorNodes(
+	sessionId: string,
+	stateDir: string = getStateDir(),
+): void {
+	const db = openStore(stateDir);
+	db.prepare("DELETE FROM raptor_nodes WHERE session_id = ?").run(
+		normalizeSessionId(sessionId),
+	);
+}
+
+/**
+ * S25: newest built_at for a session's RAPTOR tree (0 if no nodes exist).
+ * Cheap indexed MAX query used by raptorSearchHits to validate cache freshness
+ * without rehydrating the full node Map.
+ */
+export function maxRaptorNodeBuiltAt(
+	sessionId: string,
+	stateDir: string = getStateDir(),
+): number {
+	const db = openStore(stateDir);
+	const row = db
+		.prepare(
+			`SELECT MAX(built_at) AS max_built FROM raptor_nodes WHERE session_id = ?`,
+		)
+		.get(normalizeSessionId(sessionId)) as
+		| { max_built: number | null }
+		| undefined;
+	return row?.max_built ?? 0;
 }

package/src/store/sqlite/schema.ts

@@ -48,6 +48,11 @@ export function initSchema(db: DatabaseSync): void {
     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;
@@ -77,7 +82,9 @@ export function initSchema(db: DatabaseSync): void {
     CREATE TABLE IF NOT EXISTS session_state (
       session_id               TEXT PRIMARY KEY,
       injected_checkpoint_ids TEXT,      -- JSON array
-      stored_region_hashes    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 (
@@ -104,6 +111,28 @@ export function initSchema(db: DatabaseSync): void {
     );
     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/QA perf: session-scoped built_at ordering so the per-search cache
+    -- invalidation MAX(built_at) is index-satisfied.
+    CREATE INDEX IF NOT EXISTS idx_raptor_session_built
+      ON raptor_nodes(session_id, built_at DESC);
+
+    -- 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;
@@ -222,6 +251,59 @@ export function initSchema(db: DatabaseSync): void {
     );
     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.
@@ -299,6 +381,13 @@ export function initSchema(db: DatabaseSync): void {
   // S25: RAPTOR freshness-guard timestamp. Additive; old DBs have NULL → 0 →
   // treated as stale → flat fallback (safe).
   ensureColumn(db, "raptor_nodes", "built_at", "INTEGER");
+  // S43: turn_index on raw_transcript so a message points directly at its
+  // conversation turn (otherwise it must be inferred from seq ordering). NULL
+  // for legacy rows — turns written before S43 have no turn link.
+  ensureColumn(db, "raw_transcript", "turn_index", "INTEGER");
+  // S43: conversation_id + last_turn_id on session_state (legacy DBs have NULL).
+  ensureColumn(db, "session_state", "conversation_id", "TEXT");
+  ensureColumn(db, "session_state", "last_turn_id", "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).

package/src/store/sqlite/session-state.ts

@@ -14,6 +14,8 @@ function loadSessionStateRow(sid: string, db: DatabaseSync): SessionState {
   return {
     injectedCheckpointIds: row.injected_checkpoint_ids ? JSON.parse(row.injected_checkpoint_ids) : [],
     storedRegionHashes: row.stored_region_hashes ? JSON.parse(row.stored_region_hashes) : [],
+    conversationId: (row.conversation_id as string | null) ?? undefined,
+    lastTurnId: (row.last_turn_id as number | null) ?? undefined,
   };
 }
 
@@ -25,14 +27,18 @@ export function saveSessionState(sessionId: string, state: SessionState, stateDi
   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)
+    `INSERT INTO session_state(session_id, injected_checkpoint_ids, stored_region_hashes, conversation_id, last_turn_id)
+     VALUES(@sid, @inj, @reg, @conv, @tid)
      ON CONFLICT(session_id) DO UPDATE SET
        injected_checkpoint_ids=excluded.injected_checkpoint_ids,
-       stored_region_hashes=excluded.stored_region_hashes`,
+       stored_region_hashes=excluded.stored_region_hashes,
+       conversation_id=excluded.conversation_id,
+       last_turn_id=excluded.last_turn_id`,
   ).run({
     sid,
     inj: jsonText(state.injectedCheckpointIds),
     reg: jsonText(state.storedRegionHashes),
+    conv: state.conversationId ?? null,
+    tid: state.lastTurnId ?? null,
   });
 }

package/src/store/sqlite/stats.ts

@@ -18,21 +18,23 @@ export function storeStats(sessionId: string, stateDir: string = getStateDir()):
   const row = db
     .prepare(
       `SELECT COUNT(*) AS c, COALESCE(SUM(token_estimate),0) AS tok,
-              MAX(id) AS lastId
-       FROM context_chunks WHERE session_id = ?`,
+              MAX(CAST(SUBSTR(id, 7) AS INTEGER)) AS lastNum
+       FROM context_chunks WHERE session_id = ? AND dedup_status != 'removed'`,
     )
-    .get(sid) as { c: number; tok: number; lastId: string | null };
+    .get(sid) as { c: number; tok: number; lastNum: number | null };
+  let lastCheckpointId: string | undefined;
   let lastSummary: string | undefined;
-  if (row.lastId) {
-    const s = db.prepare("SELECT summary FROM context_chunks WHERE id = ?").get(row.lastId) as
-      | { summary: string }
-      | undefined;
+  if (row.lastNum != null) {
+    lastCheckpointId = `chkpt_${String(row.lastNum).padStart(3, "0")}`;
+    const s = db
+      .prepare("SELECT summary FROM context_chunks WHERE session_id = ? AND id = ?")
+      .get(sid, lastCheckpointId) as { summary: string } | undefined;
     lastSummary = s?.summary;
   }
   return {
     checkpointCount: row.c,
     totalTokenEstimate: row.tok,
-    lastCheckpointId: row.lastId ?? undefined,
+    lastCheckpointId,
     lastSummary,
   };
 }

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

@@ -0,0 +1,218 @@
+/**
+ * turns.test.ts — S43 per-turn + conversation tracking tests.
+ *
+ * No network. Real stores with temp state dirs.
+ */
+
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openStore } from "./utils.js";
+import {
+  recordTurn,
+  recordTurnRecall,
+  getTurn,
+  getTurnById,
+  listTurnRecall,
+  listConversationTurns,
+  ensureConversationId,
+  forkConversation,
+  newConversationId,
+  clearTurns,
+} from "./turns.js";
+import { loadSessionState, saveSessionState } from "./session-state.js";
+
+let tmpDir: string;
+let counter = 0;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "mc-turns-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function stateDir(): string {
+  return join(tmpDir, `run-${counter++}`);
+}
+
+// ─── 1. recordTurn upserts + getTurn round-trip ────────────────────────────
+
+test("S43-1: recordTurn inserts/updates + getTurn finds by conv+index", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const conv = newConversationId();
+  const id = recordTurn({
+    conversationId: conv,
+    sessionId: "sess-1",
+    turnIndex: 3,
+    endedAt: 1000,
+    ctxTokens: 12000,
+    ctxPercent: 42.5,
+    pressureBand: "mid",
+    modelId: "claude-fable-5",
+  }, sd);
+  assert.ok(id > 0, "turn id returned");
+  const t = getTurn(conv, 3, sd);
+  assert.ok(t, "turn found");
+  assert.equal(t!.conversationId, conv);
+  assert.equal(t!.turnIndex, 3);
+  assert.equal(t!.ctxTokens, 12000);
+  assert.equal(t!.ctxPercent, 42.5);
+  assert.equal(t!.pressureBand, "mid");
+  assert.equal(t!.modelId, "claude-fable-5");
+  assert.equal(t!.endedAt, 1000);
+  // Re-record (upsert) with additional metrics — COALESCE preserves started_at.
+  const id2 = recordTurn({
+    conversationId: conv,
+    sessionId: "sess-1",
+    turnIndex: 3,
+    startedAt: 900,
+    ctxTokens: 12500,
+  }, sd);
+  assert.equal(id2, id, "same turn id on upsert");
+  const t2 = getTurn(conv, 3, sd);
+  assert.equal(t2!.ctxTokens, 12500, "metrics updated");
+  assert.equal(t2!.startedAt, 900, "started_at set on second write");
+});
+
+// ─── 2. recordTurnRecall + listTurnRecall ───────────────────────────────────
+
+test("S43-2: recordTurnRecall stores provenance + listTurnRecall returns it", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const conv = newConversationId();
+  const turnId = recordTurn({
+    conversationId: conv,
+    sessionId: "sess-1",
+    turnIndex: 1,
+  }, sd);
+  recordTurnRecall(turnId, [
+    { checkpointId: "chkpt_003", score: 0.91, source: "flat" },
+    { checkpointId: "r1_0", score: 0.78, source: "raptor", raptorLevel: 1 },
+    { checkpointId: "chkpt_007", score: 0.65, source: "cross-repo" },
+  ], sd);
+  const recalls = listTurnRecall(turnId, sd);
+  assert.equal(recalls.length, 3);
+  assert.equal(recalls[0].checkpointId, "chkpt_003", "sorted by score desc");
+  assert.equal(recalls[0].score, 0.91);
+  const raptorHit = recalls.find((r) => r.source === "raptor");
+  assert.ok(raptorHit, "raptor hit present");
+  assert.equal(raptorHit!.raptorLevel, 1);
+  assert.equal(raptorHit!.checkpointId, "r1_0");
+  // Re-record with a changed score → upsert, no duplicate.
+  recordTurnRecall(turnId, [{ checkpointId: "chkpt_003", score: 0.95, source: "flat" }], sd);
+  const recalls2 = listTurnRecall(turnId, sd);
+  assert.equal(recalls2.length, 3, "no duplicate on re-record");
+  const updated = recalls2.find((r) => r.checkpointId === "chkpt_003");
+  assert.equal(updated!.score, 0.95, "score updated");
+});
+
+// ─── 3. listConversationTurns ───────────────────────────────────────────────
+
+test("S43-3: listConversationTurns returns turns in order", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const conv = newConversationId();
+  for (let i = 1; i <= 4; i++) {
+    recordTurn({
+      conversationId: conv,
+      sessionId: "sess-1",
+      turnIndex: i,
+      endedAt: i * 100,
+    }, sd);
+  }
+  const turns = listConversationTurns(conv, sd);
+  assert.equal(turns.length, 4);
+  assert.deepEqual(turns.map((t) => t.turnIndex), [1, 2, 3, 4]);
+});
+
+// ─── 4. ensureConversationId persists + is stable across resumes ───────────
+
+test("S43-4: ensureConversationId generates once, persists, survives reload", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const sid = "sess-resume";
+  // First call generates + persists.
+  const conv1 = ensureConversationId(sid, sd);
+  assert.ok(conv1.startsWith("conv_"), "generated id has prefix");
+  // Second call (simulated resume) returns the same id — reads session_state.
+  const conv2 = ensureConversationId(sid, sd);
+  assert.equal(conv2, conv1, "stable across resumes");
+  // A different session gets a different conversation id.
+  const conv3 = ensureConversationId("sess-other", sd);
+  assert.notEqual(conv3, conv1);
+});
+
+// ─── 5. forkConversation records lineage + returns recall set ──────────────
+
+test("S43-5: forkConversation creates child + returns parent's recall set", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const parent = newConversationId();
+  // Parent conversation: turn 1 with 2 recalled checkpoints.
+  const turnId = recordTurn({
+    conversationId: parent,
+    sessionId: "sess-parent",
+    turnIndex: 1,
+  }, sd);
+  recordTurnRecall(turnId, [
+    { checkpointId: "chkpt_001", score: 0.9, source: "flat" },
+    { checkpointId: "chkpt_002", score: 0.7, source: "flat" },
+  ], sd);
+  // Fork at turn 1.
+  const { conversationId: child, recalled } = forkConversation(parent, turnId, sd);
+  assert.ok(child.startsWith("conv_"), "child is a conversation id");
+  assert.notEqual(child, parent, "child differs from parent");
+  assert.equal(recalled.length, 2, "parent's recall set returned for replay");
+  assert.ok(
+    recalled.some((r) => r.checkpointId === "chkpt_001"),
+    "includes parent's recalled checkpoint",
+  );
+  // The child conversation is recorded as a branch.
+  const branches = openStore(sd).prepare(
+    "SELECT parent_conversation_id, fork_turn_id FROM conversation_branches WHERE conversation_id = ?",
+  ).get(child) as { parent_conversation_id: string; fork_turn_id: number };
+  assert.equal(branches.parent_conversation_id, parent);
+  assert.equal(branches.fork_turn_id, turnId);
+});
+
+// ─── 6. clearTurns removes turns + their recall rows for a session ──────────
+
+test("S43-6: clearTurns removes turns + cascade turn_recall", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const conv = newConversationId();
+  const turnId = recordTurn({
+    conversationId: conv,
+    sessionId: "sess-clear",
+    turnIndex: 1,
+  }, sd);
+  recordTurnRecall(turnId, [{ checkpointId: "x", score: 0.5, source: "flat" }], sd);
+  assert.equal(listTurnRecall(turnId, sd).length, 1);
+  clearTurns("sess-clear", sd);
+  assert.equal(getTurnById(turnId, sd), null, "turn gone");
+  assert.equal(listTurnRecall(turnId, sd).length, 0, "recall rows cascaded");
+});
+
+// ─── 7. conversation id survives across SessionState save/load ──────────────
+
+test("S43-7: conversationId round-trips through SessionState", () => {
+  const sd = stateDir();
+  openStore(sd);
+  const sid = "sess-rt";
+  // Save a state with a conversationId.
+  const conv = "conv_roundtrip";
+  saveSessionState(sid, {
+    injectedCheckpointIds: [],
+    storedRegionHashes: [],
+    conversationId: conv,
+  }, sd);
+  const loaded = loadSessionState(sid, sd);
+  assert.equal(loaded.conversationId, conv, "conversationId persisted");
+  // ensureConversationId picks up the existing one.
+  assert.equal(ensureConversationId(sid, sd), conv, "ensure keeps existing");
+});