@clear-capabilities/agentic-security-scanner 0.127.0 → 0.130.0

package/src/posture/fix-verify.js

@@ -6,6 +6,10 @@
 //   1. The original finding's stableId no longer fires on the patched file.
 //   2. No new findings at severity ≥ medium were introduced by the patch.
 //   3. The project's existing linter (when present) passes on the patched file.
+//   4. The project's own test suite (when detectable) still passes. This is
+//      the R5 gap-closer: a patch that silently deletes the feature would
+//      satisfy (1) and (2) just as well as a real fix — only running the
+//      tests catches that. See `test-runner.js` for detection + execution.
 //
 // If any of those fail, the caller is expected to NOT apply the patch and
 // instead surface a "fix plan" — a numbered list of steps the engineer can
@@ -15,6 +19,8 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { runFullScan } from '../engine.js';
+import { gateFixOutput } from './fix-honesty-gate.js';
+import { runProjectTests } from './test-runner.js';
 
 const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 
@@ -110,21 +116,83 @@ function runLinter(cwd, cmd, args) {
 
 // Top-level verify: re-scan + lint. Returns the combined verdict + a
 // human-readable summary string suitable for surfacing to the user.
+// Addition #7 — deterministic honesty gates on fix output. When the caller
+// supplies `fixMeta` ({ residual, verdict, evidence, signals }) — e.g. the
+// security-fixer agent's residual-risk text + completeness signals — the fix's
+// claims are checked mechanically (no hand-wave residual prose, a cited
+// file:line for any FP/safe verdict, and a FULL/MITIGATION/WORKAROUND tier). A
+// dishonest or over-claiming fix fails the gate. When `fixMeta` is absent
+// (the deterministic MCP write path, which has no claims to check) the honesty
+// gate is skipped and behavior is unchanged.
+// R5 (partial) — the test-suite stage. Runs the target project's own tests,
+// in the target project's own directory, against whatever is currently on
+// disk there. See `test-runner.js`'s header comment for why that run is
+// deliberately NOT routed through the R1 PoC-confinement sandbox: this is
+// the project's own already-trusted suite, not untrusted synthesized code.
+//
+// Caveat that matters for callers: `verifyPatch` above re-scans the
+// candidate patch purely in memory (no write to disk), but a test runner
+// needs real files — there is no cheap way to hand a runner an in-memory
+// overlay. So this leg reports on the CURRENT on-disk tree, not the
+// candidate `files` map, when `verifyFix` is used as a pre-write preview
+// (e.g. the `verify_fix` MCP tool). Callers that apply the patch first and
+// then re-verify get the strongest signal; that ordering is not enforced
+// here — it's the caller's responsibility, same as it already is for the
+// closed-loop `fix-verify-loop.js` path.
+// Does the caller's candidate patch differ from what is on disk right now?
+// If so, any test run necessarily exercised the pre-patch tree. Compared by
+// content so a patch that happens to match disk (already applied) is correctly
+// treated as NOT pre-patch.
+function _candidateDiffersFromDisk(scanRoot, files) {
+  if (!files || typeof files !== 'object') return false;
+  for (const [rel, content] of Object.entries(files)) {
+    if (typeof content !== 'string') continue;
+    try {
+      const abs = path.resolve(scanRoot, rel);
+      if (fs.readFileSync(abs, 'utf8') !== content) return true;
+    } catch {
+      return true; // candidate file absent on disk -> definitely not applied
+    }
+  }
+  return false;
+}
+
 export async function verifyFix({
   scanRoot,
   originalFindingStableId,
   files,
   depFileContents,
+  fixMeta,
+  testTimeoutMs,
 } = {}) {
   const rescan = await verifyPatch({ scanRoot, originalFindingStableId, files, depFileContents });
   const lint = runProjectLinter(scanRoot, Object.keys(files || {}));
-  const ok = rescan.ok && (lint.ok || lint.skipped);
+  const tests = runProjectTests(scanRoot, testTimeoutMs != null ? { timeoutMs: testTimeoutMs } : {});
+  // True when a candidate patch was supplied but has not been written, so the
+  // suite necessarily ran against the pre-patch tree. Surfaced in the summary
+  // and on the result so a caller cannot mistake it for a verified patch.
+  const _testedPrePatch = !tests.skipped && _candidateDiffersFromDisk(scanRoot, files);
+  const testsOk = tests.skipped ? true : tests.passed === true;
+  let honesty = null;
+  if (fixMeta && typeof fixMeta === 'object') {
+    try { honesty = gateFixOutput(fixMeta); } catch { honesty = null; }
+  }
+  const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && (honesty ? honesty.ok : true);
   const summary = [
     `re-scan: ${rescan.ok ? 'PASS' : 'FAIL — ' + rescan.reason}`,
     `linter:  ${lint.runner === 'none' ? 'skipped (no linter config)'
               : lint.skipped ? `${lint.runner} not installed`
               : lint.ok ? `${lint.runner} PASS`
               : `${lint.runner} FAIL (exit ${lint.exitCode})`}`,
-  ].join('\n');
-  return { ok, rescan, lint, summary };
+    // Say which tree the suite actually ran against. `files` is a candidate
+    // patch held in memory; the runner needs real files, so it sees whatever is
+    // on disk. Reporting a bare "PASS" here would let a caller believe the
+    // PATCH passed the tests when the suite may have run on unpatched code.
+    `tests:   ${tests.skipped ? `skipped (${tests.reason})`
+              : tests.timedOut ? 'FAIL (timed out)'
+              : tests.passed ? `PASS${_testedPrePatch ? ' — on the CURRENT on-disk tree, NOT the candidate patch' : ''}`
+              : `FAIL (exit ${tests.exitCode})`}`,
+    honesty ? `honesty: ${honesty.ok ? `PASS (${honesty.tier})` : 'FAIL — ' + honesty.violations.join('; ')}` : null,
+  ].filter(Boolean).join('\n');
+  return { ok, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, summary };
 }

package/src/posture/license-policy.js

@@ -14,7 +14,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 
 const DEFAULT_POLICY = {
   allow: [],

package/src/posture/model-routing.js

@@ -0,0 +1,126 @@
+// Capability-based model routing for cost-sensitive subagent dispatch.
+//
+// A declarative CWE/severity → model policy. When the orchestrator is about to
+// dispatch a delegable, cost-sensitive subagent for a finding (fixer, triager,
+// PoC generator, attack-chain synthesizer), it can ask this module which model
+// tier the work actually warrants — spend Opus reasoning on the hard classes
+// (crypto, auth, deserialization, XXE, cross-file taint) and let Haiku handle
+// the mechanical hardening findings.
+//
+// Mirrors the model IDs + tier vocabulary of hooks/model-cost-advisor.js:
+//   strongest = claude-opus-4-8   (high effort)
+//   mid       = claude-sonnet-4-6 (medium effort)
+//   cheapest  = claude-haiku-4-5  (low effort)
+//
+// This is a *preference*, not a ceiling — a caller may always upgrade when the
+// specific task clearly needs more capability (same spirit as the
+// subagentOverride contract documented in the root CLAUDE.md).
+//
+// Pure + deterministic — no I/O, no network, never throws.
+
+// Model IDs (module-local; the public API is the routing functions below).
+const MODEL_STRONGEST = 'claude-opus-4-8';
+const MODEL_MID = 'claude-sonnet-4-6';
+const MODEL_CHEAPEST = 'claude-haiku-4-5';
+
+const LABEL = {
+  [MODEL_STRONGEST]: 'Opus 4.8',
+  [MODEL_MID]: 'Sonnet 4.6',
+  [MODEL_CHEAPEST]: 'Haiku 4.5',
+};
+
+// Hard classes — subtle, high-blast-radius bugs where a wrong fix is worse than
+// no fix: auth, TLS/cert validation, weak crypto/hashing/randomness, signature
+// verification, unsafe deserialization, XXE. Worth Opus when they land at high
+// or critical severity.
+const HARD_CWES = new Set([
+  'CWE-287', // improper authentication
+  'CWE-295', // improper certificate validation
+  'CWE-327', // broken / risky crypto algorithm
+  'CWE-328', // weak hash
+  'CWE-330', // use of insufficiently random values
+  'CWE-347', // improper verification of cryptographic signature
+  'CWE-502', // deserialization of untrusted data
+  'CWE-611', // XML external entity (XXE)
+]);
+
+// Mid classes — the common injection / traversal / CSRF / SSRF families.
+// Well-understood remediations; Sonnet handles them cost-effectively.
+const MID_CWES = new Set([
+  'CWE-22',  // path traversal
+  'CWE-78',  // OS command injection
+  'CWE-79',  // cross-site scripting
+  'CWE-89',  // SQL injection
+  'CWE-94',  // code injection
+  'CWE-352', // cross-site request forgery
+  'CWE-434', // unrestricted file upload
+  'CWE-601', // open redirect
+  'CWE-918', // server-side request forgery
+]);
+
+// Extract the canonical `CWE-<n>` token from a finding.cwe value that may be a
+// bare id ("CWE-89") or a descriptive string ("CWE-89: SQL Injection").
+// Returns the uppercased id, or null when nothing parseable is present.
+export function parseCwe(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/CWE-\d+/i);
+  return m ? m[0].toUpperCase() : null;
+}
+
+// Route a single finding to a model tier. First match wins.
+// Returns { model, effort, reason }.
+export function routeModelForFinding(finding) {
+  const f = finding || {};
+  const severity = typeof f.severity === 'string' ? f.severity.toLowerCase() : '';
+  const cwe = parseCwe(f.cwe);
+  const multiFile = f.multiFile === true || f.isCrossFile === true;
+  const highOrCritical = severity === 'high' || severity === 'critical';
+
+  // ── Tier 1: strongest (Opus, high effort) ──
+  if (severity === 'critical') {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `Critical severity — worth ${LABEL[MODEL_STRONGEST]} at high effort.` };
+  }
+  if (cwe && HARD_CWES.has(cwe) && highOrCritical) {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `${cwe} at ${severity} severity is a hard class (crypto / auth / deserialization / XXE) — ${LABEL[MODEL_STRONGEST]} at high effort.` };
+  }
+  if (multiFile) {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `Cross-file finding — needs ${LABEL[MODEL_STRONGEST]} at high effort to reason across files.` };
+  }
+
+  // ── Tier 2: mid (Sonnet, medium effort) ──
+  if (cwe && MID_CWES.has(cwe)) {
+    return { model: MODEL_MID, effort: 'medium',
+      reason: `${cwe} is a common injection / traversal class — ${LABEL[MODEL_MID]} at medium effort.` };
+  }
+  if (severity === 'high') {
+    return { model: MODEL_MID, effort: 'medium',
+      reason: `High severity — ${LABEL[MODEL_MID]} at medium effort.` };
+  }
+
+  // ── Tier 3: cheapest (Haiku, low effort) ──
+  return { model: MODEL_CHEAPEST, effort: 'low',
+    reason: `${cwe ? `${cwe} at ` : ''}${severity || 'low'} severity is a simple / hardening class — ${LABEL[MODEL_CHEAPEST]} at low effort.` };
+}
+
+// Route a list of findings. Returns [{ finding, model, effort, reason }, …].
+export function routeModelForFindings(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  return list.map((finding) => ({ finding, ...routeModelForFinding(finding) }));
+}
+
+// Tally how many findings land on each model tier.
+// Returns { 'claude-opus-4-8': n, 'claude-sonnet-4-6': n, 'claude-haiku-4-5': n }.
+export function summarizeRouting(findings) {
+  const counts = {
+    [MODEL_STRONGEST]: 0,
+    [MODEL_MID]: 0,
+    [MODEL_CHEAPEST]: 0,
+  };
+  for (const { model } of routeModelForFindings(findings)) {
+    if (model in counts) counts[model] += 1;
+  }
+  return counts;
+}

package/src/posture/profile.js

@@ -5,7 +5,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 import { statePath, safeWriteState, resolveProjectRoot } from './state-dir.js';
 
 export const PROFILES = ['vibecoder', 'pro'];

package/src/posture/proof-tier.js

@@ -0,0 +1,33 @@
+// How strongly a finding is backed by evidence.
+//
+//   execution-proven — a proof-of-concept RAN inside the sandbox and produced
+//                      the predicted observable effect. The strongest claim.
+//   proof-failed     — a proof-of-concept ran and did NOT demonstrate the bug.
+//                      A triage signal, NOT an automatic false-positive verdict:
+//                      absence of proof is not proof of absence.
+//   taint-proven     — the analyser's static reasoning found it; nothing executed.
+//   unproven         — no analyser backing recorded.
+export const PROOF_TIERS = Object.freeze([
+  'execution-proven', 'proof-failed', 'taint-proven', 'unproven',
+]);
+
+// Parsers that represent real analysis rather than a plain pattern match.
+const _ANALYSED = new Set(['IR-TAINT', 'MULTI-SINK']);
+
+export function proofTierOf(finding) {
+  if (finding?.proofTier) return finding.proofTier;
+  return _ANALYSED.has(finding?.parser) ? 'taint-proven' : 'unproven';
+}
+
+export function attachProofTier(finding, evidence) {
+  if (!PROOF_TIERS.includes(evidence?.tier)) {
+    throw new Error(`unknown proof tier: ${evidence?.tier}`);
+  }
+  let tier = evidence.tier;
+  // Guard the central honesty rule: nothing that did not RUN may be called
+  // execution-proven or proof-failed. Fall back to the finding's static standing.
+  if (!evidence.ran && (tier === 'execution-proven' || tier === 'proof-failed')) {
+    tier = proofTierOf({ ...finding, proofTier: undefined });
+  }
+  return { ...finding, proofTier: tier, proofEvidence: { ...evidence, tier } };
+}

package/src/posture/relevance.js

@@ -0,0 +1,379 @@
+// R6 (threat-model-first scoping) + R9 (attack-surface-forward analysis).
+//
+// Every other precision mechanism in this engine kills a false positive by
+// PATTERN — a sanitizer on the path, a proof that didn't reproduce, a
+// confidence model fit to labelled families. This module kills one by
+// RELEVANCE: a finding sitting on a path an attacker can actually reach,
+// inside something the threat model says is worth attacking, matters more
+// than one that is neither. It is a different axis, and it composes with
+// (never replaces) the sink-driven taint engine.
+//
+//   R9 — start at the attack surface and reason FORWARD. `entrypoint-
+//        inventory.js` already enumerates every attacker-reachable entry
+//        point (HTTP/queue/cron/CLI/env/upload/webhook). Here that inventory
+//        stops being a report and starts being an input: we walk the module
+//        import graph out from every entry-point file and record which files
+//        are reachable from the attack surface at all.
+//   R6 — `threat-model.js` already derives assets, trust boundaries and a
+//        STRIDE classification. Here that model re-ranks: a finding on a
+//        modelled asset, or one classified into a modelled STRIDE bucket,
+//        outranks an identical finding that is in neither.
+//
+// ── Recall-preserving contract (non-negotiable) ────────────────────────────
+// Same precedent as `falsification.js` and `dataflow/proof-gate.js`:
+//   • Never removes a finding. The array in is the array out, same length,
+//     same order, same objects.
+//   • Never touches `severity`. Ever. Severity is the customer's triage
+//     contract; relevance is an ordinal re-rank underneath it.
+//   • Never asserts `unreachable` without POSITIVE evidence. "I could not
+//     determine it" is `entrypointReachable: null` / `relevanceTier:
+//     'unknown'` — a distinct state from "I determined it is not reachable".
+//     A negative verdict additionally requires the intra-repo import graph to
+//     be provably COMPLETE: one unresolved relative import anywhere means the
+//     graph has a hole an attacker's path could be hiding in, and every
+//     would-be `unreachable` degrades to `unknown`.
+//   • Demotion has a floor. An unreachable finding's exploitability is scaled,
+//     never zeroed — a wrong reachability call must cost rank, not visibility.
+//
+// Fields set on each finding:
+//   entrypointReachable : true | false | null   (null ≠ false)
+//   relevance           : number 0..1
+//   relevanceTier       : 'direct' | 'indirect' | 'unreachable' | 'unknown'
+//   relevanceFactors    : string[]  (human-readable, like exploitabilityFactors)
+
+// ── Tunables ───────────────────────────────────────────────────────────────
+const BASE_SCORE = {
+  direct: 0.75,
+  indirect: 0.50,
+  unreachable: 0.15,
+  unknown: 0.40,
+};
+// Cap so that no accumulation of R6 bonuses can push an evidenced-unreachable
+// finding into the same band as a reachable one.
+const UNREACHABLE_CAP = 0.30;
+
+// Exploitability re-rank multipliers (R6's "re-rank exploitability").
+const EXPLOIT_MULT = { direct: 1.15, indirect: 1.0, unreachable: 0.6, unknown: 1.0 };
+const EXPLOIT_FLOOR = 0.05;   // demotion never zeroes a finding out
+
+const IMPORT_EXTS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '/index.js', '/index.ts', '/index.mjs'];
+const MAX_FILES = 5000;       // graph-size guard: bail to 'unknown' beyond this
+
+// ── Source-level import extraction ─────────────────────────────────────────
+// Static, literal specifiers only. Anything non-literal is recorded as a hole.
+const RE_IMPORT_FROM = /\bimport\s[^;'"`]*?from\s*['"]([^'"]+)['"]/g;
+const RE_IMPORT_BARE = /\bimport\s*['"]([^'"]+)['"]/g;
+const RE_EXPORT_FROM = /\bexport\s[^;'"`]*?from\s*['"]([^'"]+)['"]/g;
+const RE_REQUIRE = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_DYN_IMPORT = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_PY_FROM = /^\s*from\s+([.\w]+)\s+import\s/gm;
+const RE_PY_IMPORT = /^\s*import\s+([.\w]+)/gm;
+const RE_JAVA_IMPORT = /^\s*import\s+(?:static\s+)?([\w.]+);/gm;
+// Non-literal module loads: the graph cannot see through these.
+const RE_DYNAMIC_HOLE = /\brequire\s*\(\s*[^'")\s]|\bimport\s*\(\s*[^'")\s]/;
+
+function _entries(fileContents) {
+  if (!fileContents) return [];
+  if (fileContents instanceof Map) {
+    return [...fileContents.entries()].filter(([k, v]) => typeof k === 'string' && typeof v === 'string');
+  }
+  if (typeof fileContents === 'object') {
+    return Object.entries(fileContents).filter(([k, v]) => typeof k === 'string' && typeof v === 'string');
+  }
+  return [];
+}
+
+function _norm(p) {
+  const parts = String(p).replace(/\\/g, '/').split('/');
+  const out = [];
+  for (const seg of parts) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') { out.pop(); continue; }
+    out.push(seg);
+  }
+  return out.join('/');
+}
+
+function _dirOf(file) {
+  const i = String(file).replace(/\\/g, '/').lastIndexOf('/');
+  return i < 0 ? '' : String(file).slice(0, i);
+}
+
+// Resolve one specifier to a key in `known`. Returns the key, or null.
+function _resolve(spec, fromFile, known, suffixIndex) {
+  if (!spec) return null;
+  const relative = spec.startsWith('.');
+  const base = relative ? _norm(`${_dirOf(fromFile)}/${spec}`) : null;
+
+  if (relative) {
+    for (const ext of IMPORT_EXTS) {
+      const cand = base + ext;
+      if (known.has(cand)) return cand;
+    }
+    // Also try the raw (already-extensioned) form as written.
+    if (known.has(base)) return base;
+    return null;
+  }
+
+  // Non-relative: python dotted module, java FQCN, or a bare package name.
+  const dotted = spec.replace(/\./g, '/');
+  for (const ext of ['.py', '.java', '.js', '.ts', '/__init__.py']) {
+    const hit = suffixIndex.get(dotted + ext);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Build the attack-surface reachability view.
+ *
+ * @returns {{
+ *   entryFiles: Set<string>, unauthEntryFiles: Set<string>,
+ *   reachableFiles: Set<string>, knownFiles: Set<string>,
+ *   graphComplete: boolean, holes: number,
+ * }}
+ */
+function buildReachabilityGraph(fileContents, opts = {}) {
+  const knownFiles = new Set();
+  const entryFiles = new Set();
+  const unauthEntryFiles = new Set();
+  const reachableFiles = new Set();
+  let graphComplete = false;
+  let holes = 0;
+
+  try {
+    const files = _entries(fileContents);
+    if (files.length === 0 || files.length > MAX_FILES) {
+      return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete: false, holes: 1 };
+    }
+    for (const [k] of files) knownFiles.add(k);
+
+    // Index by path suffix so a python/java module name can find its file.
+    const suffixIndex = new Map();
+    for (const k of knownFiles) {
+      const norm = k.replace(/\\/g, '/');
+      const segs = norm.split('/');
+      for (let i = 0; i < segs.length; i++) {
+        const suf = segs.slice(i).join('/');
+        if (!suffixIndex.has(suf)) suffixIndex.set(suf, k);
+      }
+    }
+
+    // 1) Entry-point files, from the inventory and/or the raw route list.
+    const inv = opts.entrypointInventory;
+    const invEntries = inv && Array.isArray(inv.entrypoints) ? inv.entrypoints
+      : Array.isArray(opts.entrypoints) ? opts.entrypoints : [];
+    for (const e of invEntries) {
+      if (!e || typeof e.file !== 'string' || !e.file) continue;
+      entryFiles.add(e.file);
+      if (e.trust !== 'authenticated') unauthEntryFiles.add(e.file);
+    }
+    for (const r of (Array.isArray(opts.routes) ? opts.routes : [])) {
+      if (!r || typeof r.file !== 'string' || !r.file) continue;
+      entryFiles.add(r.file);
+      if (r.hasAuth !== true) unauthEntryFiles.add(r.file);
+    }
+
+    // 2) Import edges. A hole is an edge the graph cannot see: an unresolved
+    //    intra-repo (relative) specifier, or a non-literal module load. Holes
+    //    are recorded PER FILE because only holes in files that turn out to be
+    //    REACHABLE can hide a path into somewhere we'd otherwise call
+    //    unreachable — a hidden edge always originates in the importing file,
+    //    so a hole inside an already-unreachable file cannot make anything
+    //    reachable. Anything else would make a negative verdict impossible in
+    //    any real repository (one `require(varName)` anywhere would veto all).
+    const edges = new Map();
+    const holeFiles = new Set();
+    for (const [file, src] of files) {
+      const out = new Set();
+      if (RE_DYNAMIC_HOLE.test(src)) { holes++; holeFiles.add(file); }
+      for (const re of [RE_IMPORT_FROM, RE_EXPORT_FROM, RE_IMPORT_BARE, RE_REQUIRE, RE_DYN_IMPORT,
+        RE_PY_FROM, RE_PY_IMPORT, RE_JAVA_IMPORT]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(src))) {
+          const spec = m[1];
+          if (!spec) continue;
+          const target = _resolve(spec, file, knownFiles, suffixIndex);
+          if (target && target !== file) out.add(target);
+          // Only an unresolved INTRA-repo (relative) specifier is a hole:
+          // a bare package name points at a third-party module that was
+          // never part of `fileContents` in the first place.
+          else if (!target && spec.startsWith('.')) { holes++; holeFiles.add(file); }
+        }
+      }
+      edges.set(file, out);
+    }
+
+    // 3) Forward BFS from the attack surface.
+    const queue = [...entryFiles].filter(f => knownFiles.has(f));
+    for (const f of queue) reachableFiles.add(f);
+    while (queue.length) {
+      const cur = queue.shift();
+      for (const next of (edges.get(cur) || [])) {
+        if (reachableFiles.has(next)) continue;
+        reachableFiles.add(next);
+        queue.push(next);
+      }
+    }
+
+    // A negative verdict is admissible only when we actually found an attack
+    // surface AND no file reachable from it has an invisible edge.
+    let reachableHole = false;
+    for (const f of reachableFiles) if (holeFiles.has(f)) { reachableHole = true; break; }
+    graphComplete = !reachableHole && entryFiles.size > 0;
+  } catch (_) {
+    return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete: false, holes: holes || 1 };
+  }
+  return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete, holes };
+}
+
+// ── R6: threat-model bonuses ───────────────────────────────────────────────
+function _threatBonus(f, threatModel, factors) {
+  let bonus = 0;
+  if (!threatModel || typeof threatModel !== 'object') return bonus;
+
+  const assets = Array.isArray(threatModel.assets) ? threatModel.assets : [];
+  for (const a of assets) {
+    if (!a || a.file !== f.file) continue;
+    const exposed = a.exposure === 'public-api' || a.exposure === 'external-api';
+    bonus += exposed ? 0.10 : 0.07;
+    factors.push(`modelled asset in file: ${a.category || a.name || 'asset'}${exposed ? ` (${a.exposure})` : ''}`);
+    break;
+  }
+
+  const boundaries = Array.isArray(threatModel.trustBoundaries) ? threatModel.trustBoundaries : [];
+  if (boundaries.some(b => b && b.file === f.file)) {
+    bonus += 0.05;
+    factors.push('trust boundary crossed in this file');
+  }
+
+  const stride = threatModel.stride && typeof threatModel.stride === 'object' ? threatModel.stride : null;
+  if (stride) {
+    for (const [cat, items] of Object.entries(stride)) {
+      if (!Array.isArray(items)) continue;
+      if (items.some(it => it && it.file === f.file && (it.line === f.line || it.vuln === f.vuln))) {
+        bonus += 0.08;
+        factors.push(`modelled STRIDE threat: ${cat}`);
+        break;
+      }
+    }
+  }
+  return bonus;
+}
+
+/**
+ * Pure scorer. Does NOT mutate the finding.
+ *
+ * @param graph  the object returned by buildReachabilityGraph (or a subset
+ *               with entryFiles / reachableFiles / knownFiles / graphComplete).
+ * @returns {{ tier, score, reachable, factors }}
+ */
+function scoreRelevance(f, graph, threatModel) {
+  const factors = [];
+  const g = graph || {};
+  const entryFiles = g.entryFiles instanceof Set ? g.entryFiles : new Set();
+  const reachableFiles = g.reachableFiles instanceof Set ? g.reachableFiles : new Set();
+  const knownFiles = g.knownFiles instanceof Set ? g.knownFiles : new Set();
+  const unauthEntryFiles = g.unauthEntryFiles instanceof Set ? g.unauthEntryFiles : new Set();
+  const file = f && typeof f.file === 'string' ? f.file : null;
+
+  let tier;
+  let reachable;
+  if (!file || entryFiles.size === 0) {
+    tier = 'unknown';
+    reachable = null;
+    factors.push(entryFiles.size === 0
+      ? 'no attack surface enumerated — reachability not determinable'
+      : 'finding has no file — reachability not determinable');
+  } else if (entryFiles.has(file)) {
+    tier = 'direct';
+    reachable = true;
+    factors.push('finding sits in an entry-point file (direct attack surface)');
+    if (unauthEntryFiles.has(file)) factors.push('entry point is unauthenticated');
+  } else if (reachableFiles.has(file)) {
+    tier = 'indirect';
+    reachable = true;
+    factors.push('reachable from an entry point via the module import graph');
+  } else if (g.graphComplete === true && knownFiles.has(file)) {
+    tier = 'unreachable';
+    reachable = false;
+    factors.push('no import path from any enumerated entry point (import graph complete)');
+  } else {
+    tier = 'unknown';
+    reachable = null;
+    factors.push(knownFiles.has(file)
+      ? 'import graph incomplete — no reachability verdict admissible'
+      : 'file not present in the scanned set — reachability not determinable');
+  }
+
+  let score = BASE_SCORE[tier];
+  score += _threatBonus(f || {}, threatModel, factors);
+  if (tier === 'direct' && unauthEntryFiles.has(file)) score += 0.10;
+  if (tier === 'unreachable') score = Math.min(score, UNREACHABLE_CAP);
+  score = Math.max(0, Math.min(1, score));
+
+  return { tier, score: Math.round(score * 1000) / 1000, reachable, factors };
+}
+
+/**
+ * Default-on annotator. Recall-preserving: never removes a finding, never
+ * touches severity, never asserts 'unreachable' without positive evidence.
+ *
+ * @param ctx.fileContents          Map|object of scanned sources
+ * @param ctx.entrypointInventory   output of buildEntrypointInventory()
+ * @param ctx.routes                route list (fallback attack surface)
+ * @param ctx.threatModel           output of buildThreatModel()
+ */
+export function annotateRelevance(findings, ctx = {}) {
+  if (!Array.isArray(findings)) return findings;
+  let graph;
+  try {
+    const c = ctx && typeof ctx === 'object' ? ctx : {};
+    graph = buildReachabilityGraph(c.fileContents, {
+      entrypointInventory: c.entrypointInventory,
+      entrypoints: c.entrypoints,
+      routes: c.routes,
+    });
+  } catch (_) {
+    graph = { entryFiles: new Set(), unauthEntryFiles: new Set(), reachableFiles: new Set(), knownFiles: new Set(), graphComplete: false, holes: 1 };
+  }
+  const threatModel = ctx && typeof ctx === 'object' ? ctx.threatModel : null;
+
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    try {
+      const r = scoreRelevance(f, graph, threatModel);
+      f.entrypointReachable = r.reachable;
+      f.relevance = r.score;
+      f.relevanceTier = r.tier;
+      f.relevanceFactors = r.factors;
+
+      // R6 re-rank: exploitability is an ordinal priority, so scaling it by
+      // relevance is exactly the intended re-ranking. Severity is untouched,
+      // and demotion has a floor — a wrong call costs rank, not visibility.
+      const mult = EXPLOIT_MULT[r.tier];
+      if (typeof f.exploitability === 'number' && Number.isFinite(f.exploitability) && mult !== 1) {
+        const adjusted = Math.max(EXPLOIT_FLOOR, Math.min(1, f.exploitability * mult));
+        f.exploitability = Math.round(adjusted * 100) / 100;
+        if (typeof f.priorityScore === 'number') f.priorityScore = f.exploitability;
+        if (Array.isArray(f.exploitabilityFactors)) f.exploitabilityFactors.push(`relevance:${r.tier}`);
+        // Keep the tier label consistent with the re-ranked score. Same
+        // thresholds as annotateExploitability; severity is NOT derived here.
+        if (f.exploitability >= 0.80) f.exploitabilityTier = 'critical';
+        else if (f.exploitability >= 0.60) f.exploitabilityTier = 'high';
+        else if (f.exploitability >= 0.35) f.exploitabilityTier = 'medium';
+        else f.exploitabilityTier = 'low';
+      }
+    } catch (_) {
+      f.entrypointReachable = null;
+      f.relevance = BASE_SCORE.unknown;
+      f.relevanceTier = 'unknown';
+      f.relevanceFactors = ['relevance scoring failed — no verdict'];
+    }
+  }
+  return findings;
+}
+
+// Test-only surface (underscore-prefixed: not part of the public API).
+export const _internals = { buildReachabilityGraph, scoreRelevance, BASE_SCORE, EXPLOIT_MULT };