pi-mega-compact 0.21.3 → 0.21.5

package/dist/src/compact.js

@@ -7,14 +7,19 @@
  * Pure, pi-agnostic, deterministic, no LLM required.
  */
 import { estimateSessionTokens } from "./tokens.js";
+// Summary tag/format/merge helpers live in the compact-summary sibling (delegate-
+// shell split, Phase D follow-up) so this file stays under the 300-line soft
+// limit. truncate + summarizeBlock are re-imported here because summarizeMessages
+// (kept below) depends on them alongside the inference helpers that stay here.
+import { truncate, summarizeBlock, formatCompactSummary, } from "./compact-summary.js";
+// Re-export the public summary API so external consumers importing from
+// `../compact.js` are unchanged by the split.
+export { formatCompactSummary, mergeCompactSummaries } from "./compact-summary.js";
 const INTERESTING_EXT = new Set(["rs", "ts", "tsx", "js", "json", "md"]);
 const PENDING_WORDS = ["todo", "next", "pending", "follow up", "remaining"];
 const COMPACT_PREAMBLE = "This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.\n\n";
 const RECENT_NOTE = "Recent messages are preserved verbatim.";
 const DIRECT_RESUME = "Continue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, and do not preface with continuation text.";
-function truncate(s, max) {
-    return s.length <= max ? s : `${s.slice(0, max)}…`;
-}
 function firstText(m) {
     // PREVENT crash: pi can hand us a message with text: undefined (pure
     // tool-call/tool-result). Guard the trim so the legacy summarizeMessages
@@ -99,40 +104,6 @@ export function collectRecentUserRequests(messages, limit) {
         .map((t) => truncate(t, 160));
     return reqs.slice(-limit);
 }
-/** Summarize a block to a one-line description. */
-function summarizeBlock(m) {
-    if (m.role === "tool")
-        return `tool_result ${m.toolName ?? "?"}: ${truncate(m.output ?? m.text, 160)}`;
-    if (m.toolName)
-        return `tool_use ${m.toolName}(${truncate(m.input ?? "", 160)})`;
-    return truncate(m.text, 160);
-}
-function stripTag(block, tag) {
-    const start = `<${tag}>`;
-    const end = `</${tag}>`;
-    const s = block.indexOf(start);
-    const e = block.indexOf(end);
-    if (s === -1 || e === -1)
-        return block;
-    return block.slice(0, s) + block.slice(e + end.length);
-}
-function extractTag(block, tag) {
-    const s = block.indexOf(`<${tag}>`);
-    const e = block.indexOf(`</${tag}>`);
-    if (s === -1 || e === -1)
-        return undefined;
-    return block.slice(s + `<${tag}>`.length, e);
-}
-/** Normalize a raw summary into user-facing "Summary: ..." text. */
-export function formatCompactSummary(summary) {
-    const withoutAnalysis = stripTag(summary, "analysis");
-    let formatted = withoutAnalysis;
-    const content = extractTag(withoutAnalysis, "summary");
-    if (content !== undefined) {
-        formatted = withoutAnalysis.replace(`<summary>${content}</summary>`, `Summary:\n${content.trim()}`);
-    }
-    return formatted.replace(/\n{3,}/g, "\n\n").trim();
-}
 /**
  * Build a <summary> block from a slice of messages (the COLLAPSE output).
  * Mirrors claw-code summarize_messages.
@@ -175,66 +146,6 @@ export function summarizeMessages(messages) {
     lines.push("</summary>");
     return lines.join("\n");
 }
-/** Extract the prior "highlights" + "timeline" sections from an existing summary. */
-function extractSummaryHighlights(summary) {
-    const lines = formatCompactSummary(summary).split("\n");
-    const out = [];
-    let inTimeline = false;
-    for (const line of lines) {
-        const t = line.trimEnd();
-        if (!t || t === "Summary:" || t === "Conversation summary:")
-            continue;
-        if (t === "- Key timeline:") {
-            inTimeline = true;
-            continue;
-        }
-        if (inTimeline)
-            continue;
-        out.push(t);
-    }
-    return out;
-}
-function extractSummaryTimeline(summary) {
-    const lines = formatCompactSummary(summary).split("\n");
-    const out = [];
-    let inTimeline = false;
-    for (const line of lines) {
-        const t = line.trimEnd();
-        if (t === "- Key timeline:") {
-            inTimeline = true;
-            continue;
-        }
-        if (!inTimeline)
-            continue;
-        if (!t)
-            break;
-        out.push(t);
-    }
-    return out;
-}
-/** Merge an existing compact summary with a new one (accumulate, don't overwrite). */
-export function mergeCompactSummaries(existing, newSummary) {
-    if (!existing)
-        return newSummary;
-    const prevHighlights = extractSummaryHighlights(existing);
-    const newHighlights = extractSummaryHighlights(formatCompactSummary(newSummary));
-    const newTimeline = extractSummaryTimeline(formatCompactSummary(newSummary));
-    const lines = ["<summary>", "Conversation summary:"];
-    if (prevHighlights.length) {
-        lines.push("- Previously compacted context:");
-        prevHighlights.forEach((l) => lines.push(`  ${l}`));
-    }
-    if (newHighlights.length) {
-        lines.push("- Newly compacted context:");
-        newHighlights.forEach((l) => lines.push(`  ${l}`));
-    }
-    if (newTimeline.length) {
-        lines.push("- Key timeline:");
-        newTimeline.forEach((l) => lines.push(`  ${l}`));
-    }
-    lines.push("</summary>");
-    return lines.join("\n");
-}
 /** True when the compactable portion exceeds the budget. */
 export function shouldCompact(messages, maxEstimatedTokens, preserveRecent) {
     if (messages.length <= preserveRecent)
@@ -242,8 +153,13 @@ export function shouldCompact(messages, maxEstimatedTokens, preserveRecent) {
     const compactable = messages.slice(0, messages.length - preserveRecent);
     return estimateSessionTokens(compactable) >= maxEstimatedTokens;
 }
-/** Local reimplementation of memory-mcp auto_compact_check. */
-export function autoCompactCheck(currentTokens, threshold = 50000) {
+/** Local reimplementation of memory-mcp auto_compact_check.
+ *
+ * `threshold` is REQUIRED (no default) — every caller (gateCheck.ts) passes the
+ * resolved `gateThreshold` (effectiveThresholdImpl: `tierPct × window`, or the
+ * custom absolute). A bare default here would silently re-introduce a hardcoded
+ * magic-number gate that bypasses the percent-based fire point. */
+export function autoCompactCheck(currentTokens, threshold) {
     return {
         shouldCompact: currentTokens >= threshold,
         currentTokens,

package/dist/src/contextHealth.js

@@ -15,14 +15,21 @@
  */
 import { openStore } from "./store/sqlite/utils.js";
 /**
- * Weighted composite health score from five sub-dimensions.
+ * Weighted composite health score from six sub-dimensions (Sprint H — B2).
  *
  * Weights:
  *   output quality  22% — primary measure of model output health
  *   drift           22% — session-level coherence
  *   cache poison    20% — prompt-cache integrity
  *   cache health    18% — cache hit rate stability
- *   error rate      18% — error frequency
+ *   error rate       9% — API-retry error frequency (split from 18%)
+ *   store error      9% — internal store-write failure frequency (NEW 6th axis)
+ *
+ * The 0.18 `errorRate` budget was split into `errorRate 0.09` +
+ * `storeErrorRate 0.09` so a silent store-write failure is as visible as a
+ * retryable API error. Weights sum to 1.0. NOTE (step-change): historical
+ * context_health rows keep their stored composite (point-in-time snapshots — no
+ * backfill), so the trend line shows a boundary step where weights change.
  *
  * Returns 0–1: 1 = fully healthy, 0 = severely degraded.
  */
@@ -31,7 +38,8 @@ export function computeHealthScore(sub) {
         sub.drift * 0.22 +
         sub.cachePoison * 0.20 +
         sub.cacheHealth * 0.18 +
-        sub.errorRate * 0.18;
+        sub.errorRate * 0.09 +
+        sub.storeErrorRate * 0.09;
     return Math.max(0, Math.min(1, raw));
 }
 /**
@@ -47,9 +55,9 @@ export function recordContextHealth(stateDir, row) {
         const db = openStore(stateDir);
         db.prepare(`INSERT INTO context_health
        (ts, session_id, turn_index, drift_score, output_quality,
-        error_score, cache_health, cache_poison, composite,
+        error_score, cache_health, cache_poison, composite, store_error_score,
         model_id, repetition_ratio, coherence_score, prefix_hash)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.ts, row.sessionId, row.turnIndex, row.driftScore, row.outputQuality, row.errorScore, row.cacheHealth, row.cachePoison, row.composite, row.modelId ?? null, row.repetitionRatio ?? null, row.coherenceScore ?? null, row.prefixHash ?? null);
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.ts, row.sessionId, row.turnIndex, row.driftScore, row.outputQuality, row.errorScore, row.cacheHealth, row.cachePoison, row.composite, row.storeErrorScore ?? null, row.modelId ?? null, row.repetitionRatio ?? null, row.coherenceScore ?? null, row.prefixHash ?? null);
     }
     catch {
         /* non-fatal: context health instrumentation never blocks the agent loop */

package/dist/src/metrics/turns.js

@@ -50,7 +50,12 @@ export function turnMetrics(store, mainDb, conversationId) {
     }
     return turns.map((t) => {
         const recall = store.listRecallByIndex(conversationId, t.turnIndex);
-        const agg = rawAggBySessionTurn.get(`${t.sessionId}::${t.turnIndex}`);
+        // S49R: raw_transcript is keyed by pi's per-session counter. Pre-migration
+        // turn rows have NULL sessionTurnIndex and their turnIndex IS the session
+        // counter, so fall back to turnIndex (COALESCE). Post-migration rows join
+        // on sessionTurnIndex so resume doesn't zero the raw message count.
+        const sessionKey = t.sessionTurnIndex ?? t.turnIndex;
+        const agg = rawAggBySessionTurn.get(`${t.sessionId}::${sessionKey}`);
         const rawCount = agg?.raw_count ?? 0;
         const uniqueCount = agg?.unique_count ?? 0;
         return {

package/dist/src/store/sqlite/context-health-cache-poison.js

@@ -0,0 +1,60 @@
+/**
+ * context-health-cache-poison.ts — `cache_poison_events` table accessors.
+ *
+ * Extracted from context-health.ts (Sprint H split — context-health.ts crossed
+ * the soft limit when storeErrorScore was added). Records cache-poison advisory
+ * events when cache corruption/inconsistency is detected at a given cache layer.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL uses ? placeholders, no string-concatenated values.
+ * Pi-agnostic: no pi runtime types.
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+/**
+ * Record one cache-poison advisory event. All values are fully parameterized
+ * (PREVENT-002). Non-fatal: any write error is logged to stderr and silently
+ * swallowed so advisory logging never blocks the agent loop.
+ */
+export function recordCachePoisonEvent(stateDir = getStateDir(), event) {
+    try {
+        const db = openStore(stateDir);
+        db.prepare(`INSERT INTO cache_poison_events
+			   (ts, turn_index, session_id, layer, detail, severity)
+			 VALUES (?, ?, ?, ?, ?, ?)`).run(event.ts, event.turnIndex, event.sessionId, event.layer, event.detail, event.severity);
+    }
+    catch (err) {
+        // Non-fatal: advisory logging must never block the agent loop.
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[context-health] recordCachePoisonEvent error: ${msg}\n`);
+    }
+}
+/**
+ * Read cache poison events since `sinceTs`, ordered descending by ts (most
+ * recent first), capped at 100 rows. Returns an empty array on any error
+ * (non-fatal). SQL is fully parameterized (PREVENT-002).
+ */
+export function readCachePoisonEvents(stateDir = getStateDir(), sinceTs) {
+    try {
+        const db = openStore(stateDir);
+        const rows = db
+            .prepare(`SELECT id, ts, turn_index, session_id, layer, detail, severity
+				 FROM cache_poison_events
+				 WHERE ts >= ?
+				 ORDER BY ts DESC
+				 LIMIT 100`)
+            .all(sinceTs);
+        return rows.map((r) => ({
+            id: r.id,
+            ts: r.ts,
+            turnIndex: r.turn_index,
+            sessionId: r.session_id,
+            layer: r.layer,
+            detail: r.detail,
+            severity: r.severity,
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/store/sqlite/context-health.js

@@ -14,6 +14,10 @@
  */
 import { getStateDir } from "../../store.js";
 import { openStore } from "./utils.js";
+/** A single cache_poison_events row (as stored + returned). */
+// Sprint H split: cache_poison_events accessors live in context-health-cache-poison.ts.
+// Re-exported here so existing importers (barrel `export *`) are unaffected.
+export { recordCachePoisonEvent, readCachePoisonEvents, } from "./context-health-cache-poison.js";
 // ─── context_health accessors ────────────────────────────────────────────────
 /**
  * Record one context health sample. All values are fully parameterized
@@ -100,7 +104,7 @@ export function readLatestContextHealth(stateDir = getStateDir()) {
     try {
         const db = openStore(stateDir);
         const row = db
-            .prepare(`SELECT composite, drift_score, output_quality, error_score,
+            .prepare(`SELECT composite, drift_score, output_quality, error_score, store_error_score,
 				        cache_health, cache_poison, ts, model_id
 				 FROM context_health
 				 ORDER BY ts DESC
@@ -113,6 +117,7 @@ export function readLatestContextHealth(stateDir = getStateDir()) {
             driftScore: row.drift_score,
             outputQuality: row.output_quality,
             errorScore: row.error_score,
+            storeErrorScore: row.store_error_score ?? 1,
             cacheHealth: row.cache_health,
             cachePoison: row.cache_poison,
             ts: row.ts,
@@ -144,50 +149,3 @@ export function readContextHealthTrend(stateDir = getStateDir(), limit) {
         return [];
     }
 }
-// ─── cache_poison_events accessors ───────────────────────────────────────────
-/**
- * Record one cache poison advisory event. Fully parameterized (PREVENT-002).
- * Non-fatal: write errors are logged to stderr and silently swallowed.
- */
-export function recordCachePoisonEvent(stateDir = getStateDir(), event) {
-    try {
-        const db = openStore(stateDir);
-        db.prepare(`INSERT INTO cache_poison_events
-			   (ts, turn_index, session_id, layer, detail, severity)
-			 VALUES (?, ?, ?, ?, ?, ?)`).run(event.ts, event.turnIndex, event.sessionId, event.layer, event.detail, event.severity);
-    }
-    catch (err) {
-        // Non-fatal: advisory logging must never block the agent loop.
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[context-health] recordCachePoisonEvent error: ${msg}\n`);
-    }
-}
-/**
- * Read cache poison events since `sinceTs`, ordered descending by ts (most
- * recent first), capped at 100 rows. Returns an empty array on any error
- * (non-fatal). SQL is fully parameterized (PREVENT-002).
- */
-export function readCachePoisonEvents(stateDir = getStateDir(), sinceTs) {
-    try {
-        const db = openStore(stateDir);
-        const rows = db
-            .prepare(`SELECT id, ts, turn_index, session_id, layer, detail, severity
-				 FROM cache_poison_events
-				 WHERE ts >= ?
-				 ORDER BY ts DESC
-				 LIMIT 100`)
-            .all(sinceTs);
-        return rows.map((r) => ({
-            id: r.id,
-            ts: r.ts,
-            turnIndex: r.turn_index,
-            sessionId: r.session_id,
-            layer: r.layer,
-            detail: r.detail,
-            severity: r.severity,
-        }));
-    }
-    catch {
-        return [];
-    }
-}

package/dist/src/store/sqlite/embedding-cache.js

@@ -66,6 +66,10 @@ export function getOrComputeEmbedding(db, content) {
         // Logger not imported here to keep this leaf self-contained; stderr is
         // acceptable for an error path that signals a bug, not a user‑facing log.
         process.stderr.write(`[embedding-cache] getOrComputeEmbedding error: ${msg}\n`);
+        // Sprint H (Option A): this leaf src/ cache-persist path has no runtime
+        // handle, so the embedder cache-write failure is recorded by callers that
+        // own a runtime, not here.
+        // guardrails-allow INTERNAL-ERR: src/ leaf cache writer, no runtime handle — callers record embedder cache failures
         return [];
     }
 }

package/dist/src/store/sqlite/schema.js

@@ -51,6 +51,10 @@ export function initSchema(db) {
     // 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");
+    // Sprint H (B2): store_error_score column on context_health — the 6th health
+    // axis. Additive; DBs created before this version have NULL → the health
+    // handler degrades to 1.0 (no data → healthy), matching the empty-ring rule.
+    ensureColumn(db, "context_health", "store_error_score", "REAL");
     // 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/dist/src/store/turns/memory-store/admin.js

@@ -0,0 +1,119 @@
+import { allocId, normalizeSessionId, resetIdCounter, } from "./ctx.js";
+export function prune(ctx, policy) {
+    const cutoff = Date.now() - policy.maxTurnAgeMs;
+    let turnsRemoved = 0;
+    let recallRemoved = 0;
+    for (const [convId, turnIds] of ctx.convIndex.entries()) {
+        const total = turnIds.length;
+        const canDelete = Math.max(0, total - policy.keepMinPerConversation);
+        if (canDelete === 0)
+            continue;
+        // Find old turns to delete
+        const oldIds = turnIds
+            .filter((id) => {
+            const row = ctx.turns.get(id);
+            return row && row.entry.endedAt < cutoff;
+        })
+            .slice(0, canDelete);
+        for (const id of oldIds) {
+            // Remove recall for this turn, in place (preserve ctx.recall reference)
+            const before = ctx.recall.length;
+            let w = 0;
+            for (let i = 0; i < ctx.recall.length; i++) {
+                if (ctx.recall[i].turnId !== id)
+                    ctx.recall[w++] = ctx.recall[i];
+            }
+            ctx.recall.length = w;
+            recallRemoved += before - ctx.recall.length;
+            ctx.turns.delete(id);
+            turnsRemoved++;
+        }
+        // Update convIndex
+        ctx.convIndex.set(convId, turnIds.filter((id) => ctx.turns.has(id)));
+    }
+    const branchesPreserved = ctx.forks.length;
+    return {
+        turnsRemoved,
+        recallRemoved,
+        branchesPreserved,
+        freedBytes: 0, // in-memory — no file size to measure
+    };
+}
+export function vacuum(_ctx) {
+    // No-op for in-memory store
+}
+export function checkpoint(ctx) {
+    // Emit turns in a stable order (by internal ID / insertion order)
+    const sorted = [...ctx.turns.values()].sort((a, b) => a.id - b.id);
+    const turns = sorted.map((r) => r.entry);
+    // Build mapping: internal ID → 1-based position
+    const idToPos = new Map();
+    for (let i = 0; i < sorted.length; i++) {
+        idToPos.set(sorted[i].id, i + 1);
+    }
+    // Replace recall's turnId with the stable 1-based position
+    const recall = ctx.recall.map((r) => ({
+        turnId: String(idToPos.get(r.turnId) ?? r.turnId),
+        checkpointId: r.entry.checkpointId,
+        score: r.entry.score,
+        source: r.entry.source,
+        raptorLevel: r.entry.raptorLevel,
+    }));
+    return {
+        version: 1,
+        exportedAt: Date.now(),
+        turns,
+        recall,
+        forks: [...ctx.forks],
+    };
+}
+export function restore(ctx, from) {
+    clear(ctx);
+    // Map: 1-based position → new internal ID
+    const posToNewId = new Map();
+    for (let i = 0; i < from.turns.length; i++) {
+        const t = from.turns[i];
+        const newId = allocId();
+        const sid = normalizeSessionId(t.sessionId);
+        const normalized = { ...t, sessionId: sid };
+        ctx.turns.set(newId, { id: newId, entry: normalized });
+        // Update indices
+        const convIds = ctx.convIndex.get(t.conversationId) ?? [];
+        convIds.push(newId);
+        ctx.convIndex.set(t.conversationId, convIds);
+        ctx.sessionConv.set(sid, t.conversationId);
+        posToNewId.set(i + 1, newId);
+    }
+    // Re-attach recall with position-based TurnId → new internal ID mapping
+    for (const r of from.recall) {
+        const targetInternalId = posToNewId.get(Number(r.turnId));
+        if (targetInternalId !== undefined) {
+            ctx.recall.push({
+                turnId: targetInternalId,
+                entry: r,
+            });
+        }
+    }
+    // In-place replace forks (preserve ctx.forks reference)
+    ctx.forks.length = 0;
+    ctx.forks.push(...from.forks);
+}
+export function clear(ctx) {
+    ctx.turns.clear();
+    ctx.recall.length = 0;
+    ctx.forks.length = 0;
+    ctx.convIndex.clear();
+    ctx.sessionConv.clear();
+    resetIdCounter();
+}
+export function stampTurnsEpoch(ctx, sessionId, epochId) {
+    const sid = normalizeSessionId(sessionId);
+    let stamped = 0;
+    for (const row of ctx.turns.values()) {
+        if (row.epochId === undefined && row.entry.sessionId === sid) {
+            row.epochId = epochId;
+            stamped++;
+        }
+    }
+    return stamped;
+}

package/dist/src/store/turns/memory-store/ctx.js

@@ -0,0 +1,28 @@
+/**
+ * ctx.ts — internal context interface for InMemoryTurnStore method bodies
+ * (extracted from memory-store.ts). Each free function in this directory
+ * operates on a MemoryTurnStoreCtx so the shell class can delegate without
+ * exposing its private fields.
+ *
+ * Mirrors sqlite-store/ctx.ts. The Map/array references are stable for the
+ * life of the store: arrays (recall, forks) are mutated IN PLACE
+ * (push/splice/length=0), never reassigned, so a ctx captured at any point
+ * sees the current contents. The id counter is module-scoped here so both the
+ * shell (writers) and admin.ts share one allocator.
+ */
+import { randomBytes } from "node:crypto";
+// Auto-increment counter — shared by writers (appendTurn/forkConversation) and
+// admin (restore). Module-scoped so a single counter spans the store's life.
+let nextId = 1;
+export function allocId() {
+    return nextId++;
+}
+export function resetIdCounter() {
+    nextId = 1;
+}
+export function newConversationId() {
+    return `conv_${randomBytes(8).toString("hex")}`;
+}
+export function normalizeSessionId(sid) {
+    return sid.replace(/-.*$/, "");
+}

package/dist/src/store/turns/memory-store/read.js

@@ -0,0 +1,110 @@
+import { normalizeSessionId } from "./ctx.js";
+export function query(ctx, filter) {
+    let results = [...ctx.turns.values()].map((r) => r.entry);
+    if (filter.conversationId !== undefined) {
+        results = results.filter((t) => t.conversationId === filter.conversationId);
+    }
+    if (filter.sessionId !== undefined) {
+        results = results.filter((t) => normalizeSessionId(t.sessionId) ===
+            normalizeSessionId(filter.sessionId));
+    }
+    if (filter.sinceMs !== undefined) {
+        results = results.filter((t) => t.endedAt >= filter.sinceMs);
+    }
+    if (filter.untilMs !== undefined) {
+        results = results.filter((t) => t.endedAt <= filter.untilMs);
+    }
+    if (filter.pressureBand !== undefined) {
+        results = results.filter((t) => t.pressureBand === filter.pressureBand);
+    }
+    results.sort((a, b) => a.endedAt - b.endedAt);
+    const offset = filter.offset ?? 0;
+    const limit = filter.limit ?? 1000;
+    return results.slice(offset, offset + limit);
+}
+export function getTurn(ctx, turnId) {
+    const row = ctx.turns.get(Number(turnId));
+    return row ? { ...row.entry, epochId: row.epochId } : undefined;
+}
+export function getTurnByIndex(ctx, conversationId, turnIndex) {
+    const ids = ctx.convIndex.get(conversationId) ?? [];
+    for (const id of ids) {
+        const row = ctx.turns.get(id);
+        if (row && row.entry.turnIndex === turnIndex) {
+            return { ...row.entry, epochId: row.epochId };
+        }
+    }
+    return undefined;
+}
+export function listRecall(ctx, turnId) {
+    return ctx.recall
+        .filter((r) => r.turnId === Number(turnId))
+        .map((r) => r.entry)
+        .sort((a, b) => b.score - a.score);
+}
+export function listRecallByIndex(ctx, conversationId, turnIndex) {
+    const turn = getTurnByIndex(ctx, conversationId, turnIndex);
+    if (!turn)
+        return [];
+    // Resolve the numeric row id for this turn via the convIndex.
+    const ids = ctx.convIndex.get(conversationId) ?? [];
+    for (const id of ids) {
+        const row = ctx.turns.get(id);
+        if (row && row.entry.turnIndex === turnIndex) {
+            return listRecall(ctx, String(id));
+        }
+    }
+    return [];
+}
+export function listForks(ctx, conversationId) {
+    return ctx.forks
+        .filter((f) => f.parentConversationId === conversationId)
+        .sort((a, b) => a.createdAt - b.createdAt);
+}
+export function countTurns(ctx, conversationId) {
+    const ids = ctx.convIndex.get(conversationId);
+    return ids?.length ?? 0;
+}
+export function conversationStats(ctx, conversationId) {
+    const ids = ctx.convIndex.get(conversationId) ?? [];
+    const entries = ids
+        .map((id) => ctx.turns.get(id)?.entry)
+        .filter((e) => e !== undefined);
+    if (entries.length === 0) {
+        return {
+            turnCount: 0,
+            firstTurnAt: 0,
+            lastTurnAt: 0,
+            avgCtxPercent: 0,
+            pressureBands: {},
+        };
+    }
+    let ctxSum = 0;
+    let ctxCount = 0;
+    const bands = {};
+    for (const e of entries) {
+        if (e.ctxPercent !== undefined) {
+            ctxSum += e.ctxPercent;
+            ctxCount++;
+        }
+        if (e.pressureBand)
+            bands[e.pressureBand] = (bands[e.pressureBand] ?? 0) + 1;
+    }
+    return {
+        turnCount: entries.length,
+        firstTurnAt: entries[0].endedAt,
+        lastTurnAt: entries[entries.length - 1].endedAt,
+        avgCtxPercent: ctxCount > 0 ? ctxSum / ctxCount : 0,
+        pressureBands: bands,
+    };
+}
+export function nextTurnIndexFor(ctx, conversationId) {
+    let max = -1;
+    for (const [, row] of ctx.turns) {
+        if (row.entry.conversationId === conversationId &&
+            row.entry.turnIndex > max) {
+            max = row.entry.turnIndex;
+        }
+    }
+    return max + 1;
+}