pi-mega-compact 0.11.4 → 0.11.6

package/src/store/sqlite/perf-samples.ts

@@ -15,6 +15,7 @@
  */
 import { getStateDir } from "../../store.js";
 import { openStore } from "./utils.js";
+import type { PrefixBreak } from "../../prefix-break.js";
 
 /** Sample kinds recorded into perf_samples. */
 export type PerfKind =
@@ -22,12 +23,14 @@ export type PerfKind =
 	| "provider_latency_ms"
 	| "tps"
 	| "cache_hit_pct"
+	| "prefix_break"
 	| "rss_mb"
 	| "heap_mb"
 	| "cpu_user_ms"
 	| "cpu_sys_ms"
 	| "db_recompute_ms"
-	| "disk_write_ms";
+	| "disk_write_ms"
+	| "cache_health";
 
 /** Allow-list of valid perf sample kinds (mirrors the table's domain). */
 export const PERF_KINDS: readonly PerfKind[] = [
@@ -35,12 +38,14 @@ export const PERF_KINDS: readonly PerfKind[] = [
 	"provider_latency_ms",
 	"tps",
 	"cache_hit_pct",
+	"prefix_break",
 	"rss_mb",
 	"heap_mb",
 	"cpu_user_ms",
 	"cpu_sys_ms",
 	"db_recompute_ms",
 	"disk_write_ms",
+	"cache_health",
 ];
 
 /** A single perf sample row (as stored + returned). */
@@ -137,30 +142,69 @@ export interface ProviderCacheLifetime {
 	firstSampleAt: string | null;
 	/** ISO timestamp of the most recent sample, or null if no samples. */
 	latestSampleAt: string | null;
+	/**
+	 * Per-model breakdown of aggregates (F4). Samples without a model tag are
+	 * omitted from this array (they remain in the flat totals above).
+	 */
+	byModel: ProviderCacheModelAgg[];
+}
+
+/** Per-model provider cache aggregate (F4). */
+export interface ProviderCacheModelAgg {
+	/** Model label (modelName || modelId from meta, or null for untagged). */
+	model: string;
+	/** Average hit rate for this model (0-100). */
+	hitPct: number;
+	/** Sum of cache-read tokens for this model. */
+	totalCacheRead: number;
+	/** Sum of cache-write tokens for this model. */
+	totalCacheWrite: number;
+	/** Number of samples for this model. */
+	sampleCount: number;
 }
 
 /**
- * Read lifetime provider prompt cache aggregates from `perf_samples`.
- *
- * Aggregates `cache_creation_input_tokens` / `cache_read_input_tokens` from
- * the `meta` JSON column of `cache_hit_pct` samples (`json_extract`,
- * available in node:sqlite ≥22.13 / SQLite ≥3.38). Returns a zeroed
- * `ProviderCacheLifetime` when no samples exist (never undefined).
+ * Extract a model label from parsed meta (modelName or modelId), or null.
  */
-export function readProviderCacheLifetime(
-	stateDir: string = getStateDir(),
+function extractModelLabel(
+	meta: Record<string, unknown>,
+): string | null {
+	if (typeof meta.modelName === "string" && meta.modelName.length > 0)
+		return meta.modelName;
+	if (typeof meta.modelId === "string" && meta.modelId.length > 0)
+		return meta.modelId;
+	return null;
+}
+
+/**
+ * Build sorted byModel array from the model aggregation map.
+ */
+function byModelFromMap(
+	map: Map<string, { sumCr: number; sumCw: number; sumInp: number; sumHitPct: number; hitCount: number; samples: number }>,
+): ProviderCacheModelAgg[] {
+	const out: ProviderCacheModelAgg[] = [];
+	for (const [model, m] of map) {
+		out.push({
+			model,
+			hitPct: m.hitCount > 0 ? m.sumHitPct / m.hitCount : 0,
+			totalCacheRead: m.sumCr,
+			totalCacheWrite: m.sumCw,
+			sampleCount: m.samples,
+		});
+	}
+	out.sort((a, b) => b.sampleCount - a.sampleCount);
+	return out;
+}
+
+/**
+ * Aggregate `cache_hit_pct` rows (ts + parsed meta) into a
+ * `ProviderCacheLifetime`. Shared by the lifetime and window readers so both
+ * use the identical aggregation formula. `meta` is parsed defensively
+ * (PREVENT-001 null-safe). Rows must be ascending by ts.
+ */
+function aggregateCacheRows(
+	rows: Array<{ ts: number; meta: string | null }>,
 ): ProviderCacheLifetime {
-	const db = openStore(stateDir);
-	const rows = db
-		.prepare(
-			`SELECT ts, meta FROM perf_samples
-       WHERE kind = ?
-       ORDER BY ts ASC`,
-		)
-		.all("cache_hit_pct") as Array<{
-		ts: number;
-		meta: string | null;
-	}>;
 	if (rows.length === 0) {
 		return {
 			sampleCount: 0,
@@ -170,6 +214,7 @@ export function readProviderCacheLifetime(
 			totalInput: 0,
 			firstSampleAt: null,
 			latestSampleAt: null,
+			byModel: [],
 		};
 	}
 	let totalCacheRead = 0;
@@ -177,6 +222,17 @@ export function readProviderCacheLifetime(
 	let totalInput = 0;
 	let sumHitPct = 0;
 	let hitPctCount = 0;
+	const modelMap = new Map<
+		string,
+		{
+			sumCr: number;
+			sumCw: number;
+			sumInp: number;
+			sumHitPct: number;
+			hitCount: number;
+			samples: number;
+		}
+	>();
 	for (const r of rows) {
 		if (r.meta != null) {
 			let meta: Record<string, unknown> | null = null;
@@ -208,6 +264,31 @@ export function readProviderCacheLifetime(
 					sumHitPct += (cr / denom) * 100;
 					hitPctCount++;
 				}
+				// Per-model grouping (F4)
+				const modelLabel = extractModelLabel(meta);
+				if (modelLabel != null) {
+					let m = modelMap.get(modelLabel);
+					if (!m) {
+						m = {
+							sumCr: 0,
+							sumCw: 0,
+							sumInp: 0,
+							sumHitPct: 0,
+							hitCount: 0,
+							samples: 0,
+						};
+						modelMap.set(modelLabel, m);
+					}
+					m.sumCr += cr;
+					m.sumCw += cw;
+					m.sumInp += inp;
+					m.samples++;
+					if (denom > 0) {
+						m.sumHitPct += (cr / denom) * 100;
+						m.hitCount++;
+					}
+				}
+				// Untagged samples are omitted from byModel
 			}
 		}
 	}
@@ -219,9 +300,62 @@ export function readProviderCacheLifetime(
 		totalInput,
 		firstSampleAt: new Date(rows[0].ts).toISOString(),
 		latestSampleAt: new Date(rows[rows.length - 1].ts).toISOString(),
+		byModel: byModelFromMap(modelMap),
 	};
 }
 
+/**
+ * Read lifetime provider prompt cache aggregates from `perf_samples`.
+ *
+ * Aggregates `cache_creation_input_tokens` / `cache_read_input_tokens` from
+ * the `meta` JSON column of `cache_hit_pct` samples (`json_extract`,
+ * available in node:sqlite >=22.13 / SQLite >=3.38). Returns a zeroed
+ * `ProviderCacheLifetime` when no samples exist (never undefined).
+ */
+export function readProviderCacheLifetime(
+	stateDir: string = getStateDir(),
+): ProviderCacheLifetime {
+	const db = openStore(stateDir);
+	const rows = db
+		.prepare(
+			`SELECT ts, meta FROM perf_samples
+	       WHERE kind = ?
+	       ORDER BY ts ASC`,
+		)
+		.all("cache_hit_pct") as Array<{
+		ts: number;
+		meta: string | null;
+	}>;
+	return aggregateCacheRows(rows);
+}
+
+/**
+ * Read provider prompt cache aggregates over a trailing window of `minutes`
+ * (samples with ts >= now - minutes*60_000). Same aggregate shape as
+ * `readProviderCacheLifetime`; the existing lifetime reader is untouched.
+ * Returns a zeroed `ProviderCacheLifetime` when no samples fall in the window.
+ */
+export function readProviderCacheWindow(
+	stateDir: string = getStateDir(),
+	minutes: number,
+): ProviderCacheLifetime {
+	const db = openStore(stateDir);
+	const sinceTs = Date.now() - minutes * 60_000;
+	const rows = db
+		.prepare(
+			`SELECT ts, meta FROM perf_samples
+	       WHERE kind = ? AND ts >= ?
+	       ORDER BY ts ASC`,
+		)
+		.all("cache_hit_pct", sinceTs) as Array<{
+		ts: number;
+		meta: string | null;
+	}>;
+	return aggregateCacheRows(rows);
+}
+
+// ... keep every function below unchanged ...
+
 /**
  * Read the most recent `cache_hit_pct` value from `perf_samples`.
  *
@@ -236,9 +370,9 @@ export function readLatestCacheHitPct(
 	const row = db
 		.prepare(
 			`SELECT value FROM perf_samples
-       WHERE kind = ?
-       ORDER BY ts DESC, id DESC
-       LIMIT 1`,
+	       WHERE kind = ?
+	       ORDER BY ts DESC, id DESC
+	       LIMIT 1`,
 		)
 		.get("cache_hit_pct") as { value: number } | undefined;
 	if (!row || typeof row.value !== "number" || !Number.isFinite(row.value))
@@ -259,3 +393,64 @@ export function readProviderCacheForRepo(
 ): ProviderCacheLifetime {
 	return readProviderCacheLifetime(stateDir);
 }
+
+// ─── Prefix-break reader (S53A) ───────────────────────────────────────────────
+
+/** Re-exported for consumers that import via perf-samples. */
+export type { PrefixBreak } from "../../prefix-break.js";
+
+/**
+ * Read `prefix_break` samples in a time window.
+ *
+ * @param stateDir  State directory for this repo.
+ * @param sinceTs   Lower bound (epoch ms). Pass 0 for no lower bound.
+ * @param untilTs   Upper bound (epoch ms). Pass 0 for no upper bound.
+ *                  Rows with ts > untilTs are excluded.
+ * @returns         Sorted ascending array of PrefixBreak rows.
+ *
+ * SQL is fully parameterized (PREVENT-002). `meta` is parsed defensively
+ * (PREVENT-001 null-safe). When no rows exist the return is an empty array.
+ */
+export function readPrefixBreaks(
+	stateDir: string = getStateDir(),
+	sinceTs: number = 0,
+	untilTs: number = 0,
+): PrefixBreak[] {
+	const db = openStore(stateDir);
+	let rows: Array<{
+		id: number;
+		ts: number;
+		value: number;
+		meta: string | null;
+	}>;
+
+	if (untilTs > 0) {
+		const sql = `SELECT id, ts, value, meta FROM perf_samples
+		   WHERE kind = ? AND ts >= ? AND ts <= ? ORDER BY ts ASC`;
+		rows = db.prepare(sql).all("prefix_break", sinceTs, untilTs) as typeof rows;
+	} else {
+		const sql = `SELECT id, ts, value, meta FROM perf_samples
+		   WHERE kind = ? AND ts >= ? ORDER BY ts ASC`;
+		rows = db.prepare(sql).all("prefix_break", sinceTs) as typeof rows;
+	}
+
+	const out: PrefixBreak[] = [];
+	for (const r of rows) {
+		let meta: unknown = null;
+		if (r.meta != null) {
+			try {
+				meta = JSON.parse(r.meta);
+			} catch {
+				meta = null;
+			}
+		}
+		out.push({
+			id: r.id,
+			ts: r.ts,
+			kind: "prefix_break",
+			value: r.value,
+			meta: meta as PrefixBreak["meta"],
+		});
+	}
+	return out;
+}

package/src/store/sqlite/schema.ts

@@ -4,7 +4,7 @@
 import type { DatabaseSync } from "node:sqlite";
 import { ACHIEVEMENT_DEFS } from "../../game/scoring.js";
 
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 4;
 
 /**
  * Add `column` (with `decl`, e.g. "INTEGER") to `table` if it does not already
@@ -366,6 +366,65 @@ export function initSchema(db: DatabaseSync): void {
     );
     CREATE INDEX IF NOT EXISTS idx_perf_samples_ts ON perf_samples(ts);
     CREATE INDEX IF NOT EXISTS idx_perf_samples_kind_ts ON perf_samples(kind, ts);
+
+    -- A1 PLAN_V2 Phase 2: Message Separation tables (SCHEMA_VERSION 3).
+    -- Stable conversation thread: user + assistant turns ONLY. Tool results are
+    -- stored in tool_results to keep the conversation thread cache-predictable.
+    -- Parameterized queries only (PREVENT-002). CREATE TABLE IF NOT EXISTS is
+    -- a no-op on re-open — no migration needed.
+    CREATE TABLE IF NOT EXISTS conversation_thread (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      conversation_id TEXT NOT NULL,
+      role            TEXT NOT NULL CHECK(role IN ('user','assistant')),
+      content         TEXT NOT NULL,
+      turn_index      INTEGER NOT NULL,
+      timestamp       INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_conv_thread_conv_turn
+      ON conversation_thread(conversation_id, turn_index);
+
+    -- Volatile tool results: appended at END so they never disrupt the
+    -- conversation thread prefix (the prompt-cache-friendly prefix).
+    CREATE TABLE IF NOT EXISTS tool_results (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      conversation_id TEXT NOT NULL,
+      tool_call_id    TEXT NOT NULL,
+      tool_result     TEXT NOT NULL,
+      turn_index      INTEGER NOT NULL,
+      timestamp       INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_tool_results_conv_turn
+      ON tool_results(conversation_id, turn_index);
+
+    -- A2 PLAN_V2 Phase 3: Vector-Aware Cache Striping (SCHEMA_VERSION 4).
+    -- Cache stripe assignments: maps each context chunk to a cache stability
+    -- tier (stripe). Layer 0=permanent, 1=epoch, 2=topic, 3=thread, 4=volatile.
+    -- stability is the composite score (0.0-1.0) from computeStabilityScore.
+    -- Primary key is (chunk_id, epoch_id) so the same chunk can be reassigned
+    -- across epochs without conflict. See cache-stripe.ts for scoring details.
+    -- Parameterized queries only (PREVENT-002). IF NOT EXISTS is a no-op on re-open.
+    CREATE TABLE IF NOT EXISTS cache_stripes (
+      chunk_id      TEXT NOT NULL,
+      stripe        INTEGER NOT NULL,
+      stability     REAL NOT NULL,
+      assigned_at   INTEGER NOT NULL,
+      epoch_id      TEXT,
+      PRIMARY KEY (chunk_id, epoch_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_cs_stripe_stability
+      ON cache_stripes(stripe, stability DESC);
+
+    -- Embedding computation cache: avoids re-embedding content every time
+    -- stability scores are recomputed across epochs. Keyed by content_hash
+    -- (SHA-256 64-hex-char string). Embeddings are serialized via
+    -- Float64Array-to-Buffer to match the embedding_blob convention.
+    CREATE TABLE IF NOT EXISTS embedding_cache (
+      content_hash  TEXT PRIMARY KEY,
+      embedding     BLOB NOT NULL,
+      computed_at   INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_emb_cache_computed
+      ON embedding_cache(computed_at DESC);
   `);
 	// Idempotent column migrations. `CREATE TABLE IF NOT EXISTS` is a no-op on a
 	// pre-existing table, so new columns added to context_chunks after a store was

package/src/store/sqlite.ts

@@ -24,4 +24,5 @@ export * from "./sqlite/game-state.js";
 export * from "./sqlite/game-scores.js";
 export * from "./sqlite/game-achievements.js";
 export * from "./sqlite/perf-samples.js";
+export * from "./sqlite/cache-stripes.js";
 export * from "./sqlite/turns.js";

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

@@ -8,7 +8,7 @@
  */
 
 import { randomBytes } from "node:crypto";
-import type {
+import { DuplicateTurnError, type
 	TurnStore,
 	TurnReader,
 	TurnWriter,
@@ -198,6 +198,15 @@ export class InMemoryTurnStore implements TurnStore {
 	// ── TurnWriter ──────────────────────────────────────────────
 
 	appendTurn(entry: TurnEntry): TurnId {
+		// Check for duplicate (conversationId, turnIndex)
+		for (const [, row] of this.turns) {
+			if (
+				row.entry.conversationId === entry.conversationId &&
+				row.entry.turnIndex === entry.turnIndex
+			) {
+				throw new DuplicateTurnError(entry.conversationId, entry.turnIndex);
+			}
+		}
 		const id = allocId();
 		const sid = normalizeSessionId(entry.sessionId);
 		const normalized = { ...entry, sessionId: sid };

package/src/store/turns/sqlite-store.ts

@@ -33,6 +33,7 @@ import type {
 	ConversationStats,
 	TurnStoreOptions,
 } from "./types.js";
+import { DuplicateTurnError } from "./types.js";
 
 // ─── Helpers ──────────────────────────────────────────────────────
 
@@ -237,23 +238,34 @@ export class SqliteTurnStore implements TurnStore {
 	appendTurn(entry: TurnEntry): TurnId {
 		const sid = normalizeSessionId(entry.sessionId);
 		this.persistSessionConv(sid, entry.conversationId);
-		this.db
-			.prepare(
-				`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at,
+		try {
+			this.db
+				.prepare(
+					`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at,
                                    ctx_tokens, ctx_percent, pressure_band, model)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-			)
-			.run(
-				entry.conversationId,
-				sid,
-				entry.turnIndex,
-				entry.role,
-				entry.endedAt,
-				entry.ctxTokens ?? null,
-				entry.ctxPercent ?? null,
-				entry.pressureBand ?? null,
-				entry.model ?? null,
-			);
+				)
+				.run(
+					entry.conversationId,
+					sid,
+					entry.turnIndex,
+					entry.role,
+					entry.endedAt,
+					entry.ctxTokens ?? null,
+					entry.ctxPercent ?? null,
+					entry.pressureBand ?? null,
+					entry.model ?? null,
+				);
+		} catch (e) {
+			if (
+				e instanceof Error &&
+				e.message.includes("UNIQUE constraint") &&
+				(e as { code?: string }).code === "ERR_SQLITE_ERROR"
+			) {
+				throw new DuplicateTurnError(entry.conversationId, entry.turnIndex);
+			}
+			throw e;
+		}
 		const row = this.db
 			.prepare(
 				"SELECT id FROM turns WHERE conversation_id = ? AND turn_index = ?",

package/src/store/turns/types.ts

@@ -16,6 +16,27 @@
 
 // ─── Domain types ───────────────────────────────────────────────────
 
+/**
+ * Thrown when appendTurn is called with a (conversationId, turnIndex) pair
+ * that already exists. Both backends must throw this in lieu of a raw
+ * SQLite error (SqliteTurnStore) or silent success (InMemoryTurnStore).
+ */
+export class DuplicateTurnError extends Error {
+	/** The conversation that already has this turn index. */
+	readonly conversationId: ConversationId;
+	/** The duplicate turn index. */
+	readonly turnIndex: number;
+
+	constructor(conversationId: ConversationId, turnIndex: number) {
+		super(
+			`Duplicate turn: conversation "${conversationId}" already has turnIndex ${turnIndex}`,
+		);
+		this.name = "DuplicateTurnError";
+		this.conversationId = conversationId;
+		this.turnIndex = turnIndex;
+	}
+}
+
 /** Unique turn identifier (string to stay backend-agnostic). */
 export type TurnId = string;
 

package/src/store/vectorIndex.ts

@@ -230,13 +230,21 @@ export async function upsertEmbedding(
     const pg = await initVectorIndex();
     if (!pg) return;
     const lit = toVectorLiteral(embedding);
-    await pg.query(
-      `INSERT INTO vector_index (repo_id, session_id, checkpoint_id, embedding)
-       VALUES ($1, $2, $3, $4::vector)
-       ON CONFLICT (repo_id, session_id, checkpoint_id)
-       DO UPDATE SET embedding = EXCLUDED.embedding;`,
-      [repoId, sessionId, checkpointId, lit],
+    const upserted = await withOpenTimeout(
+      pg.query(
+        `INSERT INTO vector_index (repo_id, session_id, checkpoint_id, embedding)
+         VALUES ($1, $2, $3, $4::vector)
+         ON CONFLICT (repo_id, session_id, checkpoint_id)
+         DO UPDATE SET embedding = EXCLUDED.embedding;`,
+        [repoId, sessionId, checkpointId, lit],
+      ),
+      (reason) => {
+        disabled = true;
+        logWarn(`upsert query timed out after ${queryTimeoutMs()}ms: ${reason}`);
+      },
+      queryTimeoutMs(),
     );
+    if (upserted === undefined) return; // timed out — non-fatal
   } catch (err) {
     disabled = true;
     logWarn(`upsert failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -274,7 +282,15 @@ export async function searchAsync(
       params.push(repoId);
     }
     sql += " ORDER BY embedding <=> $1::vector LIMIT $2";
-    const res = await pg.query(sql, params);
+    const res = await withOpenTimeout(
+      pg.query(sql, params),
+      (reason) => {
+        disabled = true;
+        logWarn(`search query timed out after ${queryTimeoutMs()}ms: ${reason}`);
+      },
+      queryTimeoutMs(),
+    );
+    if (!res) return []; // query timed out — degrade to empty (non-fatal)
     return res.rows.map((r: any) => ({
       repoId: r.repo_id as string,
       sessionId: r.session_id as string,
@@ -288,13 +304,57 @@ export async function searchAsync(
   }
 }
 
+/** Default cap for the WASM close (PGlite can stall ~40 min on teardown). */
+export const DEFAULT_CLOSE_TIMEOUT_MS = 5_000;
+
+function closeTimeoutMs(): number {
+  const raw = process.env.MEGACOMPACT_PGLITE_CLOSE_TIMEOUT_MS;
+  if (raw) {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return DEFAULT_CLOSE_TIMEOUT_MS;
+}
+
+/** Default cap for a PGlite search query. A WASM query that never resolves would
+ *  otherwise hang the calling turn (and node --test) forever — the catch below
+ *  only handles thrown errors, not a stalled promise. 0 disables the guard
+ *  (preserve original unbounded behavior). Mirrors the open/close timeouts. */
+export const DEFAULT_QUERY_TIMEOUT_MS = 10_000;
+
+function queryTimeoutMs(): number {
+  const raw = process.env.MEGACOMPACT_PGLITE_QUERY_TIMEOUT_MS;
+  if (raw !== undefined) {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return DEFAULT_QUERY_TIMEOUT_MS;
+}
+
+/**
+ * Race a promise against a timeout. If the inner promise never settles, the
+ * timer fires, resolves with `undefined`, and the caller proceeds. This mirrors
+ * `withOpenTimeout` (pgOpenGuard.ts) but is local to the close path.
+ */
+function withCloseTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+): Promise<T | undefined> {
+  return Promise.race([
+    promise,
+    new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), timeoutMs)),
+  ]);
+}
+
 /** Close the index (test teardown / shutdown). Safe to call when unopened. */
 export async function closeVectorIndex(): Promise<void> {
   if (db) {
-    try {
-      await db.close();
-    } catch {
-      /* ignore */
+    const closePromise = db.close().catch(() => {});
+    const result = await withCloseTimeout(closePromise, closeTimeoutMs());
+    if (result === undefined) {
+      logWarn(
+        `close timed out after ${closeTimeoutMs()}ms (WASM teardown stalled; OS will reclaim)`,
+      );
     }
   }
   db = undefined;

package/src/tiered-router/types.ts

@@ -0,0 +1,64 @@
+/**
+ * tiered-router/types.ts — S44 tiered router types, interfaces, and defaults.
+ *
+ * Shell file: pure data/type definitions. Zero runtime dependencies on store
+ * internals. Imported by tieredRouter.ts and any consumer that needs the
+ * RecallResult / TieredRouterMetrics shapes.
+ */
+
+import type { SearchHit } from "../vectorStore.js";
+
+// ---------------------------------------------------------------------------
+// Public interfaces
+// ---------------------------------------------------------------------------
+
+export interface TieredRecallOpts {
+  /** Session ID to scope search. When absent, searches cross-session. */
+  sessionId?: string;
+  /** Max number of results to return (default 10). */
+  k?: number;
+  /** Skip LRU-cache lookup (force L1 hit). */
+  bypassCache?: boolean;
+  /**
+   * FTS5 max BM25 score for the L1 confidence gate.
+   * Read from calibration.json at construction; overridable per-call.
+   */
+  overrideFts5MaxBm25?: number;
+}
+
+export interface RecallResult {
+  /** Checkpoint search hits, ranked by relevance. */
+  hits: SearchHit[];
+  /** Which tier produced the result. */
+  tier: "L0" | "L1" | "L2";
+  /** Per-tier latency deltas in ms (contains only tiers that ran). */
+  latencyMs: { l0?: number; l1?: number; l2?: number };
+}
+
+export interface TieredRouterMetrics {
+  l0Hits: number;
+  l0Misses: number;
+  l1Hits: number;
+  l1Misses: number;
+  l2Hits: number;
+  l2Misses: number;
+  totalQueries: number;
+  avgLatencyMs: { l0: number; l1: number; l2: number };
+  fts5MaxBm25: number | null;
+  uncalibrated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+/** Default LRU cache size. */
+export const DEFAULT_CACHE_SIZE = 256;
+
+/** Default latency budgets per tier (ms). */
+export const DEFAULT_BUDGET_L0_MS = 1;
+export const DEFAULT_BUDGET_L1_MS = 50;
+export const DEFAULT_BUDGET_L2_MS = 500;
+
+/** Default cadence for tiered-metrics logging (every N queries). */
+export const DEFAULT_LOG_CADENCE = 100;