pi-mega-compact 0.13.4 → 0.13.6

package/src/recall/format.ts

@@ -12,6 +12,7 @@ import { normalizeSessionId } from "../store.js";
 import { cosineSimilarity } from "../embedder.js";
 import { computeRecallMetrics } from "../recallMetrics.js";
 import { Logger } from "../log.js";
+import type { RecallMetricsSnapshot } from "./types.js";
 
 /** Wrap a recall block so the model reads it as restored compacted context. */
 export function formatRecallBlock(hits: SearchHit[]): string {
@@ -150,7 +151,10 @@ export function raptorOverviewBlock(
  * B3: Compute recall-quality metrics on the injected hits and log them.
  * Only called when RAG_RECALL_METRICS() is ON. Non-fatal.
  */
-export function scoreAndLogRecallMetrics(query: string, toInject: SearchHit[]): void {
+export function scoreAndLogRecallMetrics(
+	query: string,
+	toInject: SearchHit[],
+): RecallMetricsSnapshot | null {
 	try {
 		const logger = new Logger();
 		const metrics = computeRecallMetrics(query, toInject);
@@ -167,7 +171,16 @@ export function scoreAndLogRecallMetrics(query: string, toInject: SearchHit[]):
 				diversity: metrics.breakdown.diversity,
 			});
 		}
+		return {
+			hitCount: toInject.length,
+			score: metrics.score,
+			pass: metrics.pass,
+			relevance: metrics.breakdown.relevance,
+			coverage: metrics.breakdown.coverage,
+			diversity: metrics.breakdown.diversity,
+			specificity: metrics.breakdown.specificity,
+		};
 	} catch {
-		/* non-fatal: metrics never break recall */
+		return null; // non-fatal: metrics never break recall
 	}
 }

package/src/recall/hydeTelemetry.ts

@@ -0,0 +1,44 @@
+/**
+ * recall/hydeTelemetry.ts — pure builder for HydeInvocationInfo.
+ *
+ * No I/O, no logging: turns a HyDE outcome + hit counts into the
+ * serialization-safe telemetry object surfaced on RecallInjectResult.
+ */
+import type { HydeInvocationInfo } from "./types.js";
+
+export type HydeOutcome = "ran" | "disabled" | "no-llm" | "generation-failed";
+
+export function buildHydeInfo(
+	outcome: HydeOutcome,
+	hypotheticalDoc: string,
+	generationMs: number,
+	rawHitCount: number,
+	hydeHitCount: number,
+	fusedHitCount: number,
+): HydeInvocationInfo {
+	const ran = outcome === "ran";
+	const skipped = !ran;
+	// Lift = fusedHitCount / max(1, rawHitCount) — how much HyDE changed recall
+	// breadth. Skipped passes yield 1 (raw hits cascade unchanged) unless there
+	// were no raw hits to compare against.
+	const lift = fusedHitCount / Math.max(1, rawHitCount);
+	return {
+		ran,
+		skipped,
+		reason: outcome,
+		hypotheticalDoc,
+		generationMs: ran ? generationMs : 0,
+		rawHitCount,
+		hydeHitCount: ran ? hydeHitCount : 0,
+		fusedHitCount,
+		lift: Math.round(lift * 100) / 100,
+	};
+}
+
+export function hydeSkipped(
+	reason: "disabled" | "no-llm" | "generation-failed",
+	rawHitCount: number,
+	fusedHitCount: number,
+): HydeInvocationInfo {
+	return buildHydeInfo(reason, "", 0, rawHitCount, 0, fusedHitCount);
+}

package/src/recall/sync.ts

@@ -19,10 +19,16 @@ import { estimateBlockTokens } from "../tokens.js";
 import { defaultEmbedder, cosineSimilarity } from "../embedder.js";
 import { RAG_QUERY_REFORMULATION, RAG_TIERED_ROUTER, RAG_RECALL_METRICS, RAG_HYDE_ENABLED } from "../config.js";
 import { generateHypotheticalDoc, fuseRecallHits } from "../hyde.js";
-import type { RecallInjectOptions, RecallInjectResult } from "./types.js";
+import type {
+	RecallInjectOptions,
+	RecallInjectResult,
+	HydeInvocationInfo,
+	RecallMetricsSnapshot,
+} from "./types.js";
 import type { SearchHit } from "../vectorStore.js";
 import { reformulateRecallQuery, runTieredRecall } from "./reformulate.js";
 import { formatRecallBlock, scoreAndLogRecallMetrics, raptorOverviewBlock } from "./format.js";
+import { buildHydeInfo, hydeSkipped } from "./hydeTelemetry.js";
 
 /**
  * Recall and inline context from the checkpoint store.
@@ -94,10 +100,17 @@ export function recallAndInline(
 	// RRF-fuses with the raw-query results. Non-fatal: any error → raw-only.
 	// TrigramEmbedder (kind !== "http") skips this — S57 B1 reformulation above
 	// already handles the no-LLM path.
+	// H1 telemetry tracking for the HyDE block below.
 	let hydeHits: SearchHit[] | null = null;
+	let hydeDoc = "";
+	let hydeGenMs = 0;
+	let hydeRawCount = 0;
 	if (RAG_HYDE_ENABLED() && embedder.kind === "http") {
+		const t0 = Date.now();
 		const hyde = generateHypotheticalDoc(opts.query, embedder);
+		hydeGenMs = Date.now() - t0;
 		if (hyde) {
+			hydeDoc = hyde;
 			try {
 				const r2 = searchRecall(
 					{ sessionId: opts.sessionId, query: hyde, limit, skipInjected: skip },
@@ -120,6 +133,8 @@ export function recallAndInline(
 		);
 		newHits = result.newHits;
 	}
+	// H1: the raw-query hit count is taken BEFORE fusion.
+	hydeRawCount = newHits.length;
 
 	// S43 re-plan: fuse the hypothetical-doc hits with the raw-query hits via RRF
 	// when HyDE produced results. The downstream inline dedupe + metrics + format
@@ -162,7 +177,10 @@ export function recallAndInline(
 	// byte-identical). Scores the injected hits against the ORIGINAL query so the
 	// metric measures whether the (possibly expanded) search results stay
 	// relevant to what the user actually asked.
-	if (RAG_RECALL_METRICS()) scoreAndLogRecallMetrics(opts.query, toInject);
+	let recallMetrics: RecallMetricsSnapshot | null = null;
+	if (RAG_RECALL_METRICS()) {
+		recallMetrics = scoreAndLogRecallMetrics(opts.query, toInject);
+	}
 
 	// F3: format once — one preamble, correct [1..n] numbering.
 	const recallBlock = toInject.length > 0 ? formatRecallBlock(toInject) : "";
@@ -188,10 +206,24 @@ export function recallAndInline(
 			? overview + "\n" + recallBlock
 			: overview || recallBlock;
 
+	// H1: build the HyDE invocation telemetry for this pass.
+	const fusedCount = toInject.length;
+	let hydeInfo: HydeInvocationInfo;
+	if (RAG_HYDE_ENABLED() && embedder.kind === "http") {
+		hydeInfo =
+			hydeHits && hydeHits.length > 0
+				? buildHydeInfo("ran", hydeDoc, hydeGenMs, hydeRawCount, hydeHits.length, fusedCount)
+				: hydeSkipped(hydeDoc ? "generation-failed" : "no-llm", hydeRawCount, fusedCount);
+	} else {
+		hydeInfo = hydeSkipped("disabled", hydeRawCount, fusedCount);
+	}
+
 	return {
 		toInject,
 		report,
 		block,
 		empty: block.length === 0,
+		hydeInfo,
+		recallMetrics,
 	};
 }

package/src/recall/types.ts

@@ -46,6 +46,42 @@ export interface RecallInjectResult {
 	block: string;
 	/** True when nothing new was inlined. */
 	empty: boolean;
+	/** H1: HyDE invocation telemetry for this recall pass. Non-null always. */
+	hydeInfo: HydeInvocationInfo | null;
+	/** H1: recall-quality metrics (only populated when RAG_RECALL_METRICS() is ON). */
+	recallMetrics: RecallMetricsSnapshot | null;
+}
+
+export interface HydeInvocationInfo {
+	/** True when HyDE ran (LLM generated a hypothetical doc + embedded + searched). */
+	ran: boolean;
+	/** True when HyDE was considered but explicitly skipped (e.g. no LLM surface). */
+	skipped: boolean;
+	/** Human-readable reason: "ran", "disabled", "no-llm", "generation-failed". */
+	reason: string;
+	/** The hypothetical answer document the LLM produced ("" when skipped/failed). */
+	hypotheticalDoc: string;
+	/** Wall-clock ms spent generating + embedding the hypothetical doc (0 when skipped). */
+	generationMs: number;
+	/** Hit count from the raw-query search before fusion. */
+	rawHitCount: number;
+	/** Hit count from the hypothetical-doc search before fusion. */
+	hydeHitCount: number;
+	/** Hit count of the RRF-fused result actually injected (after dedupe+cap). */
+	fusedHitCount: number;
+	/** Lift = fusedHitCount / max(1, rawHitCount) — how much HyDE changed recall breadth. */
+	lift: number;
+}
+
+/** Slim, serialization-safe slice of RecallQualityResult for persistence + SSE. */
+export interface RecallMetricsSnapshot {
+	hitCount: number;
+	score: number;
+	pass: boolean;
+	relevance: number;
+	coverage: number;
+	diversity: number;
+	specificity: number;
 }
 
 export interface MemoryRecallInjectOptions {

package/src/store/turns/hydeStore.ts

@@ -0,0 +1,82 @@
+/**
+ * turns/hydeStore.ts — read helpers over the H1 telemetry columns.
+ *
+ * Pure read aggregations on the turns table. All queries parameterized
+ * (PREVENT-002); no mutation here (turns stays append-only).
+ */
+import type { DatabaseSync } from "node:sqlite";
+
+export interface TurnTelemetryRow {
+	turnId: string;
+	conversationId: string;
+	turnIndex: number;
+	role: string;
+	endedAt: number;
+	hydeRan: number;
+	hydeReason: string;
+	hydeDoc: string;
+	hydeRawCount: number;
+	hydeHydeCount: number;
+	hydeFusedCount: number;
+	hydeLift: number;
+	hydeGenerationMs: number;
+	recallScore: number;
+	recallPass: number;
+	recallRelevance: number;
+	recallCoverage: number;
+	recallDiversity: number;
+	recallSpecificity: number;
+}
+
+export function listTelemetryTurns(
+	db: DatabaseSync,
+	opts: { limit?: number } = {},
+): TurnTelemetryRow[] {
+	const limit = Math.max(1, opts.limit ?? 200);
+	return db
+		.prepare(
+			`SELECT id AS turnId, conversation_id AS conversationId,
+			        turn_index AS turnIndex, role, ended_at AS endedAt,
+			        hyde_ran AS hydeRan, hyde_reason AS hydeReason, hyde_doc AS hydeDoc,
+			        hyde_raw_count AS hydeRawCount, hyde_hyde_count AS hydeHydeCount,
+			        hyde_fused_count AS hydeFusedCount, hyde_lift AS hydeLift,
+			        hyde_generation_ms AS hydeGenerationMs,
+			        recall_score AS recallScore, recall_pass AS recallPass,
+			        recall_relevance AS recallRelevance, recall_coverage AS recallCoverage,
+			        recall_diversity AS recallDiversity, recall_specificity AS recallSpecificity
+			 FROM turns
+			 WHERE hyde_ran = 1 OR recall_pass IS NOT NULL
+			 ORDER BY ended_at DESC
+			 LIMIT ?`,
+		)
+		.all(limit) as unknown as TurnTelemetryRow[];
+}
+
+export interface DailyTelemetry {
+	day: string;
+	recallCount: number;
+	hydeRanCount: number;
+	avgScore: number | null;
+	avgLift: number | null;
+	avgGenMs: number | null;
+}
+
+export function aggregateDailyTelemetry(
+	db: DatabaseSync,
+	days: number,
+): DailyTelemetry[] {
+	const since = Date.now() - days * 86_400_000;
+	return db
+		.prepare(
+			`SELECT date(ended_at / 1000, 'unixepoch') AS day,
+			        COUNT(*) AS recallCount,
+			        SUM(hyde_ran) AS hydeRanCount,
+			        AVG(recall_score) AS avgScore,
+			        AVG(hyde_lift) AS avgLift,
+			        AVG(hyde_generation_ms) AS avgGenMs
+			 FROM turns
+			 WHERE ended_at >= ? AND (hyde_ran = 1 OR recall_pass IS NOT NULL)
+			 GROUP BY day ORDER BY day ASC`,
+		)
+		.all(since) as unknown as DailyTelemetry[];
+}

package/src/store/turns/index.ts

@@ -15,6 +15,8 @@ export type {
 	SessionId,
 	TurnEntry,
 	TurnRecallEntry,
+	TurnHydeTelemetry,
+	TurnRecallTelemetry,
 	ConversationFork,
 	TurnFilter,
 	PruneReport,
@@ -46,6 +48,8 @@ export {
 } from "./connection.js";
 export { initTurnSchema } from "./schema.js";
 export { migrateTurnTablesIfNeeded } from "./migrations.js";
+export { listTelemetryTurns, aggregateDailyTelemetry } from "./hydeStore.js";
+export type { TurnTelemetryRow, DailyTelemetry } from "./hydeStore.js";
 
 import { SqliteTurnStore } from "./sqlite-store.js";
 import { InMemoryTurnStore } from "./memory-store.js";

package/src/store/turns/schema.ts

@@ -16,7 +16,7 @@
 import type { DatabaseSync } from "node:sqlite";
 
 /** Schema version stamp (written once into turns_meta). */
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
 
 /** Create the unified turn-store schema if absent. Idempotent. */
 export function initTurnSchema(db: DatabaseSync): void {
@@ -162,6 +162,131 @@ export function initTurnSchema(db: DatabaseSync): void {
 		`CREATE INDEX IF NOT EXISTS idx_memory_topics_topic ON memory_topics(topic_id)`,
 	);
 
+	// H1: additive HyDE + recall-quality telemetry columns. ALTER TABLE ADD
+	// COLUMN (idempotent via PRAGMA guard) — turns stays append-only; these land
+	// in the single INSERT at turn-record time, never via UPDATE.
+	const ensureCol = (name: string, ddl: string): void => {
+		const has = (
+			db.prepare("PRAGMA table_info(turns)").all() as Array<{ name: string }>
+		).some((c) => c.name === name);
+		if (!has) db.exec(`ALTER TABLE turns ADD COLUMN ${ddl}`);
+	};
+	ensureCol("hyde_ran", "hyde_ran INTEGER DEFAULT 0");
+	ensureCol("hyde_doc", "hyde_doc TEXT DEFAULT ''");
+	ensureCol("hyde_raw_count", "hyde_raw_count INTEGER DEFAULT 0");
+	ensureCol("hyde_hyde_count", "hyde_hyde_count INTEGER DEFAULT 0");
+	ensureCol("hyde_fused_count", "hyde_fused_count INTEGER DEFAULT 0");
+	ensureCol("hyde_lift", "hyde_lift REAL DEFAULT 0");
+	ensureCol("hyde_generation_ms", "hyde_generation_ms INTEGER DEFAULT 0");
+	ensureCol("hyde_reason", "hyde_reason TEXT DEFAULT ''");
+	ensureCol("recall_score", "recall_score REAL DEFAULT 0");
+	ensureCol("recall_pass", "recall_pass INTEGER DEFAULT 0");
+	ensureCol("recall_relevance", "recall_relevance REAL DEFAULT 0");
+	ensureCol("recall_coverage", "recall_coverage REAL DEFAULT 0");
+	ensureCol("recall_diversity", "recall_diversity REAL DEFAULT 0");
+	ensureCol("recall_specificity", "recall_specificity REAL DEFAULT 0");
+
+	// ── Wiki Revival (Spec 3): user curation + topic evolution ────────
+	const sessionCol = (
+		db.prepare("PRAGMA table_info(memory_topics)").all() as Array<{ name: string }>
+	).some((c) => c.name === "session_id");
+	if (!sessionCol) {
+		db.exec("ALTER TABLE memory_topics ADD COLUMN session_id TEXT");
+	}
+	db.exec(
+		`CREATE INDEX IF NOT EXISTS idx_memory_topics_session ON memory_topics(session_id)`,
+	);
+
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS topic_overrides (
+      topic_id      TEXT NOT NULL,
+      kind          TEXT NOT NULL CHECK(kind IN ('label','merge','split')),
+      custom_label  TEXT,
+      merged_into   TEXT,
+      split_from    TEXT,
+      split_memory_ids TEXT,
+      merged_memory_ids TEXT,
+      overridden_at INTEGER NOT NULL,
+      PRIMARY KEY (topic_id, kind)
+    )
+  `);
+	db.exec(
+		`CREATE INDEX IF NOT EXISTS idx_topic_overrides_topic ON topic_overrides(topic_id)`,
+	);
+
+	// W5: add merged_memory_ids column to existing topic_overrides tables (same
+	// additive ensureColumn pattern as the HyDE columns). Stores the member ids
+	// from the source topic at merge time so merge overrides survive a full
+	// replaceTopicModel rebuild (topic_evolution rows are CASCADE-deleted with
+	// their parent topic, but topic_overrides rows persist across rebuilds).
+	const overridesCols = db
+		.prepare("PRAGMA table_info(topic_overrides)")
+		.all() as Array<{ name: string }>;
+	if (
+		overridesCols.length > 0 &&
+		!overridesCols.some((c) => c.name === "merged_memory_ids")
+	) {
+		db.exec("ALTER TABLE topic_overrides ADD COLUMN merged_memory_ids TEXT");
+	}
+
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS topic_evolution (
+      topic_id     TEXT NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
+      memory_id    TEXT NOT NULL,
+      session_id   TEXT,
+      assigned_at  INTEGER NOT NULL,
+      method       TEXT NOT NULL CHECK(method IN ('kmeans+tfidf','merge','split','manual')),
+      PRIMARY KEY (topic_id, memory_id)
+    )
+  `);
+	db.exec(
+		`CREATE INDEX IF NOT EXISTS idx_topic_evolution_topic ON topic_evolution(topic_id, assigned_at)`,
+	);
+	db.exec(
+		`CREATE INDEX IF NOT EXISTS idx_topic_evolution_ts   ON topic_evolution(assigned_at)`,
+	);
+
+	// Migration: topic_evolution.topic_id FK lacked ON DELETE CASCADE when the
+	// table was first created (W1). Without it, deleting a topic (merge source or
+	// replaceTopicModel rebuild) throws SQLITE_CONSTRAINT when evolution rows
+	// reference it, rolling back the delete. Recreate the table with CASCADE when
+	// the live FK definition is missing it. Non-fatal: a failure just leaves the
+	// old definition (rebuilds remain best-effort).
+	try {
+		// PRAGMA foreign_key_list exposes the referenced table + on-delete rule.
+		const fkList = db
+			.prepare("PRAGMA foreign_key_list(topic_evolution)")
+			.all() as Array<{ table: string; from: string; on_delete: string }>;
+		const topicFk = fkList.find((f) => f.from === "topic_id");
+		if (topicFk && topicFk.on_delete !== "CASCADE") {
+			db.exec("DROP TABLE IF EXISTS topic_evolution_mig");
+			db.exec(`
+	        CREATE TABLE topic_evolution_mig (
+	          topic_id     TEXT NOT NULL REFERENCES topics(id) ON DELETE CASCADE,
+	          memory_id    TEXT NOT NULL,
+	          session_id   TEXT,
+	          assigned_at  INTEGER NOT NULL,
+	          method       TEXT NOT NULL CHECK(method IN ('kmeans+tfidf','merge','split','manual')),
+	          PRIMARY KEY (topic_id, memory_id)
+	        )
+	      `);
+			db.exec(
+				`INSERT INTO topic_evolution_mig (topic_id, memory_id, session_id, assigned_at, method)
+	           SELECT topic_id, memory_id, session_id, assigned_at, method FROM topic_evolution`,
+			);
+			db.exec("DROP TABLE topic_evolution");
+			db.exec("ALTER TABLE topic_evolution_mig RENAME TO topic_evolution");
+			db.exec(
+				`CREATE INDEX IF NOT EXISTS idx_topic_evolution_topic ON topic_evolution(topic_id, assigned_at)`,
+			);
+			db.exec(
+				`CREATE INDEX IF NOT EXISTS idx_topic_evolution_ts   ON topic_evolution(assigned_at)`,
+			);
+		}
+	} catch {
+		/* non-fatal: migration never breaks turn-DB open */
+	}
+
 	// Stamp schema version once.
 	const existing = db
 		.prepare("SELECT value FROM turns_meta WHERE key = 'schema_version'")

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

@@ -32,6 +32,31 @@ export function rowToEntry(r: Record<string, unknown>): TurnEntry {
 			(r.pressure_band as "green" | "yellow" | "red" | null) ?? undefined,
 		model: (r.model as string | null) ?? undefined,
 		epochId: (r.epoch_id as string | null) ?? undefined,
+		// H1: telemetry columns (only populated when the row has them non-default).
+		hyde:
+			r.hyde_ran == null
+				? undefined
+				: {
+						ran: r.hyde_ran === 1,
+						reason: (r.hyde_reason as string) ?? "",
+						hypotheticalDoc: (r.hyde_doc as string) ?? "",
+						rawHitCount: (r.hyde_raw_count as number) ?? 0,
+						hydeHitCount: (r.hyde_hyde_count as number) ?? 0,
+						fusedHitCount: (r.hyde_fused_count as number) ?? 0,
+						lift: (r.hyde_lift as number) ?? 0,
+						generationMs: (r.hyde_generation_ms as number) ?? 0,
+					},
+		recallMetrics:
+			r.recall_score == null
+				? undefined
+				: {
+						score: (r.recall_score as number) ?? 0,
+						pass: (r.recall_pass as number) === 1,
+						relevance: (r.recall_relevance as number) ?? 0,
+						coverage: (r.recall_coverage as number) ?? 0,
+						diversity: (r.recall_diversity as number) ?? 0,
+						specificity: (r.recall_specificity as number) ?? 0,
+					},
 	};
 }
 

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

@@ -22,8 +22,12 @@ export function appendTurn(ctx: SqliteTurnStoreCtx, entry: TurnEntry): TurnId {
 		db
 			.prepare(
 				`INSERT INTO turns (conversation_id, session_id, turn_index, role, ended_at,
-	                           ctx_tokens, ctx_percent, pressure_band, model, epoch_id)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+	                           ctx_tokens, ctx_percent, pressure_band, model, epoch_id,
+	                           hyde_ran, hyde_doc, hyde_raw_count, hyde_hyde_count,
+	                           hyde_fused_count, hyde_lift, hyde_generation_ms, hyde_reason,
+	                           recall_score, recall_pass, recall_relevance, recall_coverage,
+	                           recall_diversity, recall_specificity)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
 			)
 			.run(
 				entry.conversationId,
@@ -36,6 +40,20 @@ export function appendTurn(ctx: SqliteTurnStoreCtx, entry: TurnEntry): TurnId {
 				entry.pressureBand ?? null,
 				entry.model ?? null,
 				entry.epochId ?? null,
+				entry.hyde?.ran == null ? null : entry.hyde.ran ? 1 : 0,
+				entry.hyde?.hypotheticalDoc ?? null,
+				entry.hyde?.rawHitCount ?? null,
+				entry.hyde?.hydeHitCount ?? null,
+				entry.hyde?.fusedHitCount ?? null,
+				entry.hyde?.lift ?? null,
+				entry.hyde?.generationMs ?? null,
+				entry.hyde?.reason ?? null,
+				entry.recallMetrics?.score ?? null,
+				entry.recallMetrics?.pass == null ? null : entry.recallMetrics.pass ? 1 : 0,
+				entry.recallMetrics?.relevance ?? null,
+				entry.recallMetrics?.coverage ?? null,
+				entry.recallMetrics?.diversity ?? null,
+				entry.recallMetrics?.specificity ?? null,
 			);
 	} catch (e) {
 		if (

package/src/store/turns/types.ts

@@ -59,6 +59,39 @@ export interface TurnEntry {
 	model?: string; // model used for this turn
 	/** S50B: the compact epoch that superseded this turn (stamped post-hoc). */
 	epochId?: string;
+	/** H1: HyDE invocation telemetry for this turn (persisted to hyde_* columns). */
+	hyde?: TurnHydeTelemetry;
+	/** H1: recall-quality snapshot for this turn (persisted to recall_* columns). */
+	recallMetrics?: TurnRecallTelemetry;
+}
+
+/**
+ * H1: HyDE telemetry for a turn — a structural subset of the recall-core
+ * `HydeInvocationInfo` that maps onto the turns `hyde_*` columns.
+ */
+export interface TurnHydeTelemetry {
+	ran: boolean;
+	/** Skip reason when HyDE didn't run: "disabled" | "no-llm" | "generation-failed". */
+	reason: string;
+	hypotheticalDoc: string;
+	rawHitCount: number;
+	hydeHitCount: number;
+	fusedHitCount: number;
+	lift: number;
+	generationMs: number;
+}
+
+/**
+ * H1: recall-quality snapshot for a turn — a structural subset of the recall-core
+ * `RecallMetricsSnapshot` that maps onto the turns `recall_*` columns.
+ */
+export interface TurnRecallTelemetry {
+	score: number;
+	pass: boolean;
+	relevance: number;
+	coverage: number;
+	diversity: number;
+	specificity: number;
 }
 
 /** A recall hit recorded during a turn — an immutable, append-only fact. */