pi-mega-compact 0.9.2 → 0.11.0

package/extensions/mega-topics-cmds.ts

@@ -0,0 +1,151 @@
+/**
+ * mega-topics-cmds.ts — S51C /mega-topics + /mega-topic commands.
+ *
+ * Lists auto-categorized wiki topics and renders wiki pages via ctx.ui.notify.
+ * Read-only (PREVENT-PI-001/002); local SQLite only (PREVENT-PI-004);
+ * parameterized queries (PREVENT-002). Requires turnsDbEnabled; no-ops with
+ * guidance when OFF or when AUTO_WIKI_ENABLED is false.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "./mega-runtime.js";
+import type { MegaConfig } from "./mega-config.js";
+import { createTopicStore } from "../src/topics/store.js";
+import { buildTopicModel } from "../src/topics/cluster.js";
+import { openStore } from "../src/store/sqlite/utils.js";
+
+/** Register the /mega-topics + /mega-topic commands. */
+export function registerTopicsCommands(
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): void {
+	pi.registerCommand("mega-topics", {
+		description:
+			"List auto-categorized wiki topics (k-means + TF-IDF over real embeddings). Usage: /mega-topics",
+		handler: async (_args: string, ctx: ExtensionContext) => {
+			try {
+				if (!config.turnsDbEnabled || !config.autoWikiEnabled) {
+					ctx.ui.notify(
+						"[mega-compact] /mega-topics requires turnsDbEnabled + autoWikiEnabled.",
+					);
+					return;
+				}
+				runtime.bindRepo(ctx.cwd);
+				const stateDir = runtime.currentStateDir;
+				const topicStore = createTopicStore(stateDir);
+				const topics = topicStore.getTopics();
+				const stats = topicStore.getTopicStats();
+
+				if (topics.length === 0) {
+					ctx.ui.notify(
+						"[mega-compact] No topics yet. Topics are auto-generated after every 10th compaction from real memory embeddings (k-means + TF-IDF).",
+					);
+					return;
+				}
+
+				ctx.ui.notify(
+					`[mega-compact] ${stats.totalTopics} topic(s) · ${stats.totalAssigned} assigned memories` +
+						(stats.lastRebuildAt
+							? ` · last rebuild ${new Date(stats.lastRebuildAt).toLocaleString()}`
+							: ""),
+				);
+				for (const t of topics) {
+					const terms = t.termScores
+						.slice(0, 5)
+						.map((s) => s.term)
+						.join(", ");
+					ctx.ui.notify(
+						`  ${t.id}: ${t.label} (${t.memoryCount} memories) — terms: ${terms}`,
+					);
+				}
+			} catch (e) {
+				ctx.ui.notify(`[mega-compact] /mega-topics failed: ${String(e)}`);
+			}
+		},
+	});
+
+	pi.registerCommand("mega-topic", {
+		description: "Show a wiki page for one topic. Usage: /mega-topic <topicId>",
+		handler: async (args: string, ctx: ExtensionContext) => {
+			try {
+				if (!config.turnsDbEnabled || !config.autoWikiEnabled) {
+					ctx.ui.notify(
+						"[mega-compact] /mega-topic requires turnsDbEnabled + autoWikiEnabled.",
+					);
+					return;
+				}
+				const topicId = args.trim();
+				if (!topicId) {
+					ctx.ui.notify(
+						"[mega-compact] /mega-topic needs a topic id, e.g. /mega-topic topic_0",
+					);
+					return;
+				}
+				runtime.bindRepo(ctx.cwd);
+				const stateDir = runtime.currentStateDir;
+				const topicStore = createTopicStore(stateDir);
+				const topics = topicStore.getTopics();
+				const topic = topics.find((t) => t.id === topicId);
+				if (!topic) {
+					ctx.ui.notify(
+						`[mega-compact] topic ${topicId} not found. Use /mega-topics to list.`,
+					);
+					return;
+				}
+
+				// Show topic details.
+				const assignments = topicStore.getMemoriesForTopic(topicId);
+				ctx.ui.notify(
+					`[mega-compact] ${topic.id}: ${topic.label} (${topic.memoryCount} memories)`,
+				);
+				const terms = topic.termScores
+					.slice(0, 8)
+					.map((s) => `${s.term} (${s.score.toFixed(2)})`)
+					.join(", ");
+				ctx.ui.notify(`  terms: ${terms}`);
+				ctx.ui.notify(`  assignments: ${assignments.length} memories`);
+				for (const a of assignments.slice(0, 10)) {
+					ctx.ui.notify(
+						`    ${a.memoryId} — confidence ${(a.confidence * 100).toFixed(1)}%`,
+					);
+				}
+				if (assignments.length > 10) {
+					ctx.ui.notify(`    ... and ${assignments.length - 10} more`);
+				}
+			} catch (e) {
+				ctx.ui.notify(`[mega-compact] /mega-topic failed: ${String(e)}`);
+			}
+		},
+	});
+
+	pi.registerCommand("mega-topics-rebuild", {
+		description:
+			"Force-rebuild the topic model now (k-means + TF-IDF over real embeddings). Usage: /mega-topics-rebuild",
+		handler: async (_args: string, ctx: ExtensionContext) => {
+			try {
+				if (!config.turnsDbEnabled || !config.autoWikiEnabled) {
+					ctx.ui.notify(
+						"[mega-compact] /mega-topics-rebuild requires turnsDbEnabled + autoWikiEnabled.",
+					);
+					return;
+				}
+				runtime.bindRepo(ctx.cwd);
+				const stateDir = runtime.currentStateDir;
+				const db = openStore(stateDir);
+				const model = buildTopicModel(db);
+				createTopicStore(stateDir).replaceTopicModel(model);
+				ctx.ui.notify(
+					`[mega-compact] wiki rebuilt: ${model.k} topics from ${model.totalChunks} chunks (${model.criterion}, silhouette=${model.silhouetteScore?.toFixed(3) ?? "n/a"})`,
+				);
+			} catch (e) {
+				ctx.ui.notify(
+					`[mega-compact] /mega-topics-rebuild failed: ${String(e)}`,
+				);
+			}
+		},
+	});
+}

package/extensions/mega-turn-store.test.ts

@@ -0,0 +1,108 @@
+/**
+ * mega-turn-store.test.ts — S49C adapter routing tests.
+ *
+ * Proves the adapter writes to the isolated turns.db when turnsDbEnabled is
+ * true and to the legacy main-db helpers when false. No network; temp dirs.
+ */
+
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import {
+	ensureConversationIdFor,
+	recordTurnWrite,
+	recordRecallWrite,
+} from "./mega-turn-store.js";
+import { closeTurnStore, turnDbPath } from "../src/store/turns/index.js";
+import type { MegaConfig } from "./mega-config.js";
+
+let tmpDir: string;
+let counter = 0;
+
+beforeEach(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "mc-adapter-"));
+});
+
+afterEach(() => {
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function stateDir(): string {
+	return join(tmpDir, `run-${counter++}`);
+}
+
+/** Minimal MegaConfig stub — only the flag the adapter reads. */
+function cfg(turnsDbEnabled: boolean): MegaConfig {
+	return { turnsDbEnabled } as unknown as MegaConfig;
+}
+
+test("flag ON → writes land in turns.db (not main sqlite.db)", () => {
+	const dir = stateDir();
+	const c = cfg(true);
+	const conv = ensureConversationIdFor(c, "sess_on", dir);
+	const turnId = recordTurnWrite(
+		c,
+		{
+			conversationId: conv,
+			sessionId: "sess_on",
+			turnIndex: 0,
+			role: "assistant",
+			endedAt: Date.now(),
+		},
+		dir,
+	);
+	recordRecallWrite(
+		c,
+		turnId,
+		[{ checkpointId: "cp_on", score: 0.5, source: "flat" }],
+		dir,
+	);
+	closeTurnStore(dir);
+	assert.ok(existsSync(turnDbPath(dir)), "turns.db should exist");
+	assert.ok(
+		!existsSync(join(dir, "sqlite.db")),
+		"main sqlite.db must NOT be created on the flag-ON path",
+	);
+});
+
+test("flag OFF → writes land in main sqlite.db (legacy S48 path)", () => {
+	const dir = stateDir();
+	const c = cfg(false);
+	const conv = ensureConversationIdFor(c, "sess_off", dir);
+	const turnId = recordTurnWrite(
+		c,
+		{
+			conversationId: conv,
+			sessionId: "sess_off",
+			turnIndex: 0,
+			role: "assistant",
+			endedAt: Date.now(),
+		},
+		dir,
+	);
+	recordRecallWrite(
+		c,
+		turnId,
+		[{ checkpointId: "cp_off", score: 0.5, source: "flat" }],
+		dir,
+	);
+	// Legacy helpers open the main sqlite.db.
+	assert.ok(
+		existsSync(join(dir, "sqlite.db")),
+		"main sqlite.db should exist on the flag-OFF path",
+	);
+	assert.ok(
+		!existsSync(turnDbPath(dir)),
+		"turns.db must NOT be created on the flag-OFF path",
+	);
+	// And the row is actually in the main db's turns table.
+	const main = new DatabaseSync(join(dir, "sqlite.db"));
+	const rows = main
+		.prepare("SELECT * FROM turns WHERE session_id = ?")
+		.all("sess_off") as unknown[];
+	assert.equal(rows.length, 1);
+	main.close();
+});

package/extensions/mega-turn-store.ts

@@ -0,0 +1,169 @@
+/**
+ * mega-turn-store.ts — S49 adapter: route per-turn writes to the isolated
+ * turns.db (flag ON) or the legacy main-db helpers (flag OFF).
+ *
+ * RECONCILIATION: maps the extension's per-turn writes onto the contract-first
+ * `TurnStore` (master's design): `appendTurn` / `appendRecall` /
+ * `ensureConversationId` / `asAdmin().stampTurnsEpoch` / `forkConversation`.
+ * src/store/turns/ stays pi-agnostic; this module is the ONLY pi-coupled seam for
+ * turn writes. Both paths are best-effort at the call site (try/catch in the
+ * handlers), so a failure never breaks the agent loop or the recall path.
+ */
+import {
+	createTurnStore,
+	type TurnStore,
+	type TurnEntry,
+	type TurnRecallEntry,
+} from "../src/store/turns/index.js";
+import {
+	recordTurn as legacyRecordTurn,
+	recordTurnRecall as legacyRecordTurnRecall,
+	ensureConversationId as legacyEnsureConversationId,
+} from "../src/store/sqlite/turns.js";
+import type { MegaConfig } from "./mega-config.js";
+import type { DatabaseSync } from "node:sqlite";
+import { openStore } from "../src/store/sqlite/utils.js";
+
+// Per-stateDir cache of turn stores so the extension doesn't reopen the file
+// on every turn. Keyed by stateDir; the underlying connection is also cached
+// in src/store/turns/connection.ts, so this is a thin factory memo.
+const stores = new Map<string, TurnStore>();
+
+function storeFor(stateDir: string): TurnStore {
+	let s = stores.get(stateDir);
+	if (!s) {
+		s = createTurnStore({ stateDir });
+		stores.set(stateDir, s);
+	}
+	return s;
+}
+
+/** Map a legacy RecallSource onto the contract `TurnRecallEntry.source` enum. */
+function mapSource(s: string): TurnRecallEntry["source"] {
+	switch (s) {
+		case "flat":
+		case "checkpoint":
+			return "checkpoint";
+		case "raptor":
+		case "cluster_summary":
+			return "cluster_summary";
+		default:
+			return "memory";
+	}
+}
+
+/** Resolve (or generate) a session's conversation id on the active backend. */
+export function ensureConversationIdFor(
+	config: MegaConfig,
+	sessionId: string,
+	stateDir: string,
+): string {
+	return config.turnsDbEnabled
+		? storeFor(stateDir).ensureConversationId(sessionId)
+		: legacyEnsureConversationId(sessionId, stateDir);
+}
+
+/** Record one turn row (turn_end). Returns the contract TurnId (string). */
+export function recordTurnWrite(
+	config: MegaConfig,
+	input: {
+		conversationId: string;
+		sessionId: string;
+		turnIndex: number;
+		role: string;
+		startedAt?: number;
+		endedAt?: number;
+		ctxTokens?: number;
+		ctxPercent?: number;
+		pressureBand?: string;
+		modelId?: string;
+		epochId?: string;
+	},
+	stateDir: string,
+): string {
+	if (!config.turnsDbEnabled) {
+		legacyRecordTurn(input as never, stateDir);
+		return "";
+	}
+	const entry: TurnEntry = {
+		conversationId: input.conversationId,
+		sessionId: input.sessionId,
+		turnIndex: input.turnIndex,
+		role: input.role as TurnEntry["role"],
+		endedAt: input.endedAt ?? input.startedAt ?? Date.now(),
+		ctxTokens: input.ctxTokens,
+		ctxPercent: input.ctxPercent,
+		pressureBand: input.pressureBand as TurnEntry["pressureBand"],
+		model: input.modelId,
+		epochId: input.epochId,
+	};
+	return storeFor(stateDir).appendTurn(entry);
+}
+
+/** Record recall provenance for a turn (one hit at a time — contract is append-only). */
+export function recordRecallWrite(
+	config: MegaConfig,
+	turnId: string | number,
+	hits: Array<{
+		checkpointId: string;
+		score: number;
+		source: string;
+		raptorLevel?: number;
+	}>,
+	stateDir: string,
+): void {
+	if (!config.turnsDbEnabled) {
+		legacyRecordTurnRecall(Number(turnId), hits as never, stateDir);
+		return;
+	}
+	const writer = storeFor(stateDir).asWriter();
+	for (const h of hits) {
+		const entry: TurnRecallEntry = {
+			turnId: String(turnId),
+			checkpointId: h.checkpointId,
+			score: h.score,
+			source: mapSource(h.source),
+			raptorLevel: h.raptorLevel,
+		};
+		writer.appendRecall(entry);
+	}
+}
+
+/** S50B: stamp `epoch_id` on a session's unstamped turns (compact-commit).
+ *  Isolated-store only — the legacy main-db turn path is being retired, so it
+ *  is a no-op when turnsDbEnabled is false. Returns the number stamped. */
+export function stampTurnsEpochFor(
+	config: MegaConfig,
+	sessionId: string,
+	epochId: string,
+	stateDir: string,
+): number {
+	return config.turnsDbEnabled
+		? storeFor(stateDir).asAdmin().stampTurnsEpoch(sessionId, epochId)
+		: 0;
+}
+
+/** S50C: resolve the active turn store for metrics/fork commands.
+ *  Returns null when turnsDbEnabled is OFF (legacy main-db turn path — the
+ *  per-turn metrics/fork commands are isolated-store only). */
+export function turnStoreFor(
+	config: MegaConfig,
+	stateDir: string,
+): TurnStore | null {
+	return config.turnsDbEnabled ? storeFor(stateDir) : null;
+}
+
+/** S50C: open (cached) the main db handle for metrics read-queries
+ *  (raw_transcript + checkpoint_epochs). Callers must NOT close it. */
+export function mainDbFor(stateDir: string): DatabaseSync {
+	return openStore(stateDir);
+}
+
+/** Test/teardown: close all cached turn stores for a state dir. */
+export function closeTurnStoreFor(stateDir: string): void {
+	const s = stores.get(stateDir);
+	if (s) {
+		s.close();
+		stores.delete(stateDir);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -41,6 +41,8 @@
     "compactionProvider": "mega-compact"
   },
   "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
     "build:dashboard": "cd extensions/dashboard-client && npx vite build",
     "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs",

package/src/config/turns.ts

@@ -0,0 +1,69 @@
+/**
+ * config/turns.ts — SINGLE SOURCE OF TRUTH for the S49 turn-store flags.
+ *
+ * Feature-flag semantics (docs/specs/s49-turn-db-foundation.md):
+ * - TURNS_DB_ENABLED defaults ON (isolated turns.db). OFF = byte-identical S48
+ *   behavior (turn helpers use the main sqlite.db). Opt-out, not opt-in.
+ * - All values read from MEGACOMPACT_* env at load, with the defaults below as
+ *   fallback. Booleans/numbers only — no calibration.
+ *
+ * PREVENT-PI-004: pure config, no network.
+ */
+
+function envBool(name: string, def: boolean): boolean {
+	const v = process.env[name];
+	if (v === undefined) return def;
+	return v === "true" || v === "1";
+}
+
+function envNum(name: string, def: number): number {
+	const v = process.env[name];
+	if (v === undefined) return def;
+	const n = Number(v);
+	return Number.isFinite(n) ? n : def;
+}
+
+export interface TurnsConfigShape {
+	/** Isolated turns.db store enabled (default true). OFF = legacy main-db path. */
+	TURNS_DB_ENABLED: boolean;
+	/** Per-turn provenance retention window, days (default 30). */
+	TURNS_RETENTION_DAYS: number;
+	/** Minimum turns always kept per conversation during prune (default 5). */
+	TURNS_KEEP_MIN_PER_CONVERSATION: number;
+	/** S51: auto-categorizing wiki (k-means + TF-IDF over real embeddings). Default ON. */
+	AUTO_WIKI_ENABLED: boolean;
+	/** S51: [minK, maxK] cluster-count search space (default 3..15). */
+	WIKI_K_MIN: number;
+	WIKI_K_MAX: number;
+	/** S51: how many TF-IDF terms form a topic label (default 5). */
+	WIKI_LABEL_TOP_TERMS: number;
+	/** S51: rebuild the topic model every Nth compaction (default 10). */
+	WIKI_REBUILD_EVERY_N_COMPACTS: number;
+}
+
+function envKRange(defMin: number, defMax: number): [number, number] {
+	const v = process.env.MEGACOMPACT_WIKI_K_RANGE;
+	if (v) {
+		const parts = v.split(",").map((s) => Number(s.trim()));
+		if (parts.length === 2 && parts.every((n) => Number.isFinite(n) && n >= 1)) {
+			return [Math.floor(parts[0]), Math.floor(parts[1])];
+		}
+	}
+	return [defMin, defMax];
+}
+
+export function loadTurnsConfig(): TurnsConfigShape {
+	const [kMin, kMax] = envKRange(3, 15);
+	return {
+		TURNS_DB_ENABLED: envBool("MEGACOMPACT_TURNS_DB", true),
+		TURNS_RETENTION_DAYS: envNum("MEGACOMPACT_TURNS_RETENTION_DAYS", 30),
+		TURNS_KEEP_MIN_PER_CONVERSATION: envNum("MEGACOMPACT_TURNS_KEEP_MIN", 5),
+		AUTO_WIKI_ENABLED: envBool("MEGACOMPACT_AUTO_WIKI", true),
+		WIKI_K_MIN: kMin,
+		WIKI_K_MAX: kMax,
+		WIKI_LABEL_TOP_TERMS: envNum("MEGACOMPACT_WIKI_LABEL_TOP_TERMS", 5),
+		WIKI_REBUILD_EVERY_N_COMPACTS: envNum("MEGACOMPACT_WIKI_REBUILD_EVERY", 10),
+	};
+}
+
+export const TurnsConfig: TurnsConfigShape = loadTurnsConfig();

package/src/fork.test.ts

@@ -0,0 +1,94 @@
+/**
+ * fork.test.ts — S50C fork primitive tests. No network; temp dirs.
+ *
+ * Uses the contract-first TurnStore (createTurnStore({ stateDir })).
+ */
+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 { createTurnStore, closeAllTurnDbs } from "./store/turns/index.js";
+import { forkFromConversation, ForkError } from "./fork.js";
+
+let tmpDir: string;
+let counter = 0;
+
+beforeEach(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "mc-fork-"));
+});
+
+afterEach(() => {
+	closeAllTurnDbs();
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function stateDir(): string {
+	return join(tmpDir, `run-${counter++}`);
+}
+
+test("fork resolves the turn + returns the recall set to rehydrate", () => {
+	const dir = stateDir();
+	const store = createTurnStore({ stateDir: dir });
+	const conv = store.ensureConversationId("sess_f");
+	const turnId = store.appendTurn({
+		conversationId: conv,
+		sessionId: "sess_f",
+		turnIndex: 2,
+		role: "assistant",
+		endedAt: Date.now(),
+	});
+	store.appendRecall({
+		turnId: turnId,
+		checkpointId: "cp_a",
+		score: 0.9,
+		source: "checkpoint",
+	});
+	store.appendRecall({
+		turnId: turnId,
+		checkpointId: "cp_b",
+		score: 0.7,
+		source: "cluster_summary",
+		raptorLevel: 1,
+	});
+	const out = forkFromConversation(store, conv, 2);
+	assert.ok(out.childConversationId.startsWith("conv_"));
+	assert.notEqual(out.childConversationId, conv);
+	assert.equal(out.forkTurn.turnIndex, 2);
+	assert.deepEqual(out.checkpointIds.sort(), ["cp_a", "cp_b"]);
+	assert.equal(out.recalled.length, 2);
+	store.close();
+});
+
+test("unknown turn → ForkError TURN_NOT_FOUND", () => {
+	const dir = stateDir();
+	const store = createTurnStore({ stateDir: dir });
+	const conv = store.ensureConversationId("sess_g");
+	assert.throws(
+		() => forkFromConversation(store, conv, 99),
+		(e: unknown) => {
+			return e instanceof ForkError && e.code === "TURN_NOT_FOUND";
+		},
+	);
+	store.close();
+});
+
+test("turn with no recall set → ForkError NO_RECALL", () => {
+	const dir = stateDir();
+	const store = createTurnStore({ stateDir: dir });
+	const conv = store.ensureConversationId("sess_h");
+	store.appendTurn({
+		conversationId: conv,
+		sessionId: "sess_h",
+		turnIndex: 0,
+		role: "assistant",
+		endedAt: Date.now(),
+	});
+	assert.throws(
+		() => forkFromConversation(store, conv, 0),
+		(e: unknown) => {
+			return e instanceof ForkError && e.code === "NO_RECALL";
+		},
+	);
+	store.close();
+});

package/src/fork.ts

@@ -0,0 +1,78 @@
+/**
+ * fork.ts — S50C host-agnostic conversation-fork primitive.
+ *
+ * Pi-agnostic: consumes only the S49 `TurnStore` contract. A "fork" branches a
+ * new child conversation off a parent's turn N and inherits that turn's
+ * injected-checkpoint set as its starting recall state (recall-to-point — NOT a
+ * live-window replay, which stays an S48 non-goal). The host (pi command,
+ * dashboard intent, own TUI, API gateway) supplies the store + identifiers and
+ * applies the returned recall set to its own session state.
+ *
+ * PREVENT-PI-001/002: fork writes to conversation_forks only; it never mutates
+ * memory, drop ranges, or the parent's turns. No network (PREVENT-PI-004).
+ */
+import type {
+	TurnStore,
+	TurnEntry,
+	TurnRecallEntry,
+} from "./store/turns/types.js";
+
+/** Result of a fork: the new child conversation + the recall set to rehydrate. */
+export interface ForkOutcome {
+	/** Newly-created child conversation id. */
+	childConversationId: string;
+	/** The parent turn the fork branched from (contract TurnEntry). */
+	forkTurn: TurnEntry;
+	/** The parent's injected checkpoints at the fork turn (the replay set). */
+	recalled: TurnRecallEntry[];
+	/** Distinct checkpoint ids to seed into the child's injected-set. */
+	checkpointIds: string[];
+}
+
+/** Typed error so hosts can distinguish "unknown turn" from storage failures. */
+export class ForkError extends Error {
+	readonly code: "TURN_NOT_FOUND" | "NO_RECALL";
+	constructor(code: ForkError["code"], message: string) {
+		super(message);
+		this.name = "ForkError";
+		this.code = code;
+	}
+}
+
+/**
+ * Fork `parentConversationId` at `turnIndex`. Resolves the turn entry (by
+ * conversation + index via `getTurnByIndex`), creates the child conversation via
+ * `store.forkConversation` (returns the child ConversationId), and returns the
+ * parent turn's recorded recall set (`listRecallByIndex`) to rehydrate.
+ *
+ * @throws ForkError TURN_NOT_FOUND when the (conversation, turnIndex) row is absent.
+ * @throws ForkError NO_RECALL when the fork turn has no injected checkpoints to replay.
+ */
+export function forkFromConversation(
+	store: TurnStore,
+	parentConversationId: string,
+	turnIndex: number,
+): ForkOutcome {
+	const turn = store.getTurnByIndex(parentConversationId, turnIndex);
+	if (!turn) {
+		throw new ForkError(
+			"TURN_NOT_FOUND",
+			`no turn ${turnIndex} in conversation ${parentConversationId}`,
+		);
+	}
+	const childConversationId = store.forkConversation(
+		parentConversationId,
+		turnIndex,
+	);
+	const recalled = store.listRecallByIndex(parentConversationId, turnIndex);
+	const checkpointIds = [...new Set(recalled.map((r) => r.checkpointId))];
+	if (checkpointIds.length === 0) {
+		// The child conversation was still created (lineage is recorded), but a fork
+		// with nothing to rehydrate is almost always a caller mistake — surface it.
+		throw new ForkError(
+			"NO_RECALL",
+			`turn ${turnIndex} in ${parentConversationId} has no injected checkpoints to fork from`,
+		);
+	}
+	return { childConversationId, forkTurn: turn, recalled, checkpointIds };
+}