@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/engine.js

@@ -183,6 +183,10 @@ import { classifySecretCandidate as _entropyClassifySecret } from './sast/_secre
 // Phase 1 — precision-engineering posture modules.
 import { annotateConfidence, applyUnvalidatedPenalty } from './posture/confidence.js';
 import { backfillFindingDefaults } from './posture/finding-defaults.js';
+import { redirectTargetPinsOriginAt, redirectArgumentPinsOrigin } from './sast/redirect-target.js';
+import { responseReflectsRequestInputAt } from './sast/reflected-input.js';
+import { sendFileConfinedToRootAt } from './sast/send-file-root.js';
+import { insideFunctionBody } from './sast/init-scope.js';
 import { annotatePocs } from './posture/poc-generator.js';
 import { annotateExecutionProofs } from './posture/prove-findings.js';
 import { mineVulnHistory, annotateHistoricalRisk } from './posture/vuln-archaeology.js';
@@ -211,12 +215,15 @@ import { annotateNarration } from './posture/flow-narration.js';
 import { applyPathConstraints } from './posture/path-predicates.js';
 // Phase 3 (Sentinel-parity Layer 1 + 2) — IR + interprocedural taint engine.
 import { buildProjectIR, buildProjectIRAsync } from './ir/index.js';
+import { openIrCache } from './dataflow/ir-cache.js';
 import _v8 from 'node:v8';
 import _vm from 'node:vm';
 import { createStringMemo } from './util/string-memo.js';
 import { collectIrStats, irStatsTarget, writeIrStats } from './ir/ir-stats.js';
 import { runDeepAnalysis } from './dataflow/index.js';
 import { buildLineageGraph } from './lineage/index.js';
+import { buildLineageGraphOwned, resolveLineageDeadlineMs } from './lineage/owned-build.js';
+import { completionOfGraph, summarizeForHealth as summarizeCompletionForHealth } from './lineage/completion.js';
 // v3 next-gen — Pillars 1, 4, 5, 6, 8, 9.
 import { annotateCloneClusters, findCloneOutliers } from './posture/semantic-clone.js';
 import { annotateAiProvenance } from './posture/ai-code-fingerprint.js';
@@ -1719,12 +1726,43 @@ export function dropGuardedFindings(findings, fileContents, onDrop = null) {
     const dropped = (kind) => { if (onDrop) onDrop(f, { kind, line, evidence: ctx._guardEvidence || null }); return false; };
     if (cwe === 'CWE-918' && _hasSsrfHostGuard(ctx)) return dropped('ssrf-host-guard');
     if (cwe === 'CWE-22' && _hasPathGuard(ctx)) return dropped('path-containment-guard');
+    if (cwe === 'CWE-22' && sendFileConfinedToRootAt(lines, line) === true) return dropped('send-file-root-confined');
     if (cwe === 'CWE-601' && _hasRedirectGuard(ctx)) return dropped('redirect-target-guard');
+    if (cwe === 'CWE-601' && redirectTargetPinsOriginAt(lines, line) === true) return dropped('redirect-origin-pinned');
     if (isXss && _hasXssOutputEncoding(ctx)) return dropped('xss-output-encoding');
     return true;
   });
 }
 
+// Identifiers a sink call's argument text actually READS as variables. Two things in the raw text are not
+// variable reads and used to be counted as such, which let an unrelated source variable of the same name
+// "reach" the sink: (1) words inside string literals ('Viewing user ' + ...), and (2) property names after
+// a dot (req.user.name reads `req`, not a local called `user` or `name`). Template substitutions
+// (`${x}`) stay, since they are code. Spread (`...x`) is a read of x and stays.
+function _usedIdentifiers(args){
+  const t=String(args);let code='';
+  for(let i=0;i<t.length;i++){
+    const c=t[i];
+    if(c==='"'||c==="'"){const q=c;i++;while(i<t.length&&t[i]!==q){if(t[i]==='\\')i++;i++;}code+=' ';}
+    else if(c==='`'){
+      i++;
+      while(i<t.length&&t[i]!=='`'){
+        if(t[i]==='\\'){i+=2;continue;}
+        if(t[i]==='$'&&t[i+1]==='{'){let d=1;i+=2;code+=' ';while(i<t.length&&d>0){if(t[i]==='{')d++;else if(t[i]==='}'){d--;if(d===0)break;}code+=t[i];i++;}i++;continue;}
+        i++;
+      }
+      code+=' ';
+    } else code+=c;
+  }
+  const out=new Set();
+  const re=/\b[a-zA-Z_]\w*\b/g;let m;
+  while((m=re.exec(code))){
+    let j=m.index-1;while(j>=0&&/\s/.test(code[j]))j--;
+    if(j>=0&&code[j]==='.'&&!(j>0&&code[j-1]==='.'))continue; // property name, not a variable read
+    out.add(m[0]);
+  }
+  return [...out];
+}
 function _detectSafeSinkShape(vuln, args, ctx){
   // 1.1: Reflected XSS / SSRF / Path Traversal / Open Redirect / Code Injection
   // sinks with empty or whitespace-only args cannot reflect user input — skip
@@ -1764,7 +1802,10 @@ function _detectSafeSinkShape(vuln, args, ctx){
   if(/Open Redirect/.test(vuln)) {
     // Static redirect targets (env var or string literal) are not user-controlled
     if (/^\s*process\.env\b/.test(args)) return 'static-redirect-target';
-    if (/^\s*['"`]/.test(args)) return 'static-redirect-target';
+    // A literal that fixes the origin ('/user/' + id) cannot be steered off-origin by the
+    // appended part; a literal that does not ('/' + x, '//' + x, '' + x) can, so the mere
+    // presence of a leading quote is not evidence of a static target.
+    if (/^\s*['"`]/.test(args) && redirectArgumentPinsOrigin(args)) return 'static-redirect-target';
   }
   if(/IDOR/.test(vuln)) {
     if (_IDOR_OWNERSHIP_RE.test(args)) return 'ownership-clause';
@@ -1917,11 +1958,11 @@ function performRegexAnalysis(fp,raw){if(_INTENTIONAL_VULN_PATH_RE.test(fp.repla
     const line=lineAt(cleaned,m.index);const lt=lines[line-1]||"";
     // FP-7: per-pattern surrounding-context gate — required call must appear in nearby lines
     if(sp.contextRe){const surround=lines.slice(Math.max(0,line-5),Math.min(lines.length,line+2)).join("\n");if(!sp.contextRe.test(surround))continue;}
-    const af=raw.substring(m.index,Math.min(raw.length,m.index+500));const am=af.match(/\(((?:[^()]|\([^()]*\)){0,400})\)/);const args=am?am[1]:"";const uv=[...new Set((args.match(/\b[a-zA-Z_]\w*\b/g)||[]).filter(v=>!["true","false","null","undefined","const","let","var","function","return","if","else","new","this","async","await","typeof","instanceof","void"].includes(v)&&v.length>1))];const safeShape=_detectSafeSinkShape(sp.vuln,args,{lines,line});sinks.push({type:sp.type,severity:sp.severity,vuln:sp.vuln,cwe:sp.cwe,stride:sp.stride,line,file:fp,snippet:lt.trim(),usedVars:uv,args:args.trim(),safeShape});}}
+    const af=raw.substring(m.index,Math.min(raw.length,m.index+500));const am=af.match(/\(((?:[^()]|\([^()]*\)){0,400})\)/);const args=am?am[1]:"";const uv=_usedIdentifiers(args).filter(v=>!["true","false","null","undefined","const","let","var","function","return","if","else","new","this","async","await","typeof","instanceof","void"].includes(v)&&v.length>1);const safeShape=_detectSafeSinkShape(sp.vuln,args,{lines,line});sinks.push({type:sp.type,severity:sp.severity,vuln:sp.vuln,cwe:sp.cwe,stride:sp.stride,line,file:fp,snippet:lt.trim(),usedVars:uv,args:args.trim(),safeShape});}}
   for(const sp of SANITIZER_PATTERNS){const re=new RegExp(sp.regex.source,sp.regex.flags);let m;while((m=re.exec(cleaned))){const line=lineAt(cleaned,m.index);const lt=lines[line-1]||"";const am=lt.match(/(?:const|let|var|)\s*(\w+)\s*=/)||lt.match(/(\w+)\s*=/);sanitizers.push({type:sp.type,line,file:fp,snippet:lt.trim(),outputVar:am?am[1]:null});}}
   const tv=new Map();for(const src of sources)if(src.variable)tv.set(src.variable,{source:src,path:[{type:"source",label:"Input: "+src.label,line:src.line,snippet:src.snippet}],sanitized:false,sanitizerType:null});
   for(let i=0;i<lines.length;i++){const lt=lines[i];const am=lt.match(/\b(?:const|let|var)\s+(\w+)(?:\s*:[^=]+?)?\s*=\s*(.+)/)||lt.match(/(?:const|let|var|)\s*(\w+)\s*=(?!=)\s*(.+)/);if(!am)continue;const[,dv,rhs]=am;if(tv.has(dv))continue;for(const[tn,ti]of tv){if(!new RegExp(`\\b${tn}\\b`).test(rhs))continue;let san=false,st=null;for(const s of sanitizers)if(s.line===i+1){san=true;st=s.type;break;}if(!san)for(const sp of SANITIZER_PATTERNS)if(new RegExp(sp.regex.source,sp.regex.flags).test(rhs)){san=true;st=sp.type;break;}tv.set(dv,{source:ti.source,path:[...ti.path,{type:san?"sanitizer":"propagation",label:san?`${st} on ${dv}`:`Assigned to "${dv}"`,line:i+1,snippet:lt.trim(),sanitized:san,sanitizerType:st}],sanitized:san,sanitizerType:st});break;}}
-  for(const sink of sinks){const safeShapeDowngrade=sink.safeShape?{isSan:true,sanType:sink.safeShape}:null;for(const src of sources){const sv=src.variable;let reached=false,pp=[],isSan=false,st=null;if(sv&&sink.usedVars.includes(sv)){const ti=tv.get(sv);if(ti){reached=true;pp=ti.path;isSan=!!ti.sanitized;st=ti.sanitizerType;}}if(!reached)for(const uv of sink.usedVars)if(tv.has(uv)){const ti=tv.get(uv);if(ti.source===src||ti.source.label.includes(src.label)){reached=true;pp=ti.path;isSan=!!ti.sanitized;st=ti.sanitizerType;break;}}if(!reached&&sv&&sink.line>=src.line&&sink.line-src.line<200&&((sink.args&&new RegExp(`\\b${sv}\\b`).test(sink.args))||lines.slice(Math.max(0,sink.line-10),sink.line+5).some(l=>{const re=new RegExp(`\\b${sv}\\b`);if(!re.test(l))return false;/* skip re-declarations: different binding, not a use */if(new RegExp(`\\b(?:const|let|var|function|def)\\s+${sv}\\b`).test(l))return false;return true;}))){reached=true;pp=[{type:"source",label:"Input: "+src.label,line:src.line,snippet:src.snippet}];
+  for(const sink of sinks){const safeShapeDowngrade=sink.safeShape?{isSan:true,sanType:sink.safeShape}:null;for(const src of sources){const sv=src.variable;let reached=false,pp=[],isSan=false,st=null;if(sv&&sink.usedVars.includes(sv)){const ti=tv.get(sv);if(ti){reached=true;pp=ti.path;isSan=!!ti.sanitized;st=ti.sanitizerType;}}if(!reached)for(const uv of sink.usedVars)if(tv.has(uv)){const ti=tv.get(uv);if(ti.source===src||ti.source.label.includes(src.label)){reached=true;pp=ti.path;isSan=!!ti.sanitized;st=ti.sanitizerType;break;}}if(!reached&&sv&&sink.line>=src.line&&sink.line-src.line<200&&((sink.args&&sink.usedVars.includes(sv))||lines.slice(Math.max(0,sink.line-10),sink.line+5).some(l=>{if(!_usedIdentifiers(l).includes(sv))return false;/* skip re-declarations: different binding, not a use */if(new RegExp(`\\b(?:const|let|var|function|def)\\s+${sv}\\b`).test(l))return false;return true;}))){reached=true;pp=[{type:"source",label:"Input: "+src.label,line:src.line,snippet:src.snippet}];
 // FP-3: only credit a sanitizer here if it has a captured outputVar AND that var
 // is what reaches the sink. A bare `escape(s);` (return discarded) does NOT count.
 for(const san of sanitizers){
@@ -2053,6 +2094,9 @@ const STRUCTURAL_VULN_PATTERNS=[
   // ── XSS / Output Encoding ─────────────────────────────────────────────────
   {regex:/res\s*\.\s*(?:send|write|end)\s*\([^;)]*(?:req\.|\.body\.|\.query\.|\.params\.)[^;)]{0,200}\)/g,
    type:"HTTP Response",vuln:"Reflected XSS (User Input in Response)",severity:"high",cwe:"CWE-79",stride:"Tampering",
+   // The call text mentions `req.`, which also carries session, user and app state. Fire only when the
+   // arguments reflect raw request INPUT (body/query/params/headers/...) that is not inside an HTML escaper.
+   predicate:(_m,ctx)=>{const r=responseReflectsRequestInputAt(ctx.lines,ctx.line);return r===false?{fire:false,reason:'no-raw-request-input'}:{fire:true};},
    fix:"Encode all user-supplied data with escapeHtml() before sending in responses"},
   {regex:/bypassSecurityTrust(?:Html|Script|Style|Url|ResourceUrl)\s*\(/g,
    type:"Angular Trust Bypass",vuln:"Angular DomSanitizer Bypass (XSS)",severity:"critical",cwe:"CWE-79",stride:"Tampering",
@@ -2290,6 +2334,9 @@ const STRUCTURAL_VULN_PATTERNS=[
   // ── #25: Synchronous blocking I/O in server context (DoS) ───────────────────
   {regex:/\b(?:fs\.readFileSync|fs\.writeFileSync|fs\.appendFileSync|fs\.readdirSync|fs\.statSync|fs\.existsSync|crypto\.pbkdf2Sync)\s*\(/g,
    type:"Blocking I/O",vuln:"Synchronous Blocking I/O (DoS Risk in Server Context)",severity:"medium",cwe:"CWE-400",stride:"Denial of Service",appliesTo:["server"],
+   // Only a blocking call made while serving stalls other work. At module/initialisation level (reading a TLS
+   // key or config once at startup) it delays startup once; nothing is waiting on the event loop yet.
+   predicate:(_m,ctx)=>ctx.haystack&&Number.isInteger(ctx.index)&&!insideFunctionBody(ctx.haystack,ctx.index)?{fire:false,reason:'module-init-scope'}:{fire:true},
    fix:"Replace with async equivalents: fs.promises.readFile(), fs.promises.stat(), util.promisify(crypto.pbkdf2)()"},
   // ── #26: Body parser without size limit (DoS — large payload / Billion Laughs) ─
   {regex:/(?:app|router)\s*\.\s*use\s*\(\s*express\s*\.\s*(?:json|urlencoded)\s*\(\s*\)\s*\)/g,
@@ -2522,7 +2569,7 @@ function scanStructuralVulns(fp, raw, _suppOut) {
       // FP-8: per-pattern predicate gate. If `predicate` returns {fire:false},
       // the finding is suppressed (and logged for --include-suppressed).
       if (typeof pat.predicate === 'function') {
-        const verdict = pat.predicate(m[0], { file: fp, line, snippet, lines, raw, cleanedNoise });
+        const verdict = pat.predicate(m[0], { file: fp, line, snippet, lines, raw, cleanedNoise, haystack, index: m.index });
         if (verdict && !verdict.fire) {
           _supp.push({vuln:pat.vuln, file:fp, line, snippet, reason:'predicate-pass:'+(verdict.reason||'ok')});
           continue;
@@ -2844,6 +2891,10 @@ function _pragmaSuppresses(pragma, f){
 // `line` property at all (the line survives only inside the id string, e.g.
 // `struct:app.js:22:Mass_Assignment`), so a false positive from one of those
 // cannot be silenced by a pragma and has to be fixed at the source instead.
+// UPDATE: `backfillFindingDefaults` now sets `line` from `sink.line` (then `source.line`) when a
+// detector left it off, so the line-less population is dependency and file-level findings. This
+// function already read `f.sink?.line`, so the backfill mostly makes the schema's `line` true rather
+// than newly enabling suppression.
 //
 // A file-scoped fallback was considered and REJECTED. Widening a line pragma to
 // a whole file would silently suppress findings the author never looked at, and
@@ -9464,7 +9515,15 @@ function _deterministicFileTimings(timings) {
   // import) for projects that contain no Java. `runFullScan` is already async,
   // so the await costs nothing structurally.
   const _hasJava = Object.keys(fc || {}).some(f => /\.java$/i.test(f));
-  const _buildIR = async () => (_hasJava ? await buildProjectIRAsync(fc) : buildProjectIR(fc));
+  // DAG-05: with the cross-scan cache on, an unchanged JavaScript/TypeScript file is read back from the IR cache
+  // instead of parsed again (dataflow/ir-cache.js; the content is the same, only the cost differs).
+  const _buildIR = async () => {
+    let irCache = null;
+    if (process.env.AGENTIC_SECURITY_INCREMENTAL === '1' && scanRoot) {
+      try { irCache = openIrCache(scanRoot); } catch { irCache = null; }
+    }
+    return _hasJava ? await buildProjectIRAsync(fc, { irCache }) : buildProjectIR(fc, { irCache });
+  };
   const _irStatsTarget = irStatsTarget();
   if (_irStatsTarget) {
     try {
@@ -9503,6 +9562,7 @@ function _deterministicFileTimings(timings) {
   let _deepCallGraph = null;
   let _deepFailure = null;
   let _deepIncomplete = null;
+  let _deepIncremental = null; // DAG-05 R05.7: cache provenance of the deep pass, when AGENTIC_SECURITY_INCREMENTAL=1
   if (_deepEnabled) {
     const budgetMs = parseInt(process.env.AGENTIC_SECURITY_DEEP_TIMEOUT_MS || '300000', 10);
     const t0 = Date.now();
@@ -9547,6 +9607,10 @@ function _deterministicFileTimings(timings) {
         });
       }
       if (Array.isArray(irFindings.analysisIncomplete) && irFindings.analysisIncomplete.length) _deepIncomplete = irFindings.analysisIncomplete;
+      if (irFindings._incrementalStats) {
+        const st = irFindings._incrementalStats;
+        _deepIncremental = { mode: st.mode, reason: st.reason, priorGeneration: st.priorGeneration, provenance: st.provenance, invalidation: st.invalidation, files: st.files, persisted: st.persisted && { committed: st.persisted.committed, error: st.persisted.error }, completion: st.completion };
+      }
       for (const f of irFindings) {
         f.unvalidated = true;
         f.validator_verdict = 'unvalidated';
@@ -9577,6 +9641,21 @@ function _deterministicFileTimings(timings) {
   // the finding-based notice above does not: deep mode never explicitly
   // requested at all (the common default-unset-in-CI case), which previously
   // produced no signal of any kind that assurance had quietly narrowed.
+  // DAG-05: when the cache was asked for, say what it did for this scan. Languages whose analyzers keep
+  // no cross-scan state (Nix: there is no taint IR to key a cache on) are analysed in full every time and named.
+  if (process.env.AGENTIC_SECURITY_INCREMENTAL === '1') {
+    const noHook = Object.keys(fc).some((f) => /\.nix$/i.test(f)) ? ['nix'] : [];
+    if (!_deepIncremental) {
+      _deepIncremental = { mode: 'cold', reason: _deepEnabled ? 'the deep pass recorded no incremental state' : 'deep analysis did not run, so the cross-scan cache is not used' };
+    }
+    if (noHook.length) {
+      _deepIncremental = {
+        ..._deepIncremental, languagesWithoutIncrementalHook: noHook,
+        languages: Object.fromEntries(noHook.map((l) => [l, { incremental: false, mode: 'cold', reason: 'its analysers keep no cross-scan state and run in full on every scan' }])),
+        note: `${noHook.join(', ')} analysers keep no cross-scan state and run in full on every scan`,
+      };
+    }
+  }
   const _deepStatus = {
     requested: _deepRequested,
     enabled: _deepEnabled,
@@ -9590,6 +9669,8 @@ function _deterministicFileTimings(timings) {
     failure: _deepFailure,
     // E2-05: where the deep analysis stopped short (budget, deadline, function limit, a thrown analysis). Present only when something did.
     ...(_deepIncomplete ? { incomplete: _deepIncomplete } : {}),
+    // DAG-05 R05.7: which facts were reused from the cache and which were analysed afresh, and why a run was cold.
+    ...(_deepIncremental ? { incremental: _deepIncremental } : {}),
   };
   // Sub-project E, increment 5 — Data Flow Explorer lineage graph.
   // DELIBERATELY INDEPENDENT of AGENTIC_SECURITY_DEEP/_deepEnabled above
@@ -9621,10 +9702,11 @@ function _deterministicFileTimings(timings) {
       // Reuses the SAME _sharedIR memo _deepEnabled's own block above uses —
       // if deep mode already built it, this is free; if not, this is what
       // first triggers the build (the whole reason this gate is independent).
-      const { perFile, callGraph } = _sharedIR || (_sharedIR = await _buildIR());
+      const _lineageDeadlineMs = resolveLineageDeadlineMs();
+      const { perFile, callGraph } = _lineageDeadlineMs ? {} : (_sharedIR || (_sharedIR = await _buildIR()));
       const _lineageT0 = Date.now();
       setProgress({ phase: 'Lineage graph', current: 0, total: 0, file: `starting (budget ${Math.round(_lineageBudgetMs / 1000)}s)` });
-      const _lr = buildLineageGraph(callGraph, {
+      const _lineageOpts = {
         // Live per-function progress from the field-identity driver's own
         // single pass over every function (src/lineage/driver.js).
         onProgress: (p) => setProgress({
@@ -9650,9 +9732,32 @@ function _deterministicFileTimings(timings) {
         deterministic: isDeterministic(),
         perFile,
         fileContents,
-      });
+      };
+      // DAG-07 R07.7: with AGENTIC_SECURITY_LINEAGE_DEADLINE_MS set, the build runs in an
+      // owned worker with a watchdog. Unset: the in-process call, exactly as before.
+      let _lr = _lineageDeadlineMs
+        ? await buildLineageGraphOwned(fileContents, { ..._lineageOpts, onProgress: undefined, perFile: undefined, deadlineMs: _lineageDeadlineMs }).done
+        : buildLineageGraph(callGraph, _lineageOpts);
+      // The worker entry is a separate file that the single-file bundle does not ship.
+      // When the worker cannot start, fall back to the in-process build with the
+      // cooperative deadline (no watchdog for a non-polling worker, but the analysis
+      // still stops and reports `cancelled`); never fail the build over it.
+      if (_lineageDeadlineMs && _lr.status === 'failed' && /Cannot find module|ERR_MODULE_NOT_FOUND|owned-worker/i.test(String(_lr.failure || ''))) {
+        // The deadline branch skipped the shared IR (the worker rebuilds its own); build it now.
+        const _ir = _sharedIR || (_sharedIR = await _buildIR());
+        _lr = buildLineageGraph(_ir.callGraph, { ..._lineageOpts, perFile: _ir.perFile, deadline: Date.now() + _lineageDeadlineMs });
+      }
+      if (_lr.terminatedByWatchdog) _lineageStatus.failure = _lr.failure;
       if (_lr.status === 'complete') {
         _lineageGraph = _lr.graph;
+        // DAG-07 R07.2: a graph built from a field analysis that stopped
+        // early must reach scan health, not only the graph body.
+        const _ac = _lr.graph?.coverage?.analysisCompletion;
+        if (_ac && _ac.status !== 'complete') { _lineageStatus.incomplete = _ac.incomplete; _lineageStatus.degraded = _ac.degraded; }
+        // R07.2: the whole envelope (cancelled, construction limits, seeding
+        // limits and zero-flow results included), not only the iteration
+        // and degraded-context lists above.
+        { const _env = completionOfGraph(_lr.graph); if (_env.status !== 'complete') _lineageStatus.completion = summarizeCompletionForHealth(_env); }
         if (_lr.elapsedMs > _lineageBudgetMs) {
           // Same "measured, not truly interrupted" disclosure _deepEnabled's
           // own elapsed > budgetMs branch already makes for IR-taint — see

package/src/graph/CLAUDE.md

@@ -0,0 +1,31 @@
+# scanner/src/graph/
+
+Typed, read-only graph views and identity crosswalks (DAG-06). A lens over the
+graph layers that already exist; it replaces none of them and changes none of
+their schemas, exports or validators.
+
+| Module | Responsibility |
+|---|---|
+| `refs.js` | Reference format `{v, graphKind, repository, graphDigest, entityKind, localId}`, `refKey`/`parseRef`, `GraphViewError` codes, canonical digest |
+| `relations.js` | Relation kinds (data_flow, control_dependence, calls, returns, dependency, declaration, observation, artifact_derivation), edge origins (code, derived, schema, declared, observed), the traversal filter |
+| `view.js` | `IndexedGraphView` (the view contract) and the adjacency index cache keyed by graph kind + digest + adapter version |
+| `adapters/` | `provenance` (PathStore pnode/pedge), `dataflow` (DataFlowGraph v1), `semantic` (SemanticGraph v1), `artifact` (artifact provenance graph), `crossrepo` (CrossRepoLink records, findings) |
+| `registry.js` | Registered views; rejects dangling refs, incompatible adapter versions, same-identity-different-content, ambiguous bare local ids |
+| `crosswalk.js` | Versioned, evidence-bearing mappings; cardinality is explicit; cross-repository `identity` mappings are refused |
+| `crosswalk-builders.js` | finding to call site to witnesses to flow; projected node to underlying sites |
+| `observation.js` | Attributes a runtime observation to a projected node's sites without copying it onto every site |
+
+## Rules
+
+- **Read-only, pure, no network.** Adapters never mutate their source graph;
+  `reconstruct()` returns the original object. `path-store.js` is duck-typed and
+  never imported; no analysis engine is imported anywhere here.
+- **A local id is never a key.** Every index and mapping is keyed by the full
+  reference (kind, repository, digest, entity kind, local id).
+- **Two axes.** A query filter chooses relations AND origins. The default
+  traverses `code`, `derived` and `schema` edges only; a `declared` cross-repo
+  link or an `observed` edge is walked only when the caller asks for that origin.
+- **Coarsening is stated.** A mapping with several targets is `one-to-many`
+  with `coarsens` and `unknowns`; nothing is attributed to "every" target.
+- **Versions.** Adapter versions and `CROSSWALK_VERSION` are semver; the registry
+  accepts only supported majors.

package/src/graph/adapters/artifact.js

@@ -0,0 +1,81 @@
+//
+// adapters/artifact.js: read-only view over the artifact provenance graph
+// (artifact/provenance-graph.js: commit -> build -> OCI digest -> SBOM
+// component -> finding, plus an operator-declared deployment).
+//
+// The artifact graph has no repository identity of its own, so the caller names
+// it (`repository`: the image repository or the source repository the artifact
+// was built from). The graph digest is a canonical hash of the graph body.
+//
+// Relations: commit->build, build->digest and digest->deployment are
+// `artifact_derivation`; digest->component and component->finding are
+// `dependency`. An operator-declared deployment edge has origin `declared`; an
+// edge with evidence 'none' (a commit that is not known) is kept, carries an
+// `unknowns` entry, and has grade 'none'.
+//
+// The generator can list the same SBOM component or finding twice (an OS and an
+// application package with one purl). Byte-identical duplicates are collapsed
+// in the view and counted in metadata; duplicates that DIFFER are rejected,
+// because choosing one would be a silent merge. `reconstruct()` returns the
+// original graph, duplicates included.
+
+import { digestOf, GraphViewError, canonicalJson } from '../refs.js';
+import { IndexedGraphView, local } from '../view.js';
+
+export const ARTIFACT_ADAPTER_VERSION = '1.0.0';
+
+function relationFor(fromKind, toKind) {
+  if (toKind === 'sbomComponent' || toKind === 'finding') return 'dependency';
+  return 'artifact_derivation';
+}
+
+export function artifactView(graph, opts) {
+  if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+    throw new TypeError('artifactView requires a graph with nodes[] and edges[]');
+  }
+  const graphDigest = digestOf(graph);
+  const byId = new Map();
+  let duplicateNodes = 0;
+  for (const n of graph.nodes) {
+    const prev = byId.get(n.id);
+    if (prev) {
+      if (canonicalJson(prev) !== canonicalJson(n)) throw new GraphViewError('DUPLICATE_ID', `artifact graph has two different nodes with id ${n.id}`, { id: n.id });
+      duplicateNodes += 1;
+    } else byId.set(n.id, n);
+  }
+  const nodes = [...byId.values()].map((n) => ({ entityKind: n.kind, localId: n.id, native: n, summary: { kind: n.kind } }));
+  const seenEdges = new Map();
+  let duplicateEdges = 0;
+  const edges = [];
+  for (const e of graph.edges) {
+    const id = `agedge:${e.from}->${e.to}`;
+    const prev = seenEdges.get(id);
+    if (prev) {
+      if (canonicalJson(prev) !== canonicalJson(e)) throw new GraphViewError('DUPLICATE_ID', `artifact graph has two different edges ${e.from} -> ${e.to}`, { id });
+      duplicateEdges += 1;
+      continue;
+    }
+    seenEdges.set(id, e);
+    const from = byId.get(e.from);
+    const to = byId.get(e.to);
+    if (!from || !to) throw new GraphViewError('DANGLING_REF', `artifact edge ${e.from} -> ${e.to} points at a node that is not in the graph`, { id });
+    const declared = e.evidence === 'operator-declared' || to.kind === 'deployment';
+    const none = e.evidence === 'none';
+    edges.push({
+      id, relation: relationFor(from.kind, to.kind), origin: declared ? 'declared' : 'derived',
+      from: local(from.kind, from.id), to: local(to.kind, to.id),
+      evidence: { grade: e.evidence ?? 'none', source: 'artifact-provenance-graph' },
+      unknowns: none ? [{ kind: 'unlinked', reason: 'no evidence links these two nodes' }] : (e.digestMatches === false ? [{ kind: 'digest-mismatch', reason: 'declared digest differs from the scanned artifact' }] : []),
+      attrs: e.digestMatches === undefined ? {} : { digestMatches: e.digestMatches }, native: e,
+    });
+  }
+  const unlinked = edges.filter((e) => e.unknowns.some((u) => u.kind === 'unlinked')).length;
+  const reasons = unlinked ? [`unlinked-edges:${unlinked}`] : [];
+  return new IndexedGraphView({
+    graphKind: 'artifact', adapterVersion: ARTIFACT_ADAPTER_VERSION, repository: opts?.repository, graphDigest,
+    metadata: { nodes: graph.nodes.length, edges: graph.edges.length, duplicateNodes, duplicateEdges },
+    completion: { status: reasons.length ? 'partial' : 'complete', reasons, coverage: null },
+    nodes, edges,
+    reconstruct: () => graph,
+  });
+}

package/src/graph/adapters/crossrepo.js

@@ -0,0 +1,75 @@
+//
+// adapters/crossrepo.js: read-only view over CrossRepoLink records
+// (lineage/cross-repo-link.js), plus a small findings view.
+//
+// A cross-repository link is an operator DECLARATION. In this view it is an
+// edge with origin `declared` and evidence grade `declared`, so the default
+// query filter (code-derived and derived edges only) never walks it as if it
+// were a code-derived data flow, and it can never be mistaken for observed
+// telemetry (R06.4). Its endpoints live in OTHER graphs, so they are foreign
+// references, each carrying that graph's repository and digest. An endpoint
+// that no registered graph can resolve is reported by the registry as
+// unresolved, not dropped.
+//
+// Both endpoints are `dataflow` node references: that is the only graph kind a
+// CrossRepoLink record binds today.
+
+import { validateCrossRepoLink } from '../../lineage/cross-repo-link.js';
+import { digestOf, makeRef, GraphViewError } from '../refs.js';
+import { IndexedGraphView, foreign } from '../view.js';
+
+export const CROSSREPO_ADAPTER_VERSION = '1.0.0';
+export const FINDINGS_ADAPTER_VERSION = '1.0.0';
+
+/**
+ * @param {object[]} links  CrossRepoLink records
+ * @param {{localRepository:string}} opts  the repository the `local` side belongs to
+ */
+export function crossRepoLinkView(links, opts) {
+  if (!Array.isArray(links)) throw new TypeError('crossRepoLinkView requires an array of links');
+  const localRepository = opts?.localRepository;
+  const nodes = [];
+  const edges = [];
+  for (const l of links) {
+    const v = validateCrossRepoLink(l);
+    if (!v.valid) throw new GraphViewError('INVALID_LINK', `cross-repo link ${l?.id ?? '?'} is invalid: ${v.errors[0].path} ${v.errors[0].message}`, { errors: v.errors });
+    nodes.push({ entityKind: 'link', localId: l.id, native: l, summary: { declaredBy: l.declaredBy, declaredAt: l.declaredAt } });
+    const from = makeRef({ graphKind: 'dataflow', repository: localRepository, graphDigest: l.local.graphDigest, entityKind: 'node', localId: l.local.nodeId });
+    const to = makeRef({ graphKind: 'dataflow', repository: l.remote.repository, graphDigest: l.remote.graphDigest, entityKind: 'node', localId: l.remote.nodeId });
+    edges.push({
+      id: l.id, relation: 'data_flow', origin: 'declared',
+      from: foreign(from), to: foreign(to),
+      evidence: { grade: 'declared', source: 'operator', declaredBy: l.declaredBy },
+      unknowns: [{ kind: 'not-observed', reason: 'a declared link is an assertion, not an observed data flow' }],
+      attrs: { rationale: l.rationale ?? null, provenance: l.provenance }, native: l,
+    });
+  }
+  return new IndexedGraphView({
+    graphKind: 'cross-repo-links', adapterVersion: CROSSREPO_ADAPTER_VERSION, repository: localRepository, graphDigest: digestOf(links),
+    metadata: { links: links.length },
+    completion: { status: 'complete', reasons: [], coverage: null },
+    nodes, edges, allowForeign: true,
+    reconstruct: () => links,
+  });
+}
+
+/**
+ * Findings as referenceable entities (no edges): the starting point of a
+ * finding -> call site -> witnesses -> flow join.
+ * @param {object[]} findings scanner findings; localId is `stableId` when present, else `id`
+ */
+export function findingsView(findings, opts) {
+  if (!Array.isArray(findings)) throw new TypeError('findingsView requires an array of findings');
+  const nodes = findings.map((f) => {
+    const id = f.stableId ?? f.id;
+    if (typeof id !== 'string' || !id) throw new GraphViewError('BAD_REF', 'every finding needs a stableId or id');
+    return { entityKind: 'finding', localId: id, native: f, summary: { file: f.file ?? null, line: Number.isInteger(f.line) ? f.line : null, severity: f.severity ?? null } };
+  });
+  return new IndexedGraphView({
+    graphKind: 'findings', adapterVersion: FINDINGS_ADAPTER_VERSION, repository: opts?.repository, graphDigest: digestOf(findings),
+    metadata: { findings: findings.length },
+    completion: { status: 'unknown', reasons: ['a finding list says nothing about what was not scanned'], coverage: null },
+    nodes, edges: [],
+    reconstruct: () => findings,
+  });
+}

package/src/graph/adapters/dataflow.js

@@ -0,0 +1,76 @@
+//
+// adapters/dataflow.js: read-only view over a DataFlowGraph v1 document (the
+// graph-builder output / signed export body).
+//
+// The graph keeps its own schema, validator and digest. This view:
+//   - uses the existing `computeGraphDigest` as the graph digest, so the
+//     digest in every reference equals the digest the export already signs;
+//   - exposes node, edge, flow, dataElement, evidence and transformation
+//     entities under their original ids;
+//   - maps `edge.provenance` to the origin axis (code -> code, schema ->
+//     schema, manual -> declared, runtime -> observed), so a runtime-observed
+//     or manually declared edge is never traversed as a code-derived one by a
+//     default query;
+//   - reports completion from `scanHealth`, `coverage` and `limitations`.
+//
+// Projected nodes are category-granular: one node can stand for many source
+// sites. That coarsening is not hidden here; it is recorded by crosswalks
+// (one-to-many) built in crosswalk-builders.js.
+
+import { computeGraphDigest } from '../../lineage/export-json.js';
+import { IndexedGraphView, local } from '../view.js';
+
+export const DATAFLOW_ADAPTER_VERSION = '1.0.0';
+
+const ORIGIN_OF_PROVENANCE = { code: 'code', schema: 'schema', manual: 'declared', runtime: 'observed' };
+
+const ENTITY_SECTIONS = [
+  ['node', 'nodes'], ['edge', 'edges'], ['flow', 'flows'],
+  ['dataElement', 'dataElements'], ['evidence', 'evidence'], ['transformation', 'transformations'],
+];
+
+/**
+ * @param {object} graph  DataFlowGraph v1 (e.g. buildDataFlowGraph(...).graph)
+ * @param {{repository?:string}} [opts]
+ */
+export function dataflowView(graph, opts = {}) {
+  if (!graph || typeof graph !== 'object' || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+    throw new TypeError('dataflowView requires a DataFlowGraph v1 object with nodes[] and edges[]');
+  }
+  const repository = opts.repository ?? graph.scope?.repository;
+  const graphDigest = computeGraphDigest(graph);
+
+  const nodes = [];
+  for (const [kind, section] of ENTITY_SECTIONS) {
+    for (const e of graph[section] || []) {
+      nodes.push({ entityKind: kind, localId: e.id, native: e, summary: kind === 'node' ? { kind: e.kind, subtype: e.subtype ?? null, label: e.label ?? null, coverageStatus: e.coverageStatus ?? null } : null });
+    }
+  }
+  const edges = graph.edges.map((e) => {
+    const unknowns = [];
+    if (e.protocol?.destinationResolution && e.protocol.destinationResolution !== 'literal') unknowns.push({ kind: 'destination-resolution', reason: e.protocol.destinationResolution });
+    if (e.coverageStatus && e.coverageStatus !== 'modeled') unknowns.push({ kind: 'coverage', reason: e.coverageStatus });
+    return {
+      id: e.id, relation: 'data_flow', origin: ORIGIN_OF_PROVENANCE[e.provenance] ?? 'schema',
+      from: local('node', e.from), to: local('node', e.to),
+      evidence: { grade: e.evidenceGrade ?? e.coverageStatus ?? 'none', source: 'dataflow-graph', evidenceRefs: e.evidenceRefs ?? [] },
+      unknowns, attrs: { provenance: e.provenance, relationship: e.relationship }, native: e,
+    };
+  });
+
+  const health = graph.scanHealth || {};
+  const reasons = [];
+  const status = health.status === 'complete' ? 'complete' : health.status ? 'partial' : 'unknown';
+  if (health.status && health.status !== 'complete') reasons.push(`scan-health:${health.status}${health.reason ? `:${health.reason}` : ''}`);
+  if (graph.coverage?.pathBudgetTruncation) reasons.push('path-budget-truncation');
+  if (health.analysisCompletion && health.analysisCompletion.status && health.analysisCompletion.status !== 'complete') reasons.push(`analysis-${health.analysisCompletion.status}`);
+  if ((graph.limitations || []).length) reasons.push(`limitations:${graph.limitations.length}`);
+
+  return new IndexedGraphView({
+    graphKind: 'dataflow', adapterVersion: DATAFLOW_ADAPTER_VERSION, repository, graphDigest,
+    metadata: { schemaVersion: graph.schemaVersion ?? null, graphId: graph.graphId ?? null, scope: graph.scope ?? null, counts: Object.fromEntries(ENTITY_SECTIONS.map(([k, s]) => [k, (graph[s] || []).length])) },
+    completion: { status: reasons.length && status === 'complete' ? 'partial' : status, reasons, coverage: graph.coverage ?? null },
+    nodes, edges,
+    reconstruct: () => graph,
+  });
+}

package/src/graph/adapters/provenance.js

@@ -0,0 +1,92 @@
+//
+// adapters/provenance.js: read-only view over a PathStore provenance DAG
+// (pnode / pedge). Duck-typed on the store's read API (`nodes()`, `edges()`,
+// `limitStatus()`, `diagnostics()`); it does not import path-store.js or any
+// analysis engine.
+//
+// Entities: `pnode` (a point in the DAG) and `pedge` (one witness: a join of an
+// in-half and an out-half at one program site). A pedge is BOTH an entity, so a
+// crosswalk can name it as a witness, and a relation edge between two pnodes.
+//
+// Relation choice, from the store's own fields (nothing is guessed):
+//   widenReason 'control-dependence'        -> control_dependence
+//   target path '<return>'                  -> returns
+//   crossScope (argument into a callee)     -> calls
+//   otherwise                               -> data_flow
+// Evidence grade reuses the flow-grade vocabulary: severed (loss reason),
+// ambiguous (correlation ambiguity), widened, implicit, else explicit.
+
+import { digestOf } from '../refs.js';
+import { IndexedGraphView, local } from '../view.js';
+
+export const PROVENANCE_ADAPTER_VERSION = '1.0.0';
+
+function relationOf(e, toNode) {
+  if ((e.widenReasons || []).includes('control-dependence')) return 'control_dependence';
+  if (toNode && toNode.path === '<return>') return 'returns';
+  if (e.crossScope) return 'calls';
+  return 'data_flow';
+}
+
+function gradeOf(e) {
+  if ((e.lossReasons || []).length) return 'severed';
+  if (e.ambiguousCorrelation) return 'ambiguous';
+  if ((e.widenReasons || []).includes('control-dependence')) return 'implicit';
+  if ((e.widenReasons || []).length) return 'widened';
+  return 'explicit';
+}
+
+/**
+ * @param {{nodes:()=>object[], edges:()=>object[], limitStatus?:()=>object, diagnostics?:()=>object}} store
+ * @param {{repository:string, completion?:object}} opts
+ *        `completion` may carry the driver's analysisCompletion record; it is
+ *        folded into the view's completion() so an unfinished analysis never
+ *        reads as complete.
+ */
+export function provenanceView(store, opts) {
+  if (!store || typeof store.nodes !== 'function' || typeof store.edges !== 'function') {
+    throw new TypeError('provenanceView requires a store with nodes() and edges()');
+  }
+  const repository = opts?.repository;
+  const pnodes = store.nodes();
+  const pedges = store.edges();
+  const byId = new Map(pnodes.map((n) => [n.id, n]));
+  const graphDigest = digestOf({ nodes: pnodes, edges: pedges });
+
+  const nodes = [
+    ...pnodes.map((n) => ({ entityKind: 'pnode', localId: n.id, native: n, summary: { kind: n.kind, scope: n.scope, path: n.path, truncated: !!n.truncated } })),
+    ...pedges.map((e) => ({ entityKind: 'pedge', localId: e.id, native: e, summary: { scope: e.scope, line: e.line ?? null, siteNodeId: e.siteNodeId ?? null, dataElementId: e.dataElementId } })),
+  ];
+  const edges = pedges.map((e) => {
+    const unknowns = [
+      ...(e.widenReasons || []).map((r) => ({ kind: 'widen', reason: r })),
+      ...(e.lossReasons || []).map((r) => ({ kind: 'loss', reason: r })),
+    ];
+    if (e.truncated) unknowns.push({ kind: 'truncated', reason: 'analysis-incomplete' });
+    return {
+      id: e.id, relation: relationOf(e, byId.get(e.toNodeId)), origin: 'code',
+      from: local('pnode', e.fromNodeId), to: local('pnode', e.toNodeId),
+      evidence: { grade: gradeOf(e), source: 'path-store' },
+      unknowns, attrs: { line: e.line ?? null, scope: e.scope, dataElementId: e.dataElementId }, native: e,
+    };
+  });
+
+  const reasons = [];
+  const lim = typeof store.limitStatus === 'function' ? store.limitStatus() : null;
+  if (lim?.hit) reasons.push('store-limit-hit');
+  const diag = typeof store.diagnostics === 'function' ? store.diagnostics() : null;
+  if (diag?.truncations?.length) reasons.push(`truncated-units:${diag.truncations.length}`);
+  if (diag?.orphanedPeerSources?.length) reasons.push(`orphaned-peer-sources:${diag.orphanedPeerSources.length}`);
+  if (diag?.malformed?.length) reasons.push(`malformed-hops:${diag.malformed.length}`);
+  const ac = opts?.completion ?? null;
+  if (ac && ac.status && ac.status !== 'complete') reasons.push(`analysis-${ac.status}`);
+  const status = reasons.length ? 'partial' : (lim || ac) ? 'complete' : 'unknown';
+
+  return new IndexedGraphView({
+    graphKind: 'provenance', adapterVersion: PROVENANCE_ADAPTER_VERSION, repository, graphDigest,
+    metadata: { source: 'PathStore', pnodes: pnodes.length, pedges: pedges.length, relationEdges: edges.length },
+    completion: { status, reasons, coverage: { limits: lim, analysis: ac } },
+    nodes, edges,
+    reconstruct: () => ({ nodes: pnodes, edges: pedges }),
+  });
+}