pi-mega-compact 0.11.13 → 0.12.0

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/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.13",
+  "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,
+	};
+}

package/src/contextHealth/drift.ts

@@ -0,0 +1,107 @@
+/**
+ * drift.ts — rolling-window context drift detectors.
+ *
+ * Pure functions; no I/O. All vectors are number[] (the Embedder output type).
+ * Cosine similarity is used throughout (PREVENT-PI-004 safe — no network).
+ */
+import type { Vector } from "../embedder.js";
+import { cosineSimilarity } from "../embedder.js";
+
+// ─── Topic drift ────────────────────────────────────────────────────────────
+
+/**
+ * Compute topic drift as cosine similarity between the current embedding and
+ * the centroid of recent embeddings.
+ *
+ * Returns 0–1: 1 = no drift (current topic matches the recent window exactly),
+ * 0 = completely unrelated. Empty recentEmbs returns 1.0 (baseline, no prior).
+ *
+ * Centroid: element-wise arithmetic mean of recentEmbs.
+ * cosineSimilarity normalizes internally; centroid need not be unit-normalized.
+ */
+export function computeTopicDrift(currentEmb: Vector, recentEmbs: Vector[]): number {
+	if (recentEmbs.length === 0) return 1.0;
+
+	const dim = currentEmb.length;
+	// Element-wise mean of recent embeddings.
+	const centroid = new Array<number>(dim).fill(0);
+	for (const emb of recentEmbs) {
+		if (emb.length !== dim) continue; // defensive: skip mismatched-dim rows
+		for (let i = 0; i < dim; i++) {
+			centroid[i] += emb[i];
+		}
+	}
+	for (let i = 0; i < dim; i++) {
+		centroid[i] /= recentEmbs.length;
+	}
+
+	return cosineSimilarity(currentEmb, centroid);
+}
+
+// ─── Error escalation ───────────────────────────────────────────────────────
+
+/**
+ * Compute error-rate score from recent error categories.
+ *
+ * `recentErrorCategories` is a list of error-class strings, or null for
+ * non-error turns. Returns 1.0 when the list is empty (no data → assume healthy).
+ * The score is 1 - (non-null / total), so an entirely-error list scores 0.
+ */
+export function computeErrorEscalation(recentErrorCategories: (string | null)[]): number {
+	if (recentErrorCategories.length === 0) return 1.0;
+	let errors = 0;
+	for (const cat of recentErrorCategories) {
+		if (cat !== null) errors++;
+	}
+	return 1 - errors / recentErrorCategories.length;
+}
+
+// ─── Prefix instability ─────────────────────────────────────────────────────
+
+/**
+ * Compute prefix-stability score using the cache-health formula from
+ * perf-handler.ts (tryComputeCacheHealth → stabilityScore).
+ *
+ * The stability formula from perf-handler.ts:
+ *   instability = min(1, prefixBreakCount / (windowMinutes / 5 * 2))
+ *   stabilityScore = max(0, 1 - breakSamples.length / maxExpectedBreaks)
+ *
+ * Here we expose a direct formula:
+ *   instability = min(1, prefixBreakCount / (windowMinutes / 5 * 2))
+ *   score = 1 - instability
+ *        = max(0, 1 - min(1, prefixBreakCount / (windowMinutes / 5 * 2)))
+ *
+ * Returns 0–1: 1 = perfectly stable (no prefix breaks), 0 = maximally unstable.
+ * The window is expressed in minutes so the caller controls the lookback.
+ */
+export function computePrefixInstability(
+	prefixBreakCount: number,
+	windowMinutes: number,
+): number {
+	if (prefixBreakCount <= 0) return 1.0;
+	if (windowMinutes <= 0) return 1.0; // defensive: avoid div-by-zero
+	const maxExpectedBreaks = (windowMinutes / 5) * 2;
+	const instability = Math.min(1, prefixBreakCount / maxExpectedBreaks);
+	return Math.max(0, 1 - instability);
+}
+
+// ─── Composite drift score ───────────────────────────────────────────────────
+
+/**
+ * Weighted composite drift score from three sub-components.
+ *
+ * Weights are domain-informed:
+ *   topic drift (40%)  — the strongest signal of context-switching
+ *   error rate (35%)   — errors correlate strongly with confusion
+ *   prefix stability (25%) — cache instability is secondary to content quality
+ *
+ * Returns 0–1: 1 = no drift / perfectly healthy, 0 = severe drift.
+ */
+export function computeDriftScore(
+	topic: number,
+	error: number,
+	prefix: number,
+): number {
+	const raw = topic * 0.4 + error * 0.35 + prefix * 0.25;
+	return Math.max(0, Math.min(1, raw));
+}

package/src/contextHealth/outputQuality.ts

@@ -0,0 +1,139 @@
+/**
+ * outputQuality.ts — pure assistant-output text quality detectors.
+ *
+ * No I/O beyond the injected Embedder (which is fully local / PREVENT-PI-004).
+ * All functions are deterministic and side-effect free.
+ */
+import type { Embedder } from "../embedder.js";
+import { cosineSimilarity } from "../embedder.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Tokenize on whitespace; skip empty tokens. */
+function tokenizeWords(text: string): string[] {
+	return text.split(/\s+/).filter((w) => w.length > 0);
+}
+
+/** Split on sentence-terminating punctuation; skip empty. */
+function splitSentences(text: string): string[] {
+	return text.split(/[.!?]+/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// ─── Detectors ─────────────────────────────────────────────────────────────
+
+/**
+ * Repetition ratio via 3-gram overlap.
+ *
+ * Builds sliding 3-word windows over the token stream. Returns the fraction
+ * of 3-grams that appear more than once (i.e. are repeated). Range 0–1;
+ * values above 0.30 signal likely garbled / looping output.
+ */
+export function detectRepetition(text: string): number {
+	const words = tokenizeWords(text);
+	if (words.length < 3) return 0;
+	const count = new Map<string, number>();
+	for (let i = 0; i <= words.length - 3; i++) {
+		const gram = words.slice(i, i + 3).join(" ");
+		count.set(gram, (count.get(gram) ?? 0) + 1);
+	}
+	const total = words.length - 2;
+	if (total === 0) return 0;
+	let repeated = 0;
+	for (const n of count.values()) {
+		if (n > 1) repeated += n;
+	}
+	// Each duplicate occurrence beyond the first adds to the repeated count.
+	// Clamp total to total_3grams so the ratio stays in [0,1].
+	return Math.min(1, repeated / total);
+}
+
+/**
+ * Sentence-level coherence score via adjacent cosine similarity.
+ *
+ * Splits text into sentences, embeds each, and computes the cosine similarity
+ * between every consecutive pair. Returns the average. Range 0–1 (higher =
+ * more coherent); fewer than 2 sentences returns 1.0 (cannot measure).
+ */
+export function detectCoherence(text: string, embedder: Embedder): number {
+	const sentences = splitSentences(text);
+	if (sentences.length < 2) return 1.0;
+
+	let sum = 0;
+	let pairCount = 0;
+	for (let i = 0; i < sentences.length - 1; i++) {
+		const a = embedder.embed(sentences[i]);
+		const b = embedder.embed(sentences[i + 1]);
+		sum += cosineSimilarity(a, b);
+		pairCount++;
+	}
+	return pairCount > 0 ? sum / pairCount : 1.0;
+}
+
+/**
+ * Token-salad detector.
+ *
+ * A word is "recognized" if it has length ≥ 2 AND contains at least one vowel
+ * (a / e / i / o / u, case-insensitive). Returns the fraction of unrecognized
+ * words. Values above 0.6 suggest scrambled / token-confused output.
+ */
+export function detectTokenSalad(text: string): number {
+	const words = tokenizeWords(text);
+	if (words.length === 0) return 0;
+
+	const VOWELS = /[aeiou]/i;
+	let unrecognized = 0;
+	for (const w of words) {
+		if (w.length < 2 || !VOWELS.test(w)) unrecognized++;
+	}
+	return unrecognized / words.length;
+}
+
+/**
+ * True when the output is entirely absent or whitespace-only.
+ */
+export function detectEmptyOutput(text: string): boolean {
+	return text.trim().length === 0;
+}
+
+// ─── Composite ─────────────────────────────────────────────────────────────
+
+/**
+ * Compute the full output-quality profile for assistant output text.
+ *
+ * Returns a score 0–1 (1 = healthy) and the three sub-diagnostics.
+ *
+ * Penalty weights (sum to 1.0):
+ *   repetition  40% — repeated 3-grams are the strongest corruption signal
+ *   coherence   30% — incoherent sentence transitions
+ *   salad       30% — garbage tokens
+ *
+ * Empty output is a hard 0.0 (nothing to evaluate).
+ */
+export function computeOutputQuality(
+	text: string,
+	embedder: Embedder,
+): {
+	score: number;
+	repetitionRatio: number;
+	coherenceScore: number;
+	isEmpty: boolean;
+} {
+	const isEmpty = detectEmptyOutput(text);
+	if (isEmpty) {
+		return { score: 0.0, repetitionRatio: 0, coherenceScore: 1.0, isEmpty: true };
+	}
+
+	const repetitionRatio = detectRepetition(text);
+	const coherenceScore = detectCoherence(text, embedder);
+	const saladRatio = detectTokenSalad(text);
+
+	const repetitionPenalty = repetitionRatio * 0.4;
+	const coherencePenalty = (1 - coherenceScore) * 0.3;
+	const saladPenalty = saladRatio * 0.3;
+
+	const score = Math.max(0, Math.min(1,
+		1.0 - repetitionPenalty - coherencePenalty - saladPenalty,
+	));
+
+	return { score, repetitionRatio, coherenceScore, isEmpty: false };
+}