pi-mega-compact 0.11.12 → 0.12.0

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 };
+}

package/src/contextHealth.ts

@@ -0,0 +1,191 @@
+/**
+ * contextHealth.ts — Context Health scoring engine.
+ *
+ * Composite scoring + SQLite persistence for session-level context quality
+ * telemetry. The three sub-scoring modules are:
+ *   outputQuality.ts — assistant output text analysis
+ *   drift.ts         — rolling-window topic / error / prefix drift
+ *
+ * All SQL is fully parameterized (PREVENT-002). The `context_health` table
+ * is created inline on first write so this module is self-contained and does
+ * not require schema.ts to be modified (no existing files touched).
+ *
+ * PREVENT-PI-004: local SQLite only, zero network. All I/O is node:sqlite.
+ * PREVENT-011: no `any` — all row shapes are typed.
+ */
+import { openStore } from "./store/sqlite/utils.js";
+
+// ─── Composite score ─────────────────────────────────────────────────────────
+
+/** Sub-scores fed into the composite health score. */
+export interface ContextHealthSubScores {
+	/** Topic drift score (0–1, higher = less drift). */
+	drift: number;
+	/** Output quality score (0–1, higher = healthier output). */
+	outputQuality: number;
+	/** Error-rate score (0–1, higher = fewer errors). */
+	errorRate: number;
+	/** Cache health score (0–1, higher = healthier cache). */
+	cacheHealth: number;
+	/** Cache poison score (0–1, higher = less poison). */
+	cachePoison: number;
+}
+
+/**
+ * Weighted composite health score from five sub-dimensions.
+ *
+ * Weights:
+ *   output quality  22% — primary measure of model output health
+ *   drift           22% — session-level coherence
+ *   cache poison    20% — prompt-cache integrity
+ *   cache health    18% — cache hit rate stability
+ *   error rate      18% — error frequency
+ *
+ * Returns 0–1: 1 = fully healthy, 0 = severely degraded.
+ */
+export function computeHealthScore(sub: ContextHealthSubScores): number {
+	const raw =
+		sub.outputQuality * 0.22 +
+		sub.drift * 0.22 +
+		sub.cachePoison * 0.20 +
+		sub.cacheHealth * 0.18 +
+		sub.errorRate * 0.18;
+	return Math.max(0, Math.min(1, raw));
+}
+
+// ─── SQLite persistence ───────────────────────────────────────────────────────
+
+/** A single row as stored in + returned from the context_health table. */
+export interface ContextHealthRow {
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	composite: number;
+	modelId?: string;
+	repetitionRatio?: number;
+	coherenceScore?: number;
+	prefixHash?: string;
+}
+
+/**
+ * Record one context health sample into the SQLite store.
+ *
+ * Non-fatal: errors are caught and silently ignored so instrumentation never
+ * blocks the agent loop. Table schema is owned by schema.ts (SCHEMA_VERSION 5).
+ *
+ * PREVENT-002: all values are bound as parameters (? placeholders).
+ */
+export function recordContextHealth(
+	stateDir: string,
+	row: ContextHealthRow,
+): void {
+	try {
+		const db = openStore(stateDir);
+		db.prepare(
+			`INSERT INTO context_health
+       (ts, session_id, turn_index, drift_score, output_quality,
+        error_score, cache_health, cache_poison, composite,
+        model_id, repetition_ratio, coherence_score, prefix_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			row.ts,
+			row.sessionId,
+			row.turnIndex,
+			row.driftScore,
+			row.outputQuality,
+			row.errorScore,
+			row.cacheHealth,
+			row.cachePoison,
+			row.composite,
+			row.modelId ?? null,
+			row.repetitionRatio ?? null,
+			row.coherenceScore ?? null,
+			row.prefixHash ?? null,
+		);
+	} catch {
+		/* non-fatal: context health instrumentation never blocks the agent loop */
+	}
+}
+
+/**
+ * Read context health samples since `sinceTs`, optionally filtered by modelId.
+ *
+ * Returns rows in ascending ts order. Non-fatal (empty array on error).
+ *
+ * PREVENT-002: modelId is bound as a parameter (? placeholder).
+ * PREVENT-001: row.meta column (if added later) is handled by null-safe reads.
+ */
+export function readContextHealth(
+	stateDir: string,
+	sinceTs: number,
+	modelId?: string,
+): ContextHealthRow[] {
+	try {
+		const db = openStore(stateDir);
+		const sql = modelId
+			? `SELECT ts, session_id, turn_index, drift_score, output_quality,
+              error_score, cache_health, cache_poison, composite,
+              model_id, repetition_ratio, coherence_score, prefix_hash
+         FROM context_health
+         WHERE ts >= ? AND model_id = ?
+         ORDER BY ts ASC`
+			: `SELECT ts, session_id, turn_index, drift_score, output_quality,
+              error_score, cache_health, cache_poison, composite,
+              model_id, repetition_ratio, coherence_score, prefix_hash
+         FROM context_health
+         WHERE ts >= ?
+         ORDER BY ts ASC`;
+		const params = modelId ? [sinceTs, modelId] : [sinceTs];
+		const rows = db.prepare(sql).all(...params) as Array<{
+			ts: number;
+			session_id: string;
+			turn_index: number;
+			drift_score: number;
+			output_quality: number;
+			error_score: number;
+			cache_health: number;
+			cache_poison: number;
+			composite: number;
+			model_id: string | null;
+			repetition_ratio: number | null;
+			coherence_score: number | null;
+			prefix_hash: string | null;
+		}>;
+		const out: ContextHealthRow[] = [];
+		for (const r of rows) {
+			out.push({
+				ts: r.ts,
+				sessionId: r.session_id,
+				turnIndex: r.turn_index,
+				driftScore: r.drift_score,
+				outputQuality: r.output_quality,
+				errorScore: r.error_score,
+				cacheHealth: r.cache_health,
+				cachePoison: r.cache_poison,
+				composite: r.composite,
+				modelId: r.model_id ?? undefined,
+				repetitionRatio: r.repetition_ratio ?? undefined,
+				coherenceScore: r.coherence_score ?? undefined,
+				prefixHash: r.prefix_hash ?? undefined,
+			});
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
+// ─── Re-exports for consumers ────────────────────────────────────────────────
+
+export { computeOutputQuality } from "./contextHealth/outputQuality.js";
+export {
+	computeTopicDrift,
+	computeErrorEscalation,
+	computePrefixInstability,
+	computeDriftScore,
+} from "./contextHealth/drift.js";

package/src/memoryGraph/gates.ts

@@ -112,7 +112,7 @@ export function gatePromotionGuard(ws: GraphWorkingSet): GateResult {
       continue;
     }
     const epochId = n.epochId;
-    if (epochId && checkpointIds.has(epochId)) {
+    if (epochId && checkpointIds.size > 0 && checkpointIds.has(epochId)) {
       droppedIds.add(n.id);
       dropped++;
       log.warn("graph_orphaned_epoch", {

package/src/memoryGraph/sources.ts

@@ -51,16 +51,26 @@ export function buildCheckpointNodes(
   nodes: MemoryGraphNode[],
   edges: MemoryGraphEdge[],
 ): void {
-  const rows = db
-    .prepare(
-      `SELECT id, session_id, summary, token_estimate, timestamp,
-              dedup_status, topic_summary, key_decisions,
-              normalized_text, embedding_blob
-       FROM context_chunks
-       WHERE session_id = ?
-       ORDER BY timestamp ASC`,
-    )
-    .all(sessionId) as Array<Record<string, unknown>>;
+  const rows = sessionId
+    ? (db
+        .prepare(
+          `SELECT id, session_id, summary, token_estimate, timestamp,
+                  dedup_status, topic_summary, key_decisions,
+                  normalized_text, embedding_blob
+           FROM context_chunks
+           WHERE session_id = ?
+           ORDER BY timestamp ASC`,
+        )
+        .all(sessionId) as Array<Record<string, unknown>>)
+    : (db
+        .prepare(
+          `SELECT id, session_id, summary, token_estimate, timestamp,
+                  dedup_status, topic_summary, key_decisions,
+                  normalized_text, embedding_blob
+           FROM context_chunks
+           ORDER BY timestamp ASC`,
+        )
+        .all() as Array<Record<string, unknown>>);
 
   if (rows.length === 0) return;
 
@@ -136,15 +146,24 @@ export function buildTurnNodes(
   edges: MemoryGraphEdge[],
 ): void {
   const existingIds = new Set(nodes.map((n) => n.id));
-  const rows = db
-    .prepare(
-      `SELECT turn_index, role, pressure_band, ctx_tokens, ctx_percent,
-              epoch_id, ended_at
-       FROM turns
-       WHERE session_id = ?
-       ORDER BY turn_index ASC`,
-    )
-    .all(sessionId) as Array<Record<string, unknown>>;
+  const rows = sessionId
+    ? (db
+        .prepare(
+          `SELECT turn_index, role, pressure_band, ctx_tokens, ctx_percent,
+                  epoch_id, ended_at
+           FROM turns
+           WHERE session_id = ?
+           ORDER BY turn_index ASC`,
+        )
+        .all(sessionId) as Array<Record<string, unknown>>)
+    : (db
+        .prepare(
+          `SELECT turn_index, role, pressure_band, ctx_tokens, ctx_percent,
+                  epoch_id, ended_at
+           FROM turns
+           ORDER BY turn_index ASC`,
+        )
+        .all() as Array<Record<string, unknown>>);
 
   if (rows.length === 0) return;
 
@@ -197,15 +216,24 @@ export function buildTurnContentNodes(
   // (identity_merge) merges them with the richest nodeType winning. Using the
   // global nodes array here would skip every node (Source A already added them).
   const seen = new Set<string>();
-  const rows = db
-    .prepare(
-      `SELECT t.turn_index, t.role, t.ended_at, r.content_bytes
-       FROM turns t
-       JOIN raw_transcript r ON r.session_id = t.session_id AND r.turn_index = t.turn_index
-       WHERE t.session_id = ?
-       ORDER BY t.turn_index ASC`,
-    )
-    .all(sessionId) as Array<Record<string, unknown>>;
+  const rows = sessionId
+    ? (db
+        .prepare(
+          `SELECT t.turn_index, t.role, t.ended_at, r.content_bytes
+           FROM turns t
+           JOIN raw_transcript r ON r.session_id = t.session_id AND r.turn_index = t.turn_index
+           WHERE t.session_id = ?
+           ORDER BY t.turn_index ASC`,
+        )
+        .all(sessionId) as Array<Record<string, unknown>>)
+    : (db
+        .prepare(
+          `SELECT t.turn_index, t.role, t.ended_at, r.content_bytes
+           FROM turns t
+           JOIN raw_transcript r ON r.session_id = t.session_id AND r.turn_index = t.turn_index
+           ORDER BY t.turn_index ASC`,
+        )
+        .all() as Array<Record<string, unknown>>);
 
   if (rows.length === 0) return;