pi-mega-compact 0.11.12 → 0.12.0

package/extensions/mega-events/context-handler.ts

@@ -333,120 +333,127 @@ export function registerContextHandler(
 				} catch {
 					/* non-fatal: epoch stamping never breaks compaction */
 				}
-				// S51B: auto-categorizing wiki rebuild — every Nth compaction, derived
-				// from real context_chunks embeddings. Isolated-store only, gated on
-				// AUTO_WIKI_ENABLED; best-effort + non-fatal (never breaks compaction).
-				try {
-					if (config.autoWikiEnabled && config.turnsDbEnabled) {
-						const every = Math.max(
-							1,
-							TurnsConfig.WIKI_REBUILD_EVERY_N_COMPACTS,
-						);
-						const tdb = openTurnStore(runtime.currentStateDir);
-						const n = bumpWikiCompactCounter(tdb);
-						if (n % every === 0) {
-							const model = buildTopicModel(db, {
-								kRange: [TurnsConfig.WIKI_K_MIN, TurnsConfig.WIKI_K_MAX],
-								labelTopTerms: TurnsConfig.WIKI_LABEL_TOP_TERMS,
-								restarts: 5,
-								seed: 0x9e3779b9,
+
+		// S51B: auto-categorizing wiki rebuild — every Nth compaction, derived
+		// from real context_chunks embeddings. Isolated-store only, gated on
+		// AUTO_WIKI_ENABLED; best-effort + non-fatal (never breaks compaction).
+		// Fire regardless of dbMirror — context_chunks is the isolated store.
+		// Uses the already-open db when inside the dbMirror block; opens its own
+		// connection otherwise.
+		// from real context_chunks embeddings. Isolated-store only, gated on
+		// AUTO_WIKI_ENABLED; best-effort + non-fatal (never breaks compaction).
+		try {
+			if (config.autoWikiEnabled && config.turnsDbEnabled) {
+				const every = Math.max(
+					1,
+					TurnsConfig.WIKI_REBUILD_EVERY_N_COMPACTS,
+				);
+				const tdb = openTurnStore(runtime.currentStateDir);
+				const n = bumpWikiCompactCounter(tdb);
+				if (n % every === 0) {
+					const model = buildTopicModel(db, {
+						kRange: [TurnsConfig.WIKI_K_MIN, TurnsConfig.WIKI_K_MAX],
+						labelTopTerms: TurnsConfig.WIKI_LABEL_TOP_TERMS,
+						restarts: 5,
+						seed: 0x9e3779b9,
+					});
+					createTopicStore(runtime.currentStateDir).replaceTopicModel(
+						model,
+					);
+					runtime.logger.info("wiki_rebuild", {
+						clusterCount: model.k,
+						totalChunks: model.totalChunks,
+						method: "kmeans+tfidf",
+						criterion: model.criterion,
+						silhouetteScore: model.silhouetteScore,
+						uncalibrated: false,
+					});
+				}
+			}
+		} catch (wikiErr) {
+			runtime.logger.warn("wiki_rebuild_failed", {
+				error: String(wikiErr),
+			});
+		}
+
+		// D1: seed the topic model from raw_transcript when context_chunks is
+		// thin (pre-compaction). Gated on WIKI_SEED_FROM_TURNS; non-fatal.
+		// Seeds buildTopicModel with on-the-fly trigram embeddings from
+		// recent raw_transcript rows for the current session.
+		try {
+			if (
+				config.autoWikiEnabled &&
+				config.turnsDbEnabled &&
+				TurnsConfig.WIKI_SEED_FROM_TURNS
+			) {
+				const floor = 50;
+				const countRow = db
+					.prepare(
+						`SELECT COUNT(*) AS cnt FROM context_chunks WHERE session_id = ?`,
+					)
+					.get(runtime.rt.sessionId) as { cnt: number } | undefined;
+				const chunkCount = countRow?.cnt ?? 0;
+				if (chunkCount < floor) {
+					const transcriptRows = db
+						.prepare(
+							`SELECT DISTINCT content_bytes
+	       FROM raw_transcript
+	       WHERE session_id = ?
+	         AND length(content_bytes) > 10
+	       ORDER BY seq ASC
+	       LIMIT 200`,
+						)
+						.all(runtime.rt.sessionId) as Array<{
+						content_bytes: string;
+					}>;
+					if (transcriptRows.length > 0) {
+						const embedder = new TrigramEmbedder();
+						const seedChunks: EmbeddedChunk[] = [];
+						for (let i = 0; i < transcriptRows.length; i++) {
+							const text = transcriptRows[i].content_bytes.trim();
+							if (text.length === 0) continue;
+							const vec = embedder.embed(text);
+							seedChunks.push({
+								chunkId: `seed_transcript_${i}`,
+								sessionId: runtime.rt.sessionId,
+								vec,
+								text,
 							});
-							createTopicStore(runtime.currentStateDir).replaceTopicModel(
-								model,
+						}
+						if (seedChunks.length > 0) {
+							const model = buildTopicModel(
+								db,
+								{
+									kRange: [
+										TurnsConfig.WIKI_K_MIN,
+										TurnsConfig.WIKI_K_MAX,
+									],
+									labelTopTerms:
+										TurnsConfig.WIKI_LABEL_TOP_TERMS,
+									restarts: 5,
+									seed: 0x9e3779b9,
+								},
+								seedChunks,
 							);
-							runtime.logger.info("wiki_rebuild", {
+							createTopicStore(
+								runtime.currentStateDir,
+							).replaceTopicModel(model);
+							runtime.logger.info("wiki_seed", {
 								clusterCount: model.k,
+								sourceChunks: seedChunks.length,
 								totalChunks: model.totalChunks,
 								method: "kmeans+tfidf",
-								criterion: model.criterion,
-								silhouetteScore: model.silhouetteScore,
-								uncalibrated: false,
 							});
 						}
 					}
-				} catch (wikiErr) {
-					runtime.logger.warn("wiki_rebuild_failed", {
-						error: String(wikiErr),
-					});
 				}
+			}
+		} catch (seedErr) {
+			runtime.logger.warn("wiki_seed_failed", {
+				error: String(seedErr),
+			});
+		}
 
-				// D1: seed the topic model from raw_transcript when context_chunks is
-				// thin (pre-compaction). Gated on WIKI_SEED_FROM_TURNS; non-fatal.
-				// Seeds buildTopicModel with on-the-fly trigram embeddings from
-				// recent raw_transcript rows for the current session.
-				try {
-					if (
-						config.autoWikiEnabled &&
-						config.turnsDbEnabled &&
-						TurnsConfig.WIKI_SEED_FROM_TURNS
-					) {
-						const floor = 50;
-						const countRow = db
-							.prepare(
-								`SELECT COUNT(*) AS cnt FROM context_chunks WHERE session_id = ?`,
-							)
-							.get(runtime.rt.sessionId) as { cnt: number } | undefined;
-						const chunkCount = countRow?.cnt ?? 0;
-						if (chunkCount < floor) {
-							const transcriptRows = db
-								.prepare(
-									`SELECT DISTINCT content_bytes
-			       FROM raw_transcript
-			       WHERE session_id = ?
-			         AND length(content_bytes) > 10
-			       ORDER BY seq ASC
-			       LIMIT 200`,
-								)
-								.all(runtime.rt.sessionId) as Array<{
-								content_bytes: string;
-							}>;
-							if (transcriptRows.length > 0) {
-								const embedder = new TrigramEmbedder();
-								const seedChunks: EmbeddedChunk[] = [];
-								for (let i = 0; i < transcriptRows.length; i++) {
-									const text = transcriptRows[i].content_bytes.trim();
-									if (text.length === 0) continue;
-									const vec = embedder.embed(text);
-									seedChunks.push({
-										chunkId: `seed_transcript_${i}`,
-										sessionId: runtime.rt.sessionId,
-										vec,
-										text,
-									});
-								}
-								if (seedChunks.length > 0) {
-									const model = buildTopicModel(
-										db,
-										{
-											kRange: [
-												TurnsConfig.WIKI_K_MIN,
-												TurnsConfig.WIKI_K_MAX,
-											],
-											labelTopTerms:
-												TurnsConfig.WIKI_LABEL_TOP_TERMS,
-											restarts: 5,
-											seed: 0x9e3779b9,
-										},
-										seedChunks,
-									);
-									createTopicStore(
-										runtime.currentStateDir,
-									).replaceTopicModel(model);
-									runtime.logger.info("wiki_seed", {
-										clusterCount: model.k,
-										sourceChunks: seedChunks.length,
-										totalChunks: model.totalChunks,
-										method: "kmeans+tfidf",
-									});
-								}
-							}
-						}
-					}
-				} catch (seedErr) {
-					runtime.logger.warn("wiki_seed_failed", {
-						error: String(seedErr),
-					});
-				}
 				// S27 Task 6: Fire-and-forget dedup pipeline.
 				// Deduplicates raw_transcript rows for the compacted range.
 				try {

package/extensions/mega-events/health-handler.ts

@@ -0,0 +1,190 @@
+/**
+ * health-handler.ts — Context Health turn_end hook (v0.12).
+ *
+ * Computes a composite 0-1 health score per turn from five sub-scores
+ * (drift, output quality, error rate, cache health, cache poison),
+ * persists it to the context_health SQLite table, and emits a dashboard
+ * event. All paths non-fatal — health monitoring never breaks the agent loop.
+ *
+ * PREVENT-PI-004: zero network (local TrigramEmbedder + SQLite only).
+ */
+
+import type { MegaRuntime } from "../mega-runtime.js";
+import type { MegaConfig } from "../mega-config.js";
+import { defaultEmbedder } from "../../src/embedder.js";
+import { computeOutputQuality } from "../../src/contextHealth/outputQuality.js";
+import {
+	computeTopicDrift,
+	computeErrorEscalation,
+	computePrefixInstability,
+	computeDriftScore,
+} from "../../src/contextHealth/drift.js";
+import {
+	computePrefixHash,
+	checkPrefixHash,
+	evaluateCachePoison,
+} from "../../src/contextHealth/cachePoison.js";
+import {
+	computeHealthScore,
+	recordContextHealth,
+	type ContextHealthSubScores,
+} from "../../src/contextHealth.js";
+import {
+	recordCachePoisonEvent,
+} from "../../src/store/sqlite/context-health.js";
+
+const RING_MAX = 5;
+
+/** Extract assistant text from the turn_end event message. */
+function extractAssistantText(event: { message?: { role?: string; content?: unknown } }): string {
+	const msg = event.message;
+	if (!msg || msg.role !== "assistant") return "";
+	const c = msg.content;
+	if (typeof c === "string") return c;
+	if (Array.isArray(c)) {
+		return c
+			.map((p) => (p && typeof p === "object" && "text" in p ? String((p as { text?: string }).text ?? "") : ""))
+			.join(" ");
+	}
+	return "";
+}
+
+/** Extract messages as string array for prefix hash (cache poison Layer 1). */
+function extractMessageTexts(event: { message?: { content?: unknown } }): string[] {
+	const c = event?.message?.content;
+	if (typeof c === "string") return [c];
+	if (Array.isArray(c)) {
+		return c.map((p) => (p && typeof p === "object" && "text" in p ? String((p as { text?: string }).text ?? "") : ""));
+	}
+	return [];
+}
+
+interface TurnEvent {
+	turnIndex: number;
+	message?: { role?: string; content?: unknown; stopReason?: string; usage?: { cacheRead?: number } };
+}
+
+/** Handle turn_end: compute + persist context health. Non-fatal. */
+export function handleTurnEndHealth(
+	event: TurnEvent,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): void {
+	if (!config.contextHealth) return;
+	try {
+		const text = extractAssistantText(event);
+		const embedder = defaultEmbedder();
+		const emb = text.length > 0 ? embedder.embed(text) : [];
+
+		// Output quality sub-score
+		let outputQuality = 1.0;
+		let repetitionRatio = 0;
+		let coherenceScore = 1.0;
+		if (config.contextHealthOutputQuality && text.length > 0) {
+			const oq = computeOutputQuality(text, embedder);
+			outputQuality = oq.score;
+			repetitionRatio = oq.repetitionRatio;
+			coherenceScore = oq.coherenceScore;
+		}
+
+		// Drift sub-score
+		let drift = 1.0;
+		if (config.contextHealthDrift) {
+			const topic = computeTopicDrift(emb, runtime.recentTurnEmbeddings);
+			const error = computeErrorEscalation(runtime.recentErrorCategories);
+			const prefix = computePrefixInstability(0, 5);
+			drift = computeDriftScore(topic, error, prefix);
+		}
+
+		// Error rate sub-score (1 = no errors)
+		const errorScore = computeErrorEscalation(runtime.recentErrorCategories);
+
+		// Cache health (from perf-handler)
+		const cacheHealth = runtime.rt._lastCacheHealthScore ?? 1.0;
+
+		// Cache poison sub-score
+		let cachePoison = 1.0;
+		if (config.contextHealthCachePoison) {
+			const msgTexts = extractMessageTexts(event);
+			const currentHash = computePrefixHash(msgTexts);
+			const cacheRead = event.message?.usage?.cacheRead ?? 0;
+			const l1 = checkPrefixHash(currentHash, runtime.lastPrefixHash, cacheRead);
+			const result = evaluateCachePoison({
+				currentHash,
+				storedHash: runtime.lastPrefixHash,
+				cacheRead,
+				qualityByCacheHit: [],
+				qualityByCacheMiss: [],
+				errorRateCacheHit: 0,
+				errorRateCacheMiss: 0,
+				sampleCount: 0,
+			});
+			cachePoison = result.score;
+			if (l1.poisoned) {
+				try {
+					recordCachePoisonEvent(runtime.currentStateDir, {
+						ts: Date.now(),
+						turnIndex: event.turnIndex,
+						sessionId: runtime.rt.sessionId,
+						layer: 1,
+						detail: l1.detail,
+						severity: "warn",
+					});
+				} catch { /* non-fatal */ }
+			}
+			runtime.lastPrefixHash = currentHash;
+		}
+
+		// Composite
+		const sub: ContextHealthSubScores = {
+			drift,
+			outputQuality,
+			errorRate: errorScore,
+			cacheHealth,
+			cachePoison,
+		};
+		const composite = computeHealthScore(sub);
+
+		// Persist
+		recordContextHealth(runtime.currentStateDir, {
+			ts: Date.now(),
+			turnIndex: event.turnIndex,
+			sessionId: runtime.rt.sessionId,
+			driftScore: drift,
+			outputQuality,
+			errorScore,
+			cacheHealth,
+			cachePoison,
+			composite,
+			modelId: runtime.currentModel?.modelId,
+			repetitionRatio,
+			coherenceScore,
+			prefixHash: runtime.lastPrefixHash ?? undefined,
+		});
+
+		// Emit dashboard event
+		runtime.dashboard.event("context_health", {
+			composite,
+			drift,
+			outputQuality,
+			errorRate: errorScore,
+			cacheHealth,
+			cachePoison,
+			turnIndex: event.turnIndex,
+		});
+
+		// Update ring buffers
+		runtime.recentTurnEmbeddings.push(emb);
+		if (runtime.recentTurnEmbeddings.length > RING_MAX) {
+			runtime.recentTurnEmbeddings.shift();
+		}
+		runtime.recentErrorCategories.push(runtime.lastErrorCategory);
+		if (runtime.recentErrorCategories.length > RING_MAX) {
+			runtime.recentErrorCategories.shift();
+		}
+	} catch (e) {
+		runtime.logger?.error("context_health_failed", {
+			error: String(e instanceof Error ? e.message : e),
+		});
+	}
+}

package/extensions/mega-runtime/reset-runtime.ts

@@ -42,7 +42,11 @@ export function resetRuntimeImpl(
 	self: ResetRuntimeContext,
 	sessionId: string | undefined,
 ): void {
-	const sid = normalizeSessionId(sessionId);
+	// Only call normalizeSessionId when a real sessionId string is passed.
+	// When undefined, keep the existing self.rt.sessionId (set by the real
+	// session-start / compact pipeline) so the early-return guard can fire and
+	// dashboard stats keyed by sessionId are not silently orphaned.
+	const sid = sessionId ? normalizeSessionId(sessionId) : self.rt.sessionId;
 	if (self.rt.sessionId === sid && self.rt.persistedThisSession) return; // same session, keep checkpoint memory
 	self.rt = {
 		sessionId: sid,

package/extensions/mega-runtime/runtime.ts

@@ -263,6 +263,13 @@ export class MegaRuntime {
 	diagCtxCutNull = 0; // computeLiveTrimCut returned null (anchor/boundary)
 	diagCtxThrown = 0; // live-trim try threw (caught)
 
+	// Context health instrumentation (v0.12): rolling ring buffers for
+	// drift detection + cache poison Layer 1 hash baseline.
+	recentTurnEmbeddings: number[][] = [];
+	recentErrorCategories: (string | null)[] = [];
+	lastPrefixHash: string | null = null;
+	lastErrorCategory: string | null = null;
+
 	/**
 	 * S26 capture instrumentation: the "model_snapshots empty → $0.00 cost card"
 	 * bug was invisible because captureModel swallowed the DB write in a silent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.11.12",
+  "version": "0.12.0",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/contextHealth/cachePoison.ts

@@ -0,0 +1,243 @@
+/**
+ * contextHealth/cachePoison.ts — tri-layer KV cache poison validator (v0.9.1).
+ *
+ * Three validation layers for detecting corrupted KV cache state. Each layer
+ * triggers independently; the composite score maps the number of triggered
+ * layers to a 0-1 health metric (1 = healthy, 0 = poisoned).
+ *
+ * Pure functions — zero I/O, zero SQLite, zero network. All inputs are
+ * primitive values or arrays passed in; this module makes no external calls
+ * and carries no state between invocations.
+ *
+ * Guardrails: no `any` (PREVENT-011), no un-null-checked JSON.parse
+ * (PREVENT-001), zero network (PREVENT-PI-004 trivially satisfied — this
+ * module never calls fetch or opens sockets).
+ */
+
+/** FNV-1a 32-bit offset basis (must match TrigramEmbedder._embedRaw). */
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+/** FNV-1a 32-bit prime (must match TrigramEmbedder._embedRaw). */
+const FNV_PRIME = 0x01000193;
+/** Max input characters for prefix hash (4 KB of UTF-16). */
+const PREFIX_HASH_CAP = 4096;
+
+// ─── Layer 1 — Hash validation ──────────────────────────────────────────────
+
+/**
+ * Compute a stable 32-bit FNV-1a hash over the first 4 KB of the concatenated
+ * message text. Returns a lower-case hex string.
+ *
+ * The algorithm is identical to `TrigramEmbedder._embedRaw`'s internal hash
+ * (offset basis 0x811c9dc5, prime 0x01000193), so any change visible to the
+ * embedder is also visible here.
+ */
+export function computePrefixHash(messages: string[]): string {
+	let combined = "";
+	for (let i = 0; i < messages.length; i++) {
+		combined += messages[i];
+		if (combined.length >= PREFIX_HASH_CAP) break;
+	}
+	const input = combined.length > PREFIX_HASH_CAP
+		? combined.slice(0, PREFIX_HASH_CAP)
+		: combined;
+
+	let h = FNV_OFFSET_BASIS;
+	for (let i = 0; i < input.length; i++) {
+		h ^= input.charCodeAt(i);
+		h = Math.imul(h, FNV_PRIME);
+	}
+	return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Layer 1: detect when the KV cache prefix has been silently mutated.
+ *
+ * Trigger conditions:
+ *   - cacheRead > 0  (cache was actually used)
+ *   - storedHash !== null  (we have a baseline from a prior turn)
+ *   - currentHash !== storedHash  (prefix text has drifted)
+ *
+ * Not triggered when: cache was never read, or no baseline exists (first turn).
+ */
+export function checkPrefixHash(
+	currentHash: string,
+	storedHash: string | null,
+	cacheRead: number,
+): { poisoned: boolean; detail: string } {
+	if (cacheRead === 0) {
+		return { poisoned: false, detail: "no cache read" };
+	}
+	if (storedHash === null) {
+		return { poisoned: false, detail: "no stored hash baseline" };
+	}
+	if (currentHash !== storedHash) {
+		return {
+			poisoned: true,
+			detail:
+				`prefix hash mismatch: cached prefix changed without cache invalidation (current=${currentHash} stored=${storedHash})`,
+		};
+	}
+	return { poisoned: false, detail: "prefix hash matches baseline" };
+}
+
+// ─── Layer 2 — Semantic validation ──────────────────────────────────────────
+
+/** Arithmetic mean of a non-empty number array. */
+function mean(values: number[]): number {
+	let sum = 0;
+	for (const v of values) sum += v;
+	return sum / values.length;
+}
+
+/**
+ * Layer 2: detect when cache-hit outputs are semantically worse than cache-miss
+ * outputs.
+ *
+ * Trigger conditions:
+ *   - both groups have at least 3 samples (statistical floor)
+ *   - cache-hit mean quality is more than 0.15 below cache-miss mean quality
+ *
+ * Not triggered when: insufficient data in either group.
+ */
+export function compareOutputQualityByCacheHit(
+	qualityByCacheHit: number[],
+	qualityByCacheMiss: number[],
+): { poisoned: boolean; detail: string } {
+	const hitN = qualityByCacheHit.length;
+	const missN = qualityByCacheMiss.length;
+
+	if (hitN < 3 || missN < 3) {
+		return {
+			poisoned: false,
+			detail: `insufficient quality samples: hit=${hitN} miss=${missN} (need >= 3 each)`,
+		};
+	}
+
+	const hitMean = mean(qualityByCacheHit);
+	const missMean = mean(qualityByCacheMiss);
+	const threshold = missMean - 0.15;
+
+	if (hitMean < threshold) {
+		return {
+			poisoned: true,
+			detail:
+				`cache-hit quality degraded: hitMean=${hitMean.toFixed(3)} missMean=${missMean.toFixed(3)} (threshold=${threshold.toFixed(3)})`,
+		};
+	}
+	return {
+		poisoned: false,
+		detail: `quality comparable: hitMean=${hitMean.toFixed(3)} missMean=${missMean.toFixed(3)}`,
+	};
+}
+
+// ─── Layer 3 — Behavioral validation ────────────────────────────────────────
+
+/**
+ * Layer 3: detect when errors cluster on cache-hit turns (indicating the cache
+ * is returning corrupt state rather than fresh computation catching them).
+ *
+ * Trigger conditions (all three must hold):
+ *   - sampleCount >= 5
+ *   - errorRateCacheHit > errorRateCacheMiss * 2  (hit error rate is >2x miss rate)
+ *   - errorRateCacheHit > 0.1  (absolute hit error rate is non-trivial)
+ *
+ * Not triggered when: insufficient observations.
+ */
+export function correlateErrorsWithCacheHits(
+	errorRateCacheHit: number,
+	errorRateCacheMiss: number,
+	sampleCount: number,
+): { poisoned: boolean; detail: string } {
+	if (sampleCount < 5) {
+		return {
+			poisoned: false,
+			detail: `insufficient behavioral samples: n=${sampleCount} (need >= 5)`,
+		};
+	}
+	if (
+		errorRateCacheHit > errorRateCacheMiss * 2 &&
+		errorRateCacheHit > 0.1
+	) {
+		return {
+			poisoned: true,
+			detail:
+				`error rate inflated on cache hits: hit=${errorRateCacheHit.toFixed(3)} miss=${errorRateCacheMiss.toFixed(3)} (2x breach + absolute floor)`,
+		};
+	}
+	return {
+		poisoned: false,
+		detail:
+			`error rates normal: hit=${errorRateCacheHit.toFixed(3)} miss=${errorRateCacheMiss.toFixed(3)}`,
+	};
+}
+
+// ─── Composite score ─────────────────────────────────────────────────────────
+
+/**
+ * Compute a 0-1 composite cache poison score from layer triggers.
+ *
+ * | triggered layers | score |
+ * |-----------------|-------|
+ * | 0               | 1.0   |
+ * | 1               | 0.3   |
+ * | 2               | 0.15  |
+ * | 3               | 0.0   |
+ *
+ * Higher = healthier.  Scores below ~0.3 warrant immediate cache invalidation.
+ */
+export function computeCachePoisonScore(
+	l1: boolean,
+	l2: boolean,
+	l3: boolean,
+): number {
+	const triggers = (l1 ? 1 : 0) + (l2 ? 1 : 0) + (l3 ? 1 : 0);
+	switch (triggers) {
+		case 0: return 1.0;
+		case 1: return 0.3;
+		case 2: return 0.15;
+		case 3: return 0.0;
+		default: return 0.0; // should never reach
+	}
+}
+
+/** Result shape returned by `evaluateCachePoison`. */
+export interface CachePoisonResult {
+	score: number;
+	layer1: { poisoned: boolean; detail: string };
+	layer2: { poisoned: boolean; detail: string };
+	layer3: { poisoned: boolean; detail: string };
+}
+
+/**
+ * Run all three validation layers and return a composite result.
+ *
+ * All arguments are primitive values; this function is pure and stateless.
+ */
+export function evaluateCachePoison(args: {
+	currentHash: string;
+	storedHash: string | null;
+	cacheRead: number;
+	qualityByCacheHit: number[];
+	qualityByCacheMiss: number[];
+	errorRateCacheHit: number;
+	errorRateCacheMiss: number;
+	sampleCount: number;
+}): CachePoisonResult {
+	const l1 = checkPrefixHash(args.currentHash, args.storedHash, args.cacheRead);
+	const l2 = compareOutputQualityByCacheHit(
+		args.qualityByCacheHit,
+		args.qualityByCacheMiss,
+	);
+	const l3 = correlateErrorsWithCacheHits(
+		args.errorRateCacheHit,
+		args.errorRateCacheMiss,
+		args.sampleCount,
+	);
+
+	return {
+		score: computeCachePoisonScore(l1.poisoned, l2.poisoned, l3.poisoned),
+		layer1: l1,
+		layer2: l2,
+		layer3: l3,
+	};
+}