pi-mega-compact 0.4.4 → 0.4.6

package/dist/src/extractive.test.js

@@ -0,0 +1,130 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { extractiveSummarize } from "./extractive.js";
+function msg(role, text, toolName) {
+    return toolName ? { role, text, toolName, input: text, output: text } : { role, text };
+}
+// ---- Determinism -----------------------------------------------------------
+test("extractive summary is deterministic", () => {
+    const messages = [
+        msg("user", "please write src/index.ts"),
+        msg("assistant", "I'll write src/index.ts now."),
+        msg("tool", '{"file_path":"src/index.ts"}', "write"),
+        msg("assistant", "Done."),
+    ];
+    const s1 = extractiveSummarize(messages);
+    const s2 = extractiveSummarize(messages);
+    assert.deepStrictEqual(s1, s2);
+});
+// ---- Compression -----------------------------------------------------------
+test("extractive summary produces small output", () => {
+    // Build 70 messages (simulating a session)
+    const messages = [];
+    for (let i = 0; i < 70; i++) {
+        messages.push(msg("user", `request ${i}: please help with feature ${i}`));
+        messages.push(msg("assistant", `working on feature ${i} in src/file${i % 5}.ts`));
+        messages.push(msg("tool", `{"file_path":"src/file${i % 5}.ts","content":"..."}`, "write"));
+        messages.push(msg("assistant", `done with feature ${i}`));
+    }
+    const rawText = messages.map((m) => m.text).join("\n");
+    const rawTokens = Math.ceil(rawText.length / 4);
+    const summary = extractiveSummarize(messages);
+    const ratio = rawTokens / summary.tokenEstimate;
+    // Compression should be at least 5:1 (target is 35:1)
+    assert.ok(ratio >= 5, `compression ratio ${ratio.toFixed(1)}:1 is less than 5:1`);
+    assert.ok(summary.tokenEstimate < 5000, `summary is ${summary.tokenEstimate} tokens (expected < 5000)`);
+});
+// ---- Empty input ------------------------------------------------------------
+test("empty messages returns minimal summary", () => {
+    const summary = extractiveSummarize([]);
+    assert.equal(summary.topicSummary, "(empty)");
+    assert.equal(summary.keyDecisions.length, 0);
+    assert.equal(summary.nextSteps.length, 0);
+    assert.equal(summary.filesModified.length, 0);
+    assert.equal(summary.tokenEstimate, 0);
+});
+// ---- Key decisions ----------------------------------------------------------
+test("extracts decisions from assistant messages", () => {
+    const messages = [
+        msg("user", "which database should we use?"),
+        msg("assistant", "I recommend using better-sqlite3 for the local vector store."),
+        msg("assistant", "Let's go with the Trident pipeline architecture."),
+    ];
+    const summary = extractiveSummarize(messages);
+    assert.ok(summary.keyDecisions.length >= 1, "should extract at least 1 decision");
+    assert.ok(summary.keyDecisions.some((d) => d.includes("better-sqlite3")), `decisions: ${JSON.stringify(summary.keyDecisions)}`);
+});
+test("no decisions in tool messages", () => {
+    const messages = [
+        msg("tool", "I recommend something", "bash"),
+    ];
+    const summary = extractiveSummarize(messages);
+    // Tool messages should not be checked for decisions
+    assert.equal(summary.keyDecisions.length, 0);
+});
+// ---- Files modified ---------------------------------------------------------
+test("extracts files from write/edit tool calls", () => {
+    const messages = [
+        msg("tool", '{"file_path":"/home/user/project/src/index.ts","content":"..."}', "write"),
+        msg("tool", '{"file_path":"/home/user/project/README.md","content":"..."}', "edit"),
+    ];
+    const summary = extractiveSummarize(messages);
+    assert.ok(summary.filesModified.includes("/home/user/project/src/index.ts"));
+    assert.ok(summary.filesModified.includes("/home/user/project/README.md"));
+});
+test("extracts files from git commands in bash", () => {
+    const messages = [
+        msg("tool", "git add src/index.ts src/types.ts", "bash"),
+    ];
+    const summary = extractiveSummarize(messages);
+    assert.ok(summary.filesModified.some((f) => f.includes("index.ts")));
+});
+// ---- Pending work -----------------------------------------------------------
+test("extracts pending work markers", () => {
+    const messages = [
+        msg("user", "run the tests"),
+        msg("assistant", "Tests pass. TODO: add integration tests for the dedup path."),
+    ];
+    const summary = extractiveSummarize(messages);
+    assert.ok(summary.nextSteps.length >= 1, "should find TODO");
+    assert.ok(summary.nextSteps.some((s) => /integration tests/i.test(s)));
+});
+// ---- topicSummary structure -------------------------------------------------
+test("topicSummary contains scope line", () => {
+    const messages = [
+        msg("user", "hello"),
+        msg("assistant", "hi there"),
+    ];
+    const summary = extractiveSummarize(messages);
+    assert.ok(summary.topicSummary.includes("Conversation: 2 messages"));
+    assert.ok(summary.topicSummary.includes("1 user"));
+    assert.ok(summary.topicSummary.includes("1 assistant"));
+});
+test("topicSummary includes tools when present", () => {
+    const messages = [
+        msg("tool", "ok", "write"),
+        msg("tool", "ok", "bash"),
+    ];
+    const summary = extractiveSummarize(messages);
+    assert.ok(summary.topicSummary.includes("Tools:"));
+    assert.ok(summary.topicSummary.includes("write"));
+    assert.ok(summary.topicSummary.includes("bash"));
+});
+// ---- Same messages produce same summary ------------------------------------
+test("deterministic across invocations with complex input", () => {
+    const messages = [
+        msg("user", "help me refactor the auth module"),
+        msg("assistant", "I'll look at the current auth implementation."),
+        msg("tool", '{"file_path":"src/auth.ts"}', "read"),
+        msg("assistant", "I recommend splitting auth.ts into separate files."),
+        msg("user", "sounds good, go ahead"),
+        msg("assistant", "I'll create src/auth/login.ts and src/auth/register.ts."),
+        msg("tool", '{"file_path":"src/auth/login.ts","content":"..."}', "write"),
+        msg("tool", '{"file_path":"src/auth/register.ts","content":"..."}', "write"),
+        msg("assistant", "Done. TODO: update the import paths in main.ts."),
+    ];
+    const results = Array.from({ length: 5 }, () => extractiveSummarize(messages));
+    for (let i = 1; i < results.length; i++) {
+        assert.deepStrictEqual(results[i], results[0], `run ${i} differs from run 0`);
+    }
+});

package/dist/src/httpEmbedder.js

@@ -0,0 +1,143 @@
+/**
+ * httpEmbedder.ts — pluggable LOCALHOST embeddings client (Sprint 12, BYO).
+ *
+ * Lets the user bring their own embedding backend WITHOUT this extension
+ * shipping a model, a native dependency, or a remote call. The backend is a
+ * localhost HTTP server the user runs themselves (local ONNX/TEI/llamafile/
+ * Ollama-embeddings/…) and points us at via MEGACOMPACT_EMBEDDING_URL.
+ *
+ * This honors PREVENT-PI-004 (critical: local-only, zero remote network): the
+ * only allowed network is a user-spawned localhost endpoint, in the same
+ * exception class as the optional /dashboard UI server. It is NOT a remote
+ * provider call — compacted conversation content never leaves the machine.
+ *
+ * The endpoint contract (OpenAI-style, tolerant parser):
+ *   request:  POST { url }  body { "input": ["<text>"] }
+ *   response: { "data": [ { "embedding": [0.1, …] } ] }   (also accepts
+ *             { "embeddings": [...] } and { "data": [[...]] })
+ *
+ * VectorStore is deliberately synchronous, so embed() runs the network call in
+ * a short-lived child process (its own event loop) and blocks the parent with
+ * spawnSync. We deliberately do NOT use Atomics.wait on the main thread — that
+ * would deadlock fetch (the blocked main thread can't pump the socket, so the
+ * promise never settles). A child process has its own event loop, so spawnSync
+ * blocks without that deadlock. Only used when this embedder is selected; the
+ * default TrigramEmbedder path stays pure-sync, zero-network, zero-native.
+ */
+import { l2Normalize } from "./embedder.js";
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: localhost-only user-spawned embedding server (BYO backend, never remote)
+/** Read + validate the localhost embeddings config from the environment. */
+export function embeddingConfigFromEnv() {
+    const url = process.env.MEGACOMPACT_EMBEDDING_URL;
+    if (!url)
+        return null;
+    if (!/^https?:\/\/localhost[:/]/.test(url) && !/^https?:\/\/127\.0\.0\.1[:/]/.test(url)) {
+        // Only loopback is permitted — a remote host would violate PREVENT-PI-004.
+        throw new Error(`MEGACOMPACT_EMBEDDING_URL must be a localhost/127.0.0.1 endpoint (got ${url}). ` +
+            `Remote embedding endpoints are not allowed (PREVENT-PI-004).`);
+    }
+    const headers = {};
+    if (process.env.MEGACOMPACT_EMBEDDING_HEADERS) {
+        try {
+            Object.assign(headers, JSON.parse(process.env.MEGACOMPACT_EMBEDDING_HEADERS));
+        }
+        catch {
+            throw new Error("MEGACOMPACT_EMBEDDING_HEADERS must be valid JSON");
+        }
+    }
+    const dim = process.env.MEGACOMPACT_EMBEDDING_DIM
+        ? Number(process.env.MEGACOMPACT_EMBEDDING_DIM)
+        : undefined;
+    return {
+        url,
+        apiKey: process.env.MEGACOMPACT_EMBEDDING_KEY,
+        headers,
+        dim: Number.isFinite(dim) ? dim : undefined,
+    };
+}
+/** Extract a single embedding vector from a tolerant OpenAI-style response. */
+function parseEmbedding(body) {
+    if (body && typeof body === "object") {
+        const b = body;
+        if (Array.isArray(b.data) && b.data[0] && typeof b.data[0] === "object") {
+            const first = b.data[0];
+            if (Array.isArray(first.embedding))
+                return first.embedding;
+            if (Array.isArray(first))
+                return first;
+        }
+        if (Array.isArray(b.embeddings))
+            return b.embeddings[0];
+        if (Array.isArray(b.data))
+            return b.data;
+    }
+    throw new Error("embeddings response missing a recognized vector shape");
+}
+// Inline worker script: performs the async fetch in a child process that has
+// its own event loop (no main-thread deadlock), writes the JSON response to
+// stdout. Reads request from env to avoid shell-quoting the body.
+const WORKER = String.raw `
+const u = process.env.MC_URL, b = process.env.MC_BODY, h = JSON.parse(process.env.MC_HEADERS || "{}");
+try {
+  const r = await fetch(u, { method: "POST", headers: h, body: b }); // guardrails-allow PREVENT-PI-004: localhost-only user-spawned embedding server (BYO backend, never remote)
+  const out = JSON.stringify({ status: r.status, ok: r.ok, json: await r.json() });
+  process.stdout.write(out);
+} catch (e) {
+  process.stdout.write(JSON.stringify({ error: String(e && e.message ? e.message : e) }));
+}
+`;
+export class HttpEmbedder {
+    url;
+    apiKey;
+    headers;
+    resolvedDim;
+    constructor(opts) {
+        this.url = opts.url;
+        this.apiKey = opts.apiKey;
+        this.headers = opts.headers ?? {};
+        this.resolvedDim = opts.dim ?? 0; // resolved after the first embed
+    }
+    get dim() {
+        return this.resolvedDim;
+    }
+    embed(text) {
+        const body = JSON.stringify({ input: [text] });
+        const headers = {
+            "content-type": "application/json",
+            ...this.headers,
+        };
+        if (this.apiKey)
+            headers["authorization"] = `Bearer ${this.apiKey}`;
+        // localhost-only fetch — audited PREVENT-PI-004 exception (user-spawned
+        // local embedding server, same class as the /dashboard localhost UI). The
+        // child has its own event loop, so spawnSync blocks without deadlocking.
+        const res = spawnSync(process.execPath, ["-e", WORKER], {
+            encoding: "utf8",
+            env: {
+                ...process.env,
+                MC_URL: this.url,
+                MC_BODY: body,
+                MC_HEADERS: JSON.stringify(headers),
+            },
+        });
+        if (res.error || typeof res.stdout !== "string" || res.stdout.length === 0) {
+            const detail = res.error ? String(res.error) : res.stderr || "empty response";
+            throw new Error(`embedding server ${this.url} unreachable: ${detail}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(res.stdout);
+        }
+        catch {
+            throw new Error(`embedding server ${this.url} returned non-JSON: ${res.stdout.slice(0, 200)}`);
+        }
+        if (parsed.error)
+            throw new Error(`embedding server ${this.url} failed: ${parsed.error}`);
+        if (!parsed.ok)
+            throw new Error(`embedding server ${this.url} returned ${parsed.status}`);
+        const vec = parseEmbedding(parsed.json);
+        if (this.resolvedDim === 0)
+            this.resolvedDim = vec.length;
+        return l2Normalize(vec);
+    }
+}

package/dist/src/log.js

@@ -0,0 +1,47 @@
+/**
+ * log.ts — tiny append-only structured logger.
+ *
+ * Writes one JSON object per line to a log file (default:
+ * ~/.pi/agent/extensions/mega-compact.log). Best-effort: logging never throws
+ * into the extension. Pi-agnostic and dependency-free so it can be unit-tested.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { STATE_DIR_DEFAULT } from "./config.js";
+/** Default log path lives alongside the state dir. */
+export function defaultLogPath() {
+    return join(STATE_DIR_DEFAULT, "mega-compact.log");
+}
+export class Logger {
+    path;
+    enabled;
+    /** Monotonic clock injected by the caller so the module stays deterministic. */
+    now;
+    constructor(opts = {}) {
+        this.path = opts.path ?? defaultLogPath();
+        this.enabled = opts.enabled ?? true;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Append one structured line. Swallows all I/O errors. */
+    log(level, event, fields = {}) {
+        if (!this.enabled)
+            return;
+        const entry = { ts: this.now(), level, event, ...fields };
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            appendFileSync(this.path, `${JSON.stringify(entry)}\n`);
+        }
+        catch {
+            /* best-effort: never break the extension on a log failure */
+        }
+    }
+    info(event, fields) {
+        this.log("info", event, fields);
+    }
+    warn(event, fields) {
+        this.log("warn", event, fields);
+    }
+    error(event, fields) {
+        this.log("error", event, fields);
+    }
+}

package/dist/src/log.test.js

@@ -0,0 +1,42 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Logger } from "./log.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-log-"));
+let counter = 0;
+function logPath() {
+    return join(baseTmp, `run-${counter++}`, "mega-compact.log");
+}
+test("logger appends one JSON line per entry", () => {
+    const path = logPath();
+    let clock = 1000;
+    const log = new Logger({ path, now: () => clock++ });
+    log.info("compact", { checkpointId: "chkpt_001" });
+    log.warn("recall-empty", { query: "x" });
+    const lines = readFileSync(path, "utf8").trim().split("\n");
+    assert.equal(lines.length, 2);
+    const first = JSON.parse(lines[0]);
+    assert.equal(first.level, "info");
+    assert.equal(first.event, "compact");
+    assert.equal(first.checkpointId, "chkpt_001");
+    assert.equal(first.ts, 1000);
+    const second = JSON.parse(lines[1]);
+    assert.equal(second.level, "warn");
+    assert.equal(second.ts, 1001);
+});
+test("disabled logger writes nothing", () => {
+    const path = logPath();
+    const log = new Logger({ path, enabled: false });
+    log.info("compact", { a: 1 });
+    assert.equal(existsSync(path), false);
+});
+test("logger never throws on a bad path", () => {
+    // A path whose parent cannot be created (null byte) — must be swallowed.
+    const log = new Logger({ path: "/\0/nope.log" });
+    assert.doesNotThrow(() => log.error("boom", { x: 1 }));
+});
+test("cleanup", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/src/minilm.js

@@ -0,0 +1,92 @@
+/**
+ * minilm.ts — local MiniLM (all-MiniLM-L6-v2) sentence embedder (Sprint 12).
+ *
+ * Implements the `Embedder` interface so it drops into the existing VectorStore
+ * dedup cascade and search with no call-site changes. Inference is 100% local:
+ * the ONNX model + WordPiece vocab are on-disk artifacts fetched once by
+ * scripts/setup-minilm.mjs. There is NO network call at runtime (PREVENT-PI-004).
+ *
+ * Inputs (dynamic): input_ids, attention_mask, token_type_ids (int64).
+ * Output: last_hidden_state (batch, seq, 384). We mean-pool over non-padded
+ * tokens (attention_mask == 1) and L2-normalize → 384-dim unit vector.
+ *
+ * The ONNX session + tokenizer are loaded LAZILY on first embed() so the default
+ * TrigramEmbedder path (and its zero native-init cost) is untouched unless
+ * MEGACOMPACT_EMBEDDER=minilm is selected.
+ */
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { l2Normalize, awaitSync } from "./embedder.js";
+import { WordPieceTokenizer } from "./wordpiece.js";
+export const MINILM_DIM = 384;
+export const MINILM_MAX_LEN = 256;
+/** Resolve the model directory: MEGACOMPACT_MINILM_DIR > ./models/minilm > ~/.pi … */
+function resolveModelDir() {
+    if (process.env.MEGACOMPACT_MINILM_DIR)
+        return process.env.MEGACOMPACT_MINILM_DIR;
+    // Repo-local vendored path (gitignored).
+    const local = join(process.cwd(), "models", "minilm");
+    if (existsSync(local))
+        return local;
+    return join(homedir(), ".pi", "agent", "extensions", "mega-compact", "models", "minilm");
+}
+export class MiniLMEmbedder {
+    dim = MINILM_DIM;
+    session = null;
+    tokenizer = null;
+    modelDir;
+    loadPromise = null;
+    constructor(modelDir = resolveModelDir()) {
+        this.modelDir = modelDir;
+    }
+    async ensureLoaded() {
+        if (this.session && this.tokenizer)
+            return;
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.loadPromise = (async () => {
+            const ort = await import("onnxruntime-node");
+            const modelPath = join(this.modelDir, "model_quantized.onnx");
+            const vocabPath = join(this.modelDir, "vocab.txt");
+            if (!existsSync(modelPath) || !existsSync(vocabPath)) {
+                throw new Error(`MiniLM artifacts missing in ${this.modelDir}. Run: node scripts/setup-minilm.mjs`);
+            }
+            // 1 thread is plenty for a single short-region embed and bounds CPU.
+            this.session = await ort.InferenceSession.create(modelPath, {
+                executionProviders: ["cpu"],
+                graphOptimizationLevel: "all",
+            });
+            this.tokenizer = WordPieceTokenizer.fromVocabFile(vocabPath);
+        })();
+        return this.loadPromise;
+    }
+    embed(text) {
+        awaitSync(this.ensureLoaded());
+        const enc = this.tokenizer.encode(text, MINILM_MAX_LEN);
+        const n = enc.inputIds.length;
+        const BigInt64 = (arr) => arr.map((x) => BigInt(x));
+        const ort = awaitSync(import("onnxruntime-node"));
+        const tensors = {
+            input_ids: new ort.Tensor("int64", BigInt64(enc.inputIds), [1, n]),
+            attention_mask: new ort.Tensor("int64", BigInt64(enc.attentionMask), [1, n]),
+            token_type_ids: new ort.Tensor("int64", BigInt64(enc.tokenTypeIds), [1, n]),
+        };
+        const out = awaitSync(this.session.run(tensors));
+        const hidden = out.last_hidden_state.data;
+        // hidden shape: [1, n, 384]. Mean-pool over non-padded positions.
+        const pooled = new Array(MINILM_DIM).fill(0);
+        let count = 0;
+        for (let i = 0; i < n; i++) {
+            if (enc.attentionMask[i] === 0)
+                continue;
+            const base = i * MINILM_DIM;
+            for (let d = 0; d < MINILM_DIM; d++)
+                pooled[d] += hidden[base + d];
+            count++;
+        }
+        if (count === 0)
+            return l2Normalize(new Array(MINILM_DIM).fill(0));
+        return l2Normalize(pooled.map((x) => x / count));
+    }
+}

package/dist/src/monitoring.js

@@ -0,0 +1,131 @@
+/**
+ * monitoring.ts — local dedup monitoring + alerting (Sprint 14, Phase 7).
+ *
+ * Per-decision structured events go to `events.log` (append-only JSON).
+ * Aggregate metrics (hit rate, FP rate, per-tier p95 latency, storage) go to
+ * `dashboard.json` — the SAME local-only file the /dashboard UI reads. There is
+ * NO Prometheus port and NO network listener (PREVENT-PI-004). Alerting is local
+ * only: an FP-rate breach flips the tier to MARK_ONLY and writes a warning.
+ *
+ * Best-effort: logging/metrics never throw into the add()/search() path.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { STATE_DIR_DEFAULT } from "./config.js";
+const TIERS = ["L0", "L1", "L2", "RAPTOR"];
+function emptyMetrics() {
+    const dec = {};
+    const dp = {};
+    const fp = {};
+    const lat = {};
+    for (const t of TIERS) {
+        dec[t] = 0;
+        dp[t] = 0;
+        fp[t] = 0;
+        lat[t] = [];
+    }
+    return { decisions: dec, deduped: dp, falsePositives: fp, latency: lat, storageBytes: 0 };
+}
+/** Append a structured decision event to events.log (best-effort). */
+export function logDecision(path, ev) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, `${JSON.stringify(ev)}\n`);
+    }
+    catch {
+        /* never break the extension on a log failure */
+    }
+}
+/**
+ * Load metrics from dashboard.json, or return a fresh empty snapshot.
+ * Kept simple + synchronous (no network).
+ */
+export function loadMetrics(path) {
+    try {
+        if (existsSync(path)) {
+            const raw = readFileSync(path, "utf-8");
+            const parsed = JSON.parse(raw);
+            const base = emptyMetrics();
+            return {
+                decisions: { ...base.decisions, ...(parsed.decisions ?? {}) },
+                deduped: { ...base.deduped, ...(parsed.deduped ?? {}) },
+                falsePositives: { ...base.falsePositives, ...(parsed.falsePositives ?? {}) },
+                latency: { ...base.latency, ...(parsed.latency ?? {}) },
+                storageBytes: parsed.storageBytes ?? 0,
+            };
+        }
+    }
+    catch {
+        /* corrupt metrics → fresh */
+    }
+    return emptyMetrics();
+}
+/** Persist metrics to dashboard.json (best-effort). */
+export function saveMetrics(path, m) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(m));
+    }
+    catch {
+        /* never break the extension */
+    }
+}
+/** Compute the p95 latency (ms) for a tier from its samples. */
+export function p95(samples) {
+    if (samples.length === 0)
+        return 0;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95));
+    return sorted[idx];
+}
+/** FP rate for a tier over the current window (0..1). */
+export function fpRate(m, tier) {
+    const decisions = m.decisions[tier] ?? 0;
+    if (decisions === 0)
+        return 0;
+    return (m.falsePositives[tier] ?? 0) / decisions;
+}
+/**
+ * Evaluate FP-rate breaches against the config thresholds. A breached fuzzy tier
+ * (L0 vs L1/L2 have different thresholds) is auto-downgraded to MARK_ONLY — the
+ * local re-map of "alertmanager" (QA #18/#19): record but don't collapse, no
+ * remote alert. Returns the tiers flipped so the caller can mutate its config.
+ */
+export function evaluateAlerts(m, cfg) {
+    const breached = [];
+    const warnings = [];
+    for (const tier of TIERS) {
+        const rate = fpRate(m, tier);
+        const limit = tier === "L0" ? cfg.FP_RATE_L0 : cfg.FP_RATE_L1L2;
+        if (rate > limit) {
+            breached.push(tier);
+            warnings.push(`DEDUP FP BREACH tier=${tier} rate=${rate.toFixed(4)} > ${limit}`);
+        }
+    }
+    return { breached, warnings };
+}
+/**
+ * Record one decision into the metrics snapshot (mutates `m` in place) and
+ * returns the updated snapshot. Caps stored latency samples to keep memory
+ * bounded (last 1000 per tier).
+ */
+export function recordDecision(m, tier, result, latencyMs, falsePositive = false) {
+    m.decisions[tier] = (m.decisions[tier] ?? 0) + 1;
+    if (result === "deduped")
+        m.deduped[tier] = (m.deduped[tier] ?? 0) + 1;
+    if (falsePositive)
+        m.falsePositives[tier] = (m.falsePositives[tier] ?? 0) + 1;
+    const arr = m.latency[tier] ?? (m.latency[tier] = []);
+    arr.push(latencyMs);
+    if (arr.length > 1000)
+        arr.shift();
+    return m;
+}
+/** Default metrics path alongside the state dir. */
+export function defaultMetricsPath(stateDir = STATE_DIR_DEFAULT) {
+    return join(stateDir, "dashboard.json");
+}
+/** Default events-log path alongside the state dir. */
+export function defaultEventsPath(stateDir = STATE_DIR_DEFAULT) {
+    return join(stateDir, "events.log");
+}