pi-mega-compact 0.21.3 → 0.21.5

package/src/compact.ts

@@ -9,6 +9,18 @@
 
 import type { EngineMessage } from "./types.js";
 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"];
@@ -19,10 +31,6 @@ 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: string, max: number): string {
-	return s.length <= max ? s : `${s.slice(0, max)}…`;
-}
-
 function firstText(m: EngineMessage): string | undefined {
 	// PREVENT crash: pi can hand us a message with text: undefined (pure
 	// tool-call/tool-result). Guard the trim so the legacy summarizeMessages
@@ -113,45 +121,6 @@ export function collectRecentUserRequests(
 	return reqs.slice(-limit);
 }
 
-/** Summarize a block to a one-line description. */
-function summarizeBlock(m: EngineMessage): string {
-	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: string, tag: string): string {
-	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: string, tag: string): string | undefined {
-	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: string): string {
-	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.
@@ -200,70 +169,6 @@ export function summarizeMessages(messages: EngineMessage[]): string {
 	return lines.join("\n");
 }
 
-/** Extract the prior "highlights" + "timeline" sections from an existing summary. */
-function extractSummaryHighlights(summary: string): string[] {
-	const lines = formatCompactSummary(summary).split("\n");
-	const out: string[] = [];
-	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: string): string[] {
-	const lines = formatCompactSummary(summary).split("\n");
-	const out: string[] = [];
-	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: string | undefined,
-	newSummary: string,
-): string {
-	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: EngineMessage[],
@@ -275,10 +180,15 @@ export function shouldCompact(
 	return estimateSessionTokens(compactable) >= maxEstimatedTokens;
 }
 
-/** Local reimplementation of memory-mcp auto_compact_check. */
+/** 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: number,
-	threshold = 50000,
+	threshold: number,
 ): {
 	shouldCompact: boolean;
 	currentTokens: number;

package/src/contextHealth.ts

@@ -23,23 +23,39 @@ export interface ContextHealthSubScores {
 	drift: number;
 	/** Output quality score (0–1, higher = healthier output). */
 	outputQuality: number;
-	/** Error-rate score (0–1, higher = fewer errors). */
+	/** Error-rate score (0–1, higher = fewer API-retry errors). */
 	errorRate: number;
 	/** Cache health score (0–1, higher = healthier cache). */
 	cacheHealth: number;
 	/** Cache poison score (0–1, higher = less poison). */
 	cachePoison: number;
+	/**
+	 * Store-error rate score (0–1, higher = fewer internal store-write
+	 * failures). Sprint H (B2): a SEPARATE 6th axis from `errorRate` — `errorRate`
+	 * reflects API-retry errors only; `storeErrorRate` reflects internal
+	 * store/service-write failures (turn rows, recall, dbMirror, ledger, epoch,
+	 * stats, memory consolidate, compact persist, vector index, embedder,
+	 * migration). The two are equally loud at 0.09 each.
+	 */
+	storeErrorRate: number;
 }
 
 /**
- * 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.
  */
@@ -49,7 +65,8 @@ export function computeHealthScore(sub: ContextHealthSubScores): number {
 		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));
 }
 
@@ -66,6 +83,8 @@ export interface ContextHealthRow {
 	cacheHealth: number;
 	cachePoison: number;
 	composite: number;
+	/** Sprint H (B2): 6th axis — internal store-write failure score (0–1). */
+	storeErrorScore?: number;
 	modelId?: string;
 	repetitionRatio?: number;
 	coherenceScore?: number;
@@ -89,9 +108,9 @@ export function recordContextHealth(
 		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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 		).run(
 			row.ts,
 			row.sessionId,
@@ -102,6 +121,7 @@ export function recordContextHealth(
 			row.cacheHealth,
 			row.cachePoison,
 			row.composite,
+			row.storeErrorScore ?? null,
 			row.modelId ?? null,
 			row.repetitionRatio ?? null,
 			row.coherenceScore ?? null,

package/src/metrics/turns.ts

@@ -113,7 +113,12 @@ export function turnMetrics(
 
 	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/src/store/sqlite/context-health-cache-poison.ts

@@ -0,0 +1,97 @@
+/**
+ * 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";
+
+/** A single cache_poison_events row (as stored + returned). */
+export interface CachePoisonEvent {
+	id: number;
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	layer: number | null;
+	detail: string | null;
+	severity: string | null;
+}
+
+/**
+ * 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: string = getStateDir(),
+	event: {
+		ts: number;
+		turnIndex: number;
+		sessionId: string;
+		layer: number;
+		detail: string;
+		severity: "warn" | "alert";
+	},
+): void {
+	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: string = getStateDir(),
+	sinceTs: number,
+): CachePoisonEvent[] {
+	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) as Array<{
+			id: number;
+			ts: number;
+			turn_index: number;
+			session_id: string;
+			layer: number | null;
+			detail: string | null;
+			severity: string | null;
+		}>;
+
+		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/src/store/sqlite/context-health.ts

@@ -41,6 +41,8 @@ export interface LatestContextHealth {
 	driftScore: number;
 	outputQuality: number;
 	errorScore: number;
+	/** Sprint H (B2): internal store-write failure score (NULL→1 on pre-upgrade DBs). */
+	storeErrorScore: number;
 	cacheHealth: number;
 	cachePoison: number;
 	ts: number;
@@ -48,15 +50,13 @@ export interface LatestContextHealth {
 }
 
 /** A single cache_poison_events row (as stored + returned). */
-export interface CachePoisonEvent {
-	id: number;
-	ts: number;
-	turnIndex: number;
-	sessionId: string;
-	layer: number | null;
-	detail: string | null;
-	severity: string | null;
-}
+// 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,
+	type CachePoisonEvent,
+} from "./context-health-cache-poison.js";
 
 // ─── context_health accessors ────────────────────────────────────────────────
 
@@ -205,7 +205,7 @@ export function readLatestContextHealth(
 		const db = openStore(stateDir);
 		const row = db
 			.prepare(
-				`SELECT composite, drift_score, output_quality, error_score,
+				`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
@@ -217,6 +217,7 @@ export function readLatestContextHealth(
 					drift_score: number;
 					output_quality: number;
 					error_score: number;
+					store_error_score: number | null;
 					cache_health: number;
 					cache_poison: number;
 					ts: number;
@@ -230,6 +231,7 @@ export function readLatestContextHealth(
 			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,
@@ -266,77 +268,3 @@ export function readContextHealthTrend(
 		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: string = getStateDir(),
-	event: {
-		ts: number;
-		turnIndex: number;
-		sessionId: string;
-		layer: number;
-		detail: string;
-		severity: "warn" | "alert";
-	},
-): void {
-	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: string = getStateDir(),
-	sinceTs: number,
-): CachePoisonEvent[] {
-	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) as Array<{
-			id: number;
-			ts: number;
-			turn_index: number;
-			session_id: string;
-			layer: number | null;
-			detail: string | null;
-			severity: string | null;
-		}>;
-
-		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/src/store/sqlite/embedding-cache.ts

@@ -76,6 +76,10 @@ export function getOrComputeEmbedding(db: DatabaseSync, content: string): number
     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/src/store/sqlite/schema.ts

@@ -71,6 +71,10 @@ export function initSchema(db: DatabaseSync): void {
 	// 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/src/store/turns/memory-store/admin.ts

@@ -0,0 +1,171 @@
+/**
+ * admin.ts — TurnAdmin method bodies for InMemoryTurnStore (extracted from
+ * memory-store.ts). Free functions operating on a MemoryTurnStoreCtx; the
+ * shell class delegates here. Mirrors sqlite-store/admin.ts.
+ *
+ * Arrays (recall, forks) are mutated IN PLACE (push/length=0), never
+ * reassigned, so the ctx references captured by the shell stay valid. This
+ * differs from the original class methods, which reassigned `this.recall` /
+ * `this.forks` — the rewrite is behavior-identical but in-place so the
+ * extracted ctx model works.
+ */
+import type {
+	PruneReport,
+	RetentionPolicy,
+	SessionId,
+	StoreSnapshot,
+} from "../types.js";
+import {
+	allocId,
+	normalizeSessionId,
+	resetIdCounter,
+	type MemoryTurnStoreCtx,
+} from "./ctx.js";
+
+export function prune(
+	ctx: MemoryTurnStoreCtx,
+	policy: RetentionPolicy,
+): PruneReport {
+	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: MemoryTurnStoreCtx): void {
+	// No-op for in-memory store
+}
+
+export function checkpoint(ctx: MemoryTurnStoreCtx): StoreSnapshot {
+	// 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<number, number>();
+	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: MemoryTurnStoreCtx, from: StoreSnapshot): void {
+	clear(ctx);
+
+	// Map: 1-based position → new internal ID
+	const posToNewId = new Map<number, number>();
+
+	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: MemoryTurnStoreCtx): void {
+	ctx.turns.clear();
+	ctx.recall.length = 0;
+	ctx.forks.length = 0;
+	ctx.convIndex.clear();
+	ctx.sessionConv.clear();
+	resetIdCounter();
+}
+
+export function stampTurnsEpoch(
+	ctx: MemoryTurnStoreCtx,
+	sessionId: SessionId,
+	epochId: string,
+): number {
+	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;
+}