pi-mega-compact 0.21.3 → 0.21.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -51,7 +51,7 @@
     "postbuild": "node scripts/vector-cortex-publish-acceptance.mjs",
     "build:dashboard": "cd extensions/dashboard-client && npx vite build",
     "test:dashboard-smoke": "node scripts/dashboard-tab-smoke.mjs",
-    "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs && node scripts/stub-scan.mjs --fail-on-unregistered && node scripts/mock-scan.mjs --fail-on-unregistered",
+    "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs && node scripts/stub-scan.mjs --fail-on-unregistered && node scripts/mock-scan.mjs --fail-on-unregistered && node scripts/internal-err-scan.mjs --fail-on-unregistered",
     "test": "npm run build && node scripts/run-tests.mjs",
     "guardrails": "python3 scripts/regression_check.py --all || node scripts/guardrails-scan.mjs || node scripts/semantic-scan.mjs",
     "precommit": "bash .claude/hooks/pre-commit.sh",

package/src/bridge/factory.ts

@@ -179,6 +179,10 @@ export function createMegaBridge(opts: BridgeOptions): MegaBridge {
         if (e instanceof ForkError) {
           return { error: e.code };
         }
+        // The bridge is pi-agnostic (no runtime handle) — the host-side adapter
+        // (ithacus) owns the internal-error ring for fork failures, so this
+        // re-thrown non-ForkError is recorded there, not here.
+        // guardrails-allow INTERNAL-ERR: bridge is pi-agnostic; no runtime handle — host adapter records fork failures
         throw e;
       }
     },
@@ -205,16 +209,26 @@ export function createMegaBridge(opts: BridgeOptions): MegaBridge {
     },
 
     recordTurn(input: BridgeRecordTurnInput): void {
+      // S49R: child turns get the conversation-monotonic index (MAX+1) so a
+      // re-dispatched child (same conversation, restarted session counter) never
+      // collides with UNIQUE(conversation_id, turn_index). Carry the child's
+      // session counter as sessionTurnIndex for the raw_transcript join.
+      const turnIndex = getTurnStore().asReader().nextTurnIndexFor(input.conversationId);
       const turn: TurnEntry = {
         conversationId: input.conversationId,
         sessionId: input.sessionId,
-        turnIndex: input.turnIndex,
+        turnIndex,
+        sessionTurnIndex: input.turnIndex,
         role: (input.role as TurnEntry["role"]) ?? "assistant",
         endedAt: input.endedAt ?? Date.now(),
         ctxTokens: input.ctxTokens,
         ctxPercent: input.ctxPercent,
         model: input.model,
       };
+      // The bridge is pi-agnostic (no runtime handle); the host-side adapter
+      // (ithacus) owns the internal-error ring for appendTurn failures. The
+      // recordTurn child-path twin of Finding 2 is recorded there, not here.
+      // guardrails-allow INTERNAL-ERR: bridge is pi-agnostic; no runtime handle — host adapter records appendTurn failures
       getTurnStore().asWriter().appendTurn(turn);
     },
 

package/src/bridge/types.ts

@@ -117,6 +117,8 @@ export interface BridgeRecordTurnInput {
   conversationId: string;
   sessionId: string;
   turnIndex: number;
+  /** S49R: pi's per-session counter, carried for the raw_transcript join. */
+  sessionTurnIndex?: number;
   role?: string;
   endedAt?: number;
   ctxTokens?: 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;
+}

package/src/store/turns/memory-store/ctx.ts

@@ -0,0 +1,62 @@
+/**
+ * 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";
+import type {
+	ConversationFork,
+	ConversationId,
+	SessionId,
+	TurnEntry,
+	TurnRecallEntry,
+} from "../types.js";
+
+/** Internal row with numeric id. */
+export interface TurnRow {
+	id: number;
+	entry: TurnEntry;
+	epochId?: string;
+}
+
+/** Internal recall row keyed by numeric turn id. */
+export interface RecallRow {
+	turnId: number;
+	entry: TurnRecallEntry;
+}
+
+/** The mutable in-memory state free functions operate on. */
+export interface MemoryTurnStoreCtx {
+	turns: Map<number, TurnRow>;
+	recall: RecallRow[];
+	forks: ConversationFork[];
+	convIndex: Map<ConversationId, number[]>;
+	sessionConv: Map<SessionId, ConversationId>;
+}
+
+// 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(): number {
+	return nextId++;
+}
+
+export function resetIdCounter(): void {
+	nextId = 1;
+}
+
+export function newConversationId(): ConversationId {
+	return `conv_${randomBytes(8).toString("hex")}`;
+}
+
+export function normalizeSessionId(sid: SessionId): SessionId {
+	return sid.replace(/-.*$/, "");
+}