pi-mega-compact 0.11.13 → 0.12.0

package/dist/extensions/dashboard-server/routes-health.js

@@ -0,0 +1,81 @@
+/**
+ * routes-health.ts — Context Health + KV Cache Poison route handlers.
+ *
+ * GET /api/context-health — recent health rows, latest composite, trend,
+ *   per-model averages, alert flags. Accepts ?minutes=N (default 30).
+ * GET /api/cache-poison — recent cache poison events (last 30 min).
+ *
+ * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe),
+ * PREVENT-002 (parameterized SQL via accessors). Localhost dashboard.
+ */
+import { createRequire } from "node:module";
+export function handleContextHealth(req, res, ctx) {
+    if (!req.url?.startsWith("/api/context-health"))
+        return false;
+    try {
+        if (req.method !== "GET") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "method_not_allowed" }));
+            return true;
+        }
+        const url = new URL(req.url, "http://localhost");
+        const minutes = Math.max(1, Number(url.searchParams.get("minutes") ?? 30));
+        const sinceTs = Date.now() - minutes * 60_000;
+        const pfReq = createRequire(import.meta.url);
+        const { readLatestContextHealth, readContextHealthTrend, readContextHealthRows, } = pfReq("../../src/store/sqlite.js");
+        const latest = readLatestContextHealth(ctx.stateDir);
+        const trend = readContextHealthTrend(ctx.stateDir, 50);
+        const rows = readContextHealthRows(ctx.stateDir, sinceTs);
+        const perModel = new Map();
+        for (const r of rows) {
+            const mid = r.modelId ?? "(unknown)";
+            const entry = perModel.get(mid) ?? { sum: 0, count: 0 };
+            entry.sum += r.composite;
+            entry.count += 1;
+            perModel.set(mid, entry);
+        }
+        const perModelAverages = [...perModel.entries()].map(([modelId, v]) => ({
+            modelId,
+            avgComposite: v.count > 0 ? v.sum / v.count : 0,
+            sampleCount: v.count,
+        }));
+        const alerts = rows.filter((r) => r.composite < 0.5 || r.cachePoison < 0.3);
+        const body = {
+            updatedAt: new Date().toISOString(),
+            latest,
+            trend,
+            rows: rows.slice(-200),
+            perModel: perModelAverages,
+            alerts,
+        };
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(body));
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: String(e) }));
+    }
+    return true;
+}
+export function handleCachePoison(req, res, ctx) {
+    if (!req.url?.startsWith("/api/cache-poison"))
+        return false;
+    try {
+        if (req.method !== "GET") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "method_not_allowed" }));
+            return true;
+        }
+        const sinceTs = Date.now() - 30 * 60_000;
+        const pfReq = createRequire(import.meta.url);
+        const { readCachePoisonEvents } = pfReq("../../src/store/sqlite.js");
+        const events = readCachePoisonEvents(ctx.stateDir, sinceTs);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ updatedAt: new Date().toISOString(), events }));
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: String(e) }));
+    }
+    return true;
+}

package/dist/extensions/dashboard-server/routes.js

@@ -16,3 +16,4 @@ export { handleMemoryStatus } from "./routes-memory.js";
 export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
 export { handleMemoryMap } from "./routes-memory-map.js";
 export { handleCacheStripes } from "./routes-cache.js";
+export { handleContextHealth, handleCachePoison } from "./routes-health.js";

package/dist/extensions/dashboard-server/server.js

@@ -12,7 +12,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
-import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, handleContextHealth, handleCachePoison, handleStatic, } from "./routes.js";
 export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
@@ -207,6 +207,10 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleMemoryMap(req, res, ctx))
             return;
+        if (handleContextHealth(req, res, ctx))
+            return;
+        if (handleCachePoison(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/extensions/mega-config.js

@@ -180,6 +180,11 @@ export function loadConfig() {
         memoryGraphSeedMemories: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_MEMORIES", true),
         memoryGraphCrossTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_CROSS_TYPE_THRESHOLD", 0.85),
         memoryGraphWithinTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_WITHIN_TYPE_THRESHOLD", 0.7),
+        contextHealth: envBool("MEGACOMPACT_CONTEXT_HEALTH", true),
+        contextHealthDrift: envBool("MEGACOMPACT_CONTEXT_HEALTH_DRIFT", true),
+        contextHealthOutputQuality: envBool("MEGACOMPACT_CONTEXT_HEALTH_OUTPUT_QUALITY", true),
+        contextHealthCachePoison: envBool("MEGACOMPACT_CONTEXT_HEALTH_CACHE_POISON", true),
+        contextHealthMitigate: envBool("MEGACOMPACT_CONTEXT_HEALTH_MITIGATE", false),
         // D.1: env-overridable recompact delta (minimum context growth % before
         // re-compacting instead of replaying the cached live trim). Default 50.
         recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),

package/dist/extensions/mega-events/agent-handlers.js

@@ -12,6 +12,7 @@ import { vectorStats } from "../../src/vectorStore.js";
 import { defaultEmbedder } from "../../src/embedder.js";
 import { storeTopicEmbedding, loadTopicEmbedding, detectTopicShift, } from "./separated-prompt.js";
 import { refreshStripeAssignments as writeStripeAssignments, } from "../../src/cache-stripe-impl.js";
+import { handleTurnEndHealth } from "./health-handler.js";
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(pi, runtime, config) {
     // ---- Agent tracking for real-time widget + status-line updates ---------
@@ -252,6 +253,7 @@ export function registerAgentHandlers(pi, runtime, config) {
     pi.on("turn_end", async (event, ctx) => {
         runtime.dashboard.event("turn_end", { turnIndex: event.turnIndex });
         runtime.snapshot(ctx);
+        runtime.lastErrorCategory = null;
         // S53: consume staged recall blocks ONLY if they were actually injected
         // into a view this turn. If no context event fired (edge: turn ended
         // before any LLM call), recallInjectedThisTurn stays false and the blocks
@@ -372,6 +374,7 @@ export function registerAgentHandlers(pi, runtime, config) {
             else {
                 const category = classifyError(event.message);
                 const detail = classifyErrorDetailed(event.message);
+                runtime.lastErrorCategory = category;
                 // R3: stateful poisoned-context signal — repeated identical error text
                 // across consecutive turns. The classifier is stateless, so this
                 // upgrade happens here. A 'transient' (or 'poisoned-context') turn
@@ -781,5 +784,7 @@ export function registerAgentHandlers(pi, runtime, config) {
                 /* non-fatal: stripe refresh never breaks the agent loop */
             }
         }
+        // v0.12: Context Health — compute + persist health score. Non-fatal.
+        handleTurnEndHealth(event, runtime, config);
     });
 }

package/dist/extensions/mega-events/health-handler.js

@@ -0,0 +1,156 @@
+/**
+ * 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 { 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, } 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) {
+    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.text ?? "") : ""))
+            .join(" ");
+    }
+    return "";
+}
+/** Extract messages as string array for prefix hash (cache poison Layer 1). */
+function extractMessageTexts(event) {
+    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.text ?? "") : ""));
+    }
+    return [];
+}
+/** Handle turn_end: compute + persist context health. Non-fatal. */
+export function handleTurnEndHealth(event, runtime, config) {
+    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 = {
+            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/dist/extensions/mega-runtime/runtime.js

@@ -215,6 +215,12 @@ export class MegaRuntime {
     diagCtxRunSkipped = 0; // runCompact() returned skipped
     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 = [];
+    recentErrorCategories = [];
+    lastPrefixHash = null;
+    lastErrorCategory = 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/dist/src/contextHealth/cachePoison.js

@@ -0,0 +1,183 @@
+/**
+ * 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) {
+    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, storedHash, cacheRead) {
+    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) {
+    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, qualityByCacheMiss) {
+    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, errorRateCacheMiss, sampleCount) {
+    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, l2, l3) {
+    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
+    }
+}
+/**
+ * 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) {
+    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/dist/src/contextHealth/drift.js

@@ -0,0 +1,89 @@
+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, recentEmbs) {
+    if (recentEmbs.length === 0)
+        return 1.0;
+    const dim = currentEmb.length;
+    // Element-wise mean of recent embeddings.
+    const centroid = new Array(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) {
+    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, windowMinutes) {
+    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, error, prefix) {
+    const raw = topic * 0.4 + error * 0.35 + prefix * 0.25;
+    return Math.max(0, Math.min(1, raw));
+}