@clear-capabilities/agentic-security-scanner 0.142.0 → 0.144.0

package/src/posture/risk-dollars.js

@@ -9,7 +9,7 @@
 //   Discount       reachability tier (route-reachable > function-reachable
 //                  > unknown > unreachable)
 //
-// EV per finding = P × Impact × Discount × ConfidenceFloor
+// EV per finding = P × Impact × Discount × ConfidenceWeight
 //
 // Industry breach-cost figures used here are sourced from publicly
 // reported aggregates (Ponemon Cost of a Data Breach Report — IBM/Verizon
@@ -19,6 +19,14 @@
 //
 // Disclaimer: this is an order-of-magnitude estimate for prioritization.
 // It is NOT an actuarial or insurance assessment.
+//
+// FR-803/FR-805 (assurance-hardening PRD): the single `ev` number above is
+// only ever the BASE scenario. Every finding also gets `range` (low/base/
+// high spanning conservative/base/severe), `scenarios` (all three, named),
+// `assumptions` (which table entry and which tier produced each factor),
+// and `modelVersion` — so a reader can trace any dollar figure back to
+// exactly the inputs and methodology version that produced it, and compare
+// scenarios without any of this ever touching `finding.severity`.
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -78,36 +86,126 @@ const REACH_DISCOUNT = {
   'function-reachable-but-not-route':0.4,
 };
 
+// Tiny YAML — parses the two flat "section:\n  key: number" blocks
+// (impactUSD, familyBaseProb) plus four top-level flat scalar keys (FR-802's
+// organization-specific inputs, added below). Deliberately line-based rather
+// than one multi-line regex: a single regex here
+// (`(?:\s+\w+\s*:\s*\d+\s*\n?)+`) looked correct but had a real, silent bug
+// — `\s*` before the optional trailing `\n?` greedily consumed the NEXT
+// line's leading indentation too, so the repeated group's `+` quantifier
+// only ever matched ONE entry before its required leading `\s+` failed to
+// find any whitespace left to consume. A risk-config.yml with more than one
+// impactUSD entry silently kept only the first — found while adding
+// familyBaseProb support (which inherited the identical bug) and testing
+// it with more than one entry, per this session's standing rule of testing
+// multi-entry cases, not just the single-entry case a hand-rolled parser's
+// own author tends to reach for first.
+//
+// FR-802: `organizationScale`, `industry`, `recordCount`, `controlStrength`
+// are free-form top-level scalars (not sections) — an operator states them
+// directly, e.g. `industry: healthcare`. `recordCount` is parsed as an
+// integer; a non-numeric value is treated as not configured (never silently
+// coerced to NaN, which `!= null` would otherwise count as "present").
+const FLAT_SCALAR_KEYS = ['organizationScale', 'industry', 'recordCount', 'controlStrength'];
+
 function _loadConfig(scanRoot) {
   const fp = statePath(scanRoot, 'risk-config.yml');
   if (!fs.existsSync(fp)) return null;
   try {
     const body = fs.readFileSync(fp, 'utf8');
-    // Tiny YAML — look for impactUSD / familyBaseProb overrides
     const cfg = {};
-    const impactMatch = body.match(/^impactUSD\s*:\s*\n((?:\s+\w+\s*:\s*\d+\s*\n?)+)/m);
-    if (impactMatch) {
-      cfg.impactUSD = {};
-      for (const m of impactMatch[1].matchAll(/(\w+)\s*:\s*(\d+)/g)) cfg.impactUSD[m[1]] = parseInt(m[2], 10);
+    let section = null;
+    for (const line of body.split(/\r?\n/)) {
+      const sectionMatch = line.match(/^(impactUSD|familyBaseProb)\s*:\s*$/);
+      if (sectionMatch) { section = sectionMatch[1]; continue; }
+      const flatMatch = !section && line.match(/^([A-Za-z][\w-]*)\s*:\s*(\S.*?)\s*$/);
+      if (flatMatch && FLAT_SCALAR_KEYS.includes(flatMatch[1])) {
+        if (flatMatch[1] === 'recordCount') {
+          const n = parseInt(flatMatch[2], 10);
+          if (Number.isFinite(n)) cfg.recordCount = n;
+        } else {
+          cfg[flatMatch[1]] = flatMatch[2];
+        }
+        continue;
+      }
+      if (!section) continue;
+      const entryMatch = line.match(/^[ \t]+([\w-]+)\s*:\s*([\d.]+)\s*$/);
+      if (entryMatch) {
+        if (!cfg[section]) cfg[section] = {};
+        cfg[section][entryMatch[1]] = section === 'impactUSD' ? parseInt(entryMatch[2], 10) : parseFloat(entryMatch[2]);
+      } else if (line.trim() !== '') {
+        section = null; // a non-indented, non-blank line ends the current section
+      }
     }
     return cfg;
   } catch { return null; }
 }
 
-function _baseProb(family) {
+// FR-801/FR-802: every dollar estimate is a SCENARIO by default — generic,
+// industry-wide probability/impact tables, not this organization's actual
+// exposure. `ORG_SPECIFIC_DIMENSIONS` is the full set of tunable knobs this
+// module recognizes (includes `familyBaseProb`, a bonus calibration input
+// that isn't one of FR-802's five named inputs). The stronger claim FR-802
+// gates — "likely organizational loss" — requires ALL FIVE of its literally
+// named inputs (scale, industry, record count, control strength, impact),
+// tracked separately as `REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS` so that
+// configuring `familyBaseProb` alone (or any subset of the five) can never
+// unlock that label — only 'scenario_partially_configured', same as before.
+const ORG_SPECIFIC_DIMENSIONS = ['impactUSD', 'familyBaseProb', 'organizationScale', 'industry', 'recordCount', 'controlStrength'];
+const REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS = ['impactUSD', 'organizationScale', 'industry', 'recordCount', 'controlStrength'];
+
+function _scenarioDisclosure(cfg) {
+  const configured = ORG_SPECIFIC_DIMENSIONS.filter(d => cfg && cfg[d] != null);
+  const unconfigured = ORG_SPECIFIC_DIMENSIONS.filter(d => !configured.includes(d));
+  const requiredMissing = REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS.filter(d => !(cfg && cfg[d] != null));
+
+  let status, message;
+  if (requiredMissing.length === 0) {
+    status = 'scenario_organization_specific';
+    message = `All organization-specific inputs are configured (${REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS.join(', ')}) — this estimate reflects a likely organizational loss for your organization, not a generic industry scenario.`;
+  } else if (configured.length > 0) {
+    status = 'scenario_partially_configured';
+    message = `Uses organization-configured values for: ${configured.join(', ')}. Still missing for a likely-organizational-loss estimate: ${requiredMissing.join(', ')}. This is NOT a likely-organizational-loss estimate.`;
+  } else {
+    status = 'scenario_default';
+    message = 'Uses generic industry-wide scenario defaults. No organization-specific inputs are configured (see .agentic-security/risk-config.yml) — this is NOT a likely-organizational-loss estimate.';
+  }
+
+  return {
+    status,
+    configuredInputs: configured,
+    unconfiguredInputs: unconfigured,
+    requiredForOrganizationSpecificLoss: REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS,
+    missingRequiredInputs: requiredMissing,
+    message,
+  };
+}
+
+function _baseProb(family, cfg) {
   if (!family) return 0.05;
+  const overrides = cfg && cfg.familyBaseProb;
+  if (overrides) {
+    const hit = overrides[family] ?? overrides[String(family).toLowerCase()];
+    if (typeof hit === 'number') return hit;
+  }
   return FAMILY_BASE_PROB[family] || FAMILY_BASE_PROB[String(family).toLowerCase()] || 0.05;
 }
 
+// FR-803: split out from _impactFor so an assumption can name WHICH tier
+// produced the number, not just the number itself.
+function _impactTierOf(finding) {
+  const dc = Array.isArray(finding.dataClasses) ? finding.dataClasses : [];
+  if (dc.includes('PHI')) return 'PHI';
+  if (dc.includes('PCI')) return 'PCI';
+  if (dc.includes('PII')) return 'PII';
+  if (dc.includes('Confidential')) return 'Confidential';
+  if (finding.threatModel?.crownJewel) return 'crown-jewel';
+  return 'default';
+}
+
 function _impactFor(finding, cfg) {
   const table = cfg && cfg.impactUSD ? { ...IMPACT_USD, ...cfg.impactUSD } : IMPACT_USD;
-  const dc = Array.isArray(finding.dataClasses) ? finding.dataClasses : [];
-  if (dc.includes('PHI')) return table.PHI;
-  if (dc.includes('PCI')) return table.PCI;
-  if (dc.includes('PII')) return table.PII;
-  if (dc.includes('Confidential')) return table.Confidential;
-  if (finding.threatModel?.crownJewel) return table['crown-jewel'];
-  return table.default;
+  return table[_impactTierOf(finding)];
 }
 
 // SCA entries carry reachabilityTier/routeReachable (engine.js's SCA
@@ -124,12 +222,16 @@ function _relevanceTierToReachTier(relevanceTier) {
   }
 }
 
-function _reachDiscount(finding) {
-  const tier = finding.reachabilityTier
+// FR-803: split out from _reachDiscount so an assumption can name the tier.
+function _reachTierOf(finding) {
+  return finding.reachabilityTier
     || (finding.routeReachable && 'route-reachable')
     || _relevanceTierToReachTier(finding.relevanceTier)
     || 'unknown';
-  return REACH_DISCOUNT[tier] || 0.3;
+}
+
+function _reachDiscount(finding) {
+  return REACH_DISCOUNT[_reachTierOf(finding)] || 0.3;
 }
 
 function _epssProb(finding) {
@@ -138,28 +240,111 @@ function _epssProb(finding) {
   return null;
 }
 
+// FR-803: names WHERE the probability number came from, for the assumptions
+// list — not just the value.
+function _probSource(finding, cfg) {
+  if (_epssProb(finding) != null) return 'EPSS score (finding-specific)';
+  const overrides = cfg && cfg.familyBaseProb;
+  if (overrides && (overrides[finding.family] != null || overrides[String(finding.family).toLowerCase()] != null)) {
+    return 'operator-configured familyBaseProb override';
+  }
+  return 'built-in industry base-rate table';
+}
+
+// Bump ONLY when the EV formula or a table's underlying MEANING changes
+// (e.g. re-deriving FAMILY_BASE_PROB from a new source) — never for an
+// additive field on the output shape, which stays backward compatible.
+export const RISK_MODEL_VERSION = '1.0.0';
+
+// FR-805: scenario multipliers apply only to the two GENERIC assumption
+// inputs — probability-of-exploit and impact-per-incident — that FR-801
+// already discloses as industry-wide defaults. Reachability discount and
+// confidence weight are both measured facts about THIS finding in THIS
+// scan, not assumptions with real-world spread, so they stay fixed across
+// scenarios rather than being perturbed for effect.
+const SCENARIO_MULTIPLIERS = {
+  conservative: { prob: 0.5, impact: 0.6 },
+  base: { prob: 1.0, impact: 1.0 },
+  severe: { prob: 1.75, impact: 1.5 },
+};
+
 /**
  * Compute EV per finding. Mutates the finding in place: adds
- * .riskDollars = { ev, prob, impact, discount }.
+ * .riskDollars = { ev, prob, impact, discount, confidenceWeight,
+ *   scenarioStatus, range: {low, base, high}, scenarios: {conservative,
+ *   base, severe}, assumptions: [...], modelVersion, confidence }.
  */
 export function annotateRiskDollars(scanRoot, findings) {
-  if (!Array.isArray(findings) || findings.length === 0) return { total: 0, sumEv: 0 };
+  const disclosure = _scenarioDisclosure(_loadConfig(scanRoot));
+  if (!Array.isArray(findings) || findings.length === 0) return { total: 0, sumEv: 0, scenario: disclosure };
   const cfg = _loadConfig(scanRoot);
   let sumEv = 0;
   let critEv = 0, highEv = 0;
   for (const f of findings) {
     const epss = _epssProb(f);
-    const prob = epss != null ? epss : _baseProb(f.family);
+    const prob = epss != null ? epss : _baseProb(f.family, cfg);
+    const impactTier = _impactTierOf(f);
     const impact = _impactFor(f, cfg);
-    const discount = _reachDiscount(f);
-    const confidenceFloor = Math.max(0.4, f.confidence || 0.8);
-    const ev = Math.round(prob * impact * discount * confidenceFloor);
-    f.riskDollars = { ev, prob: Number(prob.toFixed(3)), impact, discount, confidenceFloor: Number(confidenceFloor.toFixed(2)) };
+    const reachTier = _reachTierOf(f);
+    const discount = REACH_DISCOUNT[reachTier] || 0.3;
+    // FR-804 (assurance-hardening PRD): this used to be
+    // `Math.max(0.4, f.confidence || 0.8)` — TWO stacked bugs. First, `||`
+    // treats a real confidence of 0 (a legitimate, very-low value) as falsy
+    // and silently substitutes 0.8, the HIGH default — a genuinely
+    // near-zero-confidence finding got the same dollar weight as a
+    // near-certain one. Second, the unconditional `Math.max(0.4, ...)`
+    // floor inflated every OTHER low-confidence finding (0.05, 0.1, ...) up
+    // to 0.4 regardless, which is exactly "an artificially high confidence
+    // without an explicit reason" FR-804 names. Fixed: use the finding's
+    // real confidence whenever it is genuinely present (including 0), with
+    // no floor; 0.8 remains the default ONLY when confidence is absent
+    // (not a number at all), which is a "we don't know" default, not an
+    // inflation of a known low value.
+    const confidenceWeight = typeof f.confidence === 'number' ? f.confidence : 0.8;
+
+    // FR-805: three named scenarios, sharing the SAME discount/confidence —
+    // only the two generic inputs (prob, impact) are perturbed. `ev` (base
+    // scenario) is unchanged from before this cycle, since base's
+    // multipliers are 1.0/1.0.
+    const scenarios = {};
+    for (const [name, mult] of Object.entries(SCENARIO_MULTIPLIERS)) {
+      const scenarioProb = Math.min(1, prob * mult.prob);
+      const scenarioImpact = Math.round(impact * mult.impact);
+      scenarios[name] = Math.round(scenarioProb * scenarioImpact * discount * confidenceWeight);
+    }
+    const ev = scenarios.base;
+
+    // FR-803: every dollar value traces to its own assumptions and a model
+    // version — not just a bare number.
+    const assumptions = [
+      `probability of exploit: ${Number(prob.toFixed(3))} (source: ${_probSource(f, cfg)})`,
+      `impact estimate: ${fmtUsd(impact)} (tier: ${impactTier}, ${cfg?.impactUSD?.[impactTier] != null ? 'operator-configured' : 'built-in default'})`,
+      `reachability discount: ${discount} (tier: ${reachTier})`,
+      `confidence weight: ${Number(confidenceWeight.toFixed(2))} (${typeof f.confidence === 'number' ? 'measured from this scan' : 'unknown — defaulted'})`,
+    ];
+    // FR-803: a distinct confidence indicator on the estimate itself — not
+    // the per-finding confidenceWeight multiplier, but a coarse tier
+    // reflecting how much of this number is organization-specific vs.
+    // generic-default, folded with the finding's own detection confidence.
+    const confidence = disclosure.status === 'scenario_organization_specific' && confidenceWeight >= 0.7
+      ? 'high'
+      : (disclosure.status === 'scenario_default' || confidenceWeight < 0.4 ? 'low' : 'medium');
+
+    f.riskDollars = {
+      ev, prob: Number(prob.toFixed(3)), impact, discount,
+      confidenceWeight: Number(confidenceWeight.toFixed(2)),
+      scenarioStatus: disclosure.status,
+      range: { low: scenarios.conservative, base: scenarios.base, high: scenarios.severe },
+      scenarios,
+      assumptions,
+      modelVersion: RISK_MODEL_VERSION,
+      confidence,
+    };
     sumEv += ev;
     if (f.severity === 'critical') critEv += ev;
     else if (f.severity === 'high') highEv += ev;
   }
-  return { total: findings.length, sumEv, critEv, highEv };
+  return { total: findings.length, sumEv, critEv, highEv, scenario: disclosure };
 }
 
 /**
@@ -172,4 +357,9 @@ export function fmtUsd(n) {
   return `$${n}`;
 }
 
-export const _internals = { FAMILY_BASE_PROB, IMPACT_USD, REACH_DISCOUNT, _baseProb, _impactFor, _reachDiscount };
+export const _internals = {
+  FAMILY_BASE_PROB, IMPACT_USD, REACH_DISCOUNT, ORG_SPECIFIC_DIMENSIONS,
+  REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS, SCENARIO_MULTIPLIERS,
+  _baseProb, _impactFor, _impactTierOf, _reachDiscount, _reachTierOf,
+  _probSource, _loadConfig, _scenarioDisclosure,
+};

package/src/posture/scan-checkpoint.js

@@ -18,22 +18,40 @@
 //   2. Only the per-file loop is checkpointed. Every cross-file pass and the
 //      whole annotation pipeline re-runs from scratch on resume, so nothing that
 //      depends on the global picture can be stale by construction.
-//   3. Invalidation is conservative to the point of being blunt. The run key
-//      covers the engine version, the ruleset version, the bundle SHA, a content
-//      hash of every file in the scan (which subsumes mtime), and the scanner's
-//      own environment switches. If any of it moved, the checkpoint is discarded
-//      and the scan starts clean. Redoing work is merely slow; resuming stale
-//      work is a correctness bug.
+//   3. Invalidation is split into a GLOBAL identity and a PER-FILE identity
+//      (assurance-hardening PRD FR-208 — "changed inputs invalidate only
+//      affected checkpoints and record the invalidation reason"). The engine
+//      version, ruleset version, bundle SHA, dependency-manifest contents, and
+//      the scanner's own environment switches form the GLOBAL key: any of them
+//      changing affects how EVERY file would be analysed (decision #2 above —
+//      cross-file/dependency-derived results aren't checkpointed per-file at
+//      all), so a global-key mismatch still discards the whole checkpoint,
+//      exactly as before. A single scanned file's own content is NOT part of
+//      the global key: only THAT file's record is invalidated when its content
+//      changes, because a single file's own per-file analysis result depends
+//      only on that file's content plus the (unchanged) global identity — the
+//      cross-file passes that COULD make it depend on other files always
+//      re-run from scratch per decision #2. This was a real, deliberate
+//      widening from the original "any change discards everything" design,
+//      not a relaxation of the correctness property: it only reuses a
+//      per-file result when nothing that result could possibly depend on has
+//      moved. Redoing work is merely slow; resuming stale work is a
+//      correctness bug, and that bar has not moved.
 //
 // CRASH SAFETY: append-and-fsync. The file is a JSONL log — one header line
-// pinning the run key, then one self-describing record per completed file,
-// each carrying a SHA-256 of its own payload. Every record is written with a
+// pinning the global key (plus a plaintext meta summary used only to explain a
+// mismatch, never to decide one), then one self-describing record per
+// completed file, each carrying a SHA-256 of its own payload AND a SHA-256 of
+// the source content it was computed from. Every record is written with a
 // single `writeSync` and immediately `fsyncSync`'d before the next file is
 // analysed, so a process killed at any instant leaves either a complete record
 // or a torn tail. On recovery we read forward while records verify and truncate
 // the file at the last byte offset that did, so a torn tail is discarded rather
 // than resumed into. Nothing is ever rewritten in place, so there is no window
-// in which the file is neither the old state nor the new one.
+// in which the file is neither the old state nor the new one. A record whose
+// OWN content hash no longer matches the current file is a separate, later
+// check from tamper/tear detection — it is structurally intact, so it is not
+// truncated away, just excluded from what gets replayed (see `_recover`).
 //
 // Everything here follows the posture convention of never throwing: a failure to
 // open, read or append degrades to "no checkpoint", which just means a full scan.
@@ -54,7 +72,12 @@ import { stateWritesEnabled } from './state-dir.js';
 // exists to prevent. The read-only switch above is still honoured.
 const STATE_DIR = '.agentic-security';
 const FILE_NAME = 'scan-checkpoint.jsonl';
-const FORMAT = 'agentic-security-scan-checkpoint/1';
+// Bumped from /1: the header now stores a GLOBAL-only key (FR-208) instead of
+// one that folds in every scanned file's content, plus a plaintext meta
+// summary. A /1 checkpoint on disk must never be half-interpreted under /2
+// semantics, so the format bump alone is enough to force a clean discard of
+// anything written before this change — the safest possible migration.
+const FORMAT = 'agentic-security-scan-checkpoint/2';
 
 // Env switches that change what the engine emits are part of the run identity.
 // These three are deliberately excluded: they change how the run is driven, not
@@ -92,6 +115,14 @@ export function bundleShaForRunKey() {
  * Everything that would invalidate previously-completed per-file work, reduced
  * to one hex digest. Content hashes rather than mtimes: strictly stronger, and
  * immune to filesystems with coarse or non-monotonic timestamps.
+ *
+ * Retained as its own function (still folding in `fileContents`) because it is
+ * a useful, independently-tested "did ANYTHING about this scan change"
+ * fingerprint, and because `computeGlobalKey` below is defined in terms of it
+ * (fileContents forced empty) — changing this function's hash would silently
+ * change that one too. Production checkpointing itself uses `computeGlobalKey`,
+ * not this function directly; see FR-208's note in the module header for why
+ * file content is no longer part of what invalidates the WHOLE checkpoint.
  */
 export function computeRunKey({
   engineVersion, rulesetVersion, bundleSha,
@@ -119,6 +150,50 @@ export function computeRunKey({
   return h.digest('hex');
 }
 
+/**
+ * FR-208: the GLOBAL portion of run identity — everything that would affect
+ * how EVERY scanned file is analysed. Deliberately excludes `fileContents`
+ * (a single file's own content is checked per-record in `_recover` instead)
+ * but keeps `depFileContents`: dependency-manifest-derived findings are not
+ * part of any per-file checkpoint record (they're recomputed fresh every run,
+ * same as cross-file taint — decision #2 in the module header), so there is
+ * no per-file granularity to offer there; any manifest change invalidates
+ * everything, same as before this change.
+ */
+export function computeGlobalKey({ engineVersion, rulesetVersion, bundleSha, depFileContents = {}, env = process.env } = {}) {
+  return computeRunKey({ engineVersion, rulesetVersion, bundleSha, fileContents: {}, depFileContents, env });
+}
+
+/**
+ * A plaintext (non-hashed) summary of the same inputs `computeGlobalKey` folds
+ * in, stored alongside the key in the checkpoint header. Used ONLY to explain
+ * a global-key mismatch after the fact (`_explainGlobalMismatch`) — never to
+ * decide whether one occurred; the key comparison remains the sole source of
+ * truth for that, so a caller cannot bypass invalidation by supplying
+ * mismatched meta.
+ */
+export function globalKeyMeta({ engineVersion, rulesetVersion, bundleSha, depFileContents = {}, env = process.env } = {}) {
+  return {
+    engineVersion: String(engineVersion ?? ''),
+    rulesetVersion: String(rulesetVersion ?? ''),
+    bundleSha: String(bundleSha ?? 'unavailable'),
+    depFingerprint: computeRunKey({ engineVersion: '', rulesetVersion: '', bundleSha: '', fileContents: {}, depFileContents, env: {} }),
+    envFingerprint: computeRunKey({ engineVersion: '', rulesetVersion: '', bundleSha: '', fileContents: {}, depFileContents: {}, env }),
+  };
+}
+
+function _explainGlobalMismatch(oldMeta, newMeta) {
+  oldMeta = oldMeta || {};
+  newMeta = newMeta || {};
+  const parts = [];
+  if (oldMeta.engineVersion !== newMeta.engineVersion) parts.push(`engine version changed (${oldMeta.engineVersion || 'unknown'} -> ${newMeta.engineVersion || 'unknown'})`);
+  if (oldMeta.rulesetVersion !== newMeta.rulesetVersion) parts.push(`ruleset version changed (${oldMeta.rulesetVersion || 'unknown'} -> ${newMeta.rulesetVersion || 'unknown'})`);
+  if (oldMeta.bundleSha !== newMeta.bundleSha) parts.push('the running bundle changed');
+  if (oldMeta.depFingerprint !== newMeta.depFingerprint) parts.push('a dependency manifest file changed');
+  if (oldMeta.envFingerprint !== newMeta.envFingerprint) parts.push('an AGENTIC_SECURITY_* environment switch changed');
+  return parts.length ? `global scan identity changed: ${parts.join(', ')}` : 'global scan identity changed';
+}
+
 // A value is safe to checkpoint only if JSON can carry it back unchanged. Dates,
 // regexes, Maps, Sets, functions and BigInts all survive `JSON.stringify` in a
 // lossy or throwing way; recording one would mean the resumed run sees different
@@ -150,28 +225,39 @@ function _jsonSafe(v, depth = 0, seen = new Set()) {
 
 function _emptyHandle(reason) {
   return {
-    enabled: false, file: null, fd: null, runKey: null,
+    enabled: false, file: null, fd: null, globalKey: null,
     recovered: new Map(), order: [], written: new Set(),
-    discarded: false, reason,
+    discarded: false, reason, invalidatedFiles: [], fileContents: {},
   };
 }
 
-function _headerLine(runKey) {
-  return JSON.stringify({ v: FORMAT, runKey }) + '\n';
+function _headerLine(globalKey, meta) {
+  return JSON.stringify({ v: FORMAT, gk: globalKey, meta: meta || {} }) + '\n';
 }
 
 // Read forward from a byte offset, keeping records while they verify. Returns
-// the offset of the first byte that did NOT verify, so the caller can truncate.
-function _recover(handle, file, runKey) {
+// {offset, discardReason}: offset is the byte position the caller should keep
+// (or truncate to); discardReason is set only when offset===0 (the whole
+// checkpoint is being discarded) and explains why, per FR-208.
+//
+// A record whose payload hash (`c`) doesn't verify is torn/tampered and ends
+// recovery right there, same as before FR-208. A record that verifies
+// structurally but whose OWN content hash (`h`) no longer matches the
+// CURRENT content of that file is a different, later check — it is not
+// corrupt, so it does not truncate the file; it is simply excluded from
+// `handle.recovered` and named in `handle.invalidatedFiles`, so only that
+// file gets re-analysed this run.
+function _recover(handle, file, globalKey, meta, fileContents) {
   let buf;
   try { buf = fs.readFileSync(file); }
-  catch { return -1; } // no file yet
+  catch { return { offset: -1, discardReason: null }; } // no file yet
   const text = buf.toString('utf8');
   const nl = text.indexOf('\n');
-  if (nl < 0) return 0;
+  if (nl < 0) return { offset: 0, discardReason: 'empty or corrupt checkpoint file' };
   let header = null;
-  try { header = JSON.parse(text.slice(0, nl)); } catch { return 0; }
-  if (!header || header.v !== FORMAT || header.runKey !== runKey) return 0;
+  try { header = JSON.parse(text.slice(0, nl)); } catch { return { offset: 0, discardReason: 'corrupt checkpoint header' }; }
+  if (!header || header.v !== FORMAT) return { offset: 0, discardReason: 'checkpoint format changed' };
+  if (header.gk !== globalKey) return { offset: 0, discardReason: _explainGlobalMismatch(header.meta, meta) };
 
   let offset = Buffer.byteLength(text.slice(0, nl + 1), 'utf8');
   let cursor = nl + 1;
@@ -187,19 +273,50 @@ function _recover(handle, file, runKey) {
     if (rec.c !== _sha(rec.d)) break;         // tampered or torn-then-patched
     let payload;
     try { payload = JSON.parse(rec.d); } catch { break; }
+    // Structurally intact and parseable — advance past it regardless of what
+    // the per-file content check below decides; a stale-but-intact record is
+    // not a torn or tampered one and must not be truncated away.
+    offset = Buffer.byteLength(text.slice(0, cursor), 'utf8');
+    // FR-208: per-file content check. A record written with no tracked
+    // source hash (`h` absent — e.g. a caller that never supplied
+    // fileContents) has nothing to compare against, so it is trusted exactly
+    // as it was before this per-file check existed.
+    if (rec.h != null) {
+      const current = fileContents ? fileContents[rec.f] : undefined;
+      if (typeof current !== 'string') {
+        handle.invalidatedFiles.push({ file: rec.f, reason: 'no longer part of this scan' });
+        continue;
+      }
+      if (rec.h !== _sha(current)) {
+        handle.invalidatedFiles.push({ file: rec.f, reason: 'content changed since it was checkpointed' });
+        continue;
+      }
+    }
     if (!handle.recovered.has(rec.f)) handle.order.push(rec.f);
     handle.recovered.set(rec.f, payload);
-    offset = Buffer.byteLength(text.slice(0, cursor), 'utf8');
   }
-  return offset;
+  return { offset, discardReason: null };
 }
 
 /**
- * Open (or start) the checkpoint for `scanRoot` under `runKey`. Never throws.
- * A handle whose `enabled` is false silently no-ops through the rest of the API.
+ * Open (or start) the checkpoint for `scanRoot` under `globalKey`. Never
+ * throws. A handle whose `enabled` is false silently no-ops through the rest
+ * of the API.
+ *
+ * `fileContents` (FR-208): the CURRENT content of every file this scan would
+ * analyse, keyed by the same relative path `recordFileDone` is called with.
+ * Passed through to per-file content comparison on recovery, and to
+ * `recordFileDone` for hashing each new record's own content. Omitting it
+ * (or passing `{}`) degrades every record to trust-on-structural-validity
+ * only — the pre-FR-208 behaviour — which is exactly what a caller testing
+ * the checkpoint PROTOCOL itself (not per-file invalidation) wants, and
+ * exactly what the low-level tests in this module's test file rely on.
+ *
+ * `meta`: a plaintext summary of the inputs behind `globalKey` (see
+ * `globalKeyMeta`), stored in the header purely to explain a mismatch later.
  */
-export function openCheckpoint(scanRoot, { runKey } = {}) {
-  if (!scanRoot || !runKey) return _emptyHandle('no-run-key');
+export function openCheckpoint(scanRoot, { globalKey, meta = {}, fileContents = {} } = {}) {
+  if (!scanRoot || !globalKey) return _emptyHandle('no-global-key');
   // A read-only scan cannot checkpoint, and must not try. Resume is purely an
   // optimisation — without it the scan recomputes, which is slower and
   // identical — so `--no-state` wins over `AGENTIC_SECURITY_RESUME=1` rather
@@ -207,20 +324,25 @@ export function openCheckpoint(scanRoot, { runKey } = {}) {
   // the API, so no caller needs a new branch. (PRD M1)
   if (!stateWritesEnabled()) return _emptyHandle('state-writes-disabled');
   const handle = _emptyHandle(null);
+  handle.fileContents = fileContents || {};
   try {
     const dir = path.join(scanRoot, STATE_DIR);
     fs.mkdirSync(dir, { recursive: true });
     const file = checkpointPath(scanRoot);
     handle.file = file;
-    handle.runKey = runKey;
+    handle.globalKey = globalKey;
 
-    const keepBytes = _recover(handle, file, runKey);
+    const { offset: keepBytes, discardReason } = _recover(handle, file, globalKey, meta, handle.fileContents);
     if (keepBytes <= 0) {
-      // Absent, foreign, or unreadable — start clean. Conservative by design.
+      // Absent, foreign, or globally invalidated — start clean. A byte offset
+      // of -1 (no file yet) is a fresh checkpoint, not a discard, so it gets
+      // no reason; 0 (format/global-key mismatch, or corrupt header) does.
       handle.recovered.clear();
       handle.order.length = 0;
+      handle.invalidatedFiles = [];
       handle.discarded = keepBytes === 0;
-      fs.writeFileSync(file, _headerLine(runKey));
+      handle.reason = keepBytes === 0 ? discardReason : null;
+      fs.writeFileSync(file, _headerLine(globalKey, meta));
     } else {
       // Drop any torn tail so appends land after the last verified record.
       try {
@@ -243,6 +365,13 @@ export function openCheckpoint(scanRoot, { runKey } = {}) {
  * analysis produced. `findings` is the per-file payload object (see the engine
  * call site); it must be plain JSON data. Returns true only if the record is on
  * disk and fsync'd.
+ *
+ * Also records a SHA-256 of `relPath`'s current content (from the
+ * `fileContents` the handle was opened with), so a later run's `_recover` can
+ * tell whether this specific file has changed since — the FR-208 per-file
+ * half of invalidation. A handle opened without `fileContents` (or one that
+ * doesn't include this path) records no hash, which `_recover` treats as
+ * "nothing to compare," matching this module's pre-FR-208 behaviour exactly.
  */
 export function recordFileDone(handle, relPath, findings) {
   if (!handle || !handle.enabled || handle.fd === null || typeof relPath !== 'string') return false;
@@ -250,7 +379,9 @@ export function recordFileDone(handle, relPath, findings) {
     if (!_jsonSafe(findings)) return false;
     const d = JSON.stringify(findings === undefined ? null : findings);
     if (typeof d !== 'string') return false;
-    const line = JSON.stringify({ f: relPath, c: _sha(d), d }) + '\n';
+    const src = handle.fileContents ? handle.fileContents[relPath] : undefined;
+    const h = typeof src === 'string' ? _sha(src) : null;
+    const line = JSON.stringify({ f: relPath, h, c: _sha(d), d }) + '\n';
     fs.writeSync(handle.fd, line);
     fs.fsyncSync(handle.fd);
     handle.written.add(relPath);
@@ -260,6 +391,20 @@ export function recordFileDone(handle, relPath, findings) {
   }
 }
 
+/**
+ * FR-208: individually-invalidated files from a checkpoint whose GLOBAL
+ * identity still matched — each entry names the file and why (content
+ * changed, or the file is no longer part of this scan). Deliberately does
+ * NOT enumerate every file when the whole checkpoint was discarded instead
+ * (`handle.discarded`/`handle.reason` already say why, once, for all of
+ * them — reading the rest of a large journal just to repeat the same reason
+ * per file would cost real I/O for no new information). Always `[]` on a
+ * disabled handle, a brand-new checkpoint, or a global discard.
+ */
+export function invalidatedFiles(handle) {
+  return (handle && Array.isArray(handle.invalidatedFiles)) ? handle.invalidatedFiles : [];
+}
+
 /** Files already analysed — recovered from a prior run plus written by this one. */
 export function completedFiles(handle) {
   const out = new Set();