pi-mega-compact 0.11.1 → 0.11.3

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

@@ -0,0 +1,293 @@
+/**
+ * dashboard-server/routes-maintenance.ts — S49B Maintenance tab API routes.
+ *
+ * Handlers for:
+ *   GET  /api/maintenance            — DB stats (table row counts + storage)
+ *   GET  /api/maintenance/schema-health — SCHEMA_VERSION + integrity audit
+ *   POST /api/maintenance/action     — Trigger a maintenance action
+ *
+ * All pi-agnostic; lazy-requires maintenance primitives to avoid a top-level
+ * import of the store from the dashboard server process. PREVENT-PI-004: local
+ * SQLite only; zero network calls.
+ */
+import { createRequire } from "node:module";
+// ---------------------------------------------------------------------------
+// Lazy imports (via createRequire)
+// ---------------------------------------------------------------------------
+const lazyMaintenance = (() => {
+    let mod = null;
+    return () => {
+        if (!mod)
+            mod = createRequire(import.meta.url)("../../src/store/sqlite/maintenance.js");
+        return mod;
+    };
+})();
+const lazyStoreUtils = (() => {
+    let mod = null;
+    return () => {
+        if (!mod)
+            mod = createRequire(import.meta.url)("../../src/store/sqlite/utils.js");
+        return mod;
+    };
+})();
+// ---------------------------------------------------------------------------
+// GET /api/maintenance and sub-paths
+// ---------------------------------------------------------------------------
+export function handleMaintenance(req, res, ctx) {
+    const url = req.url ?? "";
+    if (!url.startsWith("/api/maintenance"))
+        return false;
+    const method = (req.method ?? "GET").toUpperCase();
+    // ── GET /api/maintenance/schema-health ────────────────────────────
+    if (method === "GET" && url === "/api/maintenance/schema-health") {
+        sendSchemaHealth(res, ctx);
+        return true;
+    }
+    // ── POST /api/maintenance/action ──────────────────────────────────
+    if (method === "POST" && url === "/api/maintenance/action") {
+        handleMaintenanceAction(req, res, ctx);
+        return true;
+    }
+    // ── GET /api/maintenance ──────────────────────────────────────────
+    if (method === "GET" && url === "/api/maintenance") {
+        sendDbStats(res, ctx);
+        return true;
+    }
+    // ── Unknown sub-path ──────────────────────────────────────────────
+    sendJson(res, 404, { error: "not found" });
+    return true;
+}
+// ---------------------------------------------------------------------------
+// GET /api/maintenance — DB stats
+// ---------------------------------------------------------------------------
+function sendDbStats(res, ctx) {
+    try {
+        const { getDbStats } = lazyMaintenance();
+        const raw = getDbStats(ctx.stateDir);
+        const tables = Object.entries(raw.tableCounts).map(([table, rowCount]) => ({
+            table,
+            rowCount,
+        }));
+        sendJson(res, 200, {
+            type: "db-stats",
+            tables,
+            storage: {
+                files: {
+                    dbBytes: raw.dbBytes,
+                    walBytes: raw.walBytes,
+                    shmBytes: raw.shmBytes,
+                },
+                pageSize: raw.pageSize,
+                pageCount: raw.pageCount,
+                freelistPages: raw.freelistPages,
+            },
+        });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: err.message });
+    }
+}
+// ---------------------------------------------------------------------------
+// GET /api/maintenance/schema-health — schema version + integrity audit
+// ---------------------------------------------------------------------------
+function sendSchemaHealth(res, ctx) {
+    try {
+        const { integrityCheck } = lazyMaintenance();
+        const integrity = integrityCheck(ctx.stateDir);
+        const { openStore } = lazyStoreUtils();
+        const db = openStore(ctx.stateDir);
+        // SCHEMA_VERSION from meta table
+        const metaRow = db
+            .prepare("SELECT value FROM meta WHERE key = ?")
+            .get("schema_version");
+        const schemaVersion = metaRow ? Number(metaRow.value) : 0;
+        // PRAGMA foreign_key_check
+        const fkRows = db.prepare("PRAGMA foreign_key_check").all();
+        const fkCheck = fkRows.map((r) => JSON.stringify(r));
+        // Per-column audit: every ensureColumn migration column declared in
+        // schema.ts, checked via PRAGMA table_info (read-only).
+        const expectedColumns = [
+            {
+                table: "context_chunks",
+                column: "original_token_estimate",
+                decl: "INTEGER",
+            },
+            { table: "raw_transcript", column: "content_ref", decl: "TEXT" },
+            { table: "memories", column: "category", decl: "TEXT" },
+            { table: "memories", column: "target", decl: "TEXT" },
+            { table: "memories", column: "last_referenced", decl: "INTEGER" },
+            { table: "memories", column: "source_turn", decl: "INTEGER" },
+            { table: "raptor_nodes", column: "built_at", decl: "INTEGER" },
+            { table: "raw_transcript", column: "turn_index", decl: "INTEGER" },
+            { table: "session_state", column: "conversation_id", decl: "TEXT" },
+            { table: "session_state", column: "last_turn_id", decl: "INTEGER" },
+        ];
+        const columns = expectedColumns.map((ec) => {
+            const cols = db.prepare(`PRAGMA table_info(${ec.table})`).all();
+            const present = cols.some((c) => c.name === ec.column);
+            return {
+                table: ec.table,
+                column: ec.column,
+                present,
+                expectedDecl: ec.decl,
+            };
+        });
+        const healthy = integrity.length === 1 &&
+            integrity[0] === "ok" &&
+            columns.every((c) => c.present);
+        sendJson(res, 200, {
+            type: "schema-health",
+            schemaVersion,
+            integrity,
+            fkCheck,
+            columns,
+            healthy,
+        });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: err.message });
+    }
+}
+// ---------------------------------------------------------------------------
+// POST /api/maintenance/action — Trigger a maintenance action
+// ---------------------------------------------------------------------------
+function handleMaintenanceAction(req, res, ctx) {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+        body += chunk;
+        if (body.length > 10_000)
+            req.destroy();
+    });
+    req.on("end", () => {
+        let payload;
+        try {
+            payload = JSON.parse(body);
+            if (!payload || !payload.action) {
+                sendJson(res, 400, { error: "missing 'action' field" });
+                return;
+            }
+        }
+        catch {
+            sendJson(res, 400, { error: "invalid JSON" });
+            return;
+        }
+        try {
+            const m = lazyMaintenance();
+            const u = lazyStoreUtils();
+            // All destructive actions: temp backup first
+            if (payload.action !== "integrity-check") {
+                // Non-blocking — backup failure is non-fatal
+                m.backupDb(ctx.stateDir);
+            }
+            switch (payload.action) {
+                case "vacuum": {
+                    const r = m.vacuumDb(ctx.stateDir);
+                    sendJson(res, 200, {
+                        operation: "vacuum",
+                        success: true,
+                        affected: r.affected,
+                        reclaimedBytes: r.reclaimedBytes,
+                        summary: r.summary,
+                    });
+                    return;
+                }
+                case "checkpoint": {
+                    const r = m.checkpointWal(ctx.stateDir);
+                    sendJson(res, 200, {
+                        operation: "checkpoint",
+                        success: true,
+                        affected: r.affected,
+                        reclaimedBytes: r.reclaimedBytes,
+                        summary: r.summary,
+                    });
+                    return;
+                }
+                case "reindex": {
+                    const db = u.openStore(ctx.stateDir);
+                    db.exec("REINDEX");
+                    sendJson(res, 200, {
+                        operation: "reindex",
+                        success: true,
+                        affected: 0,
+                        reclaimedBytes: 0,
+                        summary: "REINDEX completed",
+                    });
+                    return;
+                }
+                case "fts5-rebuild": {
+                    const db = u.openStore(ctx.stateDir);
+                    db.exec("INSERT INTO context_chunks_trgm(context_chunks_trgm) VALUES('rebuild')");
+                    sendJson(res, 200, {
+                        operation: "fts5-rebuild",
+                        success: true,
+                        affected: 0,
+                        reclaimedBytes: 0,
+                        summary: "FTS5 rebuild triggered",
+                    });
+                    return;
+                }
+                case "reconcile-dedup": {
+                    const r = m.reconcileDedupMirror(ctx.stateDir);
+                    const lines = [];
+                    if (r.fixedRefCount)
+                        lines.push(`${r.fixedRefCount} ref_counts corrected`);
+                    if (r.orphansDeleted)
+                        lines.push(`${r.orphansDeleted} orphans deleted`);
+                    if (r.refsBackfilled)
+                        lines.push(`${r.refsBackfilled} refs backfilled`);
+                    sendJson(res, 200, {
+                        operation: "reconcile-dedup",
+                        success: true,
+                        affected: r.fixedRefCount + r.orphansDeleted + r.refsBackfilled,
+                        reclaimedBytes: 0,
+                        summary: lines.length ? lines.join(", ") : "nothing to fix",
+                    });
+                    return;
+                }
+                case "prune": {
+                    const days = Number(payload.daysOld) || 30;
+                    const r = m.pruneOldRows(ctx.stateDir, days);
+                    sendJson(res, 200, {
+                        operation: "prune",
+                        success: true,
+                        affected: r.affected,
+                        reclaimedBytes: r.reclaimedBytes,
+                        summary: r.summary,
+                    });
+                    return;
+                }
+                case "integrity-check": {
+                    const lines = m.integrityCheck(ctx.stateDir);
+                    sendJson(res, 200, {
+                        operation: "integrity-check",
+                        success: lines.length === 1 && lines[0] === "ok",
+                        affected: 0,
+                        reclaimedBytes: 0,
+                        summary: lines.join("; "),
+                        detail: lines,
+                    });
+                    return;
+                }
+                default:
+                    sendJson(res, 400, {
+                        error: `unknown action: ${payload.action}`,
+                    });
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// JSON helper
+// ---------------------------------------------------------------------------
+function sendJson(res, status, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+    });
+    res.end(body);
+}

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

@@ -7,6 +7,9 @@ import { readSnapshot } from "./snapshot.js";
 import { dashboardHtml } from "./html.js";
 import { readIndex, getIndexDir } from "./index-reader.js";
 import { ACTIVE_WINDOW_SEC } from "./types.js";
+import { readProviderCacheForRepo } from "../../src/store/sqlite/perf-samples.js";
+import { computeCacheSavings, lookupModelInputRate } from "../../src/pricing.js";
+import { latestModelSnapshot } from "../../src/store/sqlite/model-snapshots.js";
 // ---------------------------------------------------------------------------
 // handleIndex — "/" | "/index.html" | "/api/snapshot" | "/api/version"
 // ---------------------------------------------------------------------------
@@ -132,6 +135,27 @@ export function handleRepoIndex(req, res, ctx) {
                         out.compacts = snap.compacts ?? null;
                         out.timeSaved = snap.timeSaved ?? null;
                         out.updatedAt = snap.updatedAt ?? null;
+                        // Provider cache per-repo lifetime (E.2)
+                        try {
+                            const pc = readProviderCacheForRepo(r.stateDir);
+                            // Price from model snapshot if available
+                            const modelSnap = latestModelSnapshot(r.stateDir);
+                            const inputRate = modelSnap
+                                ? modelSnap.inputRate
+                                : lookupModelInputRate(r.modelName ?? "") ?? 0;
+                            const savings = computeCacheSavings(pc.totalCacheRead, pc.totalCacheWrite, inputRate);
+                            out.providerCache = {
+                                avgHitPct: pc.avgHitPct,
+                                cacheRead: pc.totalCacheRead,
+                                cacheWrite: pc.totalCacheWrite,
+                                totalInput: pc.totalInput,
+                                sampleCount: pc.sampleCount,
+                                estimatedSaved: savings.netSaved > 0 ? savings.netSaved : null,
+                            };
+                        }
+                        catch {
+                            /* best-effort — repo may not have perf_samples */
+                        }
                     }
                 }
                 catch {

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

@@ -10,3 +10,5 @@ export { handleGameState, handleGameScores, handlePerf, handleAchievements, } fr
 export { handleEvents, handleSessions } from "./routes-sessions.js";
 export { handleTopics } from "./routes-topics.js";
 export { handleTurns } from "./routes-turns.js";
+export { handleMaintenance } from "./routes-maintenance.js";
+export { handleProviderCache } from "./routes-cache.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, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, 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
@@ -191,6 +191,10 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleTurns(req, res, ctx))
             return;
+        if (handleMaintenance(req, res, ctx))
+            return;
+        if (handleProviderCache(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/extensions/mega-cache-replay.test.js

@@ -53,17 +53,48 @@ function harness() {
     // raising `tokens` while keeping `percent` null (→ token gate + token
     // grewEnough path in context-handler.ts). The REPLAY test keeps percent=100 so
     // the percent-basis grewEnough (>=10) never trips (no re-compact → pure replay).
-    const usage = { tokens: 200000, contextWindow: 200000, percent: 100 };
+    const usage = {
+        tokens: 200000,
+        contextWindow: 200000,
+        percent: 100,
+    };
     const handlers = {};
     const compactCalls = [];
     function msg(role, text, toolName) {
         if (role === "assistant" && toolName) {
-            return { role: "assistant", content: [{ type: "toolCall", name: toolName, id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 };
+            return {
+                role: "assistant",
+                content: [
+                    { type: "toolCall", name: toolName, id: "c1", arguments: {} },
+                ],
+                api: "anthropic-messages",
+                provider: "anthropic",
+                model: "m",
+                usage: {
+                    inputTokens: 1,
+                    outputTokens: 1,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                },
+                stopReason: "tool_use",
+                timestamp: 0,
+            };
         }
         if (role === "toolResult" && toolName) {
-            return { role: "toolResult", content: [{ type: "text", text }], toolCallId: "c1", toolName, isError: false, timestamp: 0 };
+            return {
+                role: "toolResult",
+                content: [{ type: "text", text }],
+                toolCallId: "c1",
+                toolName,
+                isError: false,
+                timestamp: 0,
+            };
         }
-        return { role: "user", content: text, timestamp: 0 };
+        return {
+            role: "user",
+            content: text,
+            timestamp: 0,
+        };
     }
     // Build a session of `n` tool-call triples tagged `tag`. Set A and B differ in
     // content (so B never dedups against A) but A === A reproduces the same
@@ -77,7 +108,13 @@ function harness() {
         }
         return s;
     }
-    const toEntry = (m, i) => ({ type: "message", id: `e${i}`, parentId: null, timestamp: String(i), message: m });
+    const toEntry = (m, i) => ({
+        type: "message",
+        id: `e${i}`,
+        parentId: null,
+        timestamp: String(i),
+        message: m,
+    });
     const sessionManager = {
         getSessionId: () => "sess_cache_001",
         getEntries: () => buildSession("A", 14).map(toEntry),
@@ -85,39 +122,86 @@ function harness() {
     };
     function makeCtx(over = {}) {
         return {
-            ui: { setStatus: () => { }, notify: () => { }, select: () => { }, confirm: async () => true, input: async () => "", setWidget: () => { } },
-            mode: "tui", hasUI: true, cwd: stateDir, sessionManager,
-            modelRegistry: {}, model: undefined, isIdle: () => true, isProjectTrusted: () => true,
-            signal: undefined, abort: () => { }, hasPendingMessages: () => false, shutdown: () => { },
+            ui: {
+                setStatus: () => { },
+                notify: () => { },
+                select: () => { },
+                confirm: async () => true,
+                input: async () => "",
+                setWidget: () => { },
+            },
+            mode: "tui",
+            hasUI: true,
+            cwd: stateDir,
+            sessionManager,
+            modelRegistry: {},
+            model: undefined,
+            isIdle: () => true,
+            isProjectTrusted: () => true,
+            signal: undefined,
+            abort: () => { },
+            hasPendingMessages: () => false,
+            shutdown: () => { },
             getContextUsage: () => ({ ...usage }),
-            compact: (opts) => { compactCalls.push(opts); return undefined; },
+            compact: (opts) => {
+                compactCalls.push(opts);
+                return undefined;
+            },
             getSystemPrompt: () => "system base",
             ...over,
         };
     }
     const pi = {
-        on: (ev, h) => { if (!handlers[ev])
-            handlers[ev] = []; handlers[ev].push(h); },
-        registerCommand: () => { }, registerTool: () => { }, registerShortcut: () => { },
-        registerFlag: () => { }, getFlag: () => undefined, registerMessageRenderer: () => { },
-        registerEntryRenderer: () => { }, sendMessage: () => { }, sendUserMessage: () => { },
-        appendEntry: () => { }, setSessionName: () => { }, getSessionName: () => undefined,
-        setLabel: () => { }, exec: async () => ({ stdout: "", stderr: "", code: 0 }),
-        getActiveTools: () => [], getAllTools: () => [], setActiveTools: () => { },
-        getCommands: () => [], setModel: async () => false, getThinkingLevel: () => "off",
+        on: (ev, h) => {
+            if (!handlers[ev])
+                handlers[ev] = [];
+            handlers[ev].push(h);
+        },
+        registerCommand: () => { },
+        registerTool: () => { },
+        registerShortcut: () => { },
+        registerFlag: () => { },
+        getFlag: () => undefined,
+        registerMessageRenderer: () => { },
+        registerEntryRenderer: () => { },
+        sendMessage: () => { },
+        sendUserMessage: () => { },
+        appendEntry: () => { },
+        setSessionName: () => { },
+        getSessionName: () => undefined,
+        setLabel: () => { },
+        exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [],
+        getAllTools: () => [],
+        setActiveTools: () => { },
+        getCommands: () => [],
+        setModel: async () => false,
+        getThinkingLevel: () => "off",
         setThinkingLevel: () => { },
     };
     const mod = require("./mega-compact.js");
     mod.default(pi);
     const { lastRuntime } = require("./mega-events.js");
-    const fire = async (ev, event, ctx) => { let r; for (const h of handlers[ev] || [])
-        r = await h(event, ctx); return r; };
+    const fire = async (ev, event, ctx) => {
+        let r;
+        for (const h of handlers[ev] || [])
+            r = await h(event, ctx);
+        return r;
+    };
     return {
-        stateDir, handlers, compactCalls, fire, ctx: makeCtx, usage, buildSession,
+        stateDir,
+        handlers,
+        compactCalls,
+        fire,
+        ctx: makeCtx,
+        usage,
+        buildSession,
         runtime: lastRuntime, // MegaRuntime with diag* counters + rt + trimCache
         // Bypass the 2s debounce so each fire proceeds without real waiting.
-        clearDebounce: () => { if (lastRuntime)
-            lastRuntime.debounceUntil = 0; },
+        clearDebounce: () => {
+            if (lastRuntime)
+                lastRuntime.debounceUntil = 0;
+        },
     };
 }
 test("REPLAY: >=2 gated context events within one epoch replay verbatim (byte-identical)", async () => {
@@ -185,6 +269,131 @@ test("DEDUP: re-compact that dedups onto a DIFFERENT checkpoint still replays ne
     await h.fire("context", { type: "context", messages: setA }, ctx);
     assert.ok(rt.diagLiveTrimReplays > replaysBefore, `replay fired after dedup-onto-different-checkpoint (got ${rt.diagLiveTrimReplays}, was ${replaysBefore})`);
 });
+// D.4-test-1 — Debounce exemption: the replay path sits BEFORE the debounce guard.
+// Two gated events <2s apart (no clearDebounce) must both replay — diagCtxDebounce
+// must NOT increment because the debounce guard is never reached when replay fires.
+test("DEBOUNCE-EXEMPTION: two events <2s apart (no clearDebounce) both replay; debounce never reached", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    const session = h.buildSession("A", 14);
+    // 1) Fresh trim.
+    h.clearDebounce(); // first event always needs a clear to pass the time guard
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.equal(h.runtime.diagLiveTrimFires, 1, "first fire was fresh trim");
+    // 2) Fire two events IN QUICK SUCCESSION without clearing the debounce.
+    //    The replay path (D.2) sits BEFORE the debounce guard, so both should
+    //    replay the cached trim and the debounce guard is NEVER reached.
+    const dbgBefore = h.runtime.diagCtxDebounce;
+    const rpyBefore = h.runtime.diagLiveTrimReplays;
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.equal(h.runtime.diagCtxDebounce, dbgBefore, `debounce counter unchanged (${h.runtime.diagCtxDebounce} == ${dbgBefore}) — replay path was reached, not debounce`);
+    assert.ok(h.runtime.diagLiveTrimReplays >= rpyBefore + 2, `both events replayed (replays ${h.runtime.diagLiveTrimReplays} >= ${rpyBefore}+2)`);
+});
+// D.4-test-2 — Skip→replay fallback: when runCompact returns {skipped: true} and
+// a valid trimCache exists, the handler replays the cached trim instead of returning
+// empty. We force a skip by firing with a 1-message session (view.length ≤ 1) AFTER
+// a fresh trim with a full session has populated trimCache.
+test("SKIP-FALLBACK: runCompact skipped + valid trimCache → replays cached trim", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    const session = h.buildSession("A", 14);
+    // 1) Fresh trim with full session → populates trimCache with a valid cut.
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.equal(h.runtime.diagLiveTrimFires, 1, "fresh trim populated trimCache");
+    assert.ok(h.runtime.trimCache, "trimCache is set");
+    // 2) Lower the cut so a 1-message session still passes the cut≤length guard.
+    //    The skip→replay path checks cut <= messages.length before replaying.
+    h.runtime.trimCache.cut = 0;
+    // 3) Drive context growth so grewEnough=true (replay skipped → runCompact runs).
+    //    Then fire with just 1 message → runCompact: view.length ≤ 1 → {skipped: true}.
+    h.usage.percent = null; // token-basis path
+    h.usage.tokens = 200100; // grew 100 >= 25 (effectiveThreshold * 0.5)
+    h.clearDebounce();
+    const oneMsg = [h.buildSession("X", 1)[0]]; // single user message
+    await h.fire("context", { type: "context", messages: oneMsg }, ctx);
+    assert.ok(h.runtime.diagCtxRunSkipped >= 1, `diagCtxRunSkipped incremented (got ${h.runtime.diagCtxRunSkipped})`);
+    // The skip path replays trimCache → diagLiveTrimReplays increments.
+    assert.ok(h.runtime.diagLiveTrimReplays >= 1, `skip→replay fired (replays ${h.runtime.diagLiveTrimReplays} >= 1)`);
+});
+// D.4-test-3 — Recompact delta boundary: config.recompactPctDelta = 50.
+// 49% growth → replay (not enough to re-compact).
+// 51% growth → fresh compaction (exceeds the 50% delta threshold).
+//
+// diagLiveTrimFires counts every trim response (replay OR fresh), including
+// the initial fresh trim, so cumulative counts can't validate discrete steps.
+// Instead we snapshot (fires, replays) before each step and assert the delta.
+test("DELTA-BOUNDARY: 49% growth → replay; 51% growth → fresh compaction", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    const session = h.buildSession("A", 14);
+    // Start at low context (percent=5). The handler captures ctxPct from the first
+    // trim, then checks pct - ctxPct >= 50 (config.recompactPctDelta default=50).
+    h.usage.percent = 5;
+    h.usage.tokens = 200000;
+    // 1) Fresh trim at pct=5 → trimCache.ctxPct = 5.
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.ok(h.runtime.diagLiveTrimFires >= 1, "fresh trim at pct=5");
+    assert.equal(h.runtime.trimCache?.ctxPct, 5, "ctxPct captured as 5");
+    // 2) 49% growth: pct=54. grewEnough = 54-5 = 49 < 50 → replay.
+    //    Replay increments BOTH fires and replays (line 247-248).
+    h.usage.percent = 54;
+    h.clearDebounce();
+    const { fires: f2, replays: r2 } = {
+        fires: h.runtime.diagLiveTrimFires,
+        replays: h.runtime.diagLiveTrimReplays,
+    };
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.equal(h.runtime.diagLiveTrimFires, f2 + 1, `49% growth: fires +1 (replay counted as fire, ${f2}→${h.runtime.diagLiveTrimFires})`);
+    assert.equal(h.runtime.diagLiveTrimReplays, r2 + 1, `49% growth: replays +1 (${r2}→${h.runtime.diagLiveTrimReplays})`);
+    // 3) 51% growth: pct=56. grewEnough = 56-5 = 51 >= 50 → falls through to
+    //    debounce → runCompact → fresh compaction (line 509).
+    //    Fresh compaction increments fires but NOT replays.
+    h.usage.percent = 56;
+    h.clearDebounce();
+    const { fires: f3, replays: r3 } = {
+        fires: h.runtime.diagLiveTrimFires,
+        replays: h.runtime.diagLiveTrimReplays,
+    };
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.equal(h.runtime.diagLiveTrimFires, f3 + 1, `51% growth: fires +1 (fresh compaction, ${f3}→${h.runtime.diagLiveTrimFires})`);
+    assert.equal(h.runtime.diagLiveTrimReplays, r3, `51% growth: replays unchanged (fresh compaction ≠ replay, stays ${r3})`);
+});
+// D.4-test-4 — Epoch invalidation (PREVENT-PI-001/002 guard): a checkpointId
+// mismatch means the durable transcript was truncated (session_compact or
+// resetRuntime). The replay guard MUST reject a stale trimCache in that case.
+test("EPOCH-INVALIDATION: checkpointId mismatch → replay does NOT fire (PREVENT-PI-001/002)", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    const session = h.buildSession("A", 14);
+    // 1) Fresh trim → trimCache.checkpointId = lastCheckpointId = "cp-1".
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    assert.equal(h.runtime.diagLiveTrimFires, 1, "fresh trim");
+    assert.ok(h.runtime.trimCache?.checkpointId, "trimCache has checkpointId");
+    // 2) Simulate a session_compact (durable truncation) by advancing
+    //    lastCheckpointId (harder: the compact path tracks its own epoch).
+    //    A mismatch between trimCache.checkpointId and rt.lastCheckpointId means
+    //    the cached cut is for a truncated transcript → replay must NOT fire.
+    h.runtime.rt.lastCheckpointId = "cp-mismatch";
+    assert.notEqual(h.runtime.trimCache?.checkpointId, h.runtime.rt.lastCheckpointId, "checkpointIds differ after simulated durable truncation");
+    // 3) Fire the same session (no growth → would normally replay if epoch matched).
+    const rpyBefore = h.runtime.diagLiveTrimReplays;
+    h.clearDebounce();
+    await h.fire("context", { type: "context", messages: session }, ctx);
+    // Replay path was blocked by the checkpointId guard → a fresh trim fires instead.
+    assert.equal(h.runtime.diagLiveTrimReplays, rpyBefore, `replay NOT incremented (was ${rpyBefore}, still ${h.runtime.diagLiveTrimReplays}) — stale trimCache rejected`);
+    // A fresh compaction should have been triggered instead (grewEnough=false, but
+    // replay guard failed → falls through to debounce → runCompact → fresh trim).
+    // Actually: grewEnough is false (no growth since last fire), and the replay
+    // guard rejected → falls to debounce (cleared) → runCompact.
+    // runCompact may skip or produce a fresh trim; either way the stale replay is blocked.
+    assert.ok(h.runtime.diagLiveTrimFires >= 2 || h.runtime.diagCtxRunSkipped >= 1, `handler did NOT replay stale trimCache (fires=${h.runtime.diagLiveTrimFires}, skipped=${h.runtime.diagCtxRunSkipped}, replays=${h.runtime.diagLiveTrimReplays})`);
+    // Restore for cleanup.
+    h.runtime.rt.lastCheckpointId = "cp-1";
+});
 test("cleanup", async () => {
     await closeVectorIndex();
     rmSync(baseTmp, { recursive: true, force: true });