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

package/src/engine.js

@@ -260,6 +260,17 @@ import { annotateAttackTaxonomy, summarizeTaxonomy } from './posture/attack-taxo
 import { suppressByPastDecisions } from './posture/triage-memory.js';
 import { suppressByIntent } from './posture/intent-context.js';
 import { annotateGitHistory } from './posture/git-history.js';
+// NOT `annotateProvenance` (sca/sigstore-verify.js's build-attestation
+// annotator) and NOT `annotateFindingProvenance` (posture/provenance.js's
+// AI-code fingerprint annotator). Both are already imported above in this
+// file, so either name here is a duplicate binding — a SyntaxError — and the
+// second is worse still because it also takes a findings array as its first
+// argument, so a wrong import would RUN rather than fail. This one is named
+// for the mechanism that distinguishes it —
+// provenance derived from GIT HISTORY. See provenance/coordinator.js's header.
+import { annotateGitProvenance, PROVENANCE_DEFAULT_TIMEOUT_MS, MAX_PROVIDER_ENRICHMENTS_PER_SCAN } from './posture/provenance/coordinator.js';
+import { updateLifecycle } from './posture/provenance/lifecycle.js';
+import { emptyProvenance, PROVENANCE_STATUS } from './posture/provenance/schema.js';
 import { applyThreatModel } from './posture/threat-model-grounding.js';
 import { annotateCrossRepoSignals } from './posture/pattern-propagation.js';
 import { annotateRiskDollars } from './posture/risk-dollars.js';
@@ -2626,6 +2637,33 @@ function _resetSuppressions(){ _suppressionLog.length = 0; }
 // so pfr[p] and the aggregates share object identity, exactly as in a normal run.
 function _pfrMetaOnly(ta){ if(!ta||typeof ta!=='object')return {}; const o={}; for(const k of Object.keys(ta)){ if(k==='findings'||k==='sources'||k==='sinks'||k==='sanitizers')continue; o[k]=ta[k]; } return o; }
 function _getSuppressions(){ return [..._suppressionLog]; }
+// Task 11 reentrancy fix: `_suppressionLog` is module-level and unconditionally
+// cleared by `_resetSuppressions()` at the top of every `runFullScan` call.
+// `predicate-replay.js`'s `replayAt` calls `runFullScan` recursively FROM
+// WITHIN an outer, still-running scan's provenance resolution (to replay a
+// finding's predicate at a historical commit) -- before Task 11 wired
+// scan.secrets/scan.logicVulns into real provenance resolution, that recursive
+// call was only ever reachable from scan.findings/SCA origin walks, which this
+// exact fixture (test/fixtures/entropy-fp) never triggered. Wiring secrets in
+// exposed it for the first time: the nested call's `_resetSuppressions()`
+// silently wiped the OUTER scan's suppression log before its own return
+// statement read it via `_getSuppressions()`, so `scan.suppressions` came back
+// empty for anything that happened to walk deep git history.
+//
+// A plain snapshot/restore around ONE `replayAt` call is not sufficient on its
+// own: `coordinator.js` resolves several findings' origins CONCURRENTLY (its
+// own comment: "the scheduler runs these four at a time"), and each finding's
+// resolveOrigin walk can call `replayAt` multiple times sequentially -- so two
+// DIFFERENT findings' replay calls can be in flight at once, interleaved at
+// `runFullScan`'s own internal await points. Two overlapping snapshot/restore
+// pairs racing on the same global array means whichever restores last wins,
+// discarding whatever the other legitimately wrote in between. Exported so
+// predicate-replay.js can snapshot/restore its own call boundary AND serialize
+// that boundary process-wide (see its own comment on the exclusivity queue) --
+// the nested scan's own suppression output is never read by replayAt, so
+// nothing is lost by discarding it.
+function _snapshotSuppressionLog(){ return _suppressionLog.slice(); }
+function _restoreSuppressionLog(saved){ _suppressionLog.length = 0; if (Array.isArray(saved)) _suppressionLog.push(...saved); }
 
 // ── inline suppression pragma ───────────────────────────────────────────────
 //
@@ -7340,6 +7378,31 @@ function _makePurl(ecosystem,name,version,group){
   return`pkg:${t}/${ns}${encodeURIComponent(name)}${version?'@'+encodeURIComponent(version):''}`;
 }
 
+function _findManifestLine(text, sectionKey, depName) {
+  const lines = text.split('\n');
+  let inSection = false;
+  let depth = 0;
+  const escaped = depName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const nameRe = new RegExp(`"${escaped}"\\s*:`);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!inSection) {
+      if (new RegExp(`"${sectionKey}"\\s*:\\s*\\{`).test(line)) {
+        inSection = true;
+        depth = 1 + (line.match(/\{/g) || []).length - 1 - (line.match(/\}/g) || []).length;
+        if (nameRe.test(line)) return i + 1;
+        if (depth <= 0) inSection = false;
+      }
+      continue;
+    }
+    depth += (line.match(/\{/g) || []).length;
+    depth -= (line.match(/\}/g) || []).length;
+    if (depth <= 0) { inSection = false; continue; }
+    if (nameRe.test(line)) return i + 1;
+  }
+  return null;
+}
+
 function _parsePackageJson(text,filePath){
   const out=[];try{const d=JSON.parse(text);
     for(const[depKey,scope]of[['dependencies','required'],['devDependencies','optional']]){
@@ -7350,7 +7413,8 @@ function _parsePackageJson(text,filePath){
         const group=scoped?`@${parts[0]}`:'';
         const pkgName=scoped?parts[1]:name;
         out.push({name,version:ver,group,scope,purl:_makePurl('npm',pkgName,ver,group),ecosystem:'npm',filePath,
-          isUnpinned:verRange==='*'||verRange==='latest'||verRange===''||verRange==='>=0.0.0'});
+          isUnpinned:verRange==='*'||verRange==='latest'||verRange===''||verRange==='>=0.0.0',
+          line:_findManifestLine(text,depKey,name)});
       }
     }
   }catch(_){}return out;
@@ -7379,12 +7443,13 @@ function _parsePackageLockJson(text,filePath){
 
 function _parseRequirementsTxt(text,filePath){
   const out=[];
-  for(const line of text.split('\n')){
-    const t=line.trim();
+  const lines=text.split('\n');
+  for(let i=0;i<lines.length;i++){
+    const t=lines[i].trim();
     if(!t||t.startsWith('#')||t.startsWith('-'))continue;
     const m=t.match(/^([A-Za-z0-9_.-]+)\s*[=~<>!]+\s*([^\s;#,]*)/);
     if(m)out.push({name:m[1],version:m[2],group:'',scope:'required',
-      purl:_makePurl('pypi',m[1].toLowerCase(),m[2],''),ecosystem:'pypi',filePath,isUnpinned:false});
+      purl:_makePurl('pypi',m[1].toLowerCase(),m[2],''),ecosystem:'pypi',filePath,isUnpinned:false,line:i+1});
   }return out;
 }
 
@@ -8180,6 +8245,15 @@ async function queryOSV(components,allFileContents){
         fixedVersions: vuln.fixedVersions, severity: vuln.severity, cvssVector: vuln.cvssVector,
         hasKnownAttackRef: vuln.hasKnownAttackRef, osvVulnFunctions: vuln.osvVulnFunctions || [], reachable: comp.reachable, scope: comp.scope,
         file: comp.filePath,
+        // `isDirect` is backfilled onto every component just above the queryOSV
+        // call, but was never carried onto the entry materialized from it — so
+        // every consumer asking "is this a direct dependency" got `undefined`.
+        // The transitive-dedup block's `group.find(s => s.isDirect)` has
+        // therefore always fallen through to `group[0]`, picking an arbitrary
+        // member as the primary instead of the direct one, and the provenance
+        // pass's direct-only filter had nothing to filter on. `line` is Task
+        // 12's declaration line, which the SCA provenance evidence node reads.
+        isDirect: comp.isDirect, line: comp.line, depChain: Array.isArray(comp.depChain) ? comp.depChain.map((s) => s.replace(/\/$/, '')) : [],
         // kept for generateRecs() compat
         advisory: `${vid}${cveStr}, ${vuln.description}`,
         range: fixStr ? `< ${fixStr}` : 'see advisory' });
@@ -8526,7 +8600,28 @@ async function queryRegistries(components){
     return {content:c, pfr:ta, routes:_aR, findings:_aF, sources:_aSrc, sinks:_aSink, sanitizers:_aSan, logic:_aLogic, secrets:_aSecrets, ciphersRest:_aCiphersRest, ciphersTransit:_aCiphersTransit, suppressions:_aSupp};
   }
 
-async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null, resume=undefined, deep=undefined, deepInCi=undefined}, setProgress=()=>{}){_resetSuppressions();_buildProjectIndex(fileContents);await _loadCustomRules(scanRoot);
+// `provenance:false` is the RE-ENTRANCY BRAKE, not a feature flag.
+// posture/provenance/predicate-replay.js answers "did this finding's condition
+// hold at commit X" by calling runFullScan back on that commit's blobs. Once
+// runFullScan itself runs the provenance pass, that is an unbounded recursion —
+// scan → provenance → replay → scan → … — which manifests as a scan that never
+// returns and spawns `git` forever, because every level of it is synchronous
+// execFileSync work. The replay's findings are discarded, so it wants no
+// provenance anyway; and it must NOT touch the lifecycle store, whose events
+// would otherwise be written from historical blobs as if they were this scan.
+// Passed explicitly per invocation rather than held in a module-level guard so
+// concurrent scans in one process cannot disable each other's provenance.
+//
+// `completeScan` is a SEPARATE question from `provenance`, and conflating them
+// is what let the fourth instance of this bug through. `provenance:false` says
+// "do not run the pass at all"; `completeScan:false` says "the pass may run,
+// but this file set is a SUBSET of scanRoot, so absence of a finding proves
+// nothing." Only the lifecycle ledger's remediation pass reads it — that is the
+// one place a finding's absence is turned into a positive claim. Defaults true
+// because a direct runFullScan caller supplying no file-subsetting options is
+// scanning everything it was given; runScan.js narrows it for --changed-since
+// and for caller-supplied fileContents.
+async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null, resume=undefined, deep=undefined, deepInCi=undefined, provenance=true, completeScan=true, skipAnnotators=false}, setProgress=()=>{}){_resetSuppressions();_buildProjectIndex(fileContents);await _loadCustomRules(scanRoot);
   // Pre-pass: build cross-file Java tainted-method index so per-file taint
   // analysis can recognize calls to user-input-returning helper methods
   // defined in OTHER files (Juliet's DataflowThruInnerClass / Vector / Stream
@@ -9276,9 +9371,76 @@ function _deterministicFileTimings(timings) {
   // Every catch in this block writes into _annotatorErrors so the operator
   // can tell "didn't run" from "ran cleanly." The array is surfaced as
   // scan.annotatorErrors in the report; an empty array means clean.
+  //
+  // FR-PROV-029 (Finding Provenance PRD): `skipAnnotators` lets a caller skip
+  // this entire ~54-annotator pipeline below. The guard also covers
+  // non-annotator finalization that lives in the same block — entropy-vs-
+  // named secret dedup, orphan classification, supply-chain in-place
+  // filtering, `Object.freeze(finalFindings)`, and closing the resume
+  // checkpoint — so a skipped run leaves all of that undone too; name the
+  // option accordingly if a future caller needs annotators skipped WITHOUT
+  // skipping those steps. predicate-replay.js's `replayAt()` is the only
+  // caller that sets it — it re-runs runFullScan scoped to a historical
+  // commit's blob content purely to recompute `computeStableId()` over the
+  // raw detector output (`scan.findings`/`scan.secrets`); it never reads
+  // anything an annotator sets (verified empirically — see the commit
+  // message). Every binding the pipeline below
+  // populates that the final `return` still references is declared here,
+  // OUTSIDE the guarded block, defaulted to exactly what it was before any
+  // annotator ran. A skipped run returns those fields at their
+  // pre-annotation default instead of throwing a ReferenceError; a normal
+  // (non-skipping) run is byte-for-byte unaffected, since the guarded block
+  // below still assigns the same values to these same bindings — it just no
+  // longer *declares* them, so nothing here changes what a value ends up
+  // being, only where the variable comes into scope.
   let _executionProofSummary = null, _vulnHistory = null;
   let _logicClaims = null;
-  const _annotatorErrors = [];
+  let _annotatorErrors = [];
+  let _v3 = {};
+  let _privacyIrBacked = null;
+  let _privacyTaxonomyVersion = null;
+  let _privacyFramework = null;
+  let _threatModel = null, _apiContractFindings = [], _sbomDiff = null,
+      _complianceReport = null, _exploitBundles = null, _pqcPlan = null,
+      _licenseGraph = null, _attributions = null, _taxonomySummary = null;
+  let _scanMeta = null;
+  let _entrypointInventory = {};
+  let _rootCauseSweep = null;
+  let _proofCoverage = null;
+  let _coverageLedger = null;
+  let _scanHealth = null;
+  // Task 11 (PRD P0 scope): ruleId backfill for scan.secrets / blameable
+  // scan.logicVulns findings MUST run unconditionally, HERE, outside the
+  // `skipAnnotators` guard below -- not just because the live scan needs it,
+  // but because predicate-replay.js's replayAt() recurses into THIS function
+  // with skipAnnotators:true and recomputes computeStableId() directly on
+  // whatever it finds in the nested scan's own scan.secrets/scan.logicVulns.
+  // If the backfill only ran on the live (skipAnnotators:false) call, the
+  // nested replay scan would compute a DIFFERENT stableId (falling back to
+  // the shared f.cwe -- e.g. every secret type collapsing onto "CWE-798")
+  // than the live scan's already-backfilled finding, so replayAt's
+  // `sid === targetStableId` check would NEVER match -- permanently landing
+  // every secrets/logicVulns finding on status:'partial',
+  // reason:'predicate-never-confirmed-in-candidates'. Caught empirically:
+  // test/fixtures/entropy-fp's AWS-key fixture resolved 'partial' instead of
+  // 'complete' until this moved here from inside the (skipAnnotators-gated)
+  // provenance block further down.
+  //
+  // At this point in the function, aSecrets/aLogic hold every BLAMEABLE
+  // producer's output (scanCredentials/scanEntropySecrets;
+  // scanLogicVulns/scanBusinessLogic/scanMiddlewareOrdering/scanReDoS/
+  // scanRegexReDoS/scanTodosNearSecurity/scanConfigFiles) -- the 3 synthetic
+  // producers (license-policy:/deploy-platform:/stack-playbook:) and
+  // logic-claims.js's ingested claims are pushed LATER, inside the
+  // `skipAnnotators` guard below, so they are never present in a nested
+  // replay scan's aLogic and never need this backfill for replay-matching
+  // purposes. The provenance block further down re-applies this same
+  // idempotent backfill to the full, final `blameableLogic` (which by then
+  // includes logic-claims too) before calling annotateGitProvenance on it.
+  const _slugify = (s) => String(s || 'unknown').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
+  for (const f of aSecrets) { if (!f.ruleId) f.ruleId = `secret:${_slugify(f.vuln)}`; }
+  for (const f of aLogic) { if (!f.ruleId) f.ruleId = `logic:${_slugify(f.vuln)}`; }
+  if (!skipAnnotators) {
   // FR-106 (assurance-hardening PRD): Promise-aware, explicitly awaited at
   // every one of its ~51 call sites below (previously a sync `try{return
   // fn()}` let an async callback's rejection escape as an unhandled
@@ -9384,18 +9546,18 @@ function _deterministicFileTimings(timings) {
   // FR-405 (assurance-hardening PRD): null means "privacy analysis never
   // ran at all" (AGENTIC_SECURITY_NO_PRIVACY=1, or the annotator threw
   // before setting this) — treated the same as false by the gate below,
-  // since neither case has real IR-backed evidence to offer. Declared here,
-  // at function scope, because the annotatePrivacyTaint closure that
-  // assigns to it (inside the AGENTIC_SECURITY_NO_INTEGRATION block below)
-  // runs and exits before that block closes — a block-scoped `let` inside
-  // that if-statement would be unreachable by the later assessPrivacyFramework
-  // call and the final return, both of which are outside the block.
-  let _privacyIrBacked = null;
-  // FR-402: which taxonomy version actually classified this scan's fields —
-  // same scoping constraint as _privacyIrBacked directly above (D-0011):
-  // must be declared before the AGENTIC_SECURITY_NO_INTEGRATION block opens,
-  // not inside it.
-  let _privacyTaxonomyVersion = null;
+  // since neither case has real IR-backed evidence to offer. Declared at
+  // function scope (now hoisted above the `skipAnnotators` guard, near
+  // _executionProofSummary et al. — same reasoning: FR-PROV-029), because
+  // the annotatePrivacyTaint closure that assigns to it (inside the
+  // AGENTIC_SECURITY_NO_INTEGRATION block below) runs and exits before that
+  // block closes — a block-scoped `let` inside that if-statement would be
+  // unreachable by the later assessPrivacyFramework call and the final
+  // return, both of which are outside the block.
+  //
+  // FR-402: _privacyTaxonomyVersion (which taxonomy version actually
+  // classified this scan's fields) has the same scoping constraint as
+  // _privacyIrBacked directly above (D-0011) and is hoisted alongside it.
 
   // ── World-class integration block ─────────────────────────────────────
   // Each annotator is opt-in via env var and try/catch wrapped. They run
@@ -9894,7 +10056,7 @@ function _deterministicFileTimings(timings) {
   classifyOrphans(aSrc,aSink,finalFindings,fc);
   // v3 next-gen: capture scan-level reports (counterfactual, threat model,
   // trust-boundary diagram, calibration-drift alarms). All best-effort.
-  let _v3 = {};
+  // (_v3 is hoisted above the `skipAnnotators` guard — FR-PROV-029.)
   await _runAnnotator("_v3.counterfactual", () => { _v3.counterfactual = runCounterfactual(finalFindings, fc); });
   await _runAnnotator("_v3.threatModel", () => { _v3.threatModel = buildThreatModel(finalFindings, fc); });
   await _runAnnotator("_v3.trustBoundaryDiagram", () => { _v3.trustBoundaryDiagram = buildTrustBoundaryDiagram(finalFindings, fc); });
@@ -9912,10 +10074,9 @@ function _deterministicFileTimings(timings) {
   // Each is opt-in via env var. They produce machine-readable artifacts
   // (threat-model.json/.md, dpia.md, compliance-evidence.json/.md,
   // sbom-history/<sha>.json, exploit-bundles/) under .agentic-security/.
-  let _privacyFramework = null;
-  let _threatModel = null, _apiContractFindings = [], _sbomDiff = null,
-      _complianceReport = null, _exploitBundles = null, _pqcPlan = null,
-      _licenseGraph = null, _attributions = null, _taxonomySummary = null;
+  // (_privacyFramework/_threatModel/_apiContractFindings/_sbomDiff/
+  // _complianceReport/_exploitBundles/_pqcPlan/_licenseGraph/_attributions/
+  // _taxonomySummary are hoisted above the `skipAnnotators` guard — FR-PROV-029.)
   if (process.env.AGENTIC_SECURITY_NO_INTEGRATION !== '1') {
     // Threat model — STRIDE + entities + attack trees rooted in findings.
     if (process.env.AGENTIC_SECURITY_NO_THREAT_MODEL !== '1') {
@@ -10083,12 +10244,307 @@ function _deterministicFileTimings(timings) {
   // seen when only N-of-those-candidates were actually analyzed.
   // checkpoint.total intentionally keeps files.length — that field means the
   // full candidate set for resume bookkeeping, a different, correct meaning.
-  const _scanMeta={filesScanned:Object.keys(fc).length,filesSkipped:_filesSkipped,filesDenseSkipped:_filesDenseSkipped,filesTimedOut:_filesTimedOut,analysisTier:_analysisTier,unmodeledSinkCandidates:_unmodeledSinks,fileTimings:_deterministicFileTimings(_fileTimings),findingsBySeverity:{critical:finalFindings.filter(f=>f.severity==='critical').length,high:finalFindings.filter(f=>f.severity==='high').length,medium:finalFindings.filter(f=>f.severity==='medium').length,low:finalFindings.filter(f=>f.severity==='low').length,info:finalFindings.filter(f=>f.severity==='info').length},checkpoint:{enabled:!!(_ckpt&&_ckpt.enabled),resumed:_ckptResumed,total:files.length,discarded:!!(_ckpt&&_ckpt.discarded),discardReason:(_ckpt&&_ckpt.discarded)?(_ckpt.reason||null):null,invalidatedFileCount:_ckptInvalidated.length,invalidatedFiles:_ckptInvalidated.slice(0,20),invalidatedFilesTruncated:_ckptInvalidated.length>20}};
+  _scanMeta={filesScanned:Object.keys(fc).length,filesSkipped:_filesSkipped,filesDenseSkipped:_filesDenseSkipped,filesTimedOut:_filesTimedOut,analysisTier:_analysisTier,unmodeledSinkCandidates:_unmodeledSinks,fileTimings:_deterministicFileTimings(_fileTimings),findingsBySeverity:{critical:finalFindings.filter(f=>f.severity==='critical').length,high:finalFindings.filter(f=>f.severity==='high').length,medium:finalFindings.filter(f=>f.severity==='medium').length,low:finalFindings.filter(f=>f.severity==='low').length,info:finalFindings.filter(f=>f.severity==='info').length},checkpoint:{enabled:!!(_ckpt&&_ckpt.enabled),resumed:_ckptResumed,total:files.length,discarded:!!(_ckpt&&_ckpt.discarded),discardReason:(_ckpt&&_ckpt.discarded)?(_ckpt.reason||null):null,invalidatedFileCount:_ckptInvalidated.length,invalidatedFiles:_ckptInvalidated.slice(0,20),invalidatedFilesTruncated:_ckptInvalidated.length>20}};
   // R8: the scan completed, so the checkpoint has been fully consumed — remove
   // it. Anything that threw before this point leaves it in place to resume from.
   try { closeCheckpoint(_ckpt, { complete: true }); } catch (_) {}
+  // Finding Provenance (M0/M1) — attaches `finding.findingProvenance`.
+  //
+  // Placed HERE, not immediately after the SCA/multi-sink correlation blocks
+  // where the plan first put it, for the same reason `annotateRelevance` below
+  // runs this late: several post-scan artifact emitters between those blocks
+  // and this point still PUSH findings (`runApiContractScan`, `runSbomDiff`,
+  // the cross-language chain passes). Annotating before them would have left
+  // every finding they produce with no `findingProvenance` at all, which is
+  // precisely the "absent field" state the coordinator's terminal-status
+  // guarantee exists to make unreachable. Running after `Object.freeze` above
+  // is safe and is in fact the point: the finding SET can no longer change, and
+  // a shallow freeze still permits annotating FIELDS on the individual finding
+  // objects. This annotator never appends or drops a finding.
+  if (provenance !== false) {
+   // Task 11 (PRD P0 scope): real origin resolution for scan.secrets and
+   // blameable scan.logicVulns findings. Both channels were previously
+   // stamped an unconditional not_available (see the backstop loop below) —
+   // not because computeStableId can't handle them (its ruleId() fallback
+   // chain already tolerates a missing f.ruleId), but because nobody
+   // backfilled a real per-pattern ruleId and nobody called
+   // annotateGitProvenance on these channels at all. scan.secrets findings
+   // set neither ruleId nor family nor parser, and every secret type shares
+   // the same fixed f.cwe ("CWE-798"), so without a per-pattern backfill
+   // every secret in a scan would collide onto ONE stableId.
+   //
+   // scan.logicVulns is not one detector's output — three of its ~9
+   // producers (license-policy:, deploy-platform:, stack-playbook:) use a
+   // FIXED PLACEHOLDER `line` (0 or 1), not a real diffable source location
+   // — they read scanRoot-level files (package.json, vercel.json, ...)
+   // directly rather than from the scanned fileContents. Routing those
+   // through git-blame-style resolution would fabricate a plausible-looking
+   // but meaningless commit attribution (e.g. "package.json line 1" blamed
+   // on whatever commit last touched that line, unrelated to the actual
+   // license/platform/stack finding). They are excluded by id prefix here
+   // and stay on the honest, PERMANENT not_available path in the backstop
+   // loop below — never routed through resolveOrigin. Declared here, OUTSIDE
+   // the _runAnnotator callback below, because the backstop loop (also
+   // outside that callback — see its own comment on why) needs
+   // `blameableLogic`/`syntheticLogic` too.
+   //
+   // `aSecrets`/`aLogic`'s ruleId backfill for the producers that exist by
+   // this point in the function already happened much earlier (right before
+   // the `skipAnnotators` guard opens — see that comment for why it CANNOT
+   // live here alone). `_slugify` is declared there and is in scope here too.
+   // What's re-applied below is only the SAME idempotent backfill
+   // (`if (!f.ruleId)`), now over the full, final `blameableLogic` — which by
+   // this point additionally includes logic-claims.js's late-pushed ingested
+   // claims, the one blameable producer the early pass could not see.
+   const SYNTHETIC_LOGIC_PREFIXES = ['license-policy:', 'deploy-platform:', 'stack-playbook:'];
+   const isSyntheticLogicFinding = (f) => typeof f?.id === 'string'
+     && SYNTHETIC_LOGIC_PREFIXES.some((p) => f.id.startsWith(p));
+   const blameableLogic = aLogic.filter((f) => !isSyntheticLogicFinding(f));
+   const syntheticLogic = aLogic.filter(isSyntheticLogicFinding);
+   for (const f of blameableLogic) {
+     if (!f.ruleId) f.ruleId = `logic:${_slugify(f.vuln)}`;
+   }
+   annotateStableIds(aSecrets);
+   annotateStableIds(blameableLogic);
+   await _runAnnotator("annotateGitProvenance", async () => {
+    // ONE deadline for the whole scan's provenance work, computed here and
+    // threaded into all five annotateGitProvenance calls below. Computed per call
+    // inside the coordinator, the effective scan-level budget was 2× the
+    // configured --provenance-timeout: the SAST pass got a fresh window and
+    // then the SCA pass got another one, so an operator asking for a 30s cap
+    // could wait 60s. The spec describes a single global deadline; this is
+    // where "global" has to be established, because this is the only scope
+    // that sees both passes.
+    const provenanceTimeoutMs = process.env.AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS
+      ? parseInt(process.env.AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS, 10) : undefined;
+    // Deterministic mode promises byte-identical SARIF run-to-run
+    // (posture/deterministic.js), and `observedAt` above is already frozen to
+    // honour that. But `findingProvenance.status` (complete/partial/
+    // budget_exhausted/...) is driven by THIS deadline, which was computed
+    // from a real `Date.now()` even under --deterministic — so two runs of
+    // the identical scan could cross a 60s budget at different points under
+    // machine contention (git subprocess calls slowed by CPU/IO pressure) and
+    // land different findings on `budget_exhausted` vs a resolved status,
+    // changing the emitted SARIF between runs. An explicit
+    // --provenance-timeout / AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS still wins
+    // (an operator asking for a tight budget gets it regardless of mode);
+    // absent that, deterministic mode gets a much larger fixed ceiling so
+    // resolution has room to finish under realistic load instead of a bound
+    // that's routinely crossed — see test/proof-corpus-lib.test.js's
+    // "produces byte-identical SARIF across two runs".
+    const DETERMINISTIC_PROVENANCE_TIMEOUT_MS = 300000; // 5 minutes
+    const provenanceDeadlineAt = Date.now()
+      + (Number.isFinite(provenanceTimeoutMs) && provenanceTimeoutMs > 0
+        ? provenanceTimeoutMs
+        : (isDeterministic() ? DETERMINISTIC_PROVENANCE_TIMEOUT_MS : PROVENANCE_DEFAULT_TIMEOUT_MS));
+    const provenanceCtx = {
+      scanRoot,
+      deadlineAt: provenanceDeadlineAt,
+      // CLI flags that set these land in Task 17; reading the env directly here
+      // mirrors AGENTIC_SECURITY_NO_GIT_HISTORY's existing pattern in this file.
+      disabled: process.env.AGENTIC_SECURITY_NO_PROVENANCE === '1',
+      scanId: process.env.AGENTIC_SECURITY_SCAN_ID || null,
+      // Frozen under --deterministic so SARIF (which now carries
+      // findingProvenance.firstObserved.observedAt — see report/index.js's
+      // toSARIF) stays byte-identical run-to-run, matching the exact
+      // convention posture/deterministic.js's makeDeterministic() already
+      // uses for meta.startedAt. This value predates that guarantee; it was
+      // invisible before findingProvenance reached any output format.
+      observedAt: isDeterministic() ? '1970-01-01T00:00:00.000Z' : new Date().toISOString(),
+      // FR-PROV-028 / "Evidence integrity": the cache key (coordinator.js's
+      // `makeCacheKey`) and `computeDigest`'s `rulesetVersion` binding both
+      // read this field, so it has to be the REAL effective ruleset version,
+      // not an env var operators essentially never set. `_effectiveRulesetVersion`
+      // (posture/ruleset-version.js's `effectiveVersion`) already resolves
+      // env override > pinned file > CURRENT_RULESET_VERSION (== the running
+      // scanner's own package version) — the same helper the checkpoint
+      // identity above (`_ckptIdentity.rulesetVersion`) already calls for an
+      // unrelated purpose. Computed ONCE here and shared via `provenanceCtx`,
+      // same precedent as `deadlineAt` and `providerEnrichments` below: it's
+      // cheap (an env read plus one small JSON file stat/read), but five
+      // recomputations across the five annotateGitProvenance calls buys
+      // nothing and risks a mid-scan pinned-file edit producing five
+      // different answers in one run.
+      rulesetVersion: (_effectiveRulesetVersion(scanRoot) || {}).version || null,
+      since: process.env.AGENTIC_SECURITY_PROVENANCE_SINCE || null,
+      timeoutMs: provenanceTimeoutMs,
+      mode: process.env.AGENTIC_SECURITY_PROVENANCE_MODE || 'standard',
+      // Fix-round item 2: ONE shared provider-enrichment counter for the
+      // whole scan, same precedent as the single `deadlineAt` above. Object
+      // identity (not the primitive value) is what makes the cap survive the
+      // `{ ...provenanceCtx, findingType: ... }` spreads used by four of the
+      // five annotateGitProvenance calls below — see coordinator.js's
+      // `providerEnrichments` comment for why a bare number would not work.
+      providerEnrichments: { remaining: MAX_PROVIDER_ENRICHMENTS_PER_SCAN },
+    };
+    await annotateGitProvenance(finalFindings, provenanceCtx);
+    // Direct dependencies only: a transitive dep's vulnerable version was never
+    // declared in this repository's manifests, so there is no commit here that
+    // introduced it and `resolveDirectSCAOrigin` would have nothing to walk.
+    //
+    // Keyed on `isDirect`, the same field the transitive-dedup block above
+    // uses. The plan's `!s.isTransitive` was a silent no-op: `isTransitive`
+    // exists on dependency COMPONENTS but was never carried onto the
+    // vulnerable_dep entries, so the negation was true for every entry and the
+    // filter excluded nothing. `isDirect` is now propagated at materialization.
+    const directDeps = (supplyChain || []).filter((s) => s && s.type === 'vulnerable_dep' && s.isDirect);
+    // `resolveDirectSCAOrigin`/`scaStableId` key on `filePath`; the vulnerable_dep
+    // entries built above carry the manifest path as `file` (report/index.js
+    // already reads `sc.filePath || sc.file` for the same reason). Backfill the
+    // alias rather than teaching the SCA resolver a second field name — without
+    // it every direct dependency resolves to `not_available: no-manifest-path`.
+    for (const s of directDeps) { if (!s.filePath && s.file) s.filePath = s.file; }
+    await annotateGitProvenance(directDeps, { ...provenanceCtx, findingType: 'sca' });
+    // M3 §3.2: transitive dependencies now get real origin resolution too,
+    // narrowing what was previously an unconditional not_available backstop
+    // to genuinely unresolvable cases (non-npm lockfiles, no candidate
+    // history) — see transitive-sca.js's own scope note.
+    const transitiveDeps = (supplyChain || []).filter((s) => s && s.type === 'vulnerable_dep' && !s.isDirect);
+    for (const s of transitiveDeps) { if (!s.filePath && s.file) s.filePath = s.file; }
+    await annotateGitProvenance(transitiveDeps, { ...provenanceCtx, findingType: 'sca-transitive' });
+    // Task 11 (PRD P0 scope): `aSecrets`/`blameableLogic` already have real
+    // stableIds backfilled above (outside this callback — see that comment).
+    // findingType 'secret'/'logic' is not consumed by any branch in
+    // coordinator.js's resolveOne (only 'sca'/'sca-transitive' select a
+    // different resolution strategy) — both fall through to the plain SAST
+    // path (file+line blame short-circuit, then origin-resolver.js). Passed
+    // anyway for clarity and future debugging; harmless today.
+    await annotateGitProvenance(aSecrets, { ...provenanceCtx, findingType: 'secret' });
+    await annotateGitProvenance(blameableLogic, { ...provenanceCtx, findingType: 'logic' });
+    // FR-PROV-013 — introduce/remediate/reintroduce events. Best-effort by
+    // design: the lifecycle store is a convenience ledger, and a failed write
+    // (read-only tree, lock contention) must never fail a scan, matching how
+    // every other provenance component degrades.
+    //
+    // Gated on `disabled` as well as on the `provenance` parameter, because
+    // those are two different opt-outs and only one of them was being honoured.
+    // updateLifecycle WRITES to disk; an operator who set
+    // AGENTIC_SECURITY_NO_PROVENANCE=1 has said the feature does nothing, and a
+    // disabled feature that still litters `.agentic-security/provenance/` is
+    // not disabled. (annotateGitProvenance handles `disabled` internally by
+    // stamping not_available, which is why it is still called above — every
+    // finding must keep a terminal status even with the feature off.)
+    //
+    // Gated on `scanRoot` too. Every path into updateLifecycle resolves the
+    // store through statePath(scanRoot, …), and statePath falls back to the
+    // PROCESS CWD when scanRoot is null — so a runFullScan called with no
+    // scanRoot (the in-process test/bench harnesses, predicate replay before
+    // its provenance:false brake, any embedder) wrote a lifecycle ledger into
+    // whatever directory the process happened to be in, keyed on that
+    // unrelated run's findings. That is how this repo's own
+    // scanner/.agentic-security/provenance/lifecycle.json accumulated 374
+    // stableIds and 3000+ spurious remediated/reintroduced events. No
+    // scanRoot means no project to keep a ledger for.
+    //
+    // `completeScan` is the other half, and it is a correctness gate rather
+    // than a hygiene one — see runFullScan's parameter comment and
+    // lifecycle.js's applyScan.
+    //
+    // TRUTHY IS NOT ENOUGH — it has to be a real directory. `resolveProjectRoot`
+    // honours a caller-supplied scanRoot only when it exists on disk AND is a
+    // directory; for anything else (a typo'd path, a `/tmp/...` a test never
+    // created, a file rather than a directory) it silently falls back to walking
+    // UP FROM THE PROCESS CWD for a project marker. So `agentic-security scan
+    // ./typo` run from inside a project writes THAT project's lifecycle ledger
+    // from a scan that never looked at it — and since such a scan finds nothing
+    // while still claiming `completeScan`, the remediation pass closes every
+    // open finding the real project had. Same corruption as the null-scanRoot
+    // case above, reached through a different door: found by tracing the writes
+    // that kept reappearing in this repo's own scanner/.agentic-security AFTER
+    // the null guard was added. All three remaining writers were
+    // truthy-but-nonexistent scanRoots.
+    //
+    // Narrow on purpose. Every other state write in such a scan lands in the
+    // same wrong place, which is a wider `state-dir.js` question; the lifecycle
+    // ledger is singled out here because it is the only one that turns the
+    // mistake into a destructive claim about findings it never saw.
+    let scanRootIsRealDir = false;
+    try { scanRootIsRealDir = !!scanRoot && fs.statSync(scanRoot).isDirectory(); } catch { scanRootIsRealDir = false; }
+    if (scanRootIsRealDir && !provenanceCtx.disabled) {
+      try {
+        await updateLifecycle(scanRoot, finalFindings, {
+          scanId: provenanceCtx.scanId, observedAt: provenanceCtx.observedAt,
+          completeScan,
+        });
+      } catch (_) { /* best-effort */ }
+    }
+   });
+   // Structural backstop for the terminal-status guarantee, for BOTH channels.
+   // Deliberately OUTSIDE the _runAnnotator callback above: _runAnnotator
+   // swallows whatever the callback throws, so anything that depends on the
+   // callback reaching its last line is a convention, not a guarantee. If
+   // annotateGitProvenance threw before its per-finding loop began
+   // (getRepoState blowing up on a corrupt repo, say), everything below the
+   // throw is skipped and every finding and supplyChain entry silently carries
+   // no findingProvenance at all — exactly the absent-field state the status
+   // enum exists to make unreachable. Enforced here so it holds structurally.
+   for (const f of finalFindings) {
+     if (f && typeof f === 'object' && !f.findingProvenance) {
+       f.findingProvenance = emptyProvenance(PROVENANCE_STATUS.ERROR, {
+         limitations: ['provenance annotator did not reach this finding'],
+       });
+     }
+   }
+   // The supply-chain half. report/index.js normalizes EVERY supplyChain entry
+   // into an SCA finding — not just the direct vulnerable_dep ones the resolver
+   // can speak to — and pipeline/finding-schema.js requires findingProvenance on
+   // every channel. Three distinct populations reach this loop and they are not
+   // the same statement, so they do not share a limitation string:
+   //
+   //  - transitive vulnerable_deps: resolved by resolveTransitiveSCAOrigin
+   //    above (M3 §3.2) — this branch is now reached only if that annotation
+   //    pass itself failed to stamp the entry.
+   //  - unpinned_dep / no_lockfile and friends: these describe the ABSENCE of a
+   //    declaration, so "which commit introduced this version" is not a question
+   //    that has an answer to defer.
+   //  - anything the annotator failed to reach, as above.
+   //
+   // The first two are honest `not_available` — that is exactly what the status
+   // is for. Only a genuine annotator failure is an `error`, which is why this
+   // loop distinguishes them rather than stamping one status for all three.
+   for (const sc of (supplyChain || [])) {
+     if (!sc || typeof sc !== 'object' || sc.findingProvenance) continue;
+     sc.findingProvenance = emptyProvenance(PROVENANCE_STATUS.NOT_AVAILABLE, {
+       limitations: [sc.type === 'vulnerable_dep'
+         ? 'transitive dependency origin resolution failed for this entry (annotator error)'
+         : `origin resolution does not apply to a ${sc.type || 'non-vulnerability'} supply-chain entry`],
+     });
+   }
+   // The OTHER two channels report/index.js normalizes into findings —
+   // `scan.secrets` and `scan.logicVulns`. The same argument that produced the
+   // supplyChain loop above applies verbatim: pipeline/finding-schema.js makes
+   // `findingProvenance` REQUIRED on every channel, and normalizeFindings emits
+   // a finding for each of these, so leaving them unstamped ships a
+   // schema-incomplete finding whose absent field is indistinguishable from
+   // "escaped annotation" — the exact condition the status enum exists to
+   // remove.
+   //
+   // Task 11 (PRD P0 scope): `aSecrets` and `blameableLogic` now go through
+   // REAL resolution above (real stableIds backfilled, real
+   // annotateGitProvenance calls made), so this loop no longer covers them
+   // wholesale — it is now a defensive catch-all for any entry the real call
+   // somehow didn't reach (same precedent as the supplyChain loop above), plus
+   // `syntheticLogic`, which can NEVER get real resolution by design (see the
+   // classification comment above `SYNTHETIC_LOGIC_PREFIXES`) and stays here
+   // permanently and honestly, not as a deferral.
+   for (const x of (syntheticLogic || [])) {
+     if (!x || typeof x !== 'object' || x.findingProvenance) continue;
+     x.findingProvenance = emptyProvenance(PROVENANCE_STATUS.NOT_AVAILABLE, {
+       limitations: ['this finding describes dependency/config/policy state, not a single source line a commit introduced -- origin resolution does not apply'],
+     });
+   }
+   for (const bucket of [aSecrets, blameableLogic]) {
+     for (const x of (bucket || [])) {
+       if (!x || typeof x !== 'object' || x.findingProvenance) continue;
+       x.findingProvenance = emptyProvenance(PROVENANCE_STATUS.NOT_AVAILABLE, {
+         limitations: ['origin resolution annotator did not reach this finding'],
+       });
+     }
+   }
+  }
   // Addition #2 — attack-surface completeness inventory (entry points → dispositions).
-  let _entrypointInventory = {}; try { _entrypointInventory = buildEntrypointInventory(fc, { routes: aR, findings: finalFindings }); } catch { _entrypointInventory = {}; }
+  // (_entrypointInventory is hoisted above the `skipAnnotators` guard — FR-PROV-029.)
+  try { _entrypointInventory = buildEntrypointInventory(fc, { routes: aR, findings: finalFindings }); } catch { _entrypointInventory = {}; }
   // R9 + R6 — relevance scoping. Runs HERE, after every finding has been
   // appended (multi-sink chains, cross-language chains) and after the
   // entry-point inventory exists, so no finding escapes annotation and the
@@ -10105,24 +10561,25 @@ function _deterministicFileTimings(timings) {
   });
   // Addition #3 — root-cause sweep: from confirmed findings, find sibling instances
   // detectors missed, with total-count accounting. Confirmed-only (cheap by default).
-  let _rootCauseSweep = null; try { _rootCauseSweep = sweepRootCauses(finalFindings, fc); } catch { _rootCauseSweep = null; }
+  // (_rootCauseSweep/_proofCoverage/_coverageLedger/_scanHealth are hoisted
+  // above the `skipAnnotators` guard — FR-PROV-029.)
+  try { _rootCauseSweep = sweepRootCauses(finalFindings, fc); } catch { _rootCauseSweep = null; }
   // PRD F7.2: publish what CANNOT be proven alongside what can. A proof RATE
   // computed over the provable subset makes a narrow subset look like strength;
   // the three-bucket split (provable / declined-on-purpose / not-yet-classified)
   // is the honest shape. Measured on the CVE corpus: 19% / 13% / 68%.
-  let _proofCoverage = null;
   try { _proofCoverage = proofCoverage([...finalFindings, ...aLogic]); } catch { _proofCoverage = null; }
   // FR-203: per-file/per-analyzer coverage ledger, computed from exactly
   // the signals FR-201 (_detectorErrors) and FR-202 (the _timeout:true
   // marker finding) already produce -- files actually scanned come from
   // fc's own keys (skipped-for-size/density files were never added to it).
   const _timedOutFiles = finalFindings.filter(f => f && f._timeout === true).map(f => f.file);
-  const _coverageLedger = computeCoverageLedger({ files: Object.keys(fc), detectorErrors: _detectorErrors, timedOutFiles: _timedOutFiles });
+  _coverageLedger = computeCoverageLedger({ files: Object.keys(fc), detectorErrors: _detectorErrors, timedOutFiles: _timedOutFiles });
   // FR-206 (assurance-hardening PRD, Milestone 0): additive scan-health
   // summary, computed from signals the engine already collects.
   // `analyzers` was `null` (see pipeline/scan-health.js's prior comment)
   // until FR-203's coverage ledger existed to compute it for real.
-  let _scanHealth = computeScanHealth({
+  _scanHealth = computeScanHealth({
     scanMeta: _scanMeta,
     annotatorErrors: _annotatorErrors,
     engineErrors: { cppDataflowParseErrors: _cppDataflowParseErrors.value },
@@ -10142,6 +10599,7 @@ function _deterministicFileTimings(timings) {
     calibration: calibrationFreshness(),
     compliance: _complianceReport ? { stale: _complianceReport.summary?.stale || 0 } : null,
   });
+  } // end if (!skipAnnotators) — FR-PROV-029
   return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,proofCoverage:_proofCoverage,kevCatalog:kevCatalogMeta(),routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,detectorErrors:_detectorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,privacyFramework:_privacyFramework,privacyIrBacked:_privacyIrBacked,privacyTaxonomyVersion:_privacyTaxonomyVersion,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary,scanHealth:_scanHealth,coverageLedger:_coverageLedger};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
@@ -10609,6 +11067,7 @@ export {
   classifyOrphans, classifyField, classifyEndpoint, shouldScan,
   _isFalsePositiveCredential, _detectSafeSinkShape,
   _loadCustomRules, _isCustomSuppressed, _isPathIgnored,
+  _snapshotSuppressionLog, _restoreSuppressionLog,
   scanIaC, IAC_PATTERNS, _isIaCFile, isCloudFormationTemplate,
   payloadsForFinding, buildProofObligation,
   DATA_CLASSES, SOURCE_PATTERNS, SINK_PATTERNS, SANITIZER_PATTERNS,