pi-mega-compact 0.8.7 → 0.8.10

package/dist/extensions/mega-runtime/state.js

@@ -15,7 +15,7 @@ import { VectorStore } from "../../src/vectorStore.js";
 import { toEngineMessages } from "../../src/adapt.js";
 import { normalizeSessionId } from "../../src/store.js";
 import { Logger } from "../../src/log.js";
-import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel, getDedupStats, getCompactCount, getRecallInjected, getCacheHitTokensSaved, getGameState, } from "../../src/store/sqlite.js";
+import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel, getDedupStats, getCompactCount, getRecallInjected, getCacheHitTokensSaved, getGameState, recordPerfSample, } from "../../src/store/sqlite.js";
 import { detectCrossRepoDrift } from "../../src/driftDetection.js";
 import { repoStateDir, resolveRepoRoot, pressureRatio, pressureFromPct, pressureBand, effectiveThresholdTokens, } from "../mega-config.js";
 import { Dashboard } from "../mega-dashboard.js";
@@ -121,6 +121,12 @@ export class MegaRuntime {
     // Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
     // while fresh.
     lastWhy = undefined;
+    // v0.8.8 Perf dashboard instrumentation: turn/provider start timestamps +
+    // the 5s cpu/mem interval handle (one per MegaRuntime, cleared in dispose()).
+    perfTurnStart = 0;
+    perfProviderStart = 0;
+    perfCpuInterval;
+    perfCpuBaseline;
     // Context tracking for the dashboard (updated in the context handler).
     lastCtxTokens = null;
     lastCtxPercent = null;
@@ -329,6 +335,7 @@ export class MegaRuntime {
             this.renderWidget(ctx);
             return;
         }
+        const perfT0 = performance.now();
         const st = this.store.stats(this.rt.sessionId);
         const repo = this.store.repoStats();
         const di = this.store.dataInvariant();
@@ -479,7 +486,13 @@ export class MegaRuntime {
                 cacheHit: { sessionSec: sec(this.rt.cacheHitTokens), totalSec: sec(cacheHitsTotalTokens) },
             },
             model,
+            diag: {
+                ctxFastGate: this.diagCtxFastGate,
+                liveTrimFires: this.diagLiveTrimFires,
+                liveTrimReplays: this.diagLiveTrimReplays,
+            },
         });
+        const perfDiskMs = this.dashboard.lastWriteMs;
         // Live stats widget above the editor
         if (ctx) {
             // ── gather widget data (computed per snapshot, rendered per frame) ────
@@ -634,6 +647,13 @@ export class MegaRuntime {
         }
         // v0.8.5: record the material-change signature computed at the top so the
         // next snapshot() can skip this whole body when nothing material changed.
+        try {
+            recordPerfSample(this.currentStateDir, "db_recompute_ms", performance.now() - perfT0);
+            recordPerfSample(this.currentStateDir, "disk_write_ms", perfDiskMs);
+        }
+        catch {
+            /* non-fatal: perf instrumentation never blocks the agent */
+        }
         this.lastSnapshotSig = sig;
     }
     /** Register the above-editor widget as a width-aware factory so pi re-renders
@@ -892,6 +912,44 @@ export class MegaRuntime {
             this.gameStateWatcher = undefined;
             this.gameStateWatchDir = undefined;
         }
+        // v0.8.8: stop the cpu/mem sampling interval on teardown. Re-armed lazily
+        // by ensurePerfInterval() on the next turn_start.
+        if (this.perfCpuInterval) {
+            clearInterval(this.perfCpuInterval);
+            this.perfCpuInterval = undefined;
+            this.perfCpuBaseline = undefined;
+        }
+    }
+    /** v0.8.8: (re)start the 5s cpu/mem sampling interval (idempotent). One per
+     *  MegaRuntime; cleared in dispose(). Samples process.cpuUsage() (user/sys
+     *  delta vs the last tick → ms) + process.memoryUsage() (rss/heap → MB) and
+     *  records them as perf_samples. unref'd so it never keeps the process alive
+     *  on its own. Non-fatal: any failure is swallowed (instrumentation never
+     *  blocks the agent). PREVENT-PI-004: local process stats + SQLite only. */
+    ensurePerfInterval() {
+        if (this.perfCpuInterval)
+            return;
+        this.perfCpuBaseline = undefined; // first tick sets the baseline (no delta)
+        this.perfCpuInterval = setInterval(() => {
+            try {
+                const dir = this.currentStateDir;
+                const cpu = process.cpuUsage();
+                const mem = process.memoryUsage();
+                if (this.perfCpuBaseline) {
+                    const du = (cpu.user - this.perfCpuBaseline.user) / 1000; // μs → ms
+                    const ds = (cpu.system - this.perfCpuBaseline.sys) / 1000;
+                    recordPerfSample(dir, "cpu_user_ms", Math.max(0, du));
+                    recordPerfSample(dir, "cpu_sys_ms", Math.max(0, ds));
+                }
+                this.perfCpuBaseline = { user: cpu.user, sys: cpu.system };
+                recordPerfSample(dir, "rss_mb", mem.rss / 1_000_000);
+                recordPerfSample(dir, "heap_mb", mem.heapUsed / 1_000_000);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }, 5000);
+        this.perfCpuInterval.unref?.();
     }
     /** S31: the cached game-mode state (game_mode_on/theme/tui_display_mode).
      *  Lazily read from the game_state SQLite row on the first call, then

package/dist/src/store/sqlite/connection.js

@@ -0,0 +1,35 @@
+/**
+ * Per-repo SQLite connection management (open / reuse / close).
+ *
+ * In-process cache so the same stateDir reuses one connection (and so a fresh
+ * VectorStore over the same dir shares the open DB). Cross-process durability
+ * comes from reopening the same file path — proven by the integration test.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getStateDir } from "../../store.js";
+import { initSchema } from "./schema.js";
+const cache = new Map();
+/** Open (or reuse) the SQLite store for a state dir. */
+export function openStore(stateDir = getStateDir()) {
+    const existing = cache.get(stateDir);
+    if (existing)
+        return existing;
+    if (!existsSync(stateDir))
+        mkdirSync(stateDir, { recursive: true });
+    const db = new DatabaseSync(join(stateDir, "sqlite.db"));
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    initSchema(db);
+    cache.set(stateDir, db);
+    return db;
+}
+/** Close and evict a cached connection (test teardown only). */
+export function closeStore(stateDir) {
+    const db = cache.get(stateDir);
+    if (db) {
+        db.close();
+        cache.delete(stateDir);
+    }
+}

package/dist/src/store/sqlite/index-store.js

@@ -0,0 +1,167 @@
+/**
+ * Global machine-wide index store (Phase 5b).
+ *
+ * A single SQLite DB, separate from every per-repo store, that aggregates one
+ * row per repo this machine has run on. The multi-repo dashboard (Summary /
+ * All-repos tabs) reads it so ONE dashboard can show every repo's checkpoints,
+ * tokens saved, and active model — instead of a per-repo dashboard that only
+ * ever sees the repo it was launched from.
+ *
+ * Written by every pi process on repo-switch (bindRepo) + model capture; read by
+ * the dashboard server. Concurrency across 10+ pi processes is handled by WAL +
+ * infrequent idempotent upserts (ON CONFLICT). Fully local (PREVENT-PI-004).
+ */
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+/** Resolve the machine-wide index directory (env-overridable). */
+export function getIndexDir() {
+    const override = process.env.MEGACOMPACT_INDEX_DIR;
+    if (override && override.trim() !== "")
+        return override;
+    // homedir() can throw in exotic sandboxes; fall back to tmpdir.
+    try {
+        return join(homedir(), ".mega-compact-index");
+    }
+    catch {
+        return join(tmpdir(), ".mega-compact-index");
+    }
+}
+let indexCache;
+let indexCacheDir;
+/** Open (or reuse) the machine-wide index DB. WAL for concurrent writers. */
+export function openIndexStore(indexDir = getIndexDir()) {
+    if (indexCache && indexCacheDir === indexDir)
+        return indexCache;
+    if (!existsSync(indexDir))
+        mkdirSync(indexDir, { recursive: true });
+    const iddb = new DatabaseSync(join(indexDir, "index.sqlite"));
+    iddb.exec("PRAGMA journal_mode = WAL");
+    iddb.exec("PRAGMA busy_timeout = 3000"); // tolerate brief cross-process write contention
+    iddb.exec(`
+    CREATE TABLE IF NOT EXISTS repo_registry (
+      repo_root                 TEXT PRIMARY KEY,
+      display_name              TEXT,
+      state_dir                 TEXT NOT NULL,
+      first_seen                INTEGER,
+      last_seen                 INTEGER,
+      last_compacted_at         INTEGER,
+      checkpoint_count          INTEGER DEFAULT 0,
+      tokens_saved              INTEGER DEFAULT 0,
+      compressed_original_bytes INTEGER DEFAULT 0,
+      provider                  TEXT,
+      provider_name             TEXT,
+      model_name                TEXT,
+      input_rate                REAL,
+      output_rate               REAL,
+      model_captured_at         INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_registry_last_seen ON repo_registry(last_seen DESC);
+  `);
+    indexCache = iddb;
+    indexCacheDir = indexDir;
+    return iddb;
+}
+/**
+ * Upsert a repo's aggregate stats into the global index. Called on repo-switch
+ * (infrequent). Preserves first_seen + the model columns on update (model is
+ * written separately by recordRepoModel so we never clobber it here with nulls).
+ */
+export function upsertRepoRegistry(row, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const now = Date.now();
+    db.prepare(`INSERT INTO repo_registry
+       (repo_root, display_name, state_dir, first_seen, last_seen, last_compacted_at,
+        checkpoint_count, tokens_saved, compressed_original_bytes)
+     VALUES (@repo_root, @display_name, @state_dir, @now, @now, @last_compacted_at,
+             @checkpoint_count, @tokens_saved, @compressed_original_bytes)
+     ON CONFLICT(repo_root) DO UPDATE SET
+       display_name = excluded.display_name,
+       state_dir = excluded.state_dir,
+       last_seen = excluded.last_seen,
+       last_compacted_at = COALESCE(excluded.last_compacted_at, repo_registry.last_compacted_at),
+       checkpoint_count = excluded.checkpoint_count,
+       tokens_saved = excluded.tokens_saved,
+       compressed_original_bytes = excluded.compressed_original_bytes`).run({
+        repo_root: row.repoRoot,
+        display_name: row.displayName,
+        state_dir: row.stateDir,
+        now,
+        last_compacted_at: row.lastCompactedAt ?? null,
+        checkpoint_count: row.checkpointCount,
+        tokens_saved: row.tokensSaved,
+        compressed_original_bytes: row.compressedOriginalBytes,
+    });
+}
+/**
+ * Record the active model/provider for a repo in the global index (denormalized
+ * so the All-repos table shows model without opening each repo's DB). Upserts a
+ * bare registry row if the repo isn't registered yet.
+ */
+export function recordRepoModel(repoRoot, model, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const now = Date.now();
+    db.prepare(`INSERT INTO repo_registry
+       (repo_root, display_name, state_dir, first_seen, last_seen,
+        provider, provider_name, model_name, input_rate, output_rate, model_captured_at)
+     VALUES (@repo_root, @display_name, @state_dir, @now, @now,
+             @provider, @provider_name, @model_name, @input_rate, @output_rate, @now)
+     ON CONFLICT(repo_root) DO UPDATE SET
+       last_seen = excluded.last_seen,
+       provider = excluded.provider,
+       provider_name = excluded.provider_name,
+       model_name = excluded.model_name,
+       input_rate = excluded.input_rate,
+       output_rate = excluded.output_rate,
+       model_captured_at = excluded.model_captured_at`).run({
+        repo_root: repoRoot,
+        display_name: model.displayName,
+        state_dir: model.stateDir,
+        now,
+        provider: model.provider,
+        provider_name: model.providerName,
+        model_name: model.modelName,
+        input_rate: model.inputRate,
+        output_rate: model.outputRate,
+    });
+}
+function mapRegistryRow(row) {
+    return {
+        repoRoot: row.repo_root,
+        displayName: row.display_name ?? "",
+        stateDir: row.state_dir,
+        firstSeen: row.first_seen ?? 0,
+        lastSeen: row.last_seen ?? 0,
+        lastCompactedAt: row.last_compacted_at ?? null,
+        checkpointCount: row.checkpoint_count ?? 0,
+        tokensSaved: row.tokens_saved ?? 0,
+        compressedOriginalBytes: row.compressed_original_bytes ?? 0,
+        provider: row.provider ?? null,
+        providerName: row.provider_name ?? null,
+        modelName: row.model_name ?? null,
+        inputRate: row.input_rate ?? null,
+        outputRate: row.output_rate ?? null,
+        modelCapturedAt: row.model_captured_at ?? null,
+    };
+}
+/** All registered repos, most-recently-seen first. */
+export function listRepoRegistry(indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const rows = db.prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC").all();
+    return rows.map(mapRegistryRow);
+}
+/** A single repo's registry row, or undefined. */
+export function getRepoRegistry(repoRoot, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const row = db.prepare("SELECT * FROM repo_registry WHERE repo_root = ?").get(repoRoot);
+    return row ? mapRegistryRow(row) : undefined;
+}
+/** Close the cached index connection (test teardown only). */
+export function closeIndexStore() {
+    if (indexCache) {
+        indexCache.close();
+        indexCache = undefined;
+        indexCacheDir = undefined;
+    }
+}

package/dist/src/store/sqlite/memory.js

@@ -0,0 +1,54 @@
+/**
+ * Durable "save to memory" store (taken over from memory extensions).
+ *
+ * One SQLite store for user-saved memories, scoped by repo. Mirrors the
+ * lessons/sessions pattern: all state lives in SQLite from day one. All queries
+ * are parameterized (PREVENT-002).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./connection.js";
+/** Save a memory to the current repo's store. Returns the new row id. */
+export function addMemory(memory, repo, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const now = Math.floor(Date.now() / 1000);
+    const res = db
+        .prepare(`INSERT INTO memories(repo, kind, content, tags, created_at, last_recalled_at)
+       VALUES(?, ?, ?, ?, ?, NULL)`)
+        .run(repo ?? null, memory.kind ?? "note", memory.content, JSON.stringify(memory.tags ?? []), now);
+    return Number(res.lastInsertRowid);
+}
+/** List recent memories for a repo (or all repos when repo is null). */
+export function listMemories(repo, limit = 50, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = repo
+        ? db.prepare("SELECT * FROM memories WHERE repo = ? ORDER BY created_at DESC LIMIT ?").all(repo, limit)
+        : db.prepare("SELECT * FROM memories ORDER BY created_at DESC LIMIT ?").all(limit);
+    return rows.map(mapMemoryRow);
+}
+/** Substring search across content + tags. */
+export function searchMemories(query, repo = null, limit = 50, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const like = `%${query}%`;
+    const rows = repo
+        ? db.prepare("SELECT * FROM memories WHERE repo = ? AND (content LIKE ? OR tags LIKE ?) ORDER BY created_at DESC LIMIT ?").all(repo, like, like, limit)
+        : db.prepare("SELECT * FROM memories WHERE content LIKE ? OR tags LIKE ? ORDER BY created_at DESC LIMIT ?").all(like, like, limit);
+    return rows.map(mapMemoryRow);
+}
+/** Mark a memory as recalled (updates last_recalled_at). Returns true if found. */
+export function recallMemory(id, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const now = Math.floor(Date.now() / 1000);
+    const res = db.prepare("UPDATE memories SET last_recalled_at = ? WHERE id = ?").run(now, id);
+    return res.changes > 0;
+}
+function mapMemoryRow(row) {
+    return {
+        id: row.id,
+        repo: row.repo ?? null,
+        kind: row.kind ?? "note",
+        content: row.content ?? "",
+        tags: row.tags ? JSON.parse(row.tags) : [],
+        createdAt: row.created_at ?? 0,
+        lastRecalledAt: row.last_recalled_at ?? null,
+    };
+}

package/dist/src/store/sqlite/minhash-lsh.js

@@ -0,0 +1,47 @@
+/**
+ * Sprint 11: MinHash signatures + LSH bucket persistence and candidate lookup.
+ *
+ * All queries are parameterized (PREVENT-002) — never string-concatenated.
+ */
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { openStore } from "./connection.js";
+import { withTx } from "./transaction.js";
+/** Persist a checkpoint's MinHash signature (idempotent by chunk_id + version). */
+export function upsertMinhashSignature(chunkId, sessionId, signatureVersion, signatures, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    db.prepare(`INSERT INTO minhash_signatures(chunk_id, session_id, signature_version, signatures)
+     VALUES(?, ?, ?, ?)
+     ON CONFLICT(chunk_id, signature_version) DO UPDATE SET
+       session_id=excluded.session_id, signatures=excluded.signatures`).run(chunkId, sid, signatureVersion, JSON.stringify(signatures));
+}
+/** Persist LSH bucket memberships for a chunk (one row per bucket key). */
+export function insertLshBuckets(chunkId, sessionId, signatureVersion, bucketKeys, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const del = db.prepare("DELETE FROM dedup_lsh_buckets WHERE chunk_id = ?");
+    const ins = db.prepare("INSERT OR IGNORE INTO dedup_lsh_buckets(bucket_key, chunk_id, session_id, signature_version) VALUES(?, ?, ?, ?)");
+    withTx(db, () => {
+        del.run(chunkId);
+        for (const key of bucketKeys)
+            ins.run(key, chunkId, sid, signatureVersion);
+    });
+}
+/**
+ * Candidate chunk_ids sharing any LSH bucket with `bucketKeys`, scoped to the
+ * session, capped at `limit`. Single query (no N loops) — QA #15 amplification
+ * guard. Returns DISTINCT chunk_ids excluding `excludeChunkId` (the new row).
+ */
+export function lshCandidateChunks(bucketKeys, sessionId, excludeChunkId, stateDir = getStateDir(), limit = 100) {
+    if (bucketKeys.length === 0)
+        return [];
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const placeholders = bucketKeys.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT DISTINCT chunk_id FROM dedup_lsh_buckets
+       WHERE bucket_key IN (${placeholders}) AND session_id = ? AND chunk_id != ?
+       LIMIT ?`)
+        .all(...bucketKeys, sid, excludeChunkId, limit);
+    return rows.map((r) => r.chunk_id);
+}

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

@@ -0,0 +1,81 @@
+/**
+ * perf-samples.ts — `perf_samples` table accessors (v0.8.8 Perf dashboard).
+ *
+ * Append-only local instrumentation store for the dashboard's Perf tab: model
+ * endpoint latency, TPS, cache hit %, CPU/mem, and the snapshot() recompute /
+ * disk-write cost. One row per sample; the dashboard server reads a rolling
+ * window and derives p50/p95 + latest values.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (? placeholders). The optional `kind`
+ *   filter is bound as a parameter (never string-concatenated); the only
+ *   interpolated fragment is the code-controlled `AND kind = ?` clause toggle,
+ *   never external input.
+ * Pi-agnostic: no pi runtime types (mirrors game-scores.ts / meta.ts).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+/** Allow-list of valid perf sample kinds (mirrors the table's domain). */
+export const PERF_KINDS = [
+    "turn_latency_ms",
+    "provider_latency_ms",
+    "tps",
+    "cache_hit_pct",
+    "rss_mb",
+    "heap_mb",
+    "cpu_user_ms",
+    "cpu_sys_ms",
+    "db_recompute_ms",
+    "disk_write_ms",
+];
+function isPerfKind(k) {
+    return PERF_KINDS.includes(k);
+}
+/**
+ * Record one perf sample. `ts` is set to Date.now(). SQL is fully parameterized
+ * (PREVENT-002); the kind is validated against the fixed allow-list. Pi-agnostic.
+ * Never throws on an unknown kind or non-finite value (silently ignored) so
+ * instrumentation can never block the agent; a known kind + finite value always
+ * writes.
+ */
+export function recordPerfSample(stateDir = getStateDir(), kind, value, meta) {
+    if (!isPerfKind(kind))
+        return;
+    if (!Number.isFinite(value))
+        return;
+    const db = openStore(stateDir);
+    db.prepare(`INSERT INTO perf_samples (ts, kind, value, meta)
+		 VALUES (?, ?, ?, ?)`).run(Date.now(), kind, value, meta != null ? JSON.stringify(meta) : null);
+}
+/**
+ * Read perf samples since `sinceTs` (epoch ms), optionally filtered by kind.
+ * Returns rows ascending by ts. The optional kind filter is bound as a
+ * parameter (PREVENT-002). Pi-agnostic. `meta` is parsed defensively (null-safe:
+ * PREVENT-001 — assigned to a variable before any property access).
+ */
+export function readPerfSamples(stateDir = getStateDir(), sinceTs = 0, kind) {
+    const db = openStore(stateDir);
+    const sql = kind
+        ? `SELECT id, ts, kind, value, meta FROM perf_samples
+		   WHERE ts >= ? AND kind = ? ORDER BY ts ASC`
+        : `SELECT id, ts, kind, value, meta FROM perf_samples
+		   WHERE ts >= ? ORDER BY ts ASC`;
+    const params = kind ? [sinceTs, kind] : [sinceTs];
+    const rows = db.prepare(sql).all(...params);
+    const out = [];
+    for (const r of rows) {
+        if (!isPerfKind(r.kind))
+            continue; // defensive: unknown kind row skipped
+        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: r.kind, value: r.value, meta });
+    }
+    return out;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * perf-samples.test.ts — v0.8.8 perf_samples table round-trip + filtering.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import { recordPerfSample, readPerfSamples, PERF_KINDS, } from "./perf-samples.js";
+describe("perf-samples (v0.8.8)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-perfsamples-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        closeStore(dir);
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("records + reads back a turn_latency_ms sample with parsed meta", () => {
+        recordPerfSample(dir, "turn_latency_ms", 123.4, { turnIndex: 2 });
+        const rows = readPerfSamples(dir, 0);
+        assert.equal(rows.length, 1);
+        assert.equal(rows[0].kind, "turn_latency_ms");
+        assert.equal(rows[0].value, 123.4);
+        assert.deepEqual(rows[0].meta, { turnIndex: 2 });
+    });
+    it("filters by kind and by sinceTs", () => {
+        recordPerfSample(dir, "tps", 50);
+        recordPerfSample(dir, "rss_mb", 256);
+        const tps = readPerfSamples(dir, 0, "tps");
+        assert.equal(tps.length, 1);
+        assert.equal(tps[0].kind, "tps");
+        assert.equal(tps[0].value, 50);
+        const future = readPerfSamples(dir, Date.now() + 10000, "tps");
+        assert.equal(future.length, 0);
+    });
+    it("ignores non-finite values + unknown kinds (never throws, nothing added)", () => {
+        const before = readPerfSamples(dir, 0).length;
+        recordPerfSample(dir, "tps", Number.NaN);
+        recordPerfSample(dir, "tps", Infinity);
+        assert.doesNotThrow(() => recordPerfSample(dir, "bogus", 1));
+        const after = readPerfSamples(dir, 0).length;
+        assert.equal(after, before);
+    });
+    it("PERF_KINDS lists the 10 instrumentation kinds", () => {
+        assert.equal(PERF_KINDS.length, 10);
+        assert.ok(PERF_KINDS.includes("db_recompute_ms"));
+        assert.ok(PERF_KINDS.includes("cache_hit_pct"));
+    });
+});

package/dist/src/store/sqlite/schema.js

@@ -261,6 +261,20 @@ export function initSchema(db) {
       icon        TEXT,
       unlocked_at INTEGER NULL
     ) WITHOUT ROWID;
+
+    -- v0.8.8 Perf dashboard: append-only local instrumentation samples (one row
+    -- per turn / provider round-trip / 5s cpu-mem tick / snapshot-recompute).
+    -- Drives the dashboard Perf tab. Local SQLite (PREVENT-PI-004); parameterized
+    -- accessors in perf-samples.ts (PREVENT-002).
+    CREATE TABLE IF NOT EXISTS perf_samples (
+      id    INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts    INTEGER NOT NULL,
+      kind  TEXT NOT NULL,
+      value REAL NOT NULL,
+      meta  TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_perf_samples_ts ON perf_samples(ts);
+    CREATE INDEX IF NOT EXISTS idx_perf_samples_kind_ts ON perf_samples(kind, 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/dist/src/store/sqlite/sessions.js

@@ -0,0 +1,39 @@
+/**
+ * Future-feature foundation: resume sessions, daily activity log, lessons learned.
+ *
+ * Scaffolded tables + minimal helpers so all store data lives in SQLite from
+ * day one. Full UI/recall for these lands in later sprints. All queries are
+ * parameterized (PREVENT-002).
+ */
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { openStore } from "./connection.js";
+/** Upsert a `sessions` row (resume + per-repo session history). */
+export function touchSession(sessionId, repo, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    const existing = db
+        .prepare("SELECT started_at FROM sessions WHERE session_id = ?")
+        .get(sid);
+    const now = Math.floor(Date.now() / 1000);
+    if (!existing) {
+        db.prepare(`INSERT INTO sessions(session_id, repo, started_at, last_compacted_at, status)
+       VALUES(?, ?, ?, ?, 'active')`).run(sid, repo ?? null, now, now);
+    }
+    else {
+        db.prepare("UPDATE sessions SET last_compacted_at = ?, repo = COALESCE(?, repo), status = 'active' WHERE session_id = ?").run(now, repo ?? null, sid);
+    }
+}
+/** Append a `daily_log` entry (day = YYYY-MM-DD, local-naive from Date). */
+export function logDaily(sessionId, event, detail, tokensSaved, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const day = new Date().toISOString().slice(0, 10);
+    const now = Math.floor(Date.now() / 1000);
+    db.prepare(`INSERT INTO daily_log(day, session_id, event, detail, tokens_saved, ts)
+     VALUES(?, ?, ?, ?, ?, ?)`).run(day, normalizeSessionId(sessionId), event, detail ?? null, tokensSaved, now);
+}
+/** Append a `lessons` entry (future lessons-learned browse/recall). */
+export function addLesson(sessionId, repo, lesson, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const now = Math.floor(Date.now() / 1000);
+    db.prepare(`INSERT INTO lessons(session_id, repo, lesson, ts) VALUES(?, ?, ?, ?)`).run(normalizeSessionId(sessionId), repo ?? null, lesson, now);
+}

package/dist/src/store/sqlite/transaction.js

@@ -0,0 +1,19 @@
+/**
+ * Transaction wrapper using SAVEPOINT so it nests safely under an outer
+ * transaction (unlike `BEGIN`, which SQLite rejects when one is already open).
+ *
+ * Mirrors better-sqlite3's `db.transaction(fn)` semantics — callers that wrap a
+ * batch in withTx (e.g. backfill) can still call helpers that also use withTx.
+ */
+export function withTx(db, fn) {
+    db.exec("SAVEPOINT mc_tx");
+    try {
+        fn();
+        db.exec("RELEASE mc_tx");
+    }
+    catch (e) {
+        db.exec("ROLLBACK TO mc_tx");
+        db.exec("RELEASE mc_tx");
+        throw e;
+    }
+}

package/dist/src/store/sqlite.js

@@ -23,3 +23,4 @@ export * from "./sqlite/maintenance.js";
 export * from "./sqlite/game-state.js";
 export * from "./sqlite/game-scores.js";
 export * from "./sqlite/game-achievements.js";
+export * from "./sqlite/perf-samples.js";