@clear-capabilities/agentic-security-scanner 0.134.0 → 0.136.9

package/src/discovery/index.js

@@ -13,6 +13,7 @@ import { runHunter } from './hunter.js';
 import { confirmAll } from './confirm.js';
 import { disprovePanel } from './disprove.js';
 import { judgeCandidates } from './judge.js';
+import { loadMemory, saveMemory, rememberRun, previouslyRefuted, nextWavePlan } from './memory.js';
 
 // Bridge a candidate to the deterministic layer. A taint finding at or within
 // two lines of the candidate corroborates it; a modelled sink on the line
@@ -54,10 +55,91 @@ async function runDeepAnalysisSafe(perFileIR, callGraph) {
 // where { perFileIR, callGraph } come from buildProjectIR(fileContents),
 // which returns { perFile, callGraph } — callers must pass perFile as
 // perFileIR (see scanner/src/ir/index.js).
+/**
+ * PRD Phase 0 / C3 — the run budget.
+ *
+ * This pipeline is multiplicative and was, until now, unbounded. Eight focus
+ * areas × seven lenses is 56 hunter calls before a single candidate exists, and
+ * every surviving candidate then costs three more calls in the refutation
+ * panel. Nothing capped any of it, so the cost of a run was a function of how
+ * large the repository happened to be — which is not a property you want to
+ * discover from an invoice.
+ *
+ * ENFORCED AT THE ONE SEAM EVERY CALL PASSES THROUGH. Rather than thread checks
+ * through the hunter and the panel, the budget wraps `llmInvoke` itself. When
+ * it is spent the wrapper throws, and both callers already treat a throwing
+ * llmInvoke as ordinary degradation with a stated reason. So exhaustion arrives
+ * through the same path as a rate limit or a dead endpoint, and lands in
+ * `coverage.reasons` like any other coverage gap. No new failure mode.
+ *
+ * CALLS AND WALL CLOCK, NOT TOKENS. `llmInvoke` is an injected callback that
+ * returns a string; it carries no usage metadata, so counting tokens here would
+ * mean inventing a number. Calls are exactly countable and wall clock is
+ * exactly observable. A caller who knows their per-call cost can pass
+ * `costPerCallUsd` and get a `maxCostUsd` ceiling expressed in calls, which is
+ * honest about being an estimate derived from their figure rather than ours.
+ */
+// Internal, not exported: the dead-module guard treats an export with no
+// external call site as shipped dead code, and these are read only by
+// makeBudget below. A consumer sets a ceiling by passing opts, not by importing
+// a constant.
+const DEFAULT_MAX_LLM_CALLS = 200;
+const DEFAULT_MAX_WALL_MS = 15 * 60 * 1000;
+const DEFAULT_MAX_CANDIDATES = 50;
+
+export function makeBudget(opts = {}, now = Date.now) {
+  const startedAt = now();
+  let maxCalls = Number.isInteger(opts.maxLlmCalls) && opts.maxLlmCalls >= 0
+    ? opts.maxLlmCalls : DEFAULT_MAX_LLM_CALLS;
+  // A dollar ceiling is only meaningful with a caller-supplied per-call cost.
+  // Converting it to a call count keeps one enforcement mechanism rather than
+  // two that can disagree.
+  if (Number.isFinite(opts.maxCostUsd) && Number.isFinite(opts.costPerCallUsd) && opts.costPerCallUsd > 0) {
+    maxCalls = Math.min(maxCalls, Math.floor(opts.maxCostUsd / opts.costPerCallUsd));
+  }
+  const maxWallMs = Number.isInteger(opts.maxWallMs) && opts.maxWallMs > 0
+    ? opts.maxWallMs : DEFAULT_MAX_WALL_MS;
+
+  let calls = 0;
+  let exhaustedReason = null;
+
+  const check = () => {
+    if (exhaustedReason) return exhaustedReason;
+    if (calls >= maxCalls) return (exhaustedReason = `LLM call budget spent (${calls}/${maxCalls} calls)`);
+    if (now() - startedAt >= maxWallMs) {
+      return (exhaustedReason = `wall-clock budget spent (${Math.round(maxWallMs / 1000)}s)`);
+    }
+    return null;
+  };
+
+  return {
+    get calls() { return calls; },
+    get maxCalls() { return maxCalls; },
+    get exhaustedReason() { return exhaustedReason; },
+    spent: () => check() !== null,
+    /** Wrap an llmInvoke so every call is counted and the ceiling is enforced. */
+    wrap(llmInvoke) {
+      if (typeof llmInvoke !== 'function') return llmInvoke;
+      return async (prompt) => {
+        const stop = check();
+        if (stop) throw new Error(`discovery budget exhausted: ${stop}`);
+        calls += 1;
+        return llmInvoke(prompt);
+      };
+    },
+  };
+}
+
 export async function runDiscovery(ctx = {}, opts = {}) {
   const areas = partitionCallGraph(ctx.callGraph, { maxAreas: opts.maxAreas ?? 8 });
 
   const reasons = [];
+  const budget = makeBudget(opts);
+  // PRD C4 — what previous runs already judged. scanRoot absent => no memory,
+  // which is the correct default for a library call with nowhere to persist.
+  const memory = opts.scanRoot ? loadMemory(opts.scanRoot) : null;
+  // Every LLM call in this pipeline goes through this one wrapped callback.
+  const llmInvoke = budget.wrap(opts.llmInvoke);
 
   // An explicit array (including an empty one) is honoured exactly — a caller
   // narrowing a run to no lenses must get no lenses, not a silent fallback to
@@ -87,7 +169,7 @@ export async function runDiscovery(ctx = {}, opts = {}) {
   for (const area of areas) {
     let areaDegradedCount = 0;
     for (const lens of lenses) {
-      const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {} }, { llmInvoke: opts.llmInvoke });
+      const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {} }, { llmInvoke });
       runs.push({ focusAreaId: run.focusAreaId, lens: run.lens, degraded: run.degraded, reason: run.reason, candidateCount: run.candidates.length });
       if (run.degraded && run.reason) reasons.push(`${area.label} × ${lens.key}: ${run.reason}`);
       if (run.degraded) areaDegradedCount += 1;
@@ -97,11 +179,69 @@ export async function runDiscovery(ctx = {}, opts = {}) {
     if (lenses.length > 0 && areaDegradedCount === 0) fullyHunted.add(area.id);
   }
 
-  const taintProbe = makeTaintProbe(ctx.perFileIR, ctx.callGraph);
+  // PRD Phase 0 / C3.2 — the candidate cap.
+  //
+  // Every candidate that reaches the panel costs three more LLM calls, so an
+  // unusually productive hunt multiplies straight into spend. Cap it, and
+  // REPORT the cap rather than applying it silently: a run that quietly
+  // examined the first N candidates and said nothing would look identical to a
+  // run that found only N. Same precedent as prove-findings.js's `capped`.
+  // PRD C4 — drop what a previous run already refuted, BEFORE spending the
+  // panel's three calls per candidate on it again. Only refutals suppress: a
+  // candidate previously judged fresh is re-reported, because it was never
+  // fixed, which is the same asymmetry judge.js applies to tp/fp triage.
+  let rememberedRefutals = 0;
+  if (memory) {
+    const before = candidates.length;
+    candidates = candidates.filter(c => !previouslyRefuted(memory, c));
+    rememberedRefutals = before - candidates.length;
+    if (rememberedRefutals > 0) {
+      reasons.push(`${rememberedRefutals} candidate(s) were refuted by an earlier run and not re-examined ` +
+        '(clear with --forget-refuted if a model, ruleset or the code has changed since)');
+    }
+  }
+
+  const maxCandidates = Number.isInteger(opts.maxCandidates) && opts.maxCandidates >= 0
+    ? opts.maxCandidates : DEFAULT_MAX_CANDIDATES;
+  let candidatesCapped = 0;
+  if (candidates.length > maxCandidates) {
+    candidatesCapped = candidates.length - maxCandidates;
+    // Deterministic: candidates arrive in a stable (area, lens) order, so the
+    // cap keeps the same prefix on every run over the same inputs.
+    candidates = candidates.slice(0, maxCandidates);
+    reasons.push(`candidate cap: ${candidatesCapped} candidate(s) were NOT confirmed or refuted ` +
+      `(cap ${maxCandidates}); they are neither findings nor cleared — they were not examined`);
+  }
+
+  // PRD D3 — the hybrid-loop uplift measurement.
+  //
+  // `confirm: false` runs the pipeline with the deterministic gate switched OFF,
+  // so every candidate reaches the panel as `unconfirmed`. Running a population
+  // both ways and diffing the result isolates what the taint engine contributes
+  // on top of the model — a number no surveyed competitor can compute, because
+  // none of them has a deterministic layer to switch off.
+  //
+  // It exists ONLY to be measured against. It is not a performance switch, and
+  // a run with it disabled is strictly weaker: severity collapses to `low` for
+  // everything, since the confirmation tier is what sets it.
+  const confirmationEnabled = opts.confirm !== false;
+  const taintProbe = confirmationEnabled ? makeTaintProbe(ctx.perFileIR, ctx.callGraph) : null;
+  if (!confirmationEnabled) {
+    reasons.push('deterministic confirmation was DISABLED for this run (uplift measurement); ' +
+      'every candidate is reported unconfirmed and severity is not evidence-derived');
+  }
   const confirmed = await confirmAll(candidates, { taintProbe });
-  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke: opts.llmInvoke });
+  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke });
   const { fresh, duplicates, suppressed } = judgeCandidates(survivors, ctx.priorScan, ctx.triageFeedback);
 
+  // A spent budget is a coverage gap, stated once at the top level rather than
+  // left to be inferred from N identical per-run degradation reasons.
+  if (budget.exhaustedReason) {
+    reasons.push(`RUN INCOMPLETE — ${budget.exhaustedReason}. Work remained when the budget ran ` +
+      'out, so absence of a finding below is not evidence of absence. Raise maxLlmCalls / ' +
+      'maxWallMs, or narrow the scope with --root or --lens, and re-run.');
+  }
+
   // Coverage must not stop at the hunter stage. `confirm.js` correctly never
   // lowers a candidate below `unconfirmed`, and `disprove.js` correctly lets
   // a candidate survive when no voter votes — each rule is right on its own,
@@ -124,6 +264,16 @@ export async function runDiscovery(ctx = {}, opts = {}) {
     reasons.push(`refutation panel returned no votes for any of ${panelsRun} candidate(s) — every finding below survived unrefuted, not because it withstood scrutiny`);
   }
 
+  // PRD C4 — fold this run into the memory so the next one can be additive
+  // rather than a repeat. Persistence failure is non-fatal: the report is still
+  // valid, it just will not inform the next run.
+  if (memory && opts.scanRoot) {
+    saveMemory(opts.scanRoot, rememberRun(memory, {
+      fresh, refutedCandidates: refuted,
+      areas: areas.map(a => ({ id: a.id, label: a.label, files: a.files.length, hunted: hunted.has(a.id) })),
+    }));
+  }
+
   return {
     schema: 'agentic-security/discovery@1',
     focusAreas: areas.map(a => ({ id: a.id, label: a.label, files: a.files.length, size: a.size })),
@@ -153,6 +303,28 @@ export async function runDiscovery(ctx = {}, opts = {}) {
       // of those came back with no votes at all (undecided, not refuted).
       panelsRun,
       undecidedPanels,
+      // PRD Phase 0 / C3 — what the run cost and whether the budget stopped it.
+      // `budgetExhausted` true means the report is INCOMPLETE by construction:
+      // work remained and was not done. Reading it as a clean result is the
+      // exact misreading the coverage block exists to prevent.
+      // PRD C4 — what history contributed, and what to hunt next. A coverage
+      // report says what happened; `nextWave` says what to do about it.
+      rememberedRefutals,
+      priorRuns: memory ? memory.runs : null,
+      nextWave: memory ? nextWavePlan(memory, areas.map(a => ({ id: a.id, label: a.label }))) : null,
+      llmCalls: budget.calls,
+      maxLlmCalls: budget.maxCalls,
+      // PRD N4 — the standing cost metric. C3 bounded the worst case and C4
+      // moved the typical case by 4x, so cost is a property that drifts across
+      // several workstreams rather than one that a phase finishes. A number
+      // that only appears when somebody goes looking regresses silently, so it
+      // is reported every run and carries its denominator like every other rate
+      // in this engine. `null` when nothing was found — dividing by zero
+      // findings would print Infinity and read as a catastrophe rather than as
+      // "there is nothing to divide".
+      callsPerFinding: fresh.length > 0 ? Number((budget.calls / fresh.length).toFixed(1)) : null,
+      budgetExhausted: Boolean(budget.exhaustedReason),
+      candidatesCapped,
       reasons,
     },
   };

package/src/discovery/llm-invoke.js

@@ -13,7 +13,11 @@ export async function defaultLlmInvoke(prompt, opts = {}) {
   // variable they set. Reaching it is this module's entire purpose; no
   // request-controlled input exists anywhere on this path, and an operator who
   // can set this variable can already run code.
-  const res = await fetch(process.env.AGENTIC_SECURITY_LLM_ENDPOINT, { // agentic-security-ignore: CWE-918
+  // `opts.endpoint` lets the consensus caller target one specific provider.
+  // Absent, it falls back to the single configured endpoint — so the ordinary
+  // single-model path is byte-identical to what it was before consensus existed.
+  const endpoint = opts.endpoint || process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
+  const res = await fetch(endpoint, { // agentic-security-ignore: CWE-918
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ prompt }),
@@ -24,8 +28,93 @@ export async function defaultLlmInvoke(prompt, opts = {}) {
   return typeof body === 'string' ? body : (body?.text ?? JSON.stringify(body));
 }
 
+// --- PRD Phase 3 / C2: multi-model consensus --------------------------------
+//
+// One model's opinion is one model's opinion. Asking several INDEPENDENT
+// endpoints the same question and keeping only what a majority agree on
+// collapses the idiosyncratic failures of any single one — a model that
+// hallucinates a sink, or that is simply having a bad day on a prompt shape.
+//
+// WHY IT LIVES HERE AND NOWHERE ELSE. Every LLM call in the discovery layer
+// already funnels through `resolveLlmInvoke`. Consensus is therefore a property
+// of the seam, not of the hunter or the panel, and adding a provider cannot
+// require touching either.
+//
+// WHAT CONSENSUS DOES AND DOES NOT MEAN. It reduces variance. It does NOT make
+// the answer true — three models can agree and all be wrong, which is precisely
+// why the deterministic confirmation gate still runs afterwards and still sets
+// severity. Consensus is a noise filter in front of the real check, never a
+// replacement for it.
+//
+// A provider that errors is EXCLUDED from the vote, not counted as dissent —
+// the same rule `disprove.js` applies to its voters, for the same reason: an
+// outage must never look like disagreement.
+// Internal: read by resolveLlmInvoke below. Exporting it with no external
+// caller is shipped dead code by the dead-module guard's definition.
+const DEFAULT_CONSENSUS_ENV = 'AGENTIC_SECURITY_LLM_ENDPOINTS';
+
+/** Split a comma-separated endpoint list into distinct URLs. */
+export function parseEndpoints(raw) {
+  return String(raw || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+    .filter((v, i, a) => a.indexOf(v) === i); // duplicates would fake agreement
+}
+
+/**
+ * Combine N responses into one, keeping the most common answer.
+ *
+ * Ties are resolved towards the FIRST endpoint listed, deterministically, rather
+ * than arbitrarily — a caller ordering their endpoints by trust should get the
+ * behaviour that ordering implies, and a random tie-break would make the whole
+ * pipeline non-reproducible.
+ */
+export function consensusOf(responses) {
+  const usable = (responses || []).filter(r => typeof r === 'string' && r.trim());
+  if (usable.length === 0) return { value: null, agreement: 0, voters: 0 };
+  const counts = new Map();
+  for (const r of usable) counts.set(r, (counts.get(r) || 0) + 1);
+  let best = usable[0];
+  let bestCount = counts.get(best);
+  for (const r of usable) {
+    const c = counts.get(r);
+    if (c > bestCount) { best = r; bestCount = c; }
+  }
+  return { value: best, agreement: bestCount / usable.length, voters: usable.length };
+}
+
+/**
+ * An llmInvoke that queries several endpoints and returns the consensus answer.
+ * Returns null when no endpoint answered — the callers already treat a null or
+ * a throw as degradation, so an all-providers-down run degrades honestly.
+ */
+function makeConsensusInvoke(endpoints, { timeoutMs } = {}) {
+  const list = parseEndpoints(endpoints);
+  if (list.length === 0) return null;
+  return async (prompt) => {
+    const answers = await Promise.all(list.map(async (url) => {
+      try { return await defaultLlmInvoke(prompt, { timeoutMs, endpoint: url }); }
+      catch { return null; } // excluded from the vote, never counted as dissent
+    }));
+    const { value } = consensusOf(answers);
+    if (value === null) throw new Error('no LLM endpoint answered');
+    return value;
+  };
+}
+
 export function resolveLlmInvoke(opts = {}) {
+  // Precedence, most explicit first: an injected callback beats configuration,
+  // and a multi-endpoint list beats a single endpoint. A caller who supplied
+  // their own function must always get exactly that function.
   if (opts.llmInvoke) return opts.llmInvoke;
+
+  const multi = opts.endpoints || process.env[DEFAULT_CONSENSUS_ENV];
+  if (multi) {
+    const consensus = makeConsensusInvoke(multi, { timeoutMs: opts.timeoutMs });
+    if (consensus) return consensus;
+  }
+
   if (!process.env.AGENTIC_SECURITY_LLM_ENDPOINT) return null;
   return (prompt) => defaultLlmInvoke(prompt, { timeoutMs: opts.timeoutMs });
 }

package/src/discovery/memory.js

@@ -0,0 +1,163 @@
+// Cross-run discovery memory — PRD Phase 3 / C4.
+//
+// WHAT WAS MISSING
+// ----------------
+// `judge.js` dedupes a hunt against `last-scan.json` and the triage ledger, so
+// it knows what the RULE ENGINE found and what a human dismissed. It has never
+// known what a PREVIOUS HUNT found. Two consequences, both bad:
+//
+//   1. Every run re-proposes, re-confirms and re-refutes the same candidates.
+//      That is three LLM calls per candidate per run, spent to rediscover
+//      something already judged — the exact waste the Phase 0 budget exists to
+//      bound, being incurred deliberately.
+//   2. A second run cannot be *additive*. Without a record of what was already
+//      examined, "hunt again" means "hunt the same thing again" rather than
+//      "hunt what we missed".
+//
+// This is that record. It turns a sequence of independent runs into a campaign.
+//
+// WHAT IS AND IS NOT REMEMBERED
+// -----------------------------
+// Remembered: every candidate ever JUDGED, with the verdict and the run that
+// produced it. Also every focus area ever hunted, so coverage can become a plan
+// instead of a report.
+//
+// NOT remembered: refuted candidates as if they were settled forever. A
+// refutation is a majority opinion from three prompts on one day, not a proof.
+// It suppresses re-reporting, and `--forget-refuted` exists precisely because a
+// verdict made by a weaker model, or before a sanitiser was removed, must be
+// re-openable. A memory you cannot clear is a memory that eventually lies.
+//
+// THE PRECEDENT THIS FOLLOWS
+// --------------------------
+// `judge.js` deliberately suppresses only `fp` triage verdicts and re-reports
+// `tp` ones, because a prior true positive that is still in the code is still a
+// bug. The same asymmetry holds here: a candidate previously judged FRESH is
+// re-reported (it was never fixed), while one previously REFUTED is held back
+// until something changes.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { stateWritesEnabled } from '../posture/state-dir.js';
+const MEMORY_SCHEMA = 'agentic-security/discovery-memory@1';
+export const MEMORY_FILE = path.join('.agentic-security', 'discovery-memory.json');
+
+function emptyMemory() {
+  return { schema: MEMORY_SCHEMA, runs: 0, candidates: {}, areas: {} };
+}
+
+/** A stable identity for a candidate across runs. */
+export function memoryKey(candidate) {
+  // Location + family, matching judge.js's PRIMARY duplicate key. Deliberately
+  // NOT stableId: that is location-fuzzy by design and collides across distinct
+  // findings in one file, which is tolerable for a single scan's dedupe and
+  // corrosive when it accumulates across every run ever made.
+  const file = candidate?.file ?? '?';
+  const line = candidate?.line ?? '?';
+  const family = candidate?.family ?? candidate?.lens ?? '?';
+  return `${file}:${line}:${family}`;
+}
+
+/** Read the memory. Anything unreadable or unrecognised yields an empty one. */
+export function loadMemory(scanRoot) {
+  try {
+    const doc = JSON.parse(fs.readFileSync(path.join(scanRoot, MEMORY_FILE), 'utf8'));
+    if (doc?.schema !== MEMORY_SCHEMA) return emptyMemory();
+    return { ...emptyMemory(), ...doc };
+  } catch {
+    // A corrupt memory must degrade to "remember nothing", never to a crash and
+    // never to a partially-trusted record. Re-hunting is cheap next to acting on
+    // a half-read ledger.
+    return emptyMemory();
+  }
+}
+
+/** Persist. Failure is non-fatal — the run still produced its report. */
+export function saveMemory(scanRoot, memory) {
+  try {
+    const p = path.join(scanRoot, MEMORY_FILE);
+    if (!stateWritesEnabled()) return;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(memory, null, 2) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Should this candidate be held back because a previous run already judged it?
+ *
+ * Only a REFUTED verdict suppresses. Everything else — fresh, duplicate,
+ * suppressed-by-triage — is re-evaluated, because those states are about the
+ * code and the code may have changed.
+ */
+export function previouslyRefuted(memory, candidate) {
+  const rec = memory?.candidates?.[memoryKey(candidate)];
+  return Boolean(rec && rec.verdict === 'refuted');
+}
+
+/** Fold this run's outcome into the memory. Returns a NEW memory object. */
+export function rememberRun(memory, { fresh = [], refutedCandidates = [], areas = [], at }) {
+  const next = {
+    ...emptyMemory(),
+    ...memory,
+    candidates: { ...(memory?.candidates || {}) },
+    areas: { ...(memory?.areas || {}) },
+  };
+  next.runs = (memory?.runs || 0) + 1;
+  const stamp = at || new Date().toISOString();
+
+  for (const f of fresh) {
+    next.candidates[memoryKey(f)] = { verdict: 'fresh', run: next.runs, at: stamp };
+  }
+  for (const c of refutedCandidates) {
+    next.candidates[memoryKey(c)] = { verdict: 'refuted', run: next.runs, at: stamp };
+  }
+  for (const a of areas) {
+    const prev = next.areas[a.id] || { hunts: 0 };
+    next.areas[a.id] = {
+      label: a.label,
+      hunts: prev.hunts + (a.hunted ? 1 : 0),
+      lastRun: a.hunted ? next.runs : (prev.lastRun ?? null),
+      files: a.files ?? prev.files ?? null,
+    };
+  }
+  return next;
+}
+
+/**
+ * Turn the memory into a PLAN: which areas have never been successfully hunted.
+ *
+ * This is the half that makes a second run additive rather than repetitive. A
+ * coverage report says what happened; this says what to do next.
+ */
+export function nextWavePlan(memory, areas) {
+  const unhunted = [];
+  const stale = [];
+  for (const a of areas || []) {
+    const rec = memory?.areas?.[a.id];
+    if (!rec || rec.hunts === 0) unhunted.push(a.label || a.id);
+    else if (rec.lastRun !== memory.runs) stale.push(a.label || a.id);
+  }
+  return {
+    unhunted,
+    stale,
+    // Stated as a sentence because this lands in a report a human reads, and
+    // "3 areas" without saying which ones is not actionable.
+    summary: unhunted.length
+      ? `${unhunted.length} focus area(s) have NEVER been successfully hunted: ${unhunted.slice(0, 5).join(', ')}` +
+        (unhunted.length > 5 ? `, +${unhunted.length - 5} more` : '')
+      : 'every focus area has been hunted at least once',
+  };
+}
+
+/** Drop refuted verdicts so they can be re-examined. */
+export function forgetRefuted(memory) {
+  const candidates = {};
+  for (const [k, v] of Object.entries(memory?.candidates || {})) {
+    if (v?.verdict !== 'refuted') candidates[k] = v;
+  }
+  return { ...emptyMemory(), ...memory, candidates };
+}