pi-mega-compact 0.9.2 → 0.11.0

package/dist/extensions/mega-pipeline/recall.js

@@ -6,11 +6,11 @@
  * the shared MegaRuntime (token accounting, ticker, dashboard events).
  */
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { recallAndInline, recallAndInlineAsync, formatRecallBlock } from "../../src/recall.js";
+import { recallAndInline, recallAndInlineAsync, formatRecallBlock, } from "../../src/recall.js";
 import { normalizeSessionId } from "../../src/store.js";
-import { incRecallInjected, incCacheHitTokens, getIndexDir } from "../../src/store/sqlite.js";
-import { ensureConversationId, recordTurn, recordTurnRecall } from "../../src/store/sqlite/turns.js";
-import { C, } from "../mega-runtime.js";
+import { incRecallInjected, incCacheHitTokens, getIndexDir, } from "../../src/store/sqlite.js";
+import { ensureConversationIdFor, recordTurnWrite, recordRecallWrite, } from "../mega-turn-store.js";
+import { C } from "../mega-runtime.js";
 /**
  * Unified recall (Layer 5). The ONE path that injects. Returns the recall
  * result; callers decide whether to stage it for before_agent_start (resume)
@@ -34,12 +34,22 @@ export function doRecall(runtime, config, ctx, query, source) {
         liveWindow,
         dedupSim: config.dedupSim,
     }, runtime.store);
-    runtime.dashboard.event("recall", { source, query: query.slice(0, 120), injected: result.toInject.length, empty: result.empty });
+    runtime.dashboard.event("recall", {
+        source,
+        query: query.slice(0, 120),
+        injected: result.toInject.length,
+        empty: result.empty,
+    });
     if (!result.empty && result.toInject.length > 0) {
         const top = result.toInject[0];
         const scorePct = Math.round((top.score ?? 0) * 100);
         const files = top.checkpoint.filesModified ?? [];
-        const label = files.length ? files.map((f) => f.split("/").pop() ?? f).slice(0, 2).join(", ") : top.checkpoint.checkpointId;
+        const label = files.length
+            ? files
+                .map((f) => f.split("/").pop() ?? f)
+                .slice(0, 2)
+                .join(", ")
+            : top.checkpoint.checkpointId;
         runtime.pushTicker(`${C.amber}↩${C.reset} recalled ${top.checkpoint.checkpointId} · ${scorePct}% · ${label}`);
         runtime.lastWhy = `why: recalled@${scorePct}% (${result.toInject.length} chkpt)`;
     }
@@ -55,17 +65,22 @@ export function doRecall(runtime, config, ctx, query, source) {
         // turn, their score + source path. Linked to the turn row written at
         // turn_end via the conversation+turnIndex. Best-effort + non-fatal.
         try {
-            const convId = ensureConversationId(sid, runtime.currentStateDir);
-            const turnId = recordTurn({
+            const convId = ensureConversationIdFor(config, sid, runtime.currentStateDir);
+            const turnId = recordTurnWrite(config, {
                 conversationId: convId,
                 sessionId: sid,
                 turnIndex: runtime.currentTurn,
+                role: "assistant",
                 startedAt: Date.now(),
             }, runtime.currentStateDir);
-            recordTurnRecall(turnId, result.toInject.map((h) => ({
+            recordRecallWrite(config, turnId, result.toInject.map((h) => ({
                 checkpointId: h.checkpoint.checkpointId,
                 score: h.score,
-                source: (h.raptorLevel !== undefined ? "raptor" : h.repoId ? "cross-repo" : "flat"),
+                source: h.raptorLevel !== undefined
+                    ? "raptor"
+                    : h.repoId
+                        ? "cross-repo"
+                        : "flat",
                 raptorLevel: h.raptorLevel,
             })), runtime.currentStateDir);
         }
@@ -92,9 +107,15 @@ export async function doRecallAsync(runtime, config, ctx, query, source, opts =
     const liveWindow = config.windowDedupe ? extractLiveWindow(ctx) : undefined;
     // Sync same-repo first (fast, never blocks).
     const sameRepo = recallAndInline({
-        sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true,
-        recallMaxTokens: config.recallMaxTokens, windowDedupe: config.windowDedupe,
-        liveWindow, dedupSim: config.dedupSim,
+        sessionId: sid,
+        query,
+        limit: config.autoInlineK,
+        source,
+        skipInjected: true,
+        recallMaxTokens: config.recallMaxTokens,
+        windowDedupe: config.windowDedupe,
+        liveWindow,
+        dedupSim: config.dedupSim,
     }, runtime.store);
     if (!config.crossRepoEnabled || !opts.crossRepo)
         return sameRepo;
@@ -103,9 +124,16 @@ export async function doRecallAsync(runtime, config, ctx, query, source, opts =
     // Augment: cross-repo HNSW (async) with the stricter floor. Non-fatal.
     try {
         const x = await recallAndInlineAsync({
-            sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true,
-            recallMaxTokens: config.recallMaxTokens, windowDedupe: config.windowDedupe,
-            liveWindow, dedupSim: config.crossRepoCosine, crossRepo: true,
+            sessionId: sid,
+            query,
+            limit: config.autoInlineK,
+            source,
+            skipInjected: true,
+            recallMaxTokens: config.recallMaxTokens,
+            windowDedupe: config.windowDedupe,
+            liveWindow,
+            dedupSim: config.crossRepoCosine,
+            crossRepo: true,
             // F2: resolve the machine-wide index dir via the shared resolver so the
             // cross-repo injected-set dedup works even when MEGACOMPACT_INDEX_DIR is
             // unset. The env var still wins when set (getIndexDir checks it first);
@@ -116,7 +144,9 @@ export async function doRecallAsync(runtime, config, ctx, query, source, opts =
             globalIndexDir: getIndexDir(),
         }, runtime.store);
         runtime.dashboard.event("recall-crossrepo", {
-            source, query: query.slice(0, 120), injected: x.toInject.length,
+            source,
+            query: query.slice(0, 120),
+            injected: x.toInject.length,
             sourceRepos: x.toInject.map((h) => h.repoId).filter(Boolean),
         });
         // Merge, dedup by checkpointId, respect the same token cap by reformatting.

package/dist/extensions/mega-topics-cmds.js

@@ -0,0 +1,111 @@
+/**
+ * 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 { 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, runtime, config) {
+    pi.registerCommand("mega-topics", {
+        description: "List auto-categorized wiki topics (k-means + TF-IDF over real embeddings). Usage: /mega-topics",
+        handler: async (_args, ctx) => {
+            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, ctx) => {
+            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, ctx) => {
+            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/dist/extensions/mega-turn-store.js

@@ -0,0 +1,110 @@
+/**
+ * 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, } from "../src/store/turns/index.js";
+import { recordTurn as legacyRecordTurn, recordTurnRecall as legacyRecordTurnRecall, ensureConversationId as legacyEnsureConversationId, } from "../src/store/sqlite/turns.js";
+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();
+function storeFor(stateDir) {
+    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) {
+    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, sessionId, stateDir) {
+    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, input, stateDir) {
+    if (!config.turnsDbEnabled) {
+        legacyRecordTurn(input, stateDir);
+        return "";
+    }
+    const entry = {
+        conversationId: input.conversationId,
+        sessionId: input.sessionId,
+        turnIndex: input.turnIndex,
+        role: input.role,
+        endedAt: input.endedAt ?? input.startedAt ?? Date.now(),
+        ctxTokens: input.ctxTokens,
+        ctxPercent: input.ctxPercent,
+        pressureBand: input.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, turnId, hits, stateDir) {
+    if (!config.turnsDbEnabled) {
+        legacyRecordTurnRecall(Number(turnId), hits, stateDir);
+        return;
+    }
+    const writer = storeFor(stateDir).asWriter();
+    for (const h of hits) {
+        const entry = {
+            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, sessionId, epochId, stateDir) {
+    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, stateDir) {
+    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) {
+    return openStore(stateDir);
+}
+/** Test/teardown: close all cached turn stores for a state dir. */
+export function closeTurnStoreFor(stateDir) {
+    const s = stores.get(stateDir);
+    if (s) {
+        s.close();
+        stores.delete(stateDir);
+    }
+}

package/dist/extensions/mega-turn-store.test.js

@@ -0,0 +1,68 @@
+/**
+ * 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";
+let tmpDir;
+let counter = 0;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mc-adapter-"));
+});
+afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+function stateDir() {
+    return join(tmpDir, `run-${counter++}`);
+}
+/** Minimal MegaConfig stub — only the flag the adapter reads. */
+function cfg(turnsDbEnabled) {
+    return { turnsDbEnabled };
+}
+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");
+    assert.equal(rows.length, 1);
+    main.close();
+});

package/dist/src/config/turns.js

@@ -0,0 +1,48 @@
+/**
+ * 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, def) {
+    const v = process.env[name];
+    if (v === undefined)
+        return def;
+    return v === "true" || v === "1";
+}
+function envNum(name, def) {
+    const v = process.env[name];
+    if (v === undefined)
+        return def;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : def;
+}
+function envKRange(defMin, defMax) {
+    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() {
+    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 = loadTurnsConfig();

package/dist/src/fork.js

@@ -0,0 +1,33 @@
+/** Typed error so hosts can distinguish "unknown turn" from storage failures. */
+export class ForkError extends Error {
+    code;
+    constructor(code, message) {
+        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, parentConversationId, turnIndex) {
+    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 };
+}

package/dist/src/fork.test.js

@@ -0,0 +1,81 @@
+/**
+ * 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;
+let counter = 0;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mc-fork-"));
+});
+afterEach(() => {
+    closeAllTurnDbs();
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+function stateDir() {
+    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) => {
+        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) => {
+        return e instanceof ForkError && e.code === "NO_RECALL";
+    });
+    store.close();
+});

package/dist/src/intent.js

@@ -0,0 +1,51 @@
+/** Open an intent queue over a turns.db handle (from openTurnStore/openTurnDb). */
+export function openIntentQueue(db) {
+    function rowToIntent(r) {
+        return {
+            id: String(r.id),
+            conversationId: String(r.target_conversation_id),
+            targetTurnIndex: Number(r.target_turn_id),
+            createdAt: Number(r.requested_at),
+            status: r.consumed_at == null ? "pending" : "consumed",
+        };
+    }
+    return {
+        postIntent(input) {
+            const createdAt = Date.now();
+            const res = db
+                .prepare(`INSERT INTO pending_fork
+           (target_conversation_id, target_turn_id, requested_at, consumed_at)
+         VALUES (?, ?, ?, NULL)`)
+                .run(input.conversationId, input.targetTurnIndex, createdAt);
+            const id = String(Number(res.lastInsertRowid));
+            return {
+                id,
+                conversationId: input.conversationId,
+                targetTurnIndex: input.targetTurnIndex,
+                createdAt,
+                status: "pending",
+            };
+        },
+        pendingIntents() {
+            const rows = db
+                .prepare(`SELECT id, target_conversation_id, target_turn_id, requested_at, consumed_at
+           FROM pending_fork WHERE consumed_at IS NULL
+           ORDER BY requested_at ASC`)
+                .all();
+            return rows.map(rowToIntent);
+        },
+        allIntents(limit = 100) {
+            const rows = db
+                .prepare(`SELECT id, target_conversation_id, target_turn_id, requested_at, consumed_at
+           FROM pending_fork ORDER BY requested_at DESC, id DESC LIMIT ?`)
+                .all(limit);
+            return rows.map(rowToIntent);
+        },
+        consumeIntent(id) {
+            db.prepare("UPDATE pending_fork SET consumed_at = ? WHERE id = ?").run(Date.now(), id);
+        },
+        abandonIntent(id) {
+            db.prepare("DELETE FROM pending_fork WHERE id = ?").run(id);
+        },
+    };
+}