@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/tracking/ledger-archiver.js

@@ -0,0 +1,94 @@
+/**
+ * Shadow Ledger Archiver (ST-6).
+ *
+ * Splits `.unerr/ledger/shadow.jsonl` into:
+ *   - kept  : entries with `ts >= now - retainMs` (rewritten in place)
+ *   - archived : older entries gzipped into
+ *                `.unerr/ledger/archive/<YYYY-MM-DD>.jsonl.gz`
+ *
+ * Daily archive keeps recent context fast (small JSONL) without losing
+ * history — the gzip files are still grep-able with `zcat`. Derived facts in
+ * `timeline.db` / `facts.db` are NOT touched; archival only affects the raw
+ * append-only log.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+const DEFAULT_RETAIN_MS = 7 * 24 * 60 * 60_000;
+/**
+ * Run an archive pass over `<unerrDir>/ledger/shadow.jsonl`. Safe to run while
+ * the proxy is appending: we read the snapshot, rewrite atomically via a
+ * temp file + rename. Concurrent appends in the small window between read and
+ * rename are preserved by reading the *tail* of the file after rewrite and
+ * re-appending any new lines.
+ */
+export function archiveShadowLedger(unerrDir, opts = {}) {
+    const ledgerDir = join(unerrDir, "ledger");
+    const filePath = join(ledgerDir, "shadow.jsonl");
+    const archiveDir = join(ledgerDir, "archive");
+    if (!existsSync(filePath)) {
+        return { archived: 0, kept: 0, archivePath: null };
+    }
+    const retainMs = opts.retainMs ?? DEFAULT_RETAIN_MS;
+    const now = opts.nowMs ?? Date.now();
+    const cutoff = now - retainMs;
+    const raw = readFileSync(filePath, "utf-8");
+    const initialBytes = Buffer.byteLength(raw);
+    const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+    const keep = [];
+    const archive = [];
+    for (const line of lines) {
+        let entryTs = Number.NaN;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.ts === "string")
+                entryTs = Date.parse(obj.ts);
+        }
+        catch {
+            // Unparseable lines are kept — recovery code further down the stack
+            // already deals with them.
+            keep.push(line);
+            continue;
+        }
+        if (Number.isFinite(entryTs) && entryTs < cutoff) {
+            archive.push(line);
+        }
+        else {
+            keep.push(line);
+        }
+    }
+    if (archive.length === 0) {
+        return { archived: 0, kept: keep.length, archivePath: null };
+    }
+    mkdirSync(archiveDir, { recursive: true });
+    const dateStamp = new Date(now).toISOString().slice(0, 10);
+    const archivePath = join(archiveDir, `${dateStamp}.jsonl.gz`);
+    const payload = `${archive.join("\n")}\n`;
+    const gz = gzipSync(Buffer.from(payload, "utf-8"));
+    if (existsSync(archivePath)) {
+        // Same-day archive already exists — concatenate as a separate gzip stream.
+        // gzip handles concatenated streams correctly when read with `zcat`.
+        appendFileSync(archivePath, gz);
+    }
+    else {
+        writeFileSync(archivePath, gz);
+    }
+    // Rewrite shadow.jsonl atomically. We snapshot the file size before write
+    // and after, then re-append any bytes that landed between the two.
+    const tmpPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const kept = `${keep.join("\n")}${keep.length > 0 ? "\n" : ""}`;
+    writeFileSync(tmpPath, kept, "utf-8");
+    // Re-read the original to capture any lines appended during our work.
+    const afterRaw = readFileSync(filePath, "utf-8");
+    const afterBytes = Buffer.byteLength(afterRaw);
+    if (afterBytes > initialBytes) {
+        const tail = afterRaw.slice(raw.length);
+        appendFileSync(tmpPath, tail);
+    }
+    renameSync(tmpPath, filePath);
+    return {
+        archived: archive.length,
+        kept: keep.length,
+        archivePath,
+    };
+}

package/dist/tracking/ledger-chains.js

@@ -0,0 +1,245 @@
+/**
+ * Ledger Chain Analyzer — causality-aware history from shadow ledger.
+ *
+ * Layer 9 PI-3: Transforms flat ledger entries into:
+ *   1. Correlation chains (grouped tool calls forming one intent)
+ *   2. Entity history (what happened to a specific entity across sessions)
+ *   3. Session timelines (grouped by session, summarized by feature area)
+ *   4. Revert pattern detection (chains that led to reverted code)
+ *
+ * All operations are read-only against the existing shadow.jsonl.
+ * No mutations to ledger data — this is an analysis layer.
+ */
+// ── Chain Extraction ─────────────────────────────────────────────────
+/**
+ * Extract correlation chains from raw ledger entries.
+ * A chain is a root entry + all entries correlated to it.
+ */
+export function extractChains(entries) {
+    const rootMap = new Map();
+    for (const entry of entries) {
+        const rootId = entry.correlation_id ?? entry.id;
+        const group = rootMap.get(rootId);
+        if (group) {
+            group.push(entry);
+        }
+        else {
+            rootMap.set(rootId, [entry]);
+        }
+    }
+    const chains = [];
+    for (const [rootId, chainEntries] of rootMap) {
+        if (chainEntries.length === 0)
+            continue;
+        const sorted = chainEntries.sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+        const first = sorted[0];
+        const last = sorted[sorted.length - 1];
+        const entities = extractEntitiesFromChain(sorted);
+        const tools = [...new Set(sorted.map((e) => e.tool))];
+        const featureArea = first.feature_area ?? inferFeatureArea(sorted);
+        const outcome = classifyChainOutcome(sorted);
+        chains.push({
+            root_id: rootId,
+            session_id: first.session_id,
+            branch: first.branch,
+            started_at: first.ts,
+            ended_at: last.ts,
+            duration_ms: new Date(last.ts).getTime() - new Date(first.ts).getTime(),
+            entries: sorted,
+            entities_touched: entities,
+            tools_used: tools,
+            feature_area: featureArea,
+            outcome,
+        });
+    }
+    return chains.sort((a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime());
+}
+// ── Entity History ───────────────────────────────────────────────────
+/**
+ * Get chains that touched a specific entity (file path or entity key).
+ */
+export function getEntityHistory(entries, entityKey, limit = 20) {
+    const chains = extractChains(entries);
+    return chains
+        .filter((chain) => chain.entities_touched.some((e) => e === entityKey || e.startsWith(entityKey)))
+        .slice(0, limit);
+}
+// ── Revert Pattern Detection ─────────────────────────────────────────
+/**
+ * Detect tool sequences that frequently lead to reverts.
+ * A revert is detected when a chain contains "unerr_revert_to_working_state"
+ * or when the same entity is modified multiple times in a session (thrashing).
+ */
+export function getRevertPatterns(entries, minFrequency = 2) {
+    const chains = extractChains(entries);
+    const sequenceMap = new Map();
+    for (const chain of chains) {
+        const seqKey = chain.tools_used.slice(0, 4).join(" → ");
+        const existing = sequenceMap.get(seqKey);
+        const isRevert = chain.outcome === "reverted";
+        if (existing) {
+            existing.count++;
+            if (isRevert)
+                existing.revertCount++;
+            existing.lengths.push(chain.entries.length);
+        }
+        else {
+            sequenceMap.set(seqKey, {
+                count: 1,
+                revertCount: isRevert ? 1 : 0,
+                lengths: [chain.entries.length],
+                exampleId: chain.root_id,
+                tools: chain.tools_used.slice(0, 4),
+            });
+        }
+    }
+    const patterns = [];
+    for (const [pattern, data] of sequenceMap) {
+        if (data.count < minFrequency)
+            continue;
+        if (data.revertCount === 0)
+            continue;
+        const avgLength = data.lengths.reduce((a, b) => a + b, 0) / data.lengths.length;
+        patterns.push({
+            pattern,
+            tool_sequence: data.tools,
+            frequency: data.count,
+            revert_rate: data.revertCount / data.count,
+            avg_chain_length: Math.round(avgLength * 10) / 10,
+            example_chain_id: data.exampleId,
+        });
+    }
+    return patterns.sort((a, b) => b.revert_rate - a.revert_rate);
+}
+// ── Session Timeline ─────────────────────────────────────────────────
+/**
+ * Get session summaries from ledger entries, most recent first.
+ */
+export function getSessionTimeline(entries, count = 5) {
+    const sessionMap = new Map();
+    for (const entry of entries) {
+        const group = sessionMap.get(entry.session_id);
+        if (group) {
+            group.push(entry);
+        }
+        else {
+            sessionMap.set(entry.session_id, [entry]);
+        }
+    }
+    const summaries = [];
+    for (const [sessionId, sessionEntries] of sessionMap) {
+        if (sessionEntries.length === 0)
+            continue;
+        const sorted = sessionEntries.sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+        const first = sorted[0];
+        const last = sorted[sorted.length - 1];
+        const chains = extractChains(sorted);
+        const files = new Set();
+        const entities = new Set();
+        const toolCounts = {};
+        const featureAreas = new Set();
+        let factsRecorded = 0;
+        let revertCount = 0;
+        for (const entry of sorted) {
+            toolCounts[entry.tool] = (toolCounts[entry.tool] ?? 0) + 1;
+            if (entry.tool === "record_fact")
+                factsRecorded++;
+            const filePath = extractFilePath(entry);
+            if (filePath)
+                files.add(filePath);
+            const entityKeys = extractEntityKeys(entry);
+            for (const key of entityKeys)
+                entities.add(key);
+            if (entry.feature_area)
+                featureAreas.add(entry.feature_area);
+        }
+        for (const chain of chains) {
+            if (chain.outcome === "reverted")
+                revertCount++;
+        }
+        summaries.push({
+            session_id: sessionId,
+            started_at: first.ts,
+            ended_at: last.ts,
+            duration_ms: new Date(last.ts).getTime() - new Date(first.ts).getTime(),
+            tool_calls: sorted.length,
+            chains: chains.length,
+            files_modified: [...files],
+            entities_touched: [...entities],
+            tools_used: toolCounts,
+            feature_areas: [...featureAreas],
+            facts_recorded: factsRecorded,
+            revert_count: revertCount,
+        });
+    }
+    return summaries
+        .sort((a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime())
+        .slice(0, count);
+}
+// ── Internal Helpers ─────────────────────────────────────────────────
+function extractEntitiesFromChain(entries) {
+    const entities = new Set();
+    for (const entry of entries) {
+        const keys = extractEntityKeys(entry);
+        for (const key of keys)
+            entities.add(key);
+        const filePath = extractFilePath(entry);
+        if (filePath)
+            entities.add(filePath);
+    }
+    return [...entities];
+}
+function extractEntityKeys(entry) {
+    const keys = [];
+    const args = entry.args_summary;
+    if (typeof args.key === "string" && args.key.length > 0) {
+        keys.push(args.key);
+    }
+    if (typeof args.entity === "string" && args.entity.length > 0) {
+        keys.push(args.entity);
+    }
+    if (typeof args.subject === "string" && args.subject.length > 0) {
+        keys.push(args.subject);
+    }
+    return keys;
+}
+function extractFilePath(entry) {
+    const args = entry.args_summary;
+    if (typeof args.file_path === "string")
+        return args.file_path;
+    if (typeof args.path === "string")
+        return args.path;
+    if (typeof args.key === "string" && args.key.includes("/")) {
+        return args.key.includes("::") ? args.key.split("::")[0] : args.key;
+    }
+    return null;
+}
+function inferFeatureArea(entries) {
+    for (const entry of entries) {
+        if (entry.feature_area)
+            return entry.feature_area;
+    }
+    const paths = entries
+        .map(extractFilePath)
+        .filter((p) => p !== null);
+    if (paths.length === 0)
+        return null;
+    const segments = paths[0]?.split("/");
+    if (segments && segments.length >= 2) {
+        return segments.slice(0, 2).join("/");
+    }
+    return null;
+}
+function classifyChainOutcome(entries) {
+    const hasRevert = entries.some((e) => e.tool === "unerr_revert_to_working_state" ||
+        e.result_summary?.reverted === true);
+    if (hasRevert)
+        return "reverted";
+    const hasModify = entries.some((e) => e.tool === "sync_local_diff" || e.result_summary?.modified === true);
+    if (hasModify)
+        return "modified";
+    const hasCommit = entries.some((e) => e.commit_sha != null && e.commit_sha.length > 0);
+    if (hasCommit)
+        return "survived";
+    return "unknown";
+}

package/dist/tracking/metrics-store.js

@@ -0,0 +1,361 @@
+/**
+ * Metrics Store — `.unerr/metrics.db` (better-sqlite3, WAL).
+ *
+ * Single source of truth for time-series metric streams that were previously
+ * append-only JSONL files:
+ *   - compression_events  (was logs/compression.jsonl)
+ *   - file_read_events    (was logs/file-reads.jsonl)
+ *   - token_flow_events   (was logs/token-flow.jsonl)
+ *   - session_history     (was state/session-history.jsonl)
+ *   - session_summaries   (was sessions/{session_id}.jsonl)
+ *
+ * Why SQLite + WAL:
+ *   - autoincrement `id` gives a global monotonic counter usable by the
+ *     log-tailer (poll `SELECT ... WHERE id > $lastSeen`)
+ *   - cross-process writes serialize through WAL — no flock dance
+ *   - dashboard aggregations (`SUM/GROUP BY`) become microseconds instead
+ *     of "re-parse a 2 MB JSONL on every poll"
+ *
+ * Singleton per cwd: openMetricsStore() caches the handle so writers and
+ * readers share one prepared-statement set per process.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+// ── Store ─────────────────────────────────────────────────────────────
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS compression_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  ts_iso TEXT NOT NULL,
+  command TEXT NOT NULL,
+  category TEXT NOT NULL,
+  confidence REAL NOT NULL,
+  raw_bytes INTEGER NOT NULL,
+  compressed_bytes INTEGER NOT NULL,
+  saved_pct REAL NOT NULL,
+  omni_fallback INTEGER NOT NULL,
+  tee_file TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_compression_ts ON compression_events(ts);
+CREATE INDEX IF NOT EXISTS idx_compression_category ON compression_events(category);
+
+CREATE TABLE IF NOT EXISTS file_read_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  ts_iso TEXT NOT NULL,
+  file TEXT NOT NULL,
+  mode TEXT NOT NULL,
+  total_lines INTEGER NOT NULL,
+  returned_lines INTEGER NOT NULL,
+  saved_pct REAL NOT NULL,
+  entity TEXT,
+  token_estimate INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_file_read_ts ON file_read_events(ts);
+
+CREATE TABLE IF NOT EXISTS token_flow_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  ts_iso TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  pid INTEGER NOT NULL,
+  turn INTEGER NOT NULL,
+  mechanism TEXT NOT NULL,
+  tool TEXT,
+  tokens_without INTEGER NOT NULL,
+  tokens_with INTEGER NOT NULL,
+  tokens_saved INTEGER NOT NULL,
+  detail TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_token_flow_ts ON token_flow_events(ts);
+CREATE INDEX IF NOT EXISTS idx_token_flow_session ON token_flow_events(session_id);
+CREATE INDEX IF NOT EXISTS idx_token_flow_mechanism ON token_flow_events(mechanism);
+
+CREATE TABLE IF NOT EXISTS session_history (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL UNIQUE,
+  started_at TEXT NOT NULL,
+  ended_at TEXT NOT NULL,
+  duration_ms INTEGER NOT NULL,
+  tool_calls INTEGER NOT NULL,
+  tokens_saved INTEGER NOT NULL,
+  tokens_processed INTEGER NOT NULL,
+  efficiency REAL NOT NULL,
+  dollars_saved REAL NOT NULL,
+  model_id TEXT NOT NULL,
+  entity_count INTEGER NOT NULL,
+  agent_name TEXT,
+  token_flow_summary TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_session_history_ended ON session_history(ended_at);
+
+CREATE TABLE IF NOT EXISTS session_summaries (
+  session_id TEXT PRIMARY KEY,
+  written_at TEXT NOT NULL,
+  started_at TEXT NOT NULL,
+  ended_at TEXT NOT NULL,
+  duration_ms INTEGER NOT NULL,
+  tool_calls INTEGER NOT NULL,
+  chains INTEGER NOT NULL,
+  files_modified TEXT NOT NULL,
+  entities_touched TEXT NOT NULL,
+  tools_used TEXT NOT NULL,
+  feature_areas TEXT NOT NULL,
+  facts_recorded INTEGER NOT NULL,
+  facts_surfaced TEXT NOT NULL,
+  revert_count INTEGER NOT NULL,
+  rot_score REAL NOT NULL,
+  token_estimate INTEGER NOT NULL,
+  branch TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_session_summaries_ended ON session_summaries(ended_at);
+
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+const SCHEMA_VERSION = "1";
+export class MetricsStore {
+    db;
+    stmt;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("synchronous = NORMAL");
+        this.db.pragma("foreign_keys = ON");
+        this.db.exec(SCHEMA);
+        this.db
+            .prepare("INSERT OR IGNORE INTO meta(key, value) VALUES (?, ?)")
+            .run("schema_version", SCHEMA_VERSION);
+        this.stmt = {
+            insertCompression: this.db.prepare(`
+        INSERT INTO compression_events
+          (ts, ts_iso, command, category, confidence, raw_bytes, compressed_bytes,
+           saved_pct, omni_fallback, tee_file)
+        VALUES (@ts, @ts_iso, @command, @category, @confidence, @raw_bytes,
+                @compressed_bytes, @saved_pct, @omni_fallback, @tee_file)
+      `),
+            insertFileRead: this.db.prepare(`
+        INSERT INTO file_read_events
+          (ts, ts_iso, file, mode, total_lines, returned_lines, saved_pct,
+           entity, token_estimate)
+        VALUES (@ts, @ts_iso, @file, @mode, @total_lines, @returned_lines,
+                @saved_pct, @entity, @token_estimate)
+      `),
+            insertTokenFlow: this.db.prepare(`
+        INSERT INTO token_flow_events
+          (ts, ts_iso, session_id, pid, turn, mechanism, tool,
+           tokens_without, tokens_with, tokens_saved, detail)
+        VALUES (@ts, @ts_iso, @session_id, @pid, @turn, @mechanism, @tool,
+                @tokens_without, @tokens_with, @tokens_saved, @detail)
+      `),
+            upsertSessionHistory: this.db.prepare(`
+        INSERT INTO session_history
+          (session_id, started_at, ended_at, duration_ms, tool_calls, tokens_saved,
+           tokens_processed, efficiency, dollars_saved, model_id, entity_count,
+           agent_name, token_flow_summary)
+        VALUES (@session_id, @started_at, @ended_at, @duration_ms, @tool_calls,
+                @tokens_saved, @tokens_processed, @efficiency, @dollars_saved,
+                @model_id, @entity_count, @agent_name, @token_flow_summary)
+        ON CONFLICT(session_id) DO UPDATE SET
+          ended_at = excluded.ended_at,
+          duration_ms = excluded.duration_ms,
+          tool_calls = excluded.tool_calls,
+          tokens_saved = excluded.tokens_saved,
+          tokens_processed = excluded.tokens_processed,
+          efficiency = excluded.efficiency,
+          dollars_saved = excluded.dollars_saved,
+          entity_count = excluded.entity_count,
+          token_flow_summary = excluded.token_flow_summary
+      `),
+            upsertSessionSummary: this.db.prepare(`
+        INSERT INTO session_summaries
+          (session_id, written_at, started_at, ended_at, duration_ms, tool_calls,
+           chains, files_modified, entities_touched, tools_used, feature_areas,
+           facts_recorded, facts_surfaced, revert_count, rot_score, token_estimate,
+           branch)
+        VALUES (@session_id, @written_at, @started_at, @ended_at, @duration_ms,
+                @tool_calls, @chains, @files_modified, @entities_touched,
+                @tools_used, @feature_areas, @facts_recorded, @facts_surfaced,
+                @revert_count, @rot_score, @token_estimate, @branch)
+        ON CONFLICT(session_id) DO UPDATE SET
+          written_at = excluded.written_at,
+          ended_at = excluded.ended_at,
+          duration_ms = excluded.duration_ms,
+          tool_calls = excluded.tool_calls,
+          chains = excluded.chains,
+          files_modified = excluded.files_modified,
+          entities_touched = excluded.entities_touched,
+          tools_used = excluded.tools_used,
+          feature_areas = excluded.feature_areas,
+          facts_recorded = excluded.facts_recorded,
+          facts_surfaced = excluded.facts_surfaced,
+          revert_count = excluded.revert_count,
+          rot_score = excluded.rot_score,
+          token_estimate = excluded.token_estimate,
+          branch = excluded.branch
+      `),
+            recentCompression: this.db.prepare(`
+        SELECT * FROM compression_events ORDER BY id DESC LIMIT @limit
+      `),
+            recentFileReads: this.db.prepare(`
+        SELECT * FROM file_read_events ORDER BY id DESC LIMIT @limit
+      `),
+            compressionSince: this.db.prepare(`
+        SELECT * FROM compression_events WHERE id > @lastId ORDER BY id ASC LIMIT @limit
+      `),
+            fileReadsSince: this.db.prepare(`
+        SELECT * FROM file_read_events WHERE id > @lastId ORDER BY id ASC LIMIT @limit
+      `),
+            tokenFlowSince: this.db.prepare(`
+        SELECT * FROM token_flow_events WHERE id > @lastId ORDER BY id ASC LIMIT @limit
+      `),
+            tokenFlowAll: this.db.prepare(`
+        SELECT * FROM token_flow_events ORDER BY id ASC
+      `),
+            tokenFlowBySession: this.db.prepare(`
+        SELECT * FROM token_flow_events WHERE session_id = @sessionId ORDER BY id ASC
+      `),
+            allSessionHistory: this.db.prepare(`
+        SELECT * FROM session_history ORDER BY ended_at ASC
+      `),
+            sessionSummaryById: this.db.prepare(`
+        SELECT * FROM session_summaries WHERE session_id = @sessionId
+      `),
+            allSessionSummaries: this.db.prepare(`
+        SELECT * FROM session_summaries ORDER BY ended_at DESC
+      `),
+        };
+    }
+    // ── Writes ──────────────────────────────────────────────────────────
+    insertCompression(row) {
+        return Number(this.stmt.insertCompression.run(row).lastInsertRowid);
+    }
+    insertFileRead(row) {
+        return Number(this.stmt.insertFileRead.run(row).lastInsertRowid);
+    }
+    insertTokenFlow(row) {
+        return Number(this.stmt.insertTokenFlow.run(row).lastInsertRowid);
+    }
+    upsertSessionHistory(row) {
+        this.stmt.upsertSessionHistory.run(row);
+    }
+    upsertSessionSummary(row) {
+        this.stmt.upsertSessionSummary.run(row);
+    }
+    // ── Reads ───────────────────────────────────────────────────────────
+    recentCompression(limit) {
+        return this.stmt.recentCompression.all({ limit });
+    }
+    recentFileReads(limit) {
+        return this.stmt.recentFileReads.all({ limit });
+    }
+    /** Poll API used by the log-tailer. */
+    compressionSince(lastId, limit = 500) {
+        return this.stmt.compressionSince.all({
+            lastId,
+            limit,
+        });
+    }
+    fileReadsSince(lastId, limit = 500) {
+        return this.stmt.fileReadsSince.all({
+            lastId,
+            limit,
+        });
+    }
+    tokenFlowSince(lastId, limit = 500) {
+        return this.stmt.tokenFlowSince.all({
+            lastId,
+            limit,
+        });
+    }
+    allTokenFlow() {
+        return this.stmt.tokenFlowAll.all({});
+    }
+    tokenFlowBySession(sessionId) {
+        return this.stmt.tokenFlowBySession.all({
+            sessionId,
+        });
+    }
+    allSessionHistory() {
+        return this.stmt.allSessionHistory.all({});
+    }
+    sessionSummary(sessionId) {
+        return (this.stmt.sessionSummaryById.get({ sessionId }) ??
+            null);
+    }
+    allSessionSummaries() {
+        return this.stmt.allSessionSummaries.all({});
+    }
+    /**
+     * Current max id in each of the three polled tables — used by the
+     * log-tailer to skip events that already existed when it started.
+     * `COALESCE(MAX(id), 0)` keeps the call O(1) on an indexed PK.
+     */
+    lastIds() {
+        const c = this.db
+            .prepare("SELECT COALESCE(MAX(id), 0) AS id FROM compression_events")
+            .get();
+        const f = this.db
+            .prepare("SELECT COALESCE(MAX(id), 0) AS id FROM file_read_events")
+            .get();
+        const t = this.db
+            .prepare("SELECT COALESCE(MAX(id), 0) AS id FROM token_flow_events")
+            .get();
+        return { compression: c.id, fileRead: f.id, tokenFlow: t.id };
+    }
+    // ── Lifecycle ───────────────────────────────────────────────────────
+    close() {
+        this.db.close();
+    }
+    /** Test-only — wipe every metric table. */
+    reset() {
+        this.db.exec(`
+      DELETE FROM compression_events;
+      DELETE FROM file_read_events;
+      DELETE FROM token_flow_events;
+      DELETE FROM session_history;
+      DELETE FROM session_summaries;
+      DELETE FROM sqlite_sequence WHERE name IN
+        ('compression_events','file_read_events','token_flow_events','session_history');
+    `);
+    }
+}
+// ── Per-cwd singleton ────────────────────────────────────────────────
+const instances = new Map();
+/**
+ * Open (or reuse) the metrics store for a given unerr directory.
+ * `.unerr/metrics.db` is created on first call; the schema bootstrap is
+ * idempotent (CREATE TABLE IF NOT EXISTS).
+ */
+export function openMetricsStore(unerrDir) {
+    let store = instances.get(unerrDir);
+    if (!store) {
+        mkdirSync(unerrDir, { recursive: true });
+        store = new MetricsStore(join(unerrDir, "metrics.db"));
+        instances.set(unerrDir, store);
+    }
+    return store;
+}
+/** Test-only — close + drop the cached instance for an `unerrDir`. */
+export function closeMetricsStore(unerrDir) {
+    const store = instances.get(unerrDir);
+    if (store) {
+        store.close();
+        instances.delete(unerrDir);
+    }
+}
+/** Close every cached instance — called on process shutdown. */
+export function closeAllMetricsStores() {
+    for (const [dir, store] of instances) {
+        try {
+            store.close();
+        }
+        catch {
+            /* best effort */
+        }
+        instances.delete(dir);
+    }
+}