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

package/src/dataflow/tabulation.js

@@ -67,53 +67,107 @@ export function enumerateSinks(perFileIR, callGraph) {
 }
 
 /**
- * RHS-lite demand-driven slice. For each sink, walk backward through the
- * intra-procedural CFG via def-use, then ascend via the call graph for
- * each unresolved parameter binding. Returns the set of fn qids that are
- * REACHABLE from the sink (and therefore worth deep-analyzing).
- *
- *   sinks:          enumerateSinks() output
- *   callGraph:      { functions, callers, callees }
- *   maxCallerDepth: bounds reverse-call-graph walk
+ * Canonical caller index: callee qid -> [caller qid]. Built from each
+ * function's recorded `calls` (statement-level call nodes) and resolved with
+ * resolveKnownCallee, never the guessing resolve(). The demand selector
+ * (demand-query.js) extends it with the embedded call sites that `fn.calls`
+ * does not record (assignment right-hand sides, return values, nested
+ * arguments, callback registrations).
  */
-export function reachabilitySliceFromSinks(sinks, callGraph, maxCallerDepth = MAX_CALLER_DEPTH) {
-  const reachableFns = new Set();
-  if (!Array.isArray(sinks) || !callGraph || !callGraph.functions) return reachableFns;
-
-  // Build a reverse callgraph: who calls fn-qid?
+export function buildCallerQidIndex(callGraph) {
   const callersOf = new Map();
+  if (!callGraph || !callGraph.functions) return callersOf;
   for (const fn of callGraph.functions.values()) {
     for (const callee of (fn.calls || [])) {
-      // callee.callee is a SOURCE-LEVEL name ("b.fill"); the worklist below
-      // looks this map up by qid, so keying by the name means the lookup can
-      // never match. Resolve to a qid first.
-      const name = callee && typeof callee === 'object' ? callee.callee : callee;
-      if (!name) continue;
+      // callee.callee is a SOURCE-LEVEL name ("b.fill"); lookups are by qid,
+      // so keying by the name could never match. Resolve to a qid first.
       // resolveKnownCallee (not resolve): callee.callee may be a flattened
       // member-call string ("loader.read"); the plain resolve() would guess
       // via its bare-tail fallback and invent an edge to an unrelated
       // same-named function. See callgraph.js.
+      const name = callee && typeof callee === 'object' ? callee.callee : callee;
+      if (!name) continue;
       const qid = callGraph.resolveKnownCallee ? callGraph.resolveKnownCallee(name, fn.file) : null;
       if (!qid) continue;
       if (!callersOf.has(qid)) callersOf.set(qid, []);
       callersOf.get(qid).push(fn.qid);
     }
   }
+  return callersOf;
+}
+
+/**
+ * RHS-lite demand-driven slice. For each sink, walk backward through the
+ * intra-procedural CFG via def-use, then ascend via the call graph for
+ * each unresolved parameter binding. Returns the set of fn qids that are
+ * REACHABLE from the sink (and therefore worth deep-analyzing).
+ *
+ *   sinks:          enumerateSinks() output
+ *   callGraph:      { functions, callers, callees }
+ *   maxCallerDepth: bounds reverse-call-graph walk
+ */
+export function reachabilitySliceFromSinks(sinks, callGraph, maxCallerDepth = MAX_CALLER_DEPTH) {
+  return reachabilitySliceWithCompletion(sinks, callGraph, maxCallerDepth).reachable;
+}
+
+/**
+ * Same walk as reachabilitySliceFromSinks, plus a completion record
+ * (DAG-07 R07.1). A function the walk never reached is skipped by
+ * `shouldAnalyzeUnderRhs`, so a walk that stopped at its worklist cap or its
+ * caller-depth ceiling has silently narrowed what is analyzed; the record
+ * says so, with the number of callers left unexplored.
+ *
+ * Returns { reachable: Set<qid>, completion: { status, reasons,
+ * unexploredFrontierCount, visited, limits } }.
+ */
+export function reachabilitySliceWithCompletion(sinks, callGraph, maxCallerDepth = MAX_CALLER_DEPTH) {
+  const reachableFns = new Set();
+  const completion = {
+    status: 'complete', reasons: [], unexploredFrontierCount: 0, visited: 0,
+    limits: { maxWorklist: MAX_WORKLIST, maxCallerDepth },
+  };
+  if (!Array.isArray(sinks) || !callGraph || !callGraph.functions) {
+    completion.status = 'unavailable';
+    completion.reasons = ['no-call-graph'];
+    return { reachable: reachableFns, completion };
+  }
+
+  // Build a reverse callgraph: who calls fn-qid?
+  // DAG-02: factored into the shared, exported buildCallerQidIndex so the
+  // demand selector (demand-query.js) reuses the same canonical incoming-edge
+  // index. Behaviour is unchanged.
+  const callersOf = buildCallerQidIndex(callGraph);
 
   const work = [];
   for (const s of sinks) work.push({ qid: s.fnQid, depth: 0 });
   let visitedCount = 0;
+  let depthCut = 0;
+  let capped = false;
   while (work.length) {
-    if (++visitedCount > MAX_WORKLIST) break;
+    if (++visitedCount > MAX_WORKLIST) { capped = true; break; }
     const { qid, depth } = work.shift();
     if (reachableFns.has(qid)) continue;
     reachableFns.add(qid);
-    if (depth >= maxCallerDepth) continue;
+    if (depth >= maxCallerDepth) {
+      // Callers of this function exist but are not explored.
+      for (const callerQid of (callersOf.get(qid) || [])) if (!reachableFns.has(callerQid)) depthCut += 1;
+      continue;
+    }
     for (const callerQid of (callersOf.get(qid) || [])) {
       if (!reachableFns.has(callerQid)) work.push({ qid: callerQid, depth: depth + 1 });
     }
   }
-  return reachableFns;
+  completion.visited = visitedCount;
+  if (capped) {
+    completion.reasons.push('worklist-limit');
+    completion.unexploredFrontierCount += work.length;
+  }
+  if (depthCut > 0) {
+    completion.reasons.push('caller-depth-limit');
+    completion.unexploredFrontierCount += depthCut;
+  }
+  if (completion.reasons.length) completion.status = 'partial';
+  return { reachable: reachableFns, completion };
 }
 
 /**
@@ -128,10 +182,12 @@ export function rhsReachableFunctions(perFileIR, callGraph) {
   const sinks = enumerateSinks(perFileIR, callGraph);
   if (!sinks.length) {
     // No sinks → no demand. Return null to signal "analyze all" to caller.
-    return { reachable: null, sinks: [] };
+    // `completion` is an additive property (DAG-07 R07.1); existing callers
+    // destructure only { reachable, sinks }.
+    return { reachable: null, sinks: [], completion: { status: 'complete', reasons: [], unexploredFrontierCount: 0, visited: 0, limits: {}, note: 'no-sinks-analyze-all' } };
   }
-  const reachable = reachabilitySliceFromSinks(sinks, callGraph);
-  return { reachable, sinks };
+  const { reachable, completion } = reachabilitySliceWithCompletion(sinks, callGraph);
+  return { reachable, sinks, completion };
 }
 
 /**

package/src/engine.js

@@ -217,6 +217,8 @@ 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';
@@ -9503,6 +9505,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 +9550,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 +9584,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 +9612,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 +9645,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 +9675,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 }),
+  });
+}