phaedo-mcp 0.2.1 → 0.3.0

package/vendor/capture/exchanges.js

@@ -0,0 +1,77 @@
+// Phaedo capture — reconstructed {role, text} turns → exchange_batch.
+//
+// The tier-agnostic front door for capture surfaces that read a RENDERED transcript
+// (the Track B OS-accessibility helper: Claude Desktop's chat tab, later an OCR tier)
+// rather than Claude Code's JSONL. It emits the SAME exchange_batch shape transcript.js
+// produces (recordsToBatch), so everything downstream — detectors, state, delta-lift,
+// deposit — consumes it unchanged. The only thing that differs per surface is how the
+// turns are obtained; this module is where a11y/OCR/JSONL converge onto one pipeline.
+//
+// Pure: no model, no network, no persistence. The turns' raw text lives here only as the
+// returned in-memory batch; the caller runs detectors and discards it (the discard-raw
+// contract, architecture/persona-vs-conversation-memory.md).
+//
+// Turn shape (what the native front-end emits, one object per rendered turn IN ORDER):
+//   { role: 'user' | 'assistant', text: string, id?: string, timestamp?: string }
+// Anything else (role 'system'/'tool', empty text, a leading assistant turn with no
+// preceding user prompt) is ignored, mirroring transcript.js's isUserPrompt/isAssistant
+// filtering — so a UI label or a streamed-but-partial turn can't fabricate an exchange.
+
+const PLATFORM = 'a11y';
+
+// Turns → exchange_batch. Each user turn is paired with the assistant text that follows
+// it (concatenated across consecutive assistant turns) up to the next user turn. A
+// trailing user turn with no reply yet is dropped (incomplete exchange), matching both
+// the web path and transcript.js. `user_prompts` collects EVERY genuine user turn (Path-A
+// counts at send time, so an unanswered correction still counts).
+//   turns — array of { role, text, id?, timestamp? }.
+//   opts.sessionId — a STABLE per-conversation id (the front-end derives it, e.g. from the
+//     first user message, so re-reading the same chat REPLACES that session's counts in
+//     state.js instead of double-counting — the same idempotency the JSONL hook relies on).
+//   opts.platform — surface tag for the exchange records (default 'a11y').
+export function turnsToBatch(turns, opts = {}) {
+  const list = Array.isArray(turns) ? turns : [];
+  const sessionId = opts.sessionId || null;
+  const platform = opts.platform || PLATFORM;
+
+  const exchanges = [];
+  const user_prompts = [];
+  let pending = null;
+  let replyParts = [];
+  let seq = 0;
+
+  const flush = () => {
+    if (pending && replyParts.length) {
+      const ai = replyParts.join('\n').trim();
+      if (ai) {
+        exchanges.push({
+          exchange_id: pending.id,
+          session_id: sessionId,
+          platform,
+          timestamp: pending.timestamp,
+          user_msg: pending.text,
+          ai_response: ai,
+          delta_annotations: {},   // filled by the caller's detector pass (accumulateBatchCounts)
+        });
+      }
+    }
+    pending = null;
+    replyParts = [];
+  };
+
+  for (const t of list) {
+    if (!t || typeof t.text !== 'string') continue;
+    const text = t.text.trim();
+    if (!text) continue;
+    if (t.role === 'user') {
+      flush();                                  // close any previous exchange first
+      user_prompts.push(text);                  // count Path-A per sent prompt
+      pending = { id: (typeof t.id === 'string' && t.id) || `ex-${seq++}`, text, timestamp: t.timestamp || null };
+    } else if (t.role === 'assistant' && pending) {
+      replyParts.push(text);                    // a leading assistant turn (no pending) is ignored
+    }
+  }
+  flush();                                      // close the final exchange
+
+  return { exchange_batch_version: 'v0.1', session_local_id: sessionId, exchanges, user_prompts };
+}

package/vendor/capture/model-detect.js

@@ -0,0 +1,195 @@
+// Phaedo capture — option (b): the model-backed correction detector.
+//
+// Claude Code's terse register under-triggers the chat-tuned Path-A regexes
+// ("tldr pls", "why r u explaining this", "wall of text again"), so a local
+// model backend enriches capture — but as a RICHER DETECTOR, not a second
+// extraction pipeline. The model classifies ONLY the user messages the regexes
+// MISSED against the SAME correction taxonomy (CORRECTION_PATTERNS' layer/signal
+// pairs), and its hits increment the SAME per-session counters. Everything
+// downstream — per-session REPLACE state (resume-safe), cumulative delta-lift,
+// per-source snapshot deposit, owner-side combine — applies unchanged, and the
+// owner's "source:'delta' only" deposit guard stays exactly right: a model hit
+// is just a counter the regex would have incremented if it were smarter.
+//
+// Why not deposit source:'extraction' signals: reconcile merges extraction
+// signals ADDITIVELY (mergeSignal sums counts), so a SessionEnd re-fire (clear /
+// resume re-processes the full transcript) or a double-drain would inflate them.
+// Counters + per-session replace already solve that; the model feeds them.
+//
+// Privacy: regex-missed user messages are sent ONLY to the configured LOCAL
+// endpoint (Ollama / OpenAI-compatible — same trust boundary as the WebLLM
+// extraction and the consult model judge), and nothing derived from them but
+// signal names + integers is persisted or deposited (the discard-raw contract).
+//
+// Transport mirrors mcp/consult.js modelJudge (the consult Ollama plumbing):
+// POST {url}/v1/chat/completions, strict-JSON reply, hard timeout. Opt-in via
+// PHAEDO_CAPTURE_MODEL; everything here fails toward "regex counts only".
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { CORRECTION_PATTERNS, detectCorrection } from './detectors.js';
+
+// The classification taxonomy: unique (layer, signal) pairs from the mirrored
+// correction table, so the model can only ever emit counters the deterministic
+// path could also produce (and the parity test already locks against content.js).
+export function correctionTaxonomy() {
+  const seen = new Map();
+  for (const { layer, signal } of CORRECTION_PATTERNS) {
+    if (!seen.has(signal)) seen.set(signal, { layer, signal });
+  }
+  return [...seen.values()];
+}
+
+const MAX_MODEL_PROMPTS = 40;     // most recent regex-miss messages sent per session
+const CLIP_CHARS = 1500;          // per-message clip (corrections live in the first words)
+
+// The regex-miss user messages of a batch (the only ones the model sees), most
+// recent MAX_MODEL_PROMPTS. Same prompt-source fallback as accumulateBatchCounts.
+export function regexMissPrompts(batch) {
+  const exchanges = (batch && batch.exchanges) || [];
+  const prompts = (batch && Array.isArray(batch.user_prompts))
+    ? batch.user_prompts
+    : exchanges.map((e) => e.user_msg);
+  return prompts
+    .filter((t) => typeof t === 'string' && t.trim() && !detectCorrection(t))
+    .slice(-MAX_MODEL_PROMPTS)
+    .map((t) => t.slice(0, CLIP_CHARS));
+}
+
+export function buildDetectPrompt(prompts) {
+  const names = correctionTaxonomy().map((t) => t.signal).join(', ');
+  const system =
+    'You classify a user\'s messages to an AI assistant, looking for CORRECTIONS — moments where ' +
+    'the user pushes back on HOW the assistant responded (length, format, tone, depth, autonomy, ' +
+    'risk posture), not on facts. Signals: ' + names + '. ' +
+    'The names are literal: too_long = the reply was too long / wants it shorter; wants_confirmation = ' +
+    'asks the assistant to check before acting; and so on. Reply with STRICT JSON only:\n' +
+    '{"hits": [{"m": <message number>, "signal": "<signal name>"}]}\n' +
+    'At most ONE signal per message — the dominant correction. Messages with no correction are ' +
+    'simply omitted. When unsure, omit (precision over recall). Output ONLY the JSON object.';
+  const user = prompts.map((t, i) => `[${i + 1}] ${t}`).join('\n\n');
+  return { system, user };
+}
+
+// Parse + validate the model's reply. Returns { <1-based m>: signal } for valid,
+// in-range, first-per-message hits with known signal names; {} on any junk.
+export function parseDetectResponse(text, promptCount) {
+  let obj;
+  try {
+    const m = String(text).match(/\{[\s\S]*\}/);
+    if (!m) return {};
+    obj = JSON.parse(m[0]);
+  } catch { return {}; }
+  const valid = new Map(correctionTaxonomy().map((t) => [t.signal, t.layer]));
+  const out = {};
+  for (const hit of Array.isArray(obj?.hits) ? obj.hits : []) {
+    const m = hit && hit.m;
+    if (!Number.isInteger(m) || m < 1 || m > promptCount) continue;
+    if (out[m]) continue;                          // first hit per message wins (regex parity)
+    if (!valid.has(hit.signal)) continue;          // unknown name → dropped, never invented
+    out[m] = hit.signal;
+  }
+  return out;
+}
+
+// Fold validated model hits into a session-counts object (accumulateBatchCounts
+// shape). Pure — returns a new counts object; the input is not mutated. Only
+// behavioral_signals move: positives/mental-models stay regex-only for now.
+export function mergeModelCounts(counts, hits) {
+  const layerOf = new Map(correctionTaxonomy().map((t) => [t.signal, t.layer]));
+  const behavioral = {};
+  for (const [layer, sigs] of Object.entries((counts && counts.behavioral_signals) || {})) {
+    behavioral[layer] = { ...sigs };
+  }
+  let added = 0;
+  for (const signal of Object.values(hits || {})) {
+    const layer = layerOf.get(signal);
+    if (!layer) continue;
+    if (!behavioral[layer]) behavioral[layer] = {};
+    behavioral[layer][signal] = (behavioral[layer][signal] || 0) + 1;
+    added++;
+  }
+  return { counts: { ...counts, behavioral_signals: behavioral }, added };
+}
+
+// Opt-in config, mirroring consultOptsFromEnv's conventions. `model` unset →
+// the whole backend is off and the hook never touches the network for it.
+export function captureModelOptsFromEnv(env = process.env) {
+  return {
+    model: env.PHAEDO_CAPTURE_MODEL || null,
+    modelUrl: env.PHAEDO_CAPTURE_MODEL_URL || 'http://localhost:11434',
+    apiKey: env.PHAEDO_CAPTURE_API_KEY || null,
+    timeoutMs: Number(env.PHAEDO_CAPTURE_MODEL_TIMEOUT_MS) || 15000,
+  };
+}
+
+// The durable on-switch: <state dir>/capture-model.json, written by
+// `node install.mjs --capture-model <name>` (removed with `... off`). A shell
+// `export` only reaches TERMINAL-launched sessions — Claude Desktop / Cowork
+// launched from the Dock never read the shell profile, so their hooks would
+// silently stay regex-only. The config file lives beside capture-state.json,
+// which the hook reads anyway, so it reaches every launch path.
+// Shape: { "model": "llama3.1:8b", "url"?, "api_key"?, "timeout_ms"? }.
+export function captureModelConfigPath(env = process.env) {
+  const dir = env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+  return join(dir, 'capture-model.json');
+}
+
+// Resolved capture-model config: env vars win (per-session override, and the
+// original interface), else the config file, else off. A missing or malformed
+// file is simply "off" — the hook must never fail on config.
+export function captureModelOpts(env = process.env) {
+  const fromEnv = captureModelOptsFromEnv(env);
+  if (fromEnv.model) return fromEnv;
+  try {
+    const cfg = JSON.parse(readFileSync(captureModelConfigPath(env), 'utf8'));
+    if (cfg && typeof cfg.model === 'string' && cfg.model) {
+      return {
+        model: cfg.model,
+        modelUrl: (typeof cfg.url === 'string' && cfg.url) || fromEnv.modelUrl,
+        apiKey: (typeof cfg.api_key === 'string' && cfg.api_key) || null,
+        timeoutMs: Number(cfg.timeout_ms) || fromEnv.timeoutMs,
+      };
+    }
+  } catch { /* no/broken file → off */ }
+  return fromEnv;
+}
+
+// One chat call against an Ollama / OpenAI-compatible endpoint (the consult
+// modelJudge transport). Throws on any transport/HTTP failure; the caller
+// treats every throw as "no enrichment".
+export async function callChatModel(system, user, opts) {
+  const res = await fetch(`${String(opts.modelUrl).replace(/\/$/, '')}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}) },
+    body: JSON.stringify({
+      model: opts.model,
+      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+      temperature: 0,
+      stream: false,
+    }),
+    signal: AbortSignal.timeout(opts.timeoutMs || 15000),
+  });
+  if (!res.ok) throw new Error(`capture model endpoint ${res.status}`);
+  const data = await res.json();
+  return data?.choices?.[0]?.message?.content || '';
+}
+
+// The enrichment pass: classify the regex-miss messages and fold the hits into
+// the session counts. NEVER throws and never degrades the deterministic result —
+// any failure (endpoint down, timeout, junk output) returns the input counts.
+//   opts — captureModelOptsFromEnv shape; opts.call is injectable for tests.
+export async function enrichCountsWithModel(batch, counts, opts = {}) {
+  if (!opts.model) return { counts, added: 0 };
+  const prompts = regexMissPrompts(batch);
+  if (!prompts.length) return { counts, added: 0 };
+  try {
+    const { system, user } = buildDetectPrompt(prompts);
+    const call = opts.call || callChatModel;
+    const hits = parseDetectResponse(await call(system, user, opts), prompts.length);
+    return mergeModelCounts(counts, hits);
+  } catch {
+    return { counts, added: 0 };                   // enrichment only — regex counts always land
+  }
+}

package/vendor/capture/owner.js

@@ -0,0 +1,35 @@
+// Phaedo capture — the merge-owner precedence predicate.
+//
+// Resolves open question Q3 of docs/roadmap/desktop-capture-deposit.md. A capture
+// surface deposits a signal delta to the `capture_to_owner` mailbox lane; exactly ONE
+// device drains and reconciles it. Which device is the owner is a presence-based
+// precedence ROLE, not a hardwired device:
+//
+//   1. phone       — if a phone is paired (canonical vault owner; re-broadcasts §5)
+//   2. extension   — else, if the extension is present (today's browser-primary user)
+//   3. mcp-local   — else (phone-less + browser-less desktop/CLI — the Claude Code dev)
+//
+// Anti-deadlock (the Q3 concern — "confirm the claim rule can't have BOTH yield"):
+// the order is TOTAL and MONOTONIC in presence. The top tier (phone) never yields;
+// each lower tier yields only when a STRICTLY HIGHER tier is present. So there is
+// always exactly one owner and never zero — "both yield" is unreachable. A pairing
+// still verifying counts as NOT present (fail toward the lower, always-available
+// tier), so the extension keeps owning until the phone's pairing is verified, then
+// yields; the brief two-owner overlap during that handoff is harmless because the
+// reconcile is per-source idempotent (Q2 / §3).
+
+export const TIERS = ['phone', 'extension', 'mcp-local'];
+
+// presence — { phonePaired?: bool, extensionPresent?: bool }. Unknown/undefined
+// treated as absent (fail toward the always-available mcp-local tier).
+export function resolveMergeOwner(presence = {}) {
+  if (presence.phonePaired) return 'phone';
+  if (presence.extensionPresent) return 'extension';
+  return 'mcp-local';
+}
+
+// Does `tier` own the capture lane given this presence? Exactly one tier is true for
+// any presence, so a drainer calls isOwner(myTier, presence) to decide whether to drain.
+export function isOwner(tier, presence = {}) {
+  return resolveMergeOwner(presence) === tier;
+}

package/vendor/capture/package.json

@@ -0,0 +1,4 @@
+{
+  "//": "Declares capture/*.js as ES modules so Node (the Claude Code capture hook, tests) can import them directly. Surface-agnostic Track-A capture contract: transcript parsing, source-id derivation, merge-owner precedence. Node-only; nothing here ships in the browser extension.",
+  "type": "module"
+}

package/vendor/capture/source-id.js

@@ -0,0 +1,56 @@
+// Phaedo capture — stable per-surface, per-MACHINE source device id.
+//
+// Resolves open question Q2 of docs/roadmap/desktop-capture-deposit.md. Every capture
+// surface tags its deposits with a `source_device_id`; the merge owner's per-source
+// idempotent reconcile (replace-that-source's-snapshot, never sum) depends on this id
+// being (a) STABLE across process restarts AND pairing changes, and (b) UNIQUE per
+// (machine, surface).
+//
+// The id is derived from a persistent random MACHINE id — NOT the pairing — for two
+// reasons the review surfaced:
+//   1. Pairing-derived ids CHANGE when the user pairs/re-pairs (or fixes a
+//      pairing.capture.json), so everything captured before that transition would be
+//      stranded under an orphaned key (unpaired→paired stranding).
+//   2. Two machines that export the SAME extension pairing (desktop + laptop, per the
+//      runbook) would derive the IDENTICAL pairing-based id and clobber each other's
+//      cumulative snapshots on the owner (replace-per-source under-counts).
+// A per-machine uuid persisted once in the state dir is stable across both, and
+// distinct per machine — so each machine's snapshot accumulates as its own source.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+function defaultMachineIdPath(env = process.env) {
+  const dir = env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+  return join(dir, 'machine-id');
+}
+
+// Read (or first-time create) the persistent per-machine id. Best-effort: if the
+// state dir is unwritable we fall back to a process-stable in-memory id (capture still
+// works for the session; only cross-restart stability is lost on a read-only FS).
+let _memMachineId = null;
+export function machineId(env = process.env) {
+  const path = defaultMachineIdPath(env);
+  try {
+    return readFileSync(path, 'utf8').trim() || createAndStore(path);
+  } catch {
+    return createAndStore(path);
+  }
+}
+function createAndStore(path) {
+  const id = randomUUID();
+  try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, id + '\n', 'utf8'); }
+  catch { if (!_memMachineId) _memMachineId = randomUUID(); return _memMachineId; }
+  return id;
+}
+
+// surface — a stable string naming the capture surface, e.g. 'claude-code' or 'a11y-macos'.
+// The `pairing` param is kept for signature compatibility with callers but is NO LONGER
+// used to derive the id (see the header): the id is per-machine + per-surface.
+export function deriveSourceDeviceId(_pairing, surface, env = process.env) {
+  const tag = String(surface || 'unknown');
+  const digest = createHash('sha256').update(`${machineId(env)} ${tag}`).digest('base64url');
+  return `cap_${tag}_${digest.slice(0, 16)}`;
+}

package/vendor/capture/state.js

@@ -0,0 +1,148 @@
+// Phaedo capture — cumulative per-surface counter state.
+//
+// delta-lift's idempotency contract requires that a deposited signal's
+// observation_count be the surface's CUMULATIVE total (reconcile REPLACES a
+// source='delta' signal on key match rather than summing). A hook run is
+// per-session, so the hook needs durable local state that accumulates counts
+// across sessions — this module is that state.
+//
+// Resume-safety: Claude Code fires SessionEnd more than once for the same
+// session (clear / resume / logout), and each firing re-processes the FULL
+// transcript. Counts are therefore stored PER SESSION and REPLACED on
+// re-processing (never added), so a resumed session can only update its own
+// contribution — no double-count. The cumulative total = baseline + Σ sessions;
+// old sessions are evicted into the baseline beyond a cap so the file stays small.
+//
+// Contains COUNTS ONLY — signal names and integers, never conversation text
+// (the discard-raw contract). Plaintext JSON is acceptable at this sensitivity
+// (same class as the extension's phaedo_behavioral_signals counters); the state
+// file lives in the MCP state dir (default ~/.phaedo-mcp/, 0600-style dir the
+// server already uses for its key + cache).
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const VERSION = 1;
+const DEFAULT_MAX_SESSIONS = 200;
+
+export function defaultStatePath(env = process.env) {
+  const dir = env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+  return join(dir, 'capture-state.json');
+}
+
+export function emptyState() {
+  return { version: VERSION, surfaces: {} };
+}
+
+// ── pure helpers ─────────────────────────────────────────────────────────────
+
+function emptyCounts() {
+  return { behavioral_signals: {}, positive_count: 0, mental_models: {}, message_count: 0 };
+}
+
+// counts + counts → counts. Robust to a malformed source (null, wrong shape, string
+// counters): a hand-edited or partially-written state file must never throw here — the
+// throw happens AFTER saveState in the hook, so it would re-persist the bad entry and
+// silently kill capture forever. Non-object sources are skipped; counters are coerced
+// to finite numbers (a stray string '7' can't corrupt the sum into '07').
+const num = (v) => (Number.isFinite(v) ? v : (Number.isFinite(Number(v)) ? Number(v) : 0));
+export function mergeCounts(a, b) {
+  const out = emptyCounts();
+  for (const src of [a, b]) {
+    if (!src || typeof src !== 'object') continue;
+    for (const [layer, sigs] of Object.entries(src.behavioral_signals || {})) {
+      if (!sigs || typeof sigs !== 'object') continue;
+      if (!out.behavioral_signals[layer]) out.behavioral_signals[layer] = {};
+      for (const [sig, n] of Object.entries(sigs)) {
+        out.behavioral_signals[layer][sig] = (out.behavioral_signals[layer][sig] || 0) + num(n);
+      }
+    }
+    for (const [fw, n] of Object.entries(src.mental_models || {})) {
+      out.mental_models[fw] = (out.mental_models[fw] || 0) + num(n);
+    }
+    out.positive_count += num(src.positive_count);
+    out.message_count += num(src.message_count);
+  }
+  return out;
+}
+
+// Record a session's counts for a surface, REPLACING any prior contribution from
+// the same sessionId (resume-safe). Evicts oldest sessions into the baseline
+// beyond maxSessions. Pure — returns a new state.
+//
+// Once a session is evicted its counts are frozen into the opaque baseline sum, which
+// can't be decomposed — so if that SAME session re-fires (SessionEnd on clear/resume of
+// a long-lived session outliving 200 others), re-adding it would DOUBLE-count it
+// permanently. We track evicted ids and skip a re-fire of one: its counts stay as
+// frozen in baseline (bounded staleness) rather than doubling. The evicted-id list is
+// itself capped; an id that ages out of it is doubly-rare to re-fire.
+export function applySession(state, sourceId, sessionId, counts, { now, maxSessions = DEFAULT_MAX_SESSIONS } = {}) {
+  const stamp = now || new Date().toISOString();
+  const prev = (state && state.surfaces) || {};
+  const surface = prev[sourceId] || { baseline: emptyCounts(), sessions: {}, evicted: [] };
+  const sid = String(sessionId || 'unknown');
+  const evicted = Array.isArray(surface.evicted) ? surface.evicted.slice() : [];
+  // Drop any malformed (null / non-object) session entry from a hand-edited file so the
+  // eviction sort below (sessions[x].updated_at) can't throw.
+  const priorSessions = {};
+  for (const [k, v] of Object.entries(surface.sessions || {})) if (v && typeof v === 'object') priorSessions[k] = v;
+
+  // A re-fire of an already-evicted session: don't re-add (its counts are in baseline).
+  if (evicted.includes(sid) && !priorSessions[sid]) {
+    return { version: VERSION, surfaces: { ...prev, [sourceId]: { ...surface, sessions: priorSessions, evicted, updated_at: stamp } } };
+  }
+
+  const sessions = { ...priorSessions, [sid]: { counts, updated_at: stamp } };
+
+  // Evict oldest (by updated_at) into baseline beyond the cap.
+  let baseline = surface.baseline || emptyCounts();
+  const ids = Object.keys(sessions);
+  if (ids.length > maxSessions) {
+    ids.sort((x, y) => String(sessions[x].updated_at).localeCompare(String(sessions[y].updated_at)));
+    for (const id of ids.slice(0, ids.length - maxSessions)) {
+      baseline = mergeCounts(baseline, sessions[id].counts);
+      delete sessions[id];
+      if (!evicted.includes(id)) evicted.push(id);
+    }
+  }
+  while (evicted.length > maxSessions) evicted.shift();   // bound the evicted-id list
+
+  return {
+    version: VERSION,
+    surfaces: { ...prev, [sourceId]: { baseline, sessions, evicted, updated_at: stamp } },
+  };
+}
+
+// The cumulative counts for a surface: baseline + Σ sessions. This is what the
+// hook lifts (observation_count = cumulative total, per delta-lift's contract).
+export function cumulativeCounts(state, sourceId) {
+  const surface = state && state.surfaces && state.surfaces[sourceId];
+  if (!surface) return emptyCounts();
+  // Run the baseline through mergeCounts too, so a malformed/hand-edited baseline (null,
+  // string counters) is sanitized rather than returned raw. A null/malformed session
+  // entry is skipped (mergeCounts ignores a non-object src; guard the `.counts` access).
+  let out = mergeCounts(emptyCounts(), surface.baseline);
+  for (const s of Object.values(surface.sessions || {})) out = mergeCounts(out, s && s.counts);
+  return out;
+}
+
+// ── IO (sync — the hook is a short-lived script) ─────────────────────────────
+
+// Missing or corrupt file → empty state (a broken state file must never break a
+// session or a capture; it just restarts the counters).
+export function loadState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed && parsed.version === VERSION && parsed.surfaces) return parsed;
+  } catch { /* fall through */ }
+  return emptyState();
+}
+
+// Atomic: temp file + rename (same pattern as the receipts/auth stores).
+export function saveState(path, state) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state), 'utf8');
+  renameSync(tmp, path);
+}