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

package/src/lineage/impact-engine.js

@@ -0,0 +1,268 @@
+// impact-engine.js — M5 deliverable #4 (FR-507): the pure read/
+// aggregate computation behind "assess impact" from a compromised
+// node/edge/flow/data element. Reuses the already-shipped, already-
+// tested BFS traversal in frontend/src/lib/focus-controls.js — the
+// established scanner/src/ -> frontend/src/ cross-import precedent
+// (export-privacy.js's own computePrivacyViewModel import). No
+// mutation, no hypothesis, no re-run of the taint/path pipeline — a
+// pure filter/aggregate over the graph's own already-computed fields.
+
+import { showAllPaths } from '../../../frontend/src/lib/focus-controls.js';
+import { computeGraphDigest } from './export-json.js';
+import { impactAssessmentId } from './ids.js';
+import { IMPACT_VERSION } from './impact-assessment.js';
+
+// dataElement's real stable-id prefix is 'data:' (see ids.js's own
+// dataElementId(), which returns `data:${hash}` — every real
+// DataFlowGraph v1 document's dataElements[] carries this prefix, not
+// 'de:'). node/edge/flow below match ids.js's nodeId/edgeId/flowId
+// prefixes exactly for the identical reason.
+const _KIND_PREFIXES = Object.freeze({ node: 'node:', edge: 'edge:', flow: 'flow:', dataElement: 'data:' });
+
+function _resolveTargetKind(targetId) {
+  if (typeof targetId !== 'string') return null;
+  for (const [kind, prefix] of Object.entries(_KIND_PREFIXES)) {
+    if (targetId.startsWith(prefix)) return kind;
+  }
+  return null;
+}
+
+// The seed set for showAllPaths, node targets only — a node target
+// seeds itself; edge/flow/dataElement targets never reach this
+// function any more (final-review I1 fix). See
+// _flowRestrictedAffectedSet's header comment for why: compromising a
+// NODE genuinely puts everything reachable from it in the blast
+// radius, but compromising one EDGE/FLOW/data-element does not — the
+// affected record still NAMES that edge/flow's own two endpoint nodes
+// (you need them to know what the compromised channel actually
+// touches), it just never treats either endpoint as ITSELF fully
+// compromised for the purpose of finding everything ELSE reachable
+// from it via unrelated edges — that further step is exactly the
+// over-inclusion class the original dataElement fix removed.
+function _seedNodeIds(graph, targetId, targetKind) {
+  if (targetKind === 'node') return [targetId];
+  return [];
+}
+
+// Generalizes the direct flow-based trace to all three "named
+// relationship" target kinds (dataElement/edge/flow) — each is
+// restricted to the REAL flows that carry it, never the topology-wide
+// showAllPaths BFS below (that stays node-only). A compromised
+// flow/edge/data-element never sweeps in an unrelated sibling flow
+// that merely shares a node — the exact carrier path is already on
+// each flow's own record (source/sink/edgeIds/dataElementIds), so
+// approximating with topology reachability here would discard real
+// data, not fill a gap (reproduced live by this task's own review on
+// a branching-topology graph: one source, three sinks, one flow each
+// carrying a distinct data element — a `flow:`/`edge:` target for the
+// sink-A flow incorrectly swept in sinks B and C, and their unrelated
+// data classes/recipients with them). `matchesFlow(flow) -> boolean`
+// selects which flows carry the target. Also computes dataClasses
+// directly from the SAME matched-flow set (closes a related leak: the
+// edge-membership-based _affectedDataClasses below could pull in an
+// unrelated flow that merely shares one edge with the target flow but
+// carries a different data element — unreachable on any real
+// graph-builder output today since ids.edgeId's own discriminator
+// includes the data element id, but this closes the gap for a future
+// builder or an externally-supplied graph). Never adds a dangling
+// edge id that doesn't resolve to a real edge in graph.edges. Node
+// targets keep the showAllPaths BFS above — for those, "everything
+// topologically reachable from the compromised node's own endpoints"
+// IS the intended pessimistic scope:'possible' semantics.
+function _flowRestrictedAffectedSet(graph, matchesFlow) {
+  const nodeIds = new Set();
+  const edgeIds = new Set();
+  const dataClasses = new Set();
+  for (const f of graph.flows ?? []) {
+    if (!matchesFlow(f)) continue;
+    nodeIds.add(f.source);
+    nodeIds.add(f.sink);
+    for (const deId of f.dataElementIds ?? []) {
+      const de = (graph.dataElements ?? []).find((d) => d.id === deId);
+      for (const c of de?.dataClasses ?? []) dataClasses.add(c);
+    }
+    for (const eId of f.edgeIds ?? []) {
+      const edge = (graph.edges ?? []).find((e) => e.id === eId);
+      if (!edge) continue; // never surface a dangling/unresolved edge id
+      edgeIds.add(eId);
+      nodeIds.add(edge.from);
+      nodeIds.add(edge.to);
+    }
+  }
+  return { nodeIds, edgeIds, dataClasses };
+}
+
+// Edge-membership-based aggregation — kept ONLY as the `node` target's
+// fallback (a topology-reachability target has no single "the matched
+// flows" set to read dataClasses off directly, unlike the three named-
+// relationship kinds above, which use _flowRestrictedAffectedSet's own
+// dataClasses instead).
+function _affectedDataClasses(graph, affectedEdgeIds) {
+  const classes = new Set();
+  for (const f of graph.flows ?? []) {
+    if (!(f.edgeIds ?? []).some((id) => affectedEdgeIds.has(id))) continue;
+    for (const deId of f.dataElementIds ?? []) {
+      const de = (graph.dataElements ?? []).find((d) => d.id === deId);
+      for (const c of de?.dataClasses ?? []) classes.add(c);
+    }
+  }
+  return [...classes].sort();
+}
+
+function _affectedRecipientProfileIds(graph, affectedNodeIds) {
+  return (graph.recipientProfiles ?? [])
+    .filter((rp) => (rp.contributingGraphIds ?? []).some((id) => affectedNodeIds.has(id)))
+    .map((rp) => rp.id)
+    .sort();
+}
+
+// Whole-graph, not scoped to the affected subgraph — no node carries a
+// language field to filter by, so a per-language coverage gap is
+// reported as a real, honest limitation on any assessment computed
+// over this graph, not narrowed to the exact affected nodes. See this
+// sub-project's own implementation plan for the full disclosed
+// reasoning. Complemented, not replaced, by _affectedCoverageLimitations
+// below — that function reports the real per-entity coverageStatus gaps
+// among the entities THIS assessment actually affects, which this
+// whole-graph language disclosure cannot express.
+function _coverageLimitations(graph) {
+  return (graph.coverage?.languages ?? [])
+    .filter((l) => l.tier && l.tier !== 'full')
+    .map((l) => `${l.language}: coverage tier '${l.tier}'${typeof l.irTaintRecallPct === 'number' ? ` (${l.irTaintRecallPct}% measured recall)` : ''}`);
+}
+
+// Per-entity coverage gap among the entities THIS assessment actually
+// affects, using the real, required `coverageStatus` field every
+// node/edge/flow already carries (`modeled|partial|candidate|
+// unsupported|manual` — populated by graph-builder.js, already
+// consumed by export-csv.js/graph-diff.js). Complements (never
+// replaces) _coverageLimitations' whole-graph language disclosure
+// above — both are real, complementary limitations of the same
+// assessment.
+function _affectedCoverageLimitations(graph, affectedNodeIds, affectedEdgeIds) {
+  const limitations = [];
+  const nonModeledNodes = (graph.nodes ?? []).filter((n) => affectedNodeIds.has(n.id) && n.coverageStatus && n.coverageStatus !== 'modeled');
+  const nonModeledEdges = (graph.edges ?? []).filter((e) => affectedEdgeIds.has(e.id) && e.coverageStatus && e.coverageStatus !== 'modeled');
+  if (nonModeledNodes.length) {
+    limitations.push(`${nonModeledNodes.length} of ${affectedNodeIds.size} affected node(s) have less-than-modeled coverage (e.g. ${nonModeledNodes[0].id}: coverage tier '${nonModeledNodes[0].coverageStatus}')`);
+  }
+  if (nonModeledEdges.length) {
+    limitations.push(`${nonModeledEdges.length} of ${affectedEdgeIds.size} affected edge(s) have less-than-modeled coverage (e.g. ${nonModeledEdges[0].id}: coverage tier '${nonModeledEdges[0].coverageStatus}')`);
+  }
+  return limitations;
+}
+
+/**
+ * Compute an ImpactAssessment for `targetId` over `graph`. Throws when
+ * `graph` is structurally malformed (missing `nodes`/`edges` arrays —
+ * see `loadSignedGraph`'s own "signature-only, no schema validation"
+ * contract for why a signed-but-malformed graph can reach here) with a
+ * message prefixed `computeImpactAssessment: malformed graph — `, so a
+ * caller can distinguish that from the other thrown case: `targetId`
+ * has no recognized canonical-id prefix (a genuine caller error, not a
+ * missing-entity case). A well-formed targetId that does not exist in
+ * the graph degrades honestly to empty affected-* arrays, never an
+ * error — mirrors applyScenario's own skip-not-throw contract for a
+ * stale/missing target.
+ *
+ * `node` targets report a deliberately pessimistic "everything
+ * topologically reachable" blast radius (`traceKind:
+ * 'topology_reachable'`) — compromising a node genuinely puts
+ * everything it can reach in the blast radius. `edge`/`flow`/
+ * `dataElement` targets report only the flows/nodes/edges that
+ * actually carry that specific edge/flow/data element (`traceKind:
+ * 'flow_restricted'`) — the record still names that edge/flow's own
+ * two endpoint nodes (you need them to know what the channel actually
+ * touches), it just never treats either endpoint as itself fully
+ * compromised for finding everything ELSE reachable from it via
+ * unrelated edges. The two target-kind families answer genuinely
+ * different questions, both honestly disclosed via `traceKind` rather
+ * than silently conflated under one `scope` value.
+ */
+export function computeImpactAssessment(graph, targetId, opts = {}) {
+  if (!Array.isArray(graph?.nodes) || !Array.isArray(graph?.edges)) {
+    throw new Error('computeImpactAssessment: malformed graph — graph.nodes and graph.edges must both be arrays');
+  }
+
+  const targetKind = _resolveTargetKind(targetId);
+  if (!targetKind) {
+    throw new Error(`computeImpactAssessment: targetId "${targetId}" has no recognized prefix (expected one of node:/edge:/flow:/data:)`);
+  }
+
+  // showAllPaths (frontend/src/lib/focus-controls.js) unconditionally
+  // seeds its own result with the start id itself, even when that id
+  // does not exist in the graph at all (bfsDirection's `nodeIds = new
+  // Set([startId])`) — so a seed must be filtered against the graph's
+  // real node ids first, or a well-formed-but-nonexistent targetId
+  // would surface as a phantom single-node "affected" set instead of
+  // degrading honestly to empty arrays. The same filter is applied to
+  // _flowRestrictedAffectedSet's own node ids below, for the identical
+  // reason.
+  const realNodeIds = new Set((graph.nodes ?? []).map((n) => n.id));
+  const affectedNodeIds = new Set();
+  const affectedEdgeIds = new Set();
+  let affectedDataClasses;
+
+  if (targetKind === 'node') {
+    const seedNodeIds = _seedNodeIds(graph, targetId, targetKind).filter((id) => realNodeIds.has(id));
+    for (const seedId of seedNodeIds) {
+      const { nodeIds, edgeIds } = showAllPaths(graph, seedId);
+      for (const id of nodeIds) affectedNodeIds.add(id);
+      for (const id of edgeIds) affectedEdgeIds.add(id);
+    }
+    affectedDataClasses = _affectedDataClasses(graph, affectedEdgeIds);
+  } else {
+    // dataElement/edge/flow — direct flow-based trace via
+    // _flowRestrictedAffectedSet, never showAllPaths. See that
+    // function's own header comment for why.
+    const matchesFlow = targetKind === 'dataElement'
+      ? (f) => f.dataElementIds?.includes(targetId)
+      : targetKind === 'edge'
+        ? (f) => f.edgeIds?.includes(targetId)
+        : (f) => f.id === targetId; // flow
+    const { nodeIds, edgeIds, dataClasses } = _flowRestrictedAffectedSet(graph, matchesFlow);
+    for (const id of nodeIds) if (realNodeIds.has(id)) affectedNodeIds.add(id);
+    for (const id of edgeIds) affectedEdgeIds.add(id);
+    // N3 (final-review re-review): an edge: target that exists in
+    // graph.edges but appears in NO flow's own edgeIds (real for the
+    // real graph — an edge with zero flows using it is a legitimate
+    // graph shape, e.g. a dead-end connection no data currently
+    // traverses) must never come back fully empty — "this edge is
+    // compromised" means, at minimum, that edge and its own two
+    // endpoints are affected, flow or no flow. A nonexistent edge id
+    // still correctly degrades to fully empty (realNodeIds/the edge
+    // lookup below both filter it out).
+    if (targetKind === 'edge') {
+      const edge = (graph.edges ?? []).find((e) => e.id === targetId);
+      if (edge) {
+        affectedEdgeIds.add(edge.id);
+        if (realNodeIds.has(edge.from)) affectedNodeIds.add(edge.from);
+        if (realNodeIds.has(edge.to)) affectedNodeIds.add(edge.to);
+      }
+    }
+    affectedDataClasses = [...dataClasses].sort();
+  }
+
+  const graphDigest = computeGraphDigest(graph);
+  const generatedAt = opts.generatedAt ?? new Date().toISOString();
+
+  return {
+    id: impactAssessmentId({ graphId: graph.graphId, graphDigest, targetId }, [generatedAt]),
+    version: IMPACT_VERSION,
+    graphId: graph.graphId,
+    graphDigest,
+    targetId,
+    targetKind,
+    scope: 'possible',
+    traceKind: targetKind === 'node' ? 'topology_reachable' : 'flow_restricted',
+    affectedNodeIds: [...affectedNodeIds].sort(),
+    affectedEdgeIds: [...affectedEdgeIds].sort(),
+    affectedDataClasses,
+    affectedRecipientProfileIds: _affectedRecipientProfileIds(graph, affectedNodeIds),
+    coverageLimitations: [
+      ..._coverageLimitations(graph),
+      ..._affectedCoverageLimitations(graph, affectedNodeIds, affectedEdgeIds),
+    ],
+    generatedAt,
+  };
+}

package/src/lineage/index.js

@@ -0,0 +1,281 @@
+//
+// index.js — Sub-project E, increment 5 (E5). The scan-facing entry point
+// for the Data Flow Explorer lineage engine. This is the ONLY file under
+// src/lineage/ that engine.js/bin/agentic-security.js import — every other
+// module in this package stays isolated per its own established reuse
+// boundary (see src/lineage/CLAUDE.md's header).
+//
+// Mirrors runFullScan's own `_deepEnabled` block's CONTRACT (opt-in,
+// best-effort, every outcome returned as a structured status a caller folds
+// into scanHealth) — NOT `dataflow/index.js`'s `AGENTIC_SECURITY_PRIVACY_DEEP`
+// block, whose bare `catch {}` silently swallows failure with no scanHealth
+// signal at all (measured and disclosed in
+// docs/superpowers/plans/2026-08-31-data-flow-explorer-m1-subproject-e5-scoping.md
+// §1 — DESIGN_GRAPH_BUILDER.md §9.5 item 1's own wording describes the
+// LATTER mechanism, not the former, despite naming the former by name).
+//
+// Unlike privacy-taint, lineage analysis has NO degraded/non-IR-backed mode:
+// `buildGraphWithCoverage(callGraph, opts)` requires a real callGraph with
+// real CFGs, and there is nothing meaningful to fall back to. A missing or
+// malformed callGraph is reported as `not_available`, never attempted as a
+// degraded run.
+
+import * as fs from 'node:fs';
+import { buildGraphWithCoverage } from './coverage.js';
+import { scanTransitEvidence } from './transit-protection.js';
+// Milestone 2, Sub-project G, increment 1 (FR-408/AC-09): loaded ONCE, here
+// — mirroring `scanTransitEvidence`'s own single-computation discipline one
+// line above — never re-loaded at a lower layer (`coverage.js`/
+// `graph-builder.js` both only ever consume the already-loaded object).
+import { loadPrivacySinkPolicy } from '../dataflow/privacy-sink-policy.js';
+// Deliverable #10 (DFG-020, graph-derived DPIA/RoPA migration): loaded
+// ONCE, here — mirroring `loadPrivacySinkPolicy`'s own single-computation
+// discipline one block below. Unlike that policy load, no existence-gating
+// is needed: `loadPrivacyGovernanceConfig` already has its own honest empty
+// default ({byClass: {}, default: {}} — never throws), and
+// `governanceRecordFor` already resolves an empty config to MANUAL_REQUIRED
+// for every field, which is the correct, honest answer when no
+// .agentic-security/privacy-governance.json exists on disk.
+import { loadPrivacyGovernanceConfig } from '../dataflow/privacy-governance.js';
+import { statePath } from '../posture/state-dir.js';
+// Milestone 4, FR-506 (Third-Party and Cross-Border Intelligence): loaded
+// ONCE, here — mirroring `loadPrivacySinkPolicy`'s own single-computation
+// discipline above. `loadRecipientConfig` already has the SAME "never
+// throws, missing file degrades to {recipients: {}}" contract
+// `loadPrivacyGovernanceConfig` has, so — like that config, unlike
+// `privacySinkPolicy` — no existence-gating is needed on the CALL itself;
+// only the PATH resolution mirrors `privacySinkPolicy`'s own precedent,
+// since `loadRecipientConfig` (unlike `loadPrivacyGovernanceConfig`) takes
+// a literal file path, not a scanRoot.
+import { loadRecipientConfig, RECIPIENT_CONFIG_FILENAME } from './recipient-registry.js';
+// M5 deliverable #7 (FR-505/AC-29, Runtime-Corroborated Digital Twin, "7b"):
+// loaded ONCE, here — mirroring `loadPrivacySinkPolicy`'s own
+// single-computation discipline above, including the SAME explicit
+// `fs.existsSync` gate and the SAME reason: `loadObservations` returns the
+// identical empty array whether the store directory is missing or
+// present-and-empty, and those are two DIFFERENT answers under AC-29
+// clause 2 — see the function body below for the full reasoning.
+import { loadObservations } from './observation-store.js';
+// M5 deliverable #8 (FR-304 "declared" half): loaded ONCE, here —
+// mirroring `privacySinkPolicy`'s own existence-gated, single-computation
+// discipline below (never `recipientConfig`'s unconditional-call one — a
+// missing cross-repo-links.json here means "no links declared", a real,
+// distinguishable-from-empty state worth keeping honest the same way
+// `privacy-policy.json`'s absence is, per this deliverable's own scoping
+// doc). `validateCrossRepoLink` is imported directly (not a separate
+// loader module) — see `_loadCrossRepoLinkRecords` below for why this
+// small, local, tolerant reader lives here rather than in
+// `cross-repo-link.js` (which must stay a PURE, zero-fs-access module,
+// mirroring `scenario.js`'s own boundary) or `federation-loader.js`
+// (which owns only the REMOTE side).
+import { validateCrossRepoLink, CROSS_REPO_LINKS_FILENAME } from './cross-repo-link.js';
+
+// A small, LOCAL, tolerant loader for the operator-declared
+// cross-repo-links.json config file — mirrors `loadRecipientConfig`'s own
+// fail-closed, skip-the-whole-entry-on-any-defect discipline
+// (recipient-registry.js), but kept local to this file rather than
+// exported from `cross-repo-link.js`/`federation-loader.js` (see the
+// import comment above for the full reasoning). Never throws; a missing
+// file is never reached here at all (the caller already gated on
+// `fs.existsSync`); a malformed file or a malformed individual link
+// degrades to an empty/partial array with a console warning naming the
+// count skipped, mirroring `loadRecipientConfig`'s own per-entry
+// discipline.
+function _loadCrossRepoLinkRecords(filePath) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    console.error(`agentic-security: bad JSON in cross-repo links file (${filePath}) — falling back to no declared links (${e.message})`);
+    return [];
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !Array.isArray(raw.links)) {
+    console.error(`agentic-security: cross-repo links file ${filePath} has no "links" array — falling back to no declared links (expected {"links": [...]})`);
+    return [];
+  }
+  const records = [];
+  let skipped = 0;
+  for (const record of raw.links) {
+    const { valid } = validateCrossRepoLink(record);
+    if (!valid) { skipped += 1; continue; }
+    records.push(record);
+  }
+  if (skipped > 0) {
+    console.error(`agentic-security: skipped ${skipped} malformed cross-repo-link entr${skipped === 1 ? 'y' : 'ies'} in ${filePath} (each must be a valid CrossRepoLink-shaped object)`);
+  }
+  return records;
+}
+
+/**
+ * @param {{functions: Map}} callGraph a real callGraph — the same shape
+ *   `buildProjectIR`/`buildProjectIRAsync` produce (`_sharedIR.callGraph`
+ *   in `runFullScan`).
+ * @param {object} [opts]
+ * @param {string} [opts.repository] threaded straight to `buildGraphWithCoverage`.
+ * @param {string} [opts.scanRoot] the real scan root path — distinct from
+ *   `opts.repository`, which by the time it reaches this function is only a
+ *   basename (see `engine.js`'s own call site). Used ONLY to load the
+ *   operator's privacy sink policy (Milestone 2, Sub-project G, increment
+ *   1, FR-408/AC-09) — never threaded to `buildGraphWithCoverage` itself,
+ *   which never reads the filesystem. See the function body for why
+ *   existence is checked explicitly rather than inferred from
+ *   `loadPrivacySinkPolicy`'s own return value.
+ * @param {string} [opts.environment] optional deployment-environment
+ *   override for policy evaluation's environment-scoped rules; threaded to
+ *   `buildGraphWithCoverage`'s `opts.environment`, which falls back to
+ *   `AGENTIC_SECURITY_ENVIRONMENT` at the point the verdict is computed
+ *   (`graph-builder.js`), mirroring `dataflow/privacy-taint.js`'s own
+ *   precedent.
+ * @param {boolean} [opts.deterministic] when true, `generatedAt` is left
+ *   `undefined` so `buildDataFlowGraph`'s own fixed-literal default applies
+ *   — the literal itself lives in exactly one place, `graph-builder.js`.
+ * @param {Record<string,object>} [opts.perFile] threaded to the coverage
+ *   ledger's `languages[]` computation.
+ * @param {Array<object>} [opts.parseFailures] threaded to the coverage
+ *   ledger's `parseFailures`/`languages[].filesExpected` computation.
+ * @param {Record<string,string>} [opts.fileContents] `{path: rawSourceString}`
+ *   — threaded to `transit-protection.js`'s `scanTransitEvidence` (Milestone 2,
+ *   Sub-project B, increment 1). As of increment 2, `scanTransitEvidence` is
+ *   called EXACTLY ONCE, here, per `buildLineageGraph` call — its result
+ *   (a `Map<file, findings[]>`) feeds BOTH the returned `transitEvidence`
+ *   field below AND `buildGraphWithCoverage`'s own `opts.transitEvidenceByFile`
+ *   (the same `Map` reference, never recomputed), which is what actually
+ *   drives `edge.protection.transit` verdicts inside `graph-builder.js`. See
+ *   `DESIGN_TRANSIT_PROTECTION.md` §6 for why this single-computation
+ *   discipline is load-bearing (a second call inside `coverage.js`'s own
+ *   default hook would double-scan every file). `graph` is NOT
+ *   byte-identical to omitting `opts.fileContents` anymore — a network
+ *   sink's `edge.protection.transit` can now genuinely change with the
+ *   evidence supplied.
+ * Milestone 4, FR-506: the operator's recipient config
+ * (`.agentic-security/recipient-profiles.json`, resolved against
+ * `opts.scanRoot`) is loaded exactly once here and threaded to
+ * `buildGraphWithCoverage`'s `opts.recipientConfig`, which drives the
+ * default `opts.buildRecipientProfile` hook — no separate `opts` field
+ * needed, unlike `privacySinkPolicy`, since `loadRecipientConfig` already
+ * degrades a missing/malformed file gracefully on its own.
+ * M5 deliverable #7 (FR-505/AC-29): the operator's runtime-observation
+ * store (`.agentic-security/runtime-observations/`, resolved against
+ * `opts.scanRoot`) is loaded exactly once here, existence-gated exactly
+ * like `privacySinkPolicy` above, and threaded to `buildGraphWithCoverage`'s
+ * `opts.runtimeObservations`.
+ * @param {string} [opts.observationWindowStart] optional ISO-8601 lower
+ *   bound for runtime-observation correlation, threaded to
+ *   `buildGraphWithCoverage`'s `opts.observationWindowStart`.
+ * @param {string} [opts.observationWindowEnd] optional ISO-8601 upper
+ *   bound for runtime-observation correlation, threaded to
+ *   `buildGraphWithCoverage`'s `opts.observationWindowEnd`.
+ * @returns {{status: 'not_available'|'complete'|'failed', graph: object|null, transitEvidence: Map<string,object[]>, failure: string|null, elapsedMs: number}}
+ *   `status` is never `'not_requested'` — that decision belongs to the
+ *   CALLER (whether to call this function at all), not to this function's
+ *   own return value. `transitEvidence` is a `Map<file, findings[]>` — see
+ *   `DESIGN_TRANSIT_PROTECTION.md` §3 for why a `Map`, not a plain object.
+ *   It is a real, populated result of running `scanCryptoProtocol` over
+ *   `opts.fileContents` (empty when omitted). As of increment 2, this same
+ *   `Map` IS also joined to specific graph edges — via
+ *   `buildGraphWithCoverage`'s `opts.transitEvidenceByFile`, consulted by
+ *   `resolveTransitProtectionForSite` for `external-api` sink sites — but
+ *   this returned field itself stays the raw, ungrouped `Map<file,
+ *   findings[]>`, not a per-edge join result.
+ */
+export function buildLineageGraph(callGraph, opts = {}) {
+  const t0 = Date.now();
+  if (!callGraph || typeof callGraph.functions?.values !== 'function') {
+    return { status: 'not_available', graph: null, transitEvidence: new Map(), failure: null, elapsedMs: Date.now() - t0 };
+  }
+  try {
+    // Milestone 2, Sub-project B, increment 2 (DESIGN_TRANSIT_PROTECTION.md
+    // §6, item 4): `scanTransitEvidence` runs EXACTLY ONCE per
+    // `buildLineageGraph` call, here — the same `Map` reference feeds both
+    // this function's own `transitEvidence` return field AND
+    // `buildGraphWithCoverage`'s `opts.transitEvidenceByFile`, which is what
+    // `coverage.js`'s default `resolveTransitProtection` hook actually
+    // consults. `coverage.js` never calls `scanTransitEvidence`/
+    // `scanCryptoProtocol` itself — it only reads this pre-computed Map —
+    // so no file is ever scanned twice.
+    const transitEvidence = scanTransitEvidence(opts.fileContents ?? {});
+    // Milestone 2, Sub-project G, increment 1 (FR-408/AC-09): load the
+    // operator's privacy sink policy exactly once, here. Existence is
+    // checked EXPLICITLY (never inferred from `loadPrivacySinkPolicy`'s own
+    // return value alone) because that function deliberately returns the
+    // SAME empty `{allow: []}` shape whether the policy file is missing,
+    // malformed, or genuinely present with an empty `allow` array —
+    // collapsing three states `graph-builder.js`'s own policy-verdict logic
+    // needs to keep apart. A MISSING policy must read
+    // `flow.policyVerdict: 'not_evaluated'` (nothing was actually
+    // evaluated — privacy-sink-policy.js's own header: "nothing changes for
+    // a repo with no policy file"); a PRESENT-but-empty policy (an
+    // operator's deliberate "nothing is permitted yet" `{"allow": []}`)
+    // must read `'prohibited'` — the deny-by-default stance that same
+    // header establishes once a policy is genuinely in play.
+    // `privacySinkPolicy` therefore stays `undefined` (never coerced to
+    // `{allow: []}`) unless the file genuinely exists on disk — this is
+    // what lets `graph-builder.js`'s `opts.privacySinkPolicy != null` gate
+    // make that distinction at all.
+    const _policyFile = opts.scanRoot ? statePath(opts.scanRoot, 'privacy-policy.json') : null;
+    const privacySinkPolicy = _policyFile && fs.existsSync(_policyFile)
+      ? loadPrivacySinkPolicy(opts.scanRoot)
+      : undefined;
+    // Deliverable #10 (DFG-020): the operator's privacy governance config,
+    // loaded exactly once, here — mirroring privacySinkPolicy's own
+    // single-load precedent immediately above it. See this file's own
+    // import comment for why no existence-gating is needed here, unlike
+    // privacySinkPolicy.
+    const privacyGovernanceConfig = loadPrivacyGovernanceConfig(opts.scanRoot);
+    // Milestone 4, FR-506: the operator's recipient config, loaded exactly
+    // once, here — mirroring `privacySinkPolicy`'s own path-resolution step
+    // (gated on `opts.scanRoot`, since `loadRecipientConfig` takes a literal
+    // file path rather than a scanRoot) but, per this file's own import
+    // comment above, calling the loader UNCONDITIONALLY once the path is
+    // resolved — `loadRecipientConfig` already degrades a missing/malformed
+    // file to `{recipients: {}}` on its own, the same honest-empty-default
+    // contract `loadPrivacyGovernanceConfig` has.
+    const recipientConfigPath = opts.scanRoot ? statePath(opts.scanRoot, RECIPIENT_CONFIG_FILENAME) : null;
+    const recipientConfig = loadRecipientConfig(recipientConfigPath);
+    // M5 deliverable #7 (FR-505/AC-29): the operator's runtime-observation
+    // store, loaded exactly ONCE here — the same single-computation discipline
+    // scanTransitEvidence and loadPrivacySinkPolicy already follow. Existence
+    // is checked EXPLICITLY, exactly like privacySinkPolicy and for the
+    // identical reason: `loadObservations` returns the same empty array whether
+    // the store directory is missing or present-and-empty, and those are two
+    // DIFFERENT answers under AC-29 clause 2. A MISSING store must leave
+    // `graph.runtimeCorroboration` absent (`not_evaluated` — nothing was
+    // consulted); a PRESENT-but-empty store must produce a real correlation
+    // result whose every flow reads `not_observed_in_window` (a store WAS
+    // consulted and the window genuinely contained nothing). PRD line 2098:
+    // absence of observation is never non-occurrence.
+    const _observationsDir = opts.scanRoot ? statePath(opts.scanRoot, 'runtime-observations') : null;
+    const runtimeObservations = _observationsDir && fs.existsSync(_observationsDir)
+      ? loadObservations(opts.scanRoot)
+      : undefined;
+    // M5 deliverable #8 (FR-304 "declared" half): the operator's declared
+    // cross-repo links, loaded exactly once here — the same
+    // single-computation discipline every other config load in this
+    // function follows. Existence is checked EXPLICITLY, exactly like
+    // `privacySinkPolicy` above.
+    const _crossRepoLinksFile = opts.scanRoot ? statePath(opts.scanRoot, CROSS_REPO_LINKS_FILENAME) : null;
+    const crossRepoLinkRecords = _crossRepoLinksFile && fs.existsSync(_crossRepoLinksFile)
+      ? _loadCrossRepoLinkRecords(_crossRepoLinksFile)
+      : undefined;
+    const built = buildGraphWithCoverage(callGraph, {
+      repository: opts.repository,
+      generatedAt: opts.deterministic ? undefined : new Date().toISOString(),
+      perFile: opts.perFile,
+      parseFailures: opts.parseFailures,
+      transitEvidenceByFile: transitEvidence,
+      privacySinkPolicy,
+      privacyGovernanceConfig,
+      environment: opts.environment,
+      recipientConfig,
+      runtimeObservations,
+      crossRepoLinkRecords,
+      observationWindowStart: opts.observationWindowStart,
+      observationWindowEnd: opts.observationWindowEnd,
+    });
+    return { status: 'complete', graph: built.graph, transitEvidence, failure: null, elapsedMs: Date.now() - t0 };
+  } catch (e) {
+    // Best-effort (DESIGN_GRAPH_BUILDER.md §9.5 item 1): recorded, never
+    // swallowed. The caller (runFullScan) folds `failure` into scanHealth.
+    return { status: 'failed', graph: null, transitEvidence: new Map(), failure: String((e && e.message) || e), elapsedMs: Date.now() - t0 };
+  }
+}

package/src/lineage/language-coverage-tiers.js

@@ -0,0 +1,58 @@
+// language-coverage-tiers.js — Milestone 5, language coverage-tier
+// disclosure. A small, curated, static table answering "how much can this
+// codebase's Data Flow Explorer actually see for language X today" —
+// PRD §22.1's own explicitly-sanctioned alternative to claiming a language
+// is fully "supported" before it clears §22.3's 85% field-to-sink-recall
+// bar (as of docs/METRICS.md, measured 2026-08-19, NONE of the 9
+// lineage-wired languages do — best is python at 66%).
+//
+// Every number here is copied VERBATIM from docs/METRICS.md's own
+// currently-committed table (bench/layer-recall's IR-TAINT column — the
+// closest existing proxy for the PRD's own field-to-sink recall definition,
+// not a byte-identical measurement of it). This module does not re-measure
+// anything; re-run bench/layer-recall and update BOTH docs/METRICS.md and
+// this table together if the numbers ever change, or this file goes stale
+// silently. Zero imports — a pure, static data module, mirroring
+// flow-grade.js's own "zero imports" precedent for a self-contained
+// vocabulary/data table.
+//
+// The 9 keys below are languageForFile's own normalized vocabulary
+// (coverage.js) — js/python/java/csharp/kotlin/go/php/ruby/cpp — the exact
+// languages with real IR-to-lineage wiring today. The 4 pattern-only keys
+// (rust/solidity/swift/dart) have ZERO lineage/taint wiring: they exist
+// only as tree-sitter grammar loads feeding sast/tree-sitter-sinks.js's
+// pattern matching, never scanner/src/lineage/ or scanner/src/dataflow/ —
+// confirmed by the M5 top-level scoping doc's own investigation. No
+// lineage engine ever runs against them, so they carry no recall number at
+// all (irTaintRecallPct: null) — never a fabricated 0%, which would read
+// as "measured and found to be zero" rather than "never measured, because
+// nothing here can produce a lineage finding for this language yet."
+
+export const LANGUAGE_COVERAGE_TIERS = Object.freeze([
+  Object.freeze({ language: 'python', tier: 'partial', irTaintRecallPct: 66, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'go', tier: 'partial', irTaintRecallPct: 59, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'js', tier: 'partial', irTaintRecallPct: 58, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'csharp', tier: 'partial', irTaintRecallPct: 57, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'ruby', tier: 'partial', irTaintRecallPct: 55, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'java', tier: 'partial', irTaintRecallPct: 52, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'php', tier: 'partial', irTaintRecallPct: 52, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'kotlin', tier: 'partial', irTaintRecallPct: 48, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'cpp', tier: 'partial', irTaintRecallPct: 18, measuredAt: '2026-08-19', source: 'docs/METRICS.md' }),
+  Object.freeze({ language: 'rust', tier: 'pattern-only', irTaintRecallPct: null, measuredAt: null, source: null }),
+  Object.freeze({ language: 'solidity', tier: 'pattern-only', irTaintRecallPct: null, measuredAt: null, source: null }),
+  Object.freeze({ language: 'swift', tier: 'pattern-only', irTaintRecallPct: null, measuredAt: null, source: null }),
+  Object.freeze({ language: 'dart', tier: 'pattern-only', irTaintRecallPct: null, measuredAt: null, source: null }),
+]);
+
+const _byLanguage = new Map(LANGUAGE_COVERAGE_TIERS.map((e) => [e.language, e]));
+
+/**
+ * `coverageTierForLanguage(language) -> entry | null`. Never fabricates —
+ * returns `null` for any language string not in the curated table above
+ * (including coverage.js's own `'unknown'` fallback), so a caller must
+ * decide its own honest default (coverage.js's ledger uses `'unknown'`).
+ */
+export function coverageTierForLanguage(language) {
+  if (typeof language !== 'string' || language.length === 0) return null;
+  return _byLanguage.get(language) ?? null;
+}