pi-mega-compact 0.11.13 → 0.12.0

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/store/sqlite/context-health.ts

@@ -0,0 +1,342 @@
+/**
+ * context-health.ts — `context_health` and `cache_poison_events` table accessors.
+ *
+ * Append-only per-turn Context Health metrics recorded during compactSession:
+ * drift_score, output_quality, error_score, cache_health, cache_poison,
+ * composite, repetition_ratio, coherence_score, and prefix_hash.
+ *
+ * Also records cache-poison advisory events when cache corruption/inconsistency
+ * is detected at a given cache layer.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL uses ? placeholders, no string-concatenated values.
+ * Pi-agnostic: no pi runtime types.
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+
+// ─── Shared row types ────────────────────────────────────────────────────────
+
+/** A single context_health row (as stored + returned). */
+export interface ContextHealthRow {
+	id: number;
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	composite: number;
+	modelId: string | null;
+	repetitionRatio: number | null;
+	coherenceScore: number | null;
+	prefixHash: string | null;
+}
+
+/** Latest summary row (most recent by ts). */
+export interface LatestContextHealth {
+	composite: number;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	ts: number;
+	modelId: string | null;
+}
+
+/** A single cache_poison_events row (as stored + returned). */
+export interface CachePoisonEvent {
+	id: number;
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	layer: number | null;
+	detail: string | null;
+	severity: string | null;
+}
+
+// ─── context_health accessors ────────────────────────────────────────────────
+
+/**
+ * Record one context health sample. All values are fully parameterized
+ * (PREVENT-002). Optional columns (model_id, repetition_ratio, coherence_score,
+ * prefix_hash) are passed as-is; the column list enumerates every field so
+ * missing optional fields are NULL in the row.
+ *
+ * Non-fatal: any write error is logged to stderr and silently swallowed so
+ * instrumentation can never block the agent loop.
+ */
+export function recordContextHealthRow(
+	stateDir: string = getStateDir(),
+	row: {
+		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;
+	},
+): void {
+	try {
+		const db = openStore(stateDir);
+		db.prepare(
+			`INSERT INTO context_health
+			   (ts, turn_index, session_id, drift_score, output_quality,
+			    error_score, cache_health, cache_poison, composite,
+			    model_id, repetition_ratio, coherence_score, prefix_hash)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			row.ts,
+			row.turnIndex,
+			row.sessionId,
+			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 (err) {
+		// Non-fatal: log and continue — health sampling must never block the agent.
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[context-health] recordContextHealthRow error: ${msg}\n`);
+	}
+}
+
+/**
+ * Read context health rows since `sinceTs`. When `modelId` is provided the
+ * query adds an AND filter; otherwise all models are returned. Results are
+ * ordered ascending by ts. Returns an empty array on any error (non-fatal).
+ *
+ * SQL is fully parameterized (PREVENT-002).
+ */
+export function readContextHealthRows(
+	stateDir: string = getStateDir(),
+	sinceTs: number,
+	modelId?: string,
+): ContextHealthRow[] {
+	try {
+		const db = openStore(stateDir);
+		let rows: Array<{
+			id: number;
+			ts: number;
+			turn_index: number;
+			session_id: string;
+			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;
+		}>;
+
+		if (modelId != null) {
+			rows = db
+				.prepare(
+					`SELECT id, ts, turn_index, session_id, 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`,
+				)
+				.all(sinceTs, modelId) as typeof rows;
+		} else {
+			rows = db
+				.prepare(
+					`SELECT id, ts, turn_index, session_id, 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`,
+				)
+				.all(sinceTs) as typeof rows;
+		}
+
+		return rows.map((r) => ({
+			id: r.id,
+			ts: r.ts,
+			turnIndex: r.turn_index,
+			sessionId: r.session_id,
+			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,
+			repetitionRatio: r.repetition_ratio,
+			coherenceScore: r.coherence_score,
+			prefixHash: r.prefix_hash,
+		}));
+	} catch {
+		// Non-fatal: return empty array on DB error.
+		return [];
+	}
+}
+
+/**
+ * Read the most recent context_health row (ORDER BY ts DESC LIMIT 1).
+ * Returns null when no rows exist or on any error.
+ */
+export function readLatestContextHealth(
+	stateDir: string = getStateDir(),
+): LatestContextHealth | null {
+	try {
+		const db = openStore(stateDir);
+		const row = db
+			.prepare(
+				`SELECT composite, drift_score, output_quality, error_score,
+				        cache_health, cache_poison, ts, model_id
+				 FROM context_health
+				 ORDER BY ts DESC
+				 LIMIT 1`,
+			)
+			.get() as
+			| {
+					composite: number;
+					drift_score: number;
+					output_quality: number;
+					error_score: number;
+					cache_health: number;
+					cache_poison: number;
+					ts: number;
+					model_id: string | null;
+				}
+			| undefined;
+
+		if (!row) return null;
+		return {
+			composite: row.composite,
+			driftScore: row.drift_score,
+			outputQuality: row.output_quality,
+			errorScore: row.error_score,
+			cacheHealth: row.cache_health,
+			cachePoison: row.cache_poison,
+			ts: row.ts,
+			modelId: row.model_id,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Read the trailing `limit` composite scores (most recent first), then reverse
+ * to chronological order for sparkline rendering. Returns an empty array when
+ * no rows exist or on any error.
+ *
+ * SQL is fully parameterized (PREVENT-002).
+ */
+export function readContextHealthTrend(
+	stateDir: string = getStateDir(),
+	limit: number,
+): number[] {
+	try {
+		const db = openStore(stateDir);
+		const rows = db
+			.prepare(
+				`SELECT composite FROM context_health
+				 ORDER BY ts DESC LIMIT ?`,
+			)
+			.all(limit) as Array<{ composite: number }>;
+
+		// Reverse to chronological (oldest first) for sparkline display.
+		return rows.map((r) => r.composite).reverse();
+	} catch {
+		return [];
+	}
+}
+
+// ─── cache_poison_events accessors ───────────────────────────────────────────
+
+/**
+ * Record one cache poison advisory event. Fully parameterized (PREVENT-002).
+ * Non-fatal: write errors are logged to stderr and silently swallowed.
+ */
+export function recordCachePoisonEvent(
+	stateDir: string = getStateDir(),
+	event: {
+		ts: number;
+		turnIndex: number;
+		sessionId: string;
+		layer: number;
+		detail: string;
+		severity: "warn" | "alert";
+	},
+): void {
+	try {
+		const db = openStore(stateDir);
+		db.prepare(
+			`INSERT INTO cache_poison_events
+			   (ts, turn_index, session_id, layer, detail, severity)
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+		).run(event.ts, event.turnIndex, event.sessionId, event.layer, event.detail, event.severity);
+	} catch (err) {
+		// Non-fatal: advisory logging must never block the agent loop.
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[context-health] recordCachePoisonEvent error: ${msg}\n`);
+	}
+}
+
+/**
+ * Read cache poison events since `sinceTs`, ordered descending by ts (most
+ * recent first), capped at 100 rows. Returns an empty array on any error
+ * (non-fatal). SQL is fully parameterized (PREVENT-002).
+ */
+export function readCachePoisonEvents(
+	stateDir: string = getStateDir(),
+	sinceTs: number,
+): CachePoisonEvent[] {
+	try {
+		const db = openStore(stateDir);
+		const rows = db
+			.prepare(
+				`SELECT id, ts, turn_index, session_id, layer, detail, severity
+				 FROM cache_poison_events
+				 WHERE ts >= ?
+				 ORDER BY ts DESC
+				 LIMIT 100`,
+			)
+			.all(sinceTs) as Array<{
+			id: number;
+			ts: number;
+			turn_index: number;
+			session_id: string;
+			layer: number | null;
+			detail: string | null;
+			severity: string | null;
+		}>;
+
+		return rows.map((r) => ({
+			id: r.id,
+			ts: r.ts,
+			turnIndex: r.turn_index,
+			sessionId: r.session_id,
+			layer: r.layer,
+			detail: r.detail,
+			severity: r.severity,
+		}));
+	} catch {
+		return [];
+	}
+}

package/src/store/sqlite/schema.ts

@@ -4,7 +4,7 @@
 import type { DatabaseSync } from "node:sqlite";
 import { ACHIEVEMENT_DEFS } from "../../game/scoring.js";
 
-const SCHEMA_VERSION = 4;
+const SCHEMA_VERSION = 5;
 
 /**
  * Add `column` (with `decl`, e.g. "INTEGER") to `table` if it does not already
@@ -425,6 +425,48 @@ export function initSchema(db: DatabaseSync): void {
     );
     CREATE INDEX IF NOT EXISTS idx_emb_cache_computed
       ON embedding_cache(computed_at DESC);
+
+    -- A2 PLAN_V2 Phase 2 (SCHEMA_VERSION 5): Context Health metrics. One row
+    -- per turn recorded during compactSession. drift_score / output_quality /
+    -- error_score / cache_health / cache_poison / composite are the core signal
+    -- columns; repetition_ratio / coherence_score / prefix_hash are optional
+    -- enrichment. Parameterized accessors in context-health.ts (PREVENT-002).
+    CREATE TABLE IF NOT EXISTS context_health (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts              INTEGER NOT NULL,
+      turn_index      INTEGER NOT NULL,
+      session_id      TEXT NOT NULL,
+      drift_score     REAL,
+      output_quality  REAL,
+      error_score     REAL,
+      cache_health    REAL,
+      cache_poison    REAL,
+      composite       REAL,
+      model_id        TEXT,
+      repetition_ratio REAL,
+      coherence_score REAL,
+      prefix_hash     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_ctx_health_ts
+      ON context_health(ts);
+    CREATE INDEX IF NOT EXISTS idx_ctx_health_session
+      ON context_health(session_id, ts);
+
+    -- A2 PLAN_V2 Phase 2 (SCHEMA_VERSION 5): Cache poison advisory events.
+    -- Emitted when cache corruption / inconsistency is detected at a given
+    -- layer during compactSession. Drives the R13 advisory channel redesign.
+    -- Parameterized accessors in context-health.ts (PREVENT-002).
+    CREATE TABLE IF NOT EXISTS cache_poison_events (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts          INTEGER NOT NULL,
+      turn_index  INTEGER NOT NULL,
+      session_id  TEXT NOT NULL,
+      layer       INTEGER,
+      detail      TEXT,
+      severity    TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_cache_poison_ts
+      ON cache_poison_events(ts);
   `);
 	// Idempotent column migrations. `CREATE TABLE IF NOT EXISTS` is a no-op on a
 	// pre-existing table, so new columns added to context_chunks after a store was

package/src/store/sqlite.ts

@@ -24,6 +24,7 @@ export * from "./sqlite/game-state.js";
 export * from "./sqlite/game-scores.js";
 export * from "./sqlite/game-achievements.js";
 export * from "./sqlite/perf-samples.js";
+export * from "./sqlite/context-health.js";
 export * from "./sqlite/cache-stripes.js";
 export * from "./sqlite/turns.js";
 export * from "./sqlite/embedding-cache.js";