iterate-plugin 3.5.7 → 3.6.0

package/src/config-write.ts

@@ -14,30 +14,69 @@ import { copyFileSync, existsSync, readFileSync, readdirSync, rmSync } from 'nod
 import { basename, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
 import { writeTextAtomic } from './atomic-fs.ts'
+import {
+  MAX_ATOMIC_MAX_LINES,
+  MAX_MAX_ADJACENT_METHODS,
+  MAX_MAX_ROUNDS,
+  MAX_SCOPE_CHUNK_SIZE,
+  SUPPORTED_CONFIG_KEYS,
+} from './config-loader.ts'
+
+export {
+  MAX_ATOMIC_MAX_LINES,
+  MAX_MAX_ADJACENT_METHODS,
+  MAX_MAX_ROUNDS,
+  MAX_SCOPE_CHUNK_SIZE,
+}
 
 /** Config file name (must match config-loader). */
 export const CONFIG_FILE = 'iterate.config.yaml'
 
-/** Backup suffix helper (filesystem-safe timestamp). */
+/**
+ * Monotonic collision guard for {@link configBackupSuffix}: two writes in the
+ * SAME millisecond used to build the identical `config.bak-<iso>` path, so the
+ * second backup overwrote the first and one snapshot was silently lost.
+ * Only ever moves forward (a clock stepping backwards also counts as a
+ * collision), so every suffix issued by this process is unique.
+ */
+let lastSuffixMs = -1
+let suffixSequence = 0
+
+/**
+ * Backup suffix helper (filesystem-safe timestamp + monotonic disambiguator).
+ * The ISO timestamp is kept verbatim when the millisecond is fresh (existing
+ * `config.bak-…` names sort chronologically); repeats within the same
+ * millisecond get `-1`, `-2`, … appended so the backup path never collides.
+ */
 export function configBackupSuffix(now = new Date()): string {
-  return now.toISOString().replace(/[:.]/g, '-')
+  const ms = now.getTime()
+  if (ms > lastSuffixMs) {
+    lastSuffixMs = ms
+    suffixSequence = 0
+  } else {
+    suffixSequence += 1
+  }
+  const base = now.toISOString().replace(/[:.]/g, '-')
+  return suffixSequence === 0 ? base : `${base}-${suffixSequence}`
 }
 
-/** Upper bound on configurable iteration rounds (config bomb guard). */
-export const MAX_MAX_ROUNDS = 100
-
-/** Upper bound on `atomic.max_lines` (a single fix never needs more). */
-export const MAX_ATOMIC_MAX_LINES = 10_000
-
-/** Upper bound on `atomic.max_adjacent_methods`. */
-export const MAX_MAX_ADJACENT_METHODS = 200
-
-/** Upper bound on `reviewer.scope_chunk_size` (files per reviewer task batch). */
-export const MAX_SCOPE_CHUNK_SIZE = 1000
-
 /** Keep at most this many timestamped config backups (older ones are removed). */
 export const MAX_CONFIG_BACKUPS = 5
 
+/**
+ * Top-level keys `iterate_config` accepts in `updates`.
+ *
+ * The write path MERGES updates into the file, so an unrecognized key used to
+ * be persisted verbatim: a typo (`maxRounds`) or a hallucinated field
+ * (`task_modes`) silently became part of the project's config, survived every
+ * later read, and was never consumed by anything. Rejecting unknown keys turns
+ * that silent no-op into a structured error the model can correct.
+ *
+ * Defined once in config-loader (shared with `validateConfig`) and re-exported
+ * here under its write-path name.
+ */
+export const SUPPORTED_UPDATE_KEYS = SUPPORTED_CONFIG_KEYS
+
 /**
  * Bound the timestamped config backups: after a fresh one is written, delete
  * every older `config.bak-*` file beyond the newest `keep`. Best-effort — a
@@ -76,6 +115,16 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
     return ['updates must be a JSON object']
   }
 
+  // Unknown top-level keys are refused rather than merged into the file
+  // (see SUPPORTED_UPDATE_KEYS for why a typo used to persist forever).
+  for (const key of Object.keys(updates)) {
+    if (!(SUPPORTED_UPDATE_KEYS as readonly string[]).includes(key)) {
+      errors.push(
+        `updates.${key} is not a supported config key (supported: ${SUPPORTED_UPDATE_KEYS.join(', ')})`,
+      )
+    }
+  }
+
   if ('goal' in updates && typeof updates.goal !== 'string') {
     errors.push('updates.goal must be a string')
   }
@@ -83,8 +132,14 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
     errors.push('updates.language must be "zh" or "en"')
   }
   if ('dimensions' in updates) {
-    if (!Array.isArray(updates.dimensions) || updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)) {
-      errors.push('updates.dimensions must be an array of non-empty strings')
+    // `.some` on an EMPTY array is false, so `dimensions: []` used to validate
+    // clean and then replace the whole dimension list with "review nothing".
+    if (
+      !Array.isArray(updates.dimensions) ||
+      updates.dimensions.length === 0 ||
+      updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)
+    ) {
+      errors.push('updates.dimensions must be a non-empty array of non-empty strings')
     }
   }
   if ('max_rounds' in updates) {
@@ -107,7 +162,7 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
   }
   if ('reviewer' in updates) {
     const rv = updates.reviewer as Record<string, unknown> | undefined
-    if (!rv || typeof rv !== 'object') {
+    if (!rv || typeof rv !== 'object' || Array.isArray(rv)) {
       errors.push('updates.reviewer must be an object')
     } else {
       for (const boolKey of ['output_schema_validation', 'evidence_validation', 'coverage_validation'] as const) {
@@ -126,7 +181,7 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
   }
   if ('review' in updates) {
     const r = updates.review as Record<string, unknown> | undefined
-    if (!r || typeof r !== 'object') {
+    if (!r || typeof r !== 'object' || Array.isArray(r)) {
       errors.push('updates.review must be an object')
     } else if (r.scope !== undefined && r.scope !== 'full' && r.scope !== 'changed-only') {
       errors.push('updates.review.scope must be "full" or "changed-only"')
@@ -134,7 +189,7 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
   }
   if ('atomic' in updates) {
     const a = updates.atomic as Record<string, unknown> | undefined
-    if (!a || typeof a !== 'object') {
+    if (!a || typeof a !== 'object' || Array.isArray(a)) {
       errors.push('updates.atomic must be an object')
     } else {
       if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1 || a.max_lines > MAX_ATOMIC_MAX_LINES)) {
@@ -147,7 +202,7 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
   }
   if ('git' in updates) {
     const g = updates.git as Record<string, unknown> | undefined
-    if (!g || typeof g !== 'object') {
+    if (!g || typeof g !== 'object' || Array.isArray(g)) {
       errors.push('updates.git must be an object')
     } else {
       if (g.target_branch !== undefined && typeof g.target_branch !== 'string') {
@@ -162,15 +217,36 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
   }
   if ('validation' in updates) {
     const v = updates.validation as Record<string, unknown> | undefined
-    if (!v || typeof v !== 'object') {
+    if (!v || typeof v !== 'object' || Array.isArray(v)) {
       errors.push('updates.validation must be an object')
-    } else if ('commands' in v && v.commands !== undefined && typeof v.commands !== 'object') {
-      errors.push('updates.validation.commands must be an object of command arrays')
+    } else {
+      if ('command_whitelist' in v && v.command_whitelist !== undefined) {
+        if (!Array.isArray(v.command_whitelist) || !v.command_whitelist.every((x) => typeof x === 'string')) {
+          errors.push('updates.validation.command_whitelist must be an array of strings')
+        }
+      }
+      // `typeof [] === 'object'` let `commands: ["npm t"]` validate clean, and
+      // `flattenCommands` drops every non-object entry — the allow-list would
+      // read as configured while matching NOTHING. Require the real shape:
+      // a mapping of module → string[] (string keys, string-array values).
+      if ('commands' in v && v.commands !== undefined) {
+        const c = v.commands
+        const shapeOk =
+          typeof c === 'object' &&
+          c !== null &&
+          !Array.isArray(c) &&
+          Object.entries(c as Record<string, unknown>).every(
+            ([, value]) => Array.isArray(value) && value.every((x) => typeof x === 'string'),
+          )
+        if (!shapeOk) {
+          errors.push('updates.validation.commands must be a mapping of module → string[] (not an array)')
+        }
+      }
     }
   }
   if ('observatory' in updates) {
     const o = updates.observatory as Record<string, unknown> | undefined
-    if (!o || typeof o !== 'object') {
+    if (!o || typeof o !== 'object' || Array.isArray(o)) {
       errors.push('updates.observatory must be an object')
     } else {
       if (o.capture !== undefined && typeof o.capture !== 'boolean') {
@@ -190,10 +266,16 @@ export function validateConfigUpdates(updates: Record<string, unknown>): string[
       }
     }
   }
-  if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
+  if (
+    'personalization' in updates &&
+    (!updates.personalization || typeof updates.personalization !== 'object' || Array.isArray(updates.personalization))
+  ) {
     errors.push('updates.personalization must be an object')
   }
-  if ('onboarding' in updates && (!updates.onboarding || typeof updates.onboarding !== 'object')) {
+  if (
+    'onboarding' in updates &&
+    (!updates.onboarding || typeof updates.onboarding !== 'object' || Array.isArray(updates.onboarding))
+  ) {
     errors.push('updates.onboarding must be an object')
   }
   return errors

package/src/evidence.ts

@@ -8,8 +8,15 @@
  *
  * - a finding's `file` must resolve to an existing file under the project root
  *   (traversal-safe), otherwise evidence is poisoned (`file_not_found`);
- * - a finding with an explicit line must reference a line that actually exists
- *   in that file (`line_out_of_range`);
+ * - a finding with an explicit line must reference an INTEGER line that
+ *   actually exists in that file (`line_out_of_range`); a fractional line
+ *   (e.g. 42.5) can never anchor to real code and fails the gate, and so
+ *   does a PRESENT-but-non-numeric line (`"42"`, `true`) — only an absent or
+ *   null line keeps the whole-file semantics;
+ * - files that exist but cannot be line-addressed report a DISTINCT error:
+ *   `file_too_large` (over MAX_EVIDENCE_BYTES) or `binary_file` (NUL bytes),
+ *   so the meta-review can describe the actual reason instead of lumping
+ *   every non-addressable file into `line_out_of_range`;
  * - a whole-file finding (line 0 / undefined) must still reference an existing
  *   file, so even structural findings cannot point at nothing;
  * - `readVerified` is a best-effort, NON-gating hint: the plugin's reviewers are
@@ -38,7 +45,20 @@ export const WHOLE_FILE_LINE = 0
  */
 const MAX_EVIDENCE_BYTES = 10 * 1024 * 1024
 
-export type EvidenceError = 'file_not_found' | 'line_out_of_range'
+/**
+ * Why a finding's location could not be verified.
+ *
+ * `file_too_large` / `binary_file` are intentionally distinct from
+ * `line_out_of_range`: the finding still fails the evidence gate (any error
+ * does), but consumers (meta-review detail text, tool payloads) can describe
+ * the real reason. `line_out_of_range` keeps covering "line anchor does not
+ * exist in this file" and "target is not a regular file (dir/device)".
+ */
+export type EvidenceError =
+  | 'file_not_found'
+  | 'line_out_of_range'
+  | 'file_too_large'
+  | 'binary_file'
 
 /** Per-finding attestation result. */
 export interface FindingEvidence {
@@ -58,6 +78,36 @@ export interface EvidenceAudit {
   results: FindingEvidence[]
 }
 
+/**
+ * Cached outcome of the per-file filesystem probe (containment + stat + size
+ * cap + full read + NUL check + line count). Computed once per resolved path
+ * per audit and reused for every finding anchored to that file; the
+ * per-finding line-bounds check still runs against each finding's own `line`.
+ */
+export interface FileProbe {
+  /** Lexical resolved path (null only when the path escapes the root). */
+  resolvedPath: string | null
+  /** `'text'` = line-addressable; anything else is the EvidenceError to report. */
+  outcome: 'text' | EvidenceError
+  /** Physical line count when `outcome === 'text'`; null otherwise. */
+  lineTotal: number | null
+}
+
+/**
+ * Point-in-time per-file probe cache keyed by resolved (lexical) path.
+ *
+ * `verifyFindings` creates one per call by default, so results always reflect
+ * the filesystem at audit time. Supplying your own via `opts.cache` shares it
+ * across calls — later calls then answer from the FIRST probe (a deliberate
+ * snapshot; they do not re-stat/re-read).
+ */
+export type EvidenceFileCache = Map<string, FileProbe>
+
+/** Create an empty probe cache for `opts.cache`. */
+export function createEvidenceCache(): EvidenceFileCache {
+  return new Map()
+}
+
 /** A single finding object that exposes `file` / `line` (for verification). */
 interface Locatable {
   file?: string
@@ -103,31 +153,107 @@ function safeRealpath(p: string): string {
   }
 }
 
+/**
+ * Pure decision: does `line` anchor to an existing line in a file with
+ * `lineTotal` lines? Shared by `verifyLineBounds` and the cached probe path
+ * (which has the line count but not the text).
+ */
+function lineInBounds(line: number | null | undefined, lineTotal: number): boolean {
+  // Whole-file findings (undefined/null/0 = WHOLE_FILE_LINE) are always
+  // bounds-valid — semantics preserved from the original gate.
+  if (line === undefined || line === null || line === WHOLE_FILE_LINE) return true
+  // Only a positive INTEGER is a valid line anchor. A fractional line (e.g.
+  // 42.5 from a bypassed schema), NaN, ±Infinity or a negative value is out of
+  // bounds — a fractional line "within" the file would otherwise be accepted
+  // and poison the evidence trail with a location nothing can jump to.
+  if (line < 1 || !Number.isInteger(line)) return false
+  return line <= lineTotal
+}
+
 /**
  * Pure check that `line` (if anchored) exists in `text`.
  * Whole-file findings (undefined/0) are always bounds-valid.
+ *
+ * Exported PUBLIC API: the production gate routes through the cached probe
+ * path (`lineInBounds` + the per-file line count), while tests and external
+ * consumers use this text-based form. Kept — not deleted — for that reason.
  */
 export function verifyLineBounds(
   line: number | null | undefined,
   text: string,
 ): { inBounds: boolean; lineTotal: number } {
   const lineTotal = countLines(text)
-  if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
-    return { inBounds: true, lineTotal }
+  return { inBounds: lineInBounds(line, lineTotal), lineTotal }
+}
+
+/**
+ * One filesystem probe for `root`/`resolved`: symlink containment, stat,
+ * regular-file + size cap, full read, NUL check, line count. Everything a
+ * finding needs beyond its own per-line check is captured in the result so
+ * repeated findings on the same file never re-stat or re-read it.
+ */
+function probeEvidenceFile(root: string, resolved: string): FileProbe {
+  // Symlink containment: resolveWithin is lexical only, but existsSync /
+  // readFileSync follow symlinks. Verify the REAL path stays inside the REAL
+  // project root so a finding path can never read (or line-count) a file
+  // outside the project via a symlinked directory or file.
+  const rootReal = safeRealpath(root)
+  const real = safeRealpath(resolved)
+  if (!isWithin(rootReal, real)) {
+    return { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null }
   }
-  // Only a positive INTEGER is a valid line anchor. A fractional line (e.g.
-  // 3.7 from a bypassed schema) or a negative value is out of bounds — a
-  // fractional line "within" the file would otherwise be accepted and poison
-  // the evidence trail with a location nothing can jump to.
-  if (line < 1 || !Number.isInteger(line)) return { inBounds: false, lineTotal }
-  return { inBounds: line <= lineTotal, lineTotal }
+
+  // Regular-file + size guard: a directory, device file (/dev/zero), FIFO or
+  // multi-GB file is not a line-addressable text target. statSync follows
+  // symlinks, so a link to a device still lands here and is rejected.
+  let st
+  try {
+    st = statSync(resolved)
+  } catch {
+    return { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null }
+  }
+  if (!st.isFile()) {
+    // Directory / device / FIFO: exists but is not line-addressable at all.
+    return { resolvedPath: resolved, outcome: 'line_out_of_range', lineTotal: null }
+  }
+  if (st.size > MAX_EVIDENCE_BYTES) {
+    return { resolvedPath: resolved, outcome: 'file_too_large', lineTotal: null }
+  }
+
+  let raw: Buffer
+  try {
+    raw = readFileSync(resolved)
+  } catch {
+    return { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null }
+  }
+
+  // A file containing a NUL byte is a binary payload: anchored line numbers
+  // on it cannot be trusted (mirrors the harness `evidence.py` NUL check).
+  // Reported as `binary_file` so it is distinguishable from a plain
+  // out-of-range line anchor.
+  if (raw.includes(0)) {
+    return { resolvedPath: resolved, outcome: 'binary_file', lineTotal: null }
+  }
+  return { resolvedPath: resolved, outcome: 'text', lineTotal: countLines(raw.toString('utf-8')) }
+}
+
+/** Shared options for `verifyFinding` / `verifyFindings`. */
+export interface EvidenceVerifyOptions {
+  /** Read set backing the non-gating `readVerified` hint. */
+  readSet?: Set<string>
+  /**
+   * Optional shared probe cache. `verifyFindings` allocates one per call when
+   * omitted; pass your own to reuse a prior snapshot across calls (see
+   * `EvidenceFileCache`).
+   */
+  cache?: EvidenceFileCache
 }
 
 /** Verify a single finding's location against the real filesystem. */
 export function verifyFinding(
   root: string,
   input: Locatable,
-  opts: { readSet?: Set<string> } = {},
+  opts: EvidenceVerifyOptions = {},
 ): FindingEvidence {
   // A null element / non-object finding (hostile or model-authored JSON) must
   // be reported as poisoned evidence, never crash `path.resolve` downstream.
@@ -144,11 +270,17 @@ export function verifyFinding(
   // A non-string `file` (number, object, …) would make `resolve` throw
   // ERR_INVALID_ARG_TYPE — coerce to "" so it fails closed as not-found.
   const relFile = typeof input.file === 'string' ? input.file : ''
-  const line = typeof input.line === 'number' ? input.line : null
+  const rawLine: unknown = (input as { line?: unknown }).line
+  const line = typeof rawLine === 'number' ? rawLine : null
+  // A PRESENT `line` must be a number. `line: "42"` / `line: true` (schema-
+  // bypassing JSON) is a claimed anchor we cannot resolve — fail closed as
+  // poisoned evidence instead of silently degrading it to a whole-file
+  // finding. Only an absent / null line keeps the WHOLE_FILE_LINE semantics.
+  const badLineType = rawLine !== undefined && rawLine !== null && typeof rawLine !== 'number'
 
   // "" resolves to the project ROOT (resolve(root, '') === root), which then
-  // trips the not-a-regular-file branch as `line_out_of_range` — but there is
-  // no file reference at all. Report it as `file_not_found` upfront.
+  // trips the not-a-regular-file branch — but there is no file reference at
+  // all. Report it as `file_not_found` upfront.
   if (relFile === '') {
     return {
       file: '',
@@ -159,100 +291,59 @@ export function verifyFinding(
       error: 'file_not_found',
     }
   }
-  const resolved = resolveWithin(root, relFile)
 
-  if (resolved === null || !existsSync(resolved)) {
-    return {
-      file: relFile,
-      line,
-      lineTotal: null,
-      resolvedPath: resolved,
-      verified: false,
-      error: 'file_not_found',
-    }
-  }
-
-  // Symlink containment: resolveWithin is lexical only, but existsSync /
-  // readFileSync follow symlinks. Verify the REAL path stays inside the REAL
-  // project root so a finding path can never read (or line-count) a file
-  // outside the project via a symlinked directory or file.
-  const rootReal = safeRealpath(root)
-  const real = safeRealpath(resolved)
-  if (!isWithin(rootReal, real)) {
-    return {
-      file: relFile,
-      line,
-      lineTotal: null,
-      resolvedPath: resolved,
-      verified: false,
-      error: 'file_not_found',
-    }
-  }
-
-  // Regular-file + size guard: a directory, device file (/dev/zero), FIFO or
-  // multi-GB file is not a line-addressable text target. statSync follows
-  // symlinks, so a link to a device still lands here and is rejected.
-  let st
-  try {
-    st = statSync(resolved)
-  } catch {
-    return {
-      file: relFile,
-      line,
-      lineTotal: null,
-      resolvedPath: resolved,
-      verified: false,
-      error: 'file_not_found',
-    }
-  }
-  if (!st.isFile() || st.size > MAX_EVIDENCE_BYTES) {
-    return {
-      file: relFile,
-      line,
-      lineTotal: null,
-      resolvedPath: resolved,
-      verified: false,
-      error: 'line_out_of_range',
+  const resolved = resolveWithin(root, relFile)
+  let probe: FileProbe
+  if (resolved === null) {
+    // Path escapes the root: no I/O happens, so nothing to cache.
+    probe = { resolvedPath: null, outcome: 'file_not_found', lineTotal: null }
+  } else {
+    const cached = opts.cache?.get(resolved)
+    if (cached) {
+      probe = cached
+    } else {
+      if (!existsSync(resolved)) {
+        probe = { resolvedPath: resolved, outcome: 'file_not_found', lineTotal: null }
+      } else {
+        probe = probeEvidenceFile(root, resolved)
+      }
+      // Cache every resolved-path outcome (including not-found) so repeated
+      // findings on the same file cost one stat/read per audit, not one per
+      // finding (O(F×bytes) → O(unique files × bytes)).
+      if (opts.cache) opts.cache.set(resolved, probe)
     }
   }
 
-  let raw: Buffer
-  try {
-    raw = readFileSync(resolved)
-  } catch {
+  if (probe.outcome !== 'text') {
     return {
       file: relFile,
       line,
       lineTotal: null,
-      resolvedPath: resolved,
+      resolvedPath: probe.resolvedPath,
       verified: false,
-      error: 'file_not_found',
+      error: probe.outcome,
     }
   }
 
-  // A file is not line-addressable if it contains a NUL byte (binary payload).
-  // Anchored line numbers on a binary file cannot be trusted, so treat them the
-  // same as an out-of-range line rather than credulously accepting them
-  // (mirrors the harness `evidence.py` NUL check).
-  if (raw.includes(0)) {
+  const lineTotal = probe.lineTotal ?? 0
+  // Present-but-unanchorable line type (string/boolean/object): the file is
+  // real, but the claimed location can never be verified → poisoned.
+  if (badLineType) {
     return {
       file: relFile,
       line,
-      lineTotal: null,
-      resolvedPath: resolved,
+      lineTotal,
+      resolvedPath: probe.resolvedPath,
       verified: false,
       error: 'line_out_of_range',
     }
   }
-
-  const text = raw.toString('utf-8')
-  const { inBounds, lineTotal } = verifyLineBounds(line, text)
-  if (!inBounds) {
+  if (!lineInBounds(line, lineTotal)) {
     return {
       file: relFile,
       line,
       lineTotal,
-      resolvedPath: resolved,
+      resolvedPath: probe.resolvedPath,
       verified: false,
       error: 'line_out_of_range',
     }
@@ -262,22 +353,26 @@ export function verifyFinding(
     file: relFile,
     line,
     lineTotal,
-    resolvedPath: resolved,
+    resolvedPath: probe.resolvedPath,
     verified: true,
   }
   if (opts.readSet !== undefined) {
-    outcome.readVerified = opts.readSet.has(resolved)
+    // Per-finding, never cached: the read set may differ between calls sharing
+    // a probe cache, and membership is a cheap in-memory lookup.
+    outcome.readVerified = opts.readSet.has(resolved!)
   }
   return outcome
 }
 
-/** Attest every finding in a list. */
+/** Attest every finding in a list (one shared per-file probe per call). */
 export function verifyFindings(
   root: string,
   findings: Locatable[],
-  opts: { readSet?: Set<string> } = {},
+  opts: EvidenceVerifyOptions = {},
 ): EvidenceAudit {
-  const results = findings.map((f) => verifyFinding(root, f, opts))
+  const cache = opts.cache ?? createEvidenceCache()
+  const scoped: EvidenceVerifyOptions = opts.cache ? opts : { ...opts, cache }
+  const results = findings.map((f) => verifyFinding(root, f, scoped))
   return { checked: results.length, results }
 }
 
@@ -286,7 +381,14 @@ export function evidencePassed(audit: EvidenceAudit): boolean {
   return audit.results.every((r) => r.error === undefined)
 }
 
-/** Violating (non-grounded) results. */
+/**
+ * Violating (non-grounded) results.
+ *
+ * Exported PUBLIC API (tests and integrations filter by it directly);
+ * the production payload uses `evidenceToPlain`, which inlines the same
+ * filter — so this stays as the named, shared accessor rather than being
+ * folded into it.
+ */
 export function evidenceViolations(audit: EvidenceAudit): FindingEvidence[] {
   return audit.results.filter((r) => r.error !== undefined)
 }