pi-mega-compact 0.4.0

package/src/extractive.ts

@@ -0,0 +1,265 @@
+/**
+ * extractive.ts — deterministic, LLM-free extractive summary engine.
+ *
+ * Replaces the "Key timeline" dump in compact.ts with structured extraction:
+ * topicSummary (one paragraph), keyDecisions, nextSteps, filesModified.
+ *
+ * Target compression: 70K tokens → ~2K tokens (35:1).
+ * Deterministic: same messages → same output, every time.
+ */
+
+import type { EngineMessage } from "./types.js";
+import { estimateBlockTokens } from "./tokens.js";
+
+// ---- Limits ----------------------------------------------------------------
+
+const MAX_RECENT_USER = 3;
+const MAX_DECISIONS = 5;
+const MAX_FILES = 10;
+const MAX_PENDING = 5;
+const MAX_TOPIC_LINES = 12;
+
+// ---- Truncation helper -----------------------------------------------------
+
+function truncate(s: string, maxLen: number): string {
+  if (s.length <= maxLen) return s;
+  return s.slice(0, maxLen - 1) + "…";
+}
+
+// ---- Turn brief (conversation arc) -----------------------------------------
+
+export interface TurnBrief {
+  role: string;
+  action: string;
+}
+
+// ---- Full extracted summary ------------------------------------------------
+
+export interface ExtractiveSummary {
+  topicSummary: string;
+  keyDecisions: string[];
+  nextSteps: string[];
+  filesModified: string[];
+  tokenEstimate: number;
+}
+
+/**
+ * Build a one-paragraph topic summary from the message slice.
+ *
+ * This is the compressed replacement for the raw "Key timeline" loop.
+ * Captures: tools used, recent user requests, current work, key files,
+ * pending work. Typically 12 lines / ~500 tokens instead of ~70K.
+ */
+function buildTopicSummary(
+  messages: EngineMessage[],
+  tools: string[],
+  recentUser: string[],
+  currentWork: string | undefined,
+  keyFiles: string[],
+  pending: string[],
+): string {
+  const lines: string[] = [];
+
+  // Scope line
+  const users = messages.filter((m) => m.role === "user");
+  const assistants = messages.filter((m) => m.role === "assistant");
+  const toolMsgs = messages.filter((m) => m.role === "tool");
+  lines.push(
+    `Conversation: ${messages.length} messages (${users.length} user, ` +
+      `${assistants.length} assistant, ${toolMsgs.length} tool). ` +
+      (tools.length ? `Tools: ${tools.join(", ")}.` : "No tools used."),
+  );
+
+  // Recent user requests
+  if (recentUser.length) {
+    lines.push("User requests:");
+    for (const r of recentUser) lines.push(`  • ${r}`);
+  }
+
+  // Current work
+  if (currentWork) lines.push(`Current work: ${currentWork}`);
+
+  // Key files
+  if (keyFiles.length) lines.push(`Key files: ${keyFiles.join(", ")}.`);
+
+  // Pending work
+  if (pending.length) {
+    lines.push("Pending work:");
+    for (const p of pending) lines.push(`  • ${p}`);
+  }
+
+  // Cap total length
+  return lines.slice(0, MAX_TOPIC_LINES).join("\n");
+}
+
+// ---- File path extraction --------------------------------------------------
+
+const INTERESTING_EXT = new Set(["rs", "ts", "tsx", "js", "json", "md"]);
+const FILE_PATH_RE = /(?:^|\s)([^\s"`']+\.(rs|ts|tsx|js|json|md|py|sh|sql|toml|yaml|yml|css|html))\b/g;
+
+function extractFilePaths(text: string): string[] {
+  const paths: string[] = [];
+  for (const m of text.matchAll(FILE_PATH_RE)) {
+    const filePath = m[1];
+    const ext = m[2];
+    const basename = filePath.split("/").pop() ?? filePath;
+    if (basename === "node_modules" || filePath.includes("node_modules/")) continue;
+    if (INTERESTING_EXT.has(ext)) paths.push(filePath);
+  }
+  return paths;
+}
+
+// ---- Recent user requests (existing logic, kept) ---------------------------
+
+function collectRecentUserRequests(
+  messages: EngineMessage[],
+  limit: number,
+): string[] {
+  const requests: string[] = [];
+  for (let i = messages.length - 1; i >= 0 && requests.length < limit; i--) {
+    if (messages[i].role === "user") {
+      let snippet = messages[i].text.split("\n").slice(0, 3).join(" ");
+      snippet = snippet.replace(/^.+\nProcessed\$?\s*/i, "").replace(/\n/g, " ");
+      requests.push(truncate(snippet, 200));
+    }
+  }
+  return requests.reverse();
+}
+
+// ---- Pending work (existing logic, kept) -----------------------------------
+
+const PENDING_WORDS = ["todo", "next", "pending", "follow up", "remaining"];
+
+function inferPendingWork(messages: EngineMessage[]): string[] {
+  const pending: string[] = [];
+  const recent = messages.slice(-5);
+  for (const m of recent) {
+    const t = m.text.toLowerCase();
+    if (PENDING_WORDS.some((w) => t.includes(w))) {
+      const snippet = m.text.split("\n").find((l) => PENDING_WORDS.some((w) => l.toLowerCase().includes(w)));
+      if (snippet) pending.push(truncate(snippet.trim(), 180));
+    }
+  }
+  return [...new Set(pending)].slice(0, MAX_PENDING);
+}
+
+// ---- Current work (existing logic, kept) -----------------------------------
+
+function inferCurrentWork(messages: EngineMessage[]): string | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== "assistant") continue;
+    const path = m.text.match(
+      /(?:^|\s)([^\s"`':]+\.(rs|ts|tsx|js|json|md|py|toml|yaml|yml|sql))\b/m,
+    );
+    if (path) {
+      const line = m.text.split("\n").slice(0, 2).join(" ");
+      return truncate(line, 200);
+    }
+  }
+  return undefined;
+}
+
+// ---- Key decisions ---------------------------------------------------------
+
+const DECISION_PATTERNS = [
+  /(?:I('ll| will| decided to| chose to| recommend| suggest))\s+(.{10,120})/i,
+  /(?:let's|we('ll| should| can| will))\s+(.{10,120})/i,
+  /(?:the (?:plan|approach|decision|strategy) is (?:to )?)\s*(.{10,120})/i,
+  /(?:going (?:with|forward))\s+(.{10,120})/i,
+];
+
+function extractDecisions(messages: EngineMessage[]): string[] {
+  const decisions: string[] = [];
+  // Only look at assistant messages (they make/receive decisions)
+  for (const m of messages) {
+    if (m.role !== "assistant") continue;
+    const text = m.text;
+    if (!text || text.length < 20) continue;
+    for (const pat of DECISION_PATTERNS) {
+      const match = text.match(pat);
+      if (match) {
+        const decision = match[2]?.trim();
+        if (decision && decision.length > 10) {
+          decisions.push(truncate(decision, 150));
+        }
+      }
+    }
+    if (decisions.length >= MAX_DECISIONS) break;
+  }
+  return [...new Set(decisions)];
+}
+
+// ---- Files modified --------------------------------------------------------
+
+function extractFilesModified(tools: EngineMessage[]): string[] {
+  const files = new Set<string>();
+  for (const m of tools) {
+    if (!m.toolName) continue;
+    const name = m.toolName.toLowerCase();
+    if (name === "write" || name === "edit" || name === "notebookedit") {
+      // Extract file path from input payload
+      const input = m.input ?? m.text;
+      const pathMatch = input.match(/["']?(\/[^\s"']+\.\w+)["']?/);
+      if (pathMatch) files.add(pathMatch[1]);
+    }
+    if (name === "bash") {
+      const cmd = m.input ?? m.text;
+      if (cmd.includes("git add") || cmd.includes("git commit") || cmd.includes("git diff")) {
+        for (const p of extractFilePaths(cmd)) files.add(p);
+      }
+    }
+  }
+  return [...files].slice(0, MAX_FILES);
+}
+
+// ---- Public API ------------------------------------------------------------
+
+/**
+ * Deterministic extractive summary. Same messages → same output, every time.
+ *
+ * Returns structured data + a pre-formatted topicSummary string.
+ * Compression target: 70K tokens → ~2K tokens.
+ */
+export function extractiveSummarize(messages: EngineMessage[]): ExtractiveSummary {
+  if (messages.length === 0) {
+    return { topicSummary: "(empty)", keyDecisions: [], nextSteps: [], filesModified: [], tokenEstimate: 0 };
+  }
+
+  const toolMsgs = messages.filter((m) => m.role === "tool");
+  const tools = [...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : [])))].sort();
+
+  const recentUser = collectRecentUserRequests(messages, MAX_RECENT_USER);
+  const currentWork = inferCurrentWork(messages);
+  const keyFiles = collectKeyFiles(messages);
+  const pending = inferPendingWork(messages);
+  const keyDecisions = extractDecisions(messages);
+  const filesModified = extractFilesModified(toolMsgs);
+
+  const topicSummary = buildTopicSummary(
+    messages, tools, recentUser, currentWork, keyFiles, pending,
+  );
+
+  const tokenEstimate = estimateBlockTokens(topicSummary);
+
+  return { topicSummary, keyDecisions, nextSteps: pending, filesModified, tokenEstimate };
+}
+
+// ---- Key files (existing logic from compact.ts, moved here) ----------------
+
+const MAX_KEY_FILES = 5;
+const FRESHNESS_WINDOW = 10;
+
+function collectKeyFiles(messages: EngineMessage[]): string[] {
+  const recent = messages.slice(-FRESHNESS_WINDOW);
+  const pathFreq = new Map<string, number>();
+  for (const m of recent) {
+    for (const p of extractFilePaths(m.text)) {
+      pathFreq.set(p, (pathFreq.get(p) ?? 0) + 1);
+    }
+  }
+  return [...pathFreq.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, MAX_KEY_FILES)
+    .map(([p]) => p);
+}

package/src/httpEmbedder.ts

@@ -0,0 +1,154 @@
+/**
+ * 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 type { Embedder, Vector } from "./embedder.js";
+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)
+
+export interface HttpEmbedderOptions {
+  url: string;
+  /** Bearer token, if the local server requires one. */
+  apiKey?: string;
+  /** Extra request headers as a JSON object (env: MEGACOMPACT_EMBEDDING_HEADERS). */
+  headers?: Record<string, string>;
+  /** Known embedding dimension, if the server exposes it statically. */
+  dim?: number;
+}
+
+/** Read + validate the localhost embeddings config from the environment. */
+export function embeddingConfigFromEnv(): HttpEmbedderOptions | null {
+  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: Record<string, string> = {};
+  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: unknown): number[] {
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>;
+    if (Array.isArray(b.data) && b.data[0] && typeof b.data[0] === "object") {
+      const first = b.data[0] as Record<string, unknown>;
+      if (Array.isArray(first.embedding)) return first.embedding as number[];
+      if (Array.isArray(first)) return first as number[];
+    }
+    if (Array.isArray(b.embeddings)) return b.embeddings[0] as number[];
+    if (Array.isArray(b.data)) return b.data as number[];
+  }
+  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 implements Embedder {
+  private readonly url: string;
+  private readonly apiKey?: string;
+  private readonly headers: Record<string, string>;
+  private resolvedDim: number;
+
+  constructor(opts: HttpEmbedderOptions) {
+    this.url = opts.url;
+    this.apiKey = opts.apiKey;
+    this.headers = opts.headers ?? {};
+    this.resolvedDim = opts.dim ?? 0; // resolved after the first embed
+  }
+
+  get dim(): number {
+    return this.resolvedDim;
+  }
+
+  embed(text: string): Vector {
+    const body = JSON.stringify({ input: [text] });
+    const headers: Record<string, string> = {
+      "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], { // guardrails-allow PREVENT-PI-004: localhost-only user-spawned embedding server (BYO backend, never remote)
+      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: { status?: number; ok?: boolean; json?: unknown; error?: string };
+    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/src/log.test.ts

@@ -0,0 +1,47 @@
+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/src/log.ts

@@ -0,0 +1,60 @@
+/**
+ * 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";
+
+export type LogLevel = "info" | "warn" | "error";
+
+export interface LogEntry {
+  ts: number;
+  level: LogLevel;
+  event: string;
+  [k: string]: unknown;
+}
+
+/** Default log path lives alongside the state dir. */
+export function defaultLogPath(): string {
+  return join(STATE_DIR_DEFAULT, "mega-compact.log");
+}
+
+export class Logger {
+  private readonly path: string;
+  private readonly enabled: boolean;
+  /** Monotonic clock injected by the caller so the module stays deterministic. */
+  private readonly now: () => number;
+
+  constructor(opts: { path?: string; enabled?: boolean; now?: () => number } = {}) {
+    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: LogLevel, event: string, fields: Record<string, unknown> = {}): void {
+    if (!this.enabled) return;
+    const entry: LogEntry = { 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: string, fields?: Record<string, unknown>): void {
+    this.log("info", event, fields);
+  }
+  warn(event: string, fields?: Record<string, unknown>): void {
+    this.log("warn", event, fields);
+  }
+  error(event: string, fields?: Record<string, unknown>): void {
+    this.log("error", event, fields);
+  }
+}

package/src/monitoring.ts

@@ -0,0 +1,171 @@
+/**
+ * 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";
+import type { DedupConfigShape } from "./config/dedup.js";
+import type { DedupTier } from "./config/dedup.js";
+
+export interface DedupDecisionEvent {
+  ts: number;
+  tier: DedupTier;
+  result: "deduped" | "new" | "mark_only";
+  reason?: string;
+  latencyMs: number;
+  /** True when this dedup was later found to be a false positive. */
+  falsePositive?: boolean;
+}
+
+export interface DedupMetrics {
+  /** Decisions per tier. */
+  decisions: Record<string, number>;
+  /** Deduped (collapsed) per tier. */
+  deduped: Record<string, number>;
+  /** Rolling FP count per tier (within the alert window). */
+  falsePositives: Record<string, number>;
+  /** Latency samples per tier (for p95). */
+  latency: Record<string, number[]>;
+  /** Total storage bytes (checkpoint blobs). */
+  storageBytes: number;
+}
+
+const TIERS: DedupTier[] = ["L0", "L1", "L2", "RAPTOR"];
+
+function emptyMetrics(): DedupMetrics {
+  const dec: Record<string, number> = {};
+  const dp: Record<string, number> = {};
+  const fp: Record<string, number> = {};
+  const lat: Record<string, number[]> = {};
+  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: string, ev: DedupDecisionEvent): void {
+  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: string): DedupMetrics {
+  try {
+    if (existsSync(path)) {
+      const raw = readFileSync(path, "utf-8");
+      const parsed = JSON.parse(raw) as Partial<DedupMetrics>;
+      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: string, m: DedupMetrics): void {
+  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: number[]): number {
+  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: DedupMetrics, tier: DedupTier): number {
+  const decisions = m.decisions[tier] ?? 0;
+  if (decisions === 0) return 0;
+  return (m.falsePositives[tier] ?? 0) / decisions;
+}
+
+export interface AlertResult {
+  /** Tiers newly flipped to MARK_ONLY by this alert pass. */
+  breached: DedupTier[];
+  /** Warning lines written to events.log. */
+  warnings: string[];
+}
+
+/**
+ * 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: DedupMetrics,
+  cfg: DedupConfigShape,
+): AlertResult {
+  const breached: DedupTier[] = [];
+  const warnings: string[] = [];
+  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: DedupMetrics,
+  tier: DedupTier,
+  result: "deduped" | "new" | "mark_only",
+  latencyMs: number,
+  falsePositive = false,
+): DedupMetrics {
+  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: string = STATE_DIR_DEFAULT): string {
+  return join(stateDir, "dashboard.json");
+}
+
+/** Default events-log path alongside the state dir. */
+export function defaultEventsPath(stateDir: string = STATE_DIR_DEFAULT): string {
+  return join(stateDir, "events.log");
+}