pi-mega-compact 0.11.4 → 0.11.6

package/dist/src/recallMetrics.js

@@ -0,0 +1,258 @@
+/**
+ * recallMetrics.ts — S45 CRAG quality metrics for recall evaluation.
+ *
+ * Four metrics evaluate the quality of a set of recall hits:
+ *   - relevance:     average cosine similarity (SearchHit.score) across hits
+ *   - coverage:      fraction of query sub-terms found in at least one hit summary
+ *   - diversity:     average pairwise cosine distance among top-K embeddings (MMR-style)
+ *   - specificity:   inverse document-frequency proxy via average chunk length
+ *
+ * Pi-agnostic: no pi runtime types, no network calls (PREVENT-PI-004).
+ * All config is passed explicitly; defaults are documented but NOT hardcoded
+ * inside the metric functions (the four constants from S45A.5 are also received
+ * via config, not baked in).
+ *
+ * Best-effort: all functions handle degenerate inputs (empty hits, missing
+ * embeddings, zero query terms) and return sensible defaults instead of NaN.
+ */
+import { cosineSimilarity } from "./embedder.js";
+import { STOP_WORDS } from "./config/stopwords.js";
+/** Default config — all values marked "uncalibrated" unless CRAG_CALIBRATED=true. */
+export const DEFAULT_RECALL_QUALITY_CONFIG = {
+    minDiversity: 0.3,
+    minCoverage: 0.4,
+    minRelevance: 0.5,
+    minOverallScore: 0.4,
+    weights: { relevance: 0.35, coverage: 0.25, diversity: 0.25, specificity: 0.15 },
+    specificityDivisor: 300,
+    specificityOptimalMin: 100,
+    specificityOptimalMax: 500,
+    idfBroadenRatio: 0.5,
+    stopwords: STOP_WORDS,
+    calibrated: false,
+};
+// ---------------------------------------------------------------------------
+// Metric helpers (exported individually for unit testing)
+// ---------------------------------------------------------------------------
+/**
+ * S45A.2: Relevance — average of SearchHit.score across all hits.
+ * Scores are already cosine similarities in [0, 1].
+ * Empty hits → 0.
+ */
+export function computeRelevance(hits) {
+    if (hits.length === 0)
+        return 0;
+    let sum = 0;
+    for (const h of hits)
+        sum += h.score;
+    return sum / hits.length;
+}
+/**
+ * S45A.3: Coverage — fraction of query subterms present in at least one
+ * hit's `checkpoint.summary`. Tokenization removes stopwords and short terms.
+ * Zero query terms after filtering → coverage = 1.0 (trivially satisfied).
+ */
+export function computeCoverage(query, hits, stopwords = STOP_WORDS) {
+    const queryTerms = tokenizeTerms(query, stopwords);
+    if (queryTerms.length === 0)
+        return 1.0;
+    if (hits.length === 0)
+        return 0;
+    let foundCount = 0;
+    for (const qt of queryTerms) {
+        const found = hits.some((h) => {
+            const summary = h.checkpoint.summary ?? "";
+            return summary.toLowerCase().includes(qt);
+        });
+        if (found)
+            foundCount++;
+    }
+    return foundCount / queryTerms.length;
+}
+/**
+ * S45A.4: Diversity — average pairwise cosine distance (1 - similarity)
+ * among hit embeddings. Filtered to hits with non-empty embedding arrays.
+ *
+ * Edge cases:
+ *   - < 2 valid hits → 1.0 (nothing to compare)
+ *   - empty-embedding checkpoints are skipped (no NaN path)
+ */
+export function computeDiversity(hits) {
+    const valid = hits.filter((h) => Array.isArray(h.checkpoint.embedding) && h.checkpoint.embedding.length > 0);
+    if (valid.length < 2)
+        return 1.0;
+    let totalDist = 0;
+    let pairCount = 0;
+    for (let i = 0; i < valid.length; i++) {
+        for (let j = i + 1; j < valid.length; j++) {
+            const sim = cosineSimilarity(valid[i].checkpoint.embedding, valid[j].checkpoint.embedding);
+            // cosineSimilarity returns 0 for empty vectors, but we've filtered those out.
+            // NaN/Infinity could theoretically arise from degenerate floats; guard defensively.
+            const dist = Number.isFinite(sim) ? 1 - sim : 1.0;
+            totalDist += dist;
+            pairCount++;
+        }
+    }
+    return pairCount > 0 ? totalDist / pairCount : 1.0;
+}
+/**
+ * S45A.5: Specificity — average chunk length (tokenEstimate) as a proxy
+ * for information density.
+ *
+ * Formula (all constants from config, NOT hardcoded):
+ *   avg = mean(tokenEstimate across hits; hits missing tokenEstimate → 0)
+ *   If avg < optimalMin / 2 → 0 (too short to be specific)
+ *   base = avg / divisor
+ *   If avg > optimalMax:
+ *     ramp = 1 - (avg - optimalMax) / optimalMax  // linear to 0 at 2*optimalMax
+ *     capped = max(0, ramp)
+ *     specificity = min(base, capped)
+ *   else:
+ *     specificity = min(base, 1)
+ *
+ * Edge cases: empty hits → 1.0 (nothing to penalize).
+ */
+export function computeSpecificity(hits, config) {
+    if (hits.length === 0)
+        return 1.0;
+    const { specificityDivisor: divisor, specificityOptimalMin: optMin, specificityOptimalMax: optMax } = config;
+    let sum = 0;
+    for (const h of hits) {
+        sum += h.checkpoint.tokenEstimate ?? 0;
+    }
+    const avg = sum / hits.length;
+    // Below optMin/2 → too short to be specific
+    if (avg < optMin / 2)
+        return 0;
+    const base = divisor > 0 ? avg / divisor : 0;
+    const clamped = base > 1 ? 1 : base;
+    if (avg > optMax) {
+        // Linear ramp-down from optMax to 0 at 2*optMax
+        const ramp = optMax > 0 ? 1 - (avg - optMax) / optMax : 0;
+        const capped = ramp > 0 ? ramp : 0;
+        return clamped < capped ? clamped : capped;
+    }
+    return clamped;
+}
+// ---------------------------------------------------------------------------
+// Composite evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a four-weight vector so its components sum to 1.0.
+ * If all weights are 0, return equal weights (0.25 each).
+ * Used defensively since users may set non-sum-1 weights via env.
+ */
+export function normalizeWeights(w) {
+    const sum = w.relevance + w.coverage + w.diversity + w.specificity;
+    if (sum === 0)
+        return { relevance: 0.25, coverage: 0.25, diversity: 0.25, specificity: 0.25 };
+    return {
+        relevance: w.relevance / sum,
+        coverage: w.coverage / sum,
+        diversity: w.diversity / sum,
+        specificity: w.specificity / sum,
+    };
+}
+/**
+ * S45A.6: Evaluate recall quality — compute all four metrics and return a
+ * composite result with pass/fail + recommendation.
+ */
+export function evaluateRecall(query, hits, config) {
+    const weights = normalizeWeights(config.weights);
+    const breakdown = {
+        relevance: computeRelevance(hits),
+        coverage: computeCoverage(query, hits, config.stopwords),
+        diversity: computeDiversity(hits),
+        specificity: computeSpecificity(hits, config),
+    };
+    const score = weights.relevance * breakdown.relevance +
+        weights.coverage * breakdown.coverage +
+        weights.diversity * breakdown.diversity +
+        weights.specificity * breakdown.specificity;
+    const pass = score >= config.minOverallScore &&
+        breakdown.relevance >= config.minRelevance &&
+        breakdown.coverage >= config.minCoverage &&
+        breakdown.diversity >= config.minDiversity;
+    const recommendation = buildRecommendation(breakdown, score, config);
+    return {
+        pass,
+        score,
+        breakdown,
+        recommendation,
+        uncalibrated: !config.calibrated,
+        weights,
+    };
+}
+// ---------------------------------------------------------------------------
+// Recommendation builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a human-readable recommendation based on which metric is lowest.
+ * Uses env-overridable thresholds from config (not hardcoded).
+ */
+function buildRecommendation(breakdown, score, config) {
+    // Check each metric against its threshold (lowest first for specificity).
+    const issues = [];
+    if (breakdown.diversity < config.minDiversity) {
+        issues.push("chunks are too similar — consider expanding K or using MMR");
+    }
+    if (breakdown.coverage < config.minCoverage) {
+        issues.push("query terms not well covered — consider query expansion");
+    }
+    if (breakdown.relevance < config.minRelevance) {
+        issues.push("chunks may be irrelevant — consider stricter threshold");
+    }
+    if (score < config.minOverallScore) {
+        issues.push("quality is low — recommend re-retrieval with expanded query");
+    }
+    return issues.length > 0 ? issues.join("; ") : null;
+}
+/**
+ * Compute recall quality metrics for a set of search hits.
+ *
+ * Pi-agnostic: takes query text and SearchHit results directly, no pi types.
+ * The `config` parameter is optional — when omitted, DEFAULT_RECALL_QUALITY_CONFIG
+ * is used (labelled uncalibrated).
+ *
+ * This is the primary export for external callers (e.g., recall.ts integration).
+ */
+export function computeRecallMetrics(query, results, config) {
+    const effectiveConfig = {
+        ...DEFAULT_RECALL_QUALITY_CONFIG,
+        ...config,
+        // Merge weights shallowly if both sides exist
+        weights: {
+            ...DEFAULT_RECALL_QUALITY_CONFIG.weights,
+            ...(config?.weights ?? {}),
+        },
+    };
+    const result = evaluateRecall(query, results, effectiveConfig);
+    return {
+        breakdown: result.breakdown,
+        score: result.score,
+        pass: result.pass,
+        recommendation: result.recommendation,
+        uncalibrated: result.uncalibrated,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Tokenize text into lowercased alphanumeric terms, filtering stop words
+ * and terms shorter than 3 characters.
+ */
+function tokenizeTerms(text, stopwords) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !stopwords.has(t));
+}
+/**
+ * Estimate block tokens for a piece of text (rough approximation).
+ * Used by the specificity metric fallback when tokenEstimate is missing.
+ */
+export function estimateBlockTokens(text) {
+    // ~4 chars per token for English text
+    return Math.ceil(text.length / 4);
+}

package/dist/src/store/sqlite/cache-stripes.js

@@ -0,0 +1,133 @@
+/**
+ * src/store/sqlite/cache-stripes.ts — Cache stripe distribution reader (A3, PLAN_V2 Phase 4).
+ *
+ * Reads from the cache_stripes table (schema.ts) to produce stripe distribution
+ * stats, stability aggregates, and a composite health score. Pi-agnostic.
+ *
+ * PREVENT-002: all queries use parameterized SQL.
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+/** Human-readable labels for each stripe tier (0=permanent .. 4=volatile). */
+const STRIPE_LABELS = {
+    0: "Permanent",
+    1: "Epoch",
+    2: "Topic",
+    3: "Thread",
+    4: "Volatile",
+};
+/** Weight per stripe for health scoring (higher = more stable = better). */
+const STRIPE_HEALTH_WEIGHTS = {
+    0: 1.0,
+    1: 0.8,
+    2: 0.5,
+    3: 0.25,
+    4: 0.0,
+};
+/**
+ * Read cache stripe distribution from the database.
+ *
+ * Returns aggregated per-stripe buckets with stability stats and a composite
+ * health score. Returns empty buckets (all zeros) when the table is empty,
+ * so the dashboard always has a valid response.
+ */
+export function readCacheStripes(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    // ── Fetch per-stripe aggregates ──
+    const rows = db
+        .prepare(`SELECT
+         stripe,
+         COUNT(*)                                         AS count,
+         ROUND(AVG(stability), 4)                         AS avgStability,
+         ROUND(MIN(stability), 4)                         AS minStability,
+         ROUND(MAX(stability), 4)                         AS maxStability
+       FROM cache_stripes
+       GROUP BY stripe
+       ORDER BY stripe ASC`)
+        .all();
+    // ── Latest epoch ──
+    const epochRow = db
+        .prepare(`SELECT epoch_id, MAX(assigned_at) AS last_refresh
+       FROM cache_stripes
+       WHERE epoch_id IS NOT NULL`)
+        .get();
+    // ── Total chunk count ──
+    const totalRow = db
+        .prepare("SELECT COUNT(*) AS cnt FROM cache_stripes")
+        .get();
+    const totalChunks = totalRow?.cnt ?? 0;
+    // ── Build bucket array (always 5 entries, stripe 0–4) ──
+    const rowMap = new Map();
+    for (const r of rows)
+        rowMap.set(r.stripe, r);
+    const buckets = [];
+    for (let s = 0; s <= 4; s++) {
+        const r = rowMap.get(s);
+        buckets.push({
+            stripe: s,
+            label: STRIPE_LABELS[s] ?? `Stripe ${s}`,
+            count: r?.count ?? 0,
+            avgStability: r?.avgStability ?? 0,
+            minStability: r?.minStability ?? 0,
+            maxStability: r?.maxStability ?? 0,
+        });
+    }
+    // ── Compute health score ──
+    const health = computeCacheHealth(buckets, totalChunks, stateDir);
+    return {
+        buckets,
+        health,
+        epochId: epochRow?.epoch_id ?? null,
+        lastRefreshAt: epochRow?.last_refresh ?? 0,
+        totalChunks,
+    };
+}
+/**
+ * Compute cache health from bucket distribution.
+ *
+ * Score = weighted sum of stripe fractions (normalised 0..1).
+ * Dominant tier = fraction of chunks in the top 2 stripes (0+1).
+ * Label: >= 0.8 = good, >= 0.6 = fair, >= 0.4 = degraded, else poor.
+ */
+function computeCacheHealth(buckets, total, stateDir) {
+    if (total === 0) {
+        return { score: 1, label: "good", dominantTier: 1, churnRate: 0 };
+    }
+    let weightedSum = 0;
+    let dominantCount = 0;
+    for (const b of buckets) {
+        const w = STRIPE_HEALTH_WEIGHTS[b.stripe] ?? 0;
+        weightedSum += (b.count / total) * w;
+        if (b.stripe <= 1)
+            dominantCount += b.count;
+    }
+    const dominantTier = dominantCount / total;
+    // ── Churn rate: open a new DB connection for the churn query ──
+    let churnRate = 0;
+    try {
+        const churnDb = openStore(stateDir);
+        const churnRow = churnDb
+            .prepare(`WITH
+          ranked AS (
+            SELECT chunk_id, epoch_id,
+                   ROW_NUMBER() OVER (PARTITION BY chunk_id ORDER BY assigned_at DESC) AS rn
+            FROM cache_stripes
+          ),
+          cur AS (SELECT chunk_id, epoch_id FROM ranked WHERE rn = 1),
+          prev AS (SELECT chunk_id, epoch_id FROM ranked WHERE rn = 2)
+        SELECT
+          COUNT(*) AS total_changed
+        FROM cur c
+        JOIN prev p ON c.chunk_id = p.chunk_id AND c.epoch_id != p.epoch_id`)
+            .get();
+        if (churnRow && total > 0) {
+            churnRate = Math.min(1, (churnRow.total_changed ?? 0) / total);
+        }
+    }
+    catch {
+        // churn unavailable — keep 0
+    }
+    const score = Math.round(weightedSum * 100) / 100;
+    const label = score >= 0.8 ? "good" : score >= 0.6 ? "fair" : score >= 0.4 ? "degraded" : "poor";
+    return { score, label, dominantTier, churnRate };
+}

package/dist/src/store/sqlite/fts5-search.js

@@ -0,0 +1,68 @@
+/**
+ * fts5-search.ts — FTS5 trigram search helper (L1 tier in the S44 tiered router).
+ *
+ * Runs BM25-ranked trigram search against the existing `context_chunks_trgm`
+ * virtual table (pg_trgm-equivalent, created in schema.ts). All queries are
+ * parameterized (PREVENT-002). Pi-agnostic — pure SQL over a node:sqlite
+ * DatabaseSync handle.
+ *
+ * The virtual table stores (id UNINDEXED, normalized_text) with tokenize='trigram'.
+ * FTS5 trigram queries tokenize the user query into overlapping 3-grams at query
+ * time automatically — no manual n-gram splitting needed. The BM25 rank from
+ * fts5 ranks results by trigram-overlap density.
+ */
+/**
+ * Search the context_chunks_trgm FTS5 table for checkpoints whose
+ * `normalized_text` matches `query` via trigram similarity.
+ *
+ * @param query  Raw search text (FTS5 trigram tokenizer handles n-gram splitting
+ *               automatically; input is NOT SQL-concatenated — bound as ? param).
+ * @param reader A sync-reader handle against the SQLite store.
+ * @param limit  Max results to return (default 10).
+ * @returns BM25-ranked hits, highest score first.
+ */
+export function fts5Search(query, reader, limit = 10) {
+    const sql = `
+    SELECT id, bm25(context_chunks_trgm, 0.0, 1.0) AS score
+    FROM context_chunks_trgm
+    WHERE context_chunks_trgm MATCH ?
+    ORDER BY score
+    LIMIT ?
+  `;
+    const rows = reader
+        .prepare(sql)
+        .all(query, limit);
+    return rows.map((r) => ({ id: r.id, score: r.score }));
+}
+/**
+ * Search with an optional session_id filter for scoped FTS5 recall.
+ *
+ * JOINs the FTS5 virtual table against the real `context_chunks` table on `id`
+ * so we can filter by `session_id` while still using FTS5 MATCH. The vtab
+ * stores `id UNINDEXED` (it's a row-key passthrough, not searchable text), so
+ * the join is safe and efficient via the `idx_chunks_pk` index.
+ *
+ * @param query     Raw search text.
+ * @param reader    Sync-reader handle against the SQLite store.
+ * @param sessionId Scope to a specific session (omit for cross-session search).
+ * @param limit     Max results (default 10).
+ */
+export function fts5SearchScoped(query, reader, sessionId, limit = 10) {
+    if (sessionId) {
+        const sql = `
+      SELECT t.id, bm25(context_chunks_trgm, 0.0, 1.0) AS score
+      FROM context_chunks_trgm AS t
+      INNER JOIN context_chunks AS c ON c.id = t.id
+      WHERE t.context_chunks_trgm MATCH ?
+        AND c.session_id = ?
+      ORDER BY score
+      LIMIT ?
+    `;
+        const rows = reader
+            .prepare(sql)
+            .all(query, sessionId, limit);
+        return rows.map((r) => ({ id: r.id, score: r.score }));
+    }
+    // No session filter — plain FTS5 search across all sessions.
+    return fts5Search(query, reader, limit);
+}

package/dist/src/store/sqlite/perf-samples.js

@@ -21,12 +21,14 @@ export const PERF_KINDS = [
     "provider_latency_ms",
     "tps",
     "cache_hit_pct",
+    "prefix_break",
     "rss_mb",
     "heap_mb",
     "cpu_user_ms",
     "cpu_sys_ms",
     "db_recompute_ms",
     "disk_write_ms",
+    "cache_health",
 ];
 function isPerfKind(k) {
     return PERF_KINDS.includes(k);
@@ -80,20 +82,39 @@ export function readPerfSamples(stateDir = getStateDir(), sinceTs = 0, kind) {
     return out;
 }
 /**
- * Read lifetime provider prompt cache aggregates from `perf_samples`.
- *
- * Aggregates `cache_creation_input_tokens` / `cache_read_input_tokens` from
- * the `meta` JSON column of `cache_hit_pct` samples (`json_extract`,
- * available in node:sqlite ≥22.13 / SQLite ≥3.38). Returns a zeroed
- * `ProviderCacheLifetime` when no samples exist (never undefined).
+ * Extract a model label from parsed meta (modelName or modelId), or null.
  */
-export function readProviderCacheLifetime(stateDir = getStateDir()) {
-    const db = openStore(stateDir);
-    const rows = db
-        .prepare(`SELECT ts, meta FROM perf_samples
-       WHERE kind = ?
-       ORDER BY ts ASC`)
-        .all("cache_hit_pct");
+function extractModelLabel(meta) {
+    if (typeof meta.modelName === "string" && meta.modelName.length > 0)
+        return meta.modelName;
+    if (typeof meta.modelId === "string" && meta.modelId.length > 0)
+        return meta.modelId;
+    return null;
+}
+/**
+ * Build sorted byModel array from the model aggregation map.
+ */
+function byModelFromMap(map) {
+    const out = [];
+    for (const [model, m] of map) {
+        out.push({
+            model,
+            hitPct: m.hitCount > 0 ? m.sumHitPct / m.hitCount : 0,
+            totalCacheRead: m.sumCr,
+            totalCacheWrite: m.sumCw,
+            sampleCount: m.samples,
+        });
+    }
+    out.sort((a, b) => b.sampleCount - a.sampleCount);
+    return out;
+}
+/**
+ * Aggregate `cache_hit_pct` rows (ts + parsed meta) into a
+ * `ProviderCacheLifetime`. Shared by the lifetime and window readers so both
+ * use the identical aggregation formula. `meta` is parsed defensively
+ * (PREVENT-001 null-safe). Rows must be ascending by ts.
+ */
+function aggregateCacheRows(rows) {
     if (rows.length === 0) {
         return {
             sampleCount: 0,
@@ -103,6 +124,7 @@ export function readProviderCacheLifetime(stateDir = getStateDir()) {
             totalInput: 0,
             firstSampleAt: null,
             latestSampleAt: null,
+            byModel: [],
         };
     }
     let totalCacheRead = 0;
@@ -110,6 +132,7 @@ export function readProviderCacheLifetime(stateDir = getStateDir()) {
     let totalInput = 0;
     let sumHitPct = 0;
     let hitPctCount = 0;
+    const modelMap = new Map();
     for (const r of rows) {
         if (r.meta != null) {
             let meta = null;
@@ -140,6 +163,31 @@ export function readProviderCacheLifetime(stateDir = getStateDir()) {
                     sumHitPct += (cr / denom) * 100;
                     hitPctCount++;
                 }
+                // Per-model grouping (F4)
+                const modelLabel = extractModelLabel(meta);
+                if (modelLabel != null) {
+                    let m = modelMap.get(modelLabel);
+                    if (!m) {
+                        m = {
+                            sumCr: 0,
+                            sumCw: 0,
+                            sumInp: 0,
+                            sumHitPct: 0,
+                            hitCount: 0,
+                            samples: 0,
+                        };
+                        modelMap.set(modelLabel, m);
+                    }
+                    m.sumCr += cr;
+                    m.sumCw += cw;
+                    m.sumInp += inp;
+                    m.samples++;
+                    if (denom > 0) {
+                        m.sumHitPct += (cr / denom) * 100;
+                        m.hitCount++;
+                    }
+                }
+                // Untagged samples are omitted from byModel
             }
         }
     }
@@ -151,8 +199,43 @@ export function readProviderCacheLifetime(stateDir = getStateDir()) {
         totalInput,
         firstSampleAt: new Date(rows[0].ts).toISOString(),
         latestSampleAt: new Date(rows[rows.length - 1].ts).toISOString(),
+        byModel: byModelFromMap(modelMap),
     };
 }
+/**
+ * Read lifetime provider prompt cache aggregates from `perf_samples`.
+ *
+ * Aggregates `cache_creation_input_tokens` / `cache_read_input_tokens` from
+ * the `meta` JSON column of `cache_hit_pct` samples (`json_extract`,
+ * available in node:sqlite >=22.13 / SQLite >=3.38). Returns a zeroed
+ * `ProviderCacheLifetime` when no samples exist (never undefined).
+ */
+export function readProviderCacheLifetime(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db
+        .prepare(`SELECT ts, meta FROM perf_samples
+	       WHERE kind = ?
+	       ORDER BY ts ASC`)
+        .all("cache_hit_pct");
+    return aggregateCacheRows(rows);
+}
+/**
+ * Read provider prompt cache aggregates over a trailing window of `minutes`
+ * (samples with ts >= now - minutes*60_000). Same aggregate shape as
+ * `readProviderCacheLifetime`; the existing lifetime reader is untouched.
+ * Returns a zeroed `ProviderCacheLifetime` when no samples fall in the window.
+ */
+export function readProviderCacheWindow(stateDir = getStateDir(), minutes) {
+    const db = openStore(stateDir);
+    const sinceTs = Date.now() - minutes * 60_000;
+    const rows = db
+        .prepare(`SELECT ts, meta FROM perf_samples
+	       WHERE kind = ? AND ts >= ?
+	       ORDER BY ts ASC`)
+        .all("cache_hit_pct", sinceTs);
+    return aggregateCacheRows(rows);
+}
+// ... keep every function below unchanged ...
 /**
  * Read the most recent `cache_hit_pct` value from `perf_samples`.
  *
@@ -164,9 +247,9 @@ export function readLatestCacheHitPct(stateDir = getStateDir()) {
     const db = openStore(stateDir);
     const row = db
         .prepare(`SELECT value FROM perf_samples
-       WHERE kind = ?
-       ORDER BY ts DESC, id DESC
-       LIMIT 1`)
+	       WHERE kind = ?
+	       ORDER BY ts DESC, id DESC
+	       LIMIT 1`)
         .get("cache_hit_pct");
     if (!row || typeof row.value !== "number" || !Number.isFinite(row.value))
         return 0;
@@ -183,3 +266,49 @@ export function readLatestCacheHitPct(stateDir = getStateDir()) {
 export function readProviderCacheForRepo(stateDir) {
     return readProviderCacheLifetime(stateDir);
 }
+/**
+ * Read `prefix_break` samples in a time window.
+ *
+ * @param stateDir  State directory for this repo.
+ * @param sinceTs   Lower bound (epoch ms). Pass 0 for no lower bound.
+ * @param untilTs   Upper bound (epoch ms). Pass 0 for no upper bound.
+ *                  Rows with ts > untilTs are excluded.
+ * @returns         Sorted ascending array of PrefixBreak rows.
+ *
+ * SQL is fully parameterized (PREVENT-002). `meta` is parsed defensively
+ * (PREVENT-001 null-safe). When no rows exist the return is an empty array.
+ */
+export function readPrefixBreaks(stateDir = getStateDir(), sinceTs = 0, untilTs = 0) {
+    const db = openStore(stateDir);
+    let rows;
+    if (untilTs > 0) {
+        const sql = `SELECT id, ts, value, meta FROM perf_samples
+		   WHERE kind = ? AND ts >= ? AND ts <= ? ORDER BY ts ASC`;
+        rows = db.prepare(sql).all("prefix_break", sinceTs, untilTs);
+    }
+    else {
+        const sql = `SELECT id, ts, value, meta FROM perf_samples
+		   WHERE kind = ? AND ts >= ? ORDER BY ts ASC`;
+        rows = db.prepare(sql).all("prefix_break", sinceTs);
+    }
+    const out = [];
+    for (const r of rows) {
+        let meta = null;
+        if (r.meta != null) {
+            try {
+                meta = JSON.parse(r.meta);
+            }
+            catch {
+                meta = null;
+            }
+        }
+        out.push({
+            id: r.id,
+            ts: r.ts,
+            kind: "prefix_break",
+            value: r.value,
+            meta: meta,
+        });
+    }
+    return out;
+}