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

package/src/lineage/coverage.js

@@ -0,0 +1,658 @@
+//
+// coverage.js — Sub-project E, increment 4 (E4).
+//
+// Implements DESIGN_GRAPH_BUILDER.md §9.4/§10 exactly: finishes the coverage
+// ledger E1/E3 shipped only as a sketch (`graph-builder.js`'s own inline
+// `graph.coverage = {...}` block — still present, still the DEFAULT when a
+// caller uses `buildDataFlowGraph` directly; this module supersedes it only
+// for a caller that opts in via `buildGraphWithCoverage`), and closes FR-203
+// (a recognized sink whose destination expression could not be statically
+// resolved — `fetch(url)` with a computed `url`; an SDK client built from
+// config).
+//
+// §9.4 item 3 ("ship §5's enumerator union as a real module function") is
+// ALREADY DONE — `graph-builder.js` exports `degradedTerminals(store)` as a
+// real, tested function (E3). This module reads its result via `built.degraded`,
+// it does not reimplement it.
+//
+// §9.4 item 5's hook-vs-post-processing-pass decision: an `opts` hook on
+// `buildDataFlowGraph` (`resolveSiteDecision`, shipped in Task 1), not a
+// post-processing pass over the built graph — see graph-builder.js's own
+// header for why a post-processing pass was rejected (FR-203 changes a
+// node's identity discriminator, so "adjust after minting" means re-minting).
+//
+// Reuse boundary: imports ONLY `reclassifySink` from `./sink-registry.js`,
+// `DEFAULTS` from `./path-query.js`, and `buildDataFlowGraph` from
+// `./graph-builder.js` — all three already-shipped `src/lineage/` modules.
+// Never `dataflow/engine.js`, never `dataflow/summaries.js`.
+//
+// Disclosure: FR-203's own `external-api` headline example ("fetch(url)
+// with a computed url") is currently unreachable on this project's real
+// fixture through the privacy-catalog guard below — `vulnerable-js`'s only
+// `external-api` sites are `privacy-js-axios-post`, and
+// `reclassifyPrivacySink` has no `opts.destinationUnresolved` parameter for
+// `resolveSiteDecision` to invoke (a disclosed, deliberate asymmetry — see
+// `sink-registry.js`'s own header). Correct and deliberate; recorded here
+// so the gap is visible rather than silently true of the only real fixture
+// in this tree today. FR-203 DOES fire on `vulnerable-js` via a different
+// category — `file`/`js-fs-readFile` (a general, CWE-keyed catalog entry) —
+// so `unresolvedDestinations` is genuinely nonzero on that fixture; only
+// the `external-api`/`fetch`-shaped case is unreachable there.
+//
+// Disclosure: the RECEIVER signal (a non-plain-ident callee object) fires
+// on any fixed-but-nontrivial property chain, not just a genuinely dynamic
+// expression — `this.db.query(q)` and `ctx.services.db.query(q)` both fire,
+// even though both are perfectly static, readable paths; only a bare
+// single-identifier receiver (`pool.query(q)`) reads as "resolved". This is
+// the same shape MUST-FIX 1 closed on the arg0 side, one axis over: the
+// plain-ident/member discriminator approximates static resolvability, it
+// doesn't decide it. Defensible (this module resolves nothing, so
+// "unresolved" is an honest label for anything it can't itself read back
+// out as a flat name) but will inflate `unresolvedDestinations` on any
+// repository using an ORM/repository pattern with `this.`/nested-service
+// receivers. Not narrowed in this increment — narrowing it to genuinely
+// computed receivers (a `call` or computed-member object) is the natural
+// follow-up if this proves noisy in practice.
+
+import { reclassifySink } from './sink-registry.js';
+import { DEFAULTS as PATH_QUERY_DEFAULTS } from './path-query.js';
+import { buildDataFlowGraph } from './graph-builder.js';
+// Milestone 2, Sub-project A, increment 1: `resolveDestination` composes
+// with `resolveSiteDecision` below the same way it's imported here — a real
+// ES module cycle (resolve-destination.js imports THREE things back from
+// this file). See that module's own header for why this is safe. Kept as
+// its own import line, not folded into the block above, so the cycle is
+// visible to a reader at a glance.
+import { resolveDestination } from './resolve-destination.js';
+// Milestone 2, Sub-project B, increment 2: `resolveTransitProtectionForSite`
+// composes with `opts.resolveTransitProtection` the same way `resolveDestination`
+// composes above — see `buildGraphWithCoverage`'s own wiring below. No ES
+// module cycle here (unlike `resolve-destination.js`) — `transit-protection.js`
+// never imports anything back from this file.
+import { resolveTransitProtectionForSite } from './transit-protection.js';
+// Deliverable #10 (DFG-020, graph-derived DPIA/RoPA migration): reused
+// UNMODIFIED, per the plan's own Global Constraints — this module never
+// re-implements governance-field lookup, only composes the default hook
+// `graph-builder.js`'s `opts.resolveGovernanceRefs` expects.
+import { governanceRecordFor, GOVERNANCE_FIELDS } from '../dataflow/privacy-governance.js';
+// Milestone 4, FR-506 (Third-Party and Cross-Border Intelligence):
+// `buildRecipientProfile` composes with `opts.buildRecipientProfile` the
+// same way `resolveDestination`/`resolveTransitProtectionForSite` compose
+// above — see `buildGraphWithCoverage`'s own wiring below. No ES module
+// cycle here — `recipient-registry.js` never imports anything back from
+// this file.
+import { buildRecipientProfile } from './recipient-registry.js';
+// Milestone 5, language coverage-tier disclosure: `coverageTierForLanguage`
+// composes into `buildCoverageLedger`'s `languages` computation below —
+// pure, static data, no cycle risk (mirrors how every other sibling import
+// above composes into this file's own hooks/computations).
+import { coverageTierForLanguage } from './language-coverage-tiers.js';
+// M5 deliverable #7 (FR-505/AC-29, Runtime-Corroborated Digital Twin, "7b"):
+// `correlateObservations` composes into `opts.correlateObservations` the
+// same way every other sibling default hook in this file composes — see
+// `buildGraphWithCoverage`'s own wiring below. No ES module cycle here —
+// `observation-correlation.js` never imports anything back from this file.
+import { correlateObservations } from './observation-correlation.js';
+
+// =========================================================================
+// FR-203 — the destination-unresolved heuristic.
+//
+// No catalog entry carries per-call-site destination information
+// (DESIGN_REGISTRIES.md §7.5), so this heuristic works from the two shapes
+// a real call site actually offers: the CALLEE (is the receiver a plain
+// bound identifier, or a computed expression — "an SDK client built from
+// config"?) and the first ARGUMENT (is it a literal, or a computed
+// expression — "fetch(url) with a computed url"?). Either one firing is
+// enough; the two are deliberately not required to agree, since a call
+// site can be unresolvable via only one of the two shapes.
+// =========================================================================
+
+function isPlainIdent(e) {
+  return Boolean(e) && typeof e === 'object' && e.kind === 'ident' && typeof e.name === 'string';
+}
+
+/** Renders an IR expression node as a short, human-readable string for a
+ * FR-203 `reason` — never throws, never returns an empty string. */
+export function renderExpr(e, depth = 0) {
+  if (depth > 4 || e == null) return '<computed expression>';
+  if (typeof e === 'string') return e;
+  if (typeof e !== 'object') return '<computed expression>';
+  if (e.kind === 'ident' && typeof e.name === 'string') return e.name;
+  if (e.kind === 'literal') return JSON.stringify(e.value);
+  if (e.kind === 'member' && typeof e.prop === 'string') return `${renderExpr(e.object, depth + 1)}.${e.prop}`;
+  return '<computed expression>';
+}
+
+/**
+ * §9.4 item 2's heuristic. `site` is one entry from `enumerateSinkSites`'s
+ * `sites[]` (post Task 1: carries `.calleeExpr` and `.args`). Returns
+ * `null` when nothing here looks unresolvable — never a guess in the
+ * unresolved direction. The result names WHICH signal fired (`via`):
+ * `'receiver'` (a computed callee receiver — "an SDK client built from
+ * config") or `'arg0'` (a non-literal first argument — "fetch(url) with a
+ * computed url"). `resolveSiteDecision` uses `via` to apply the narrower
+ * category gate the arg0 signal needs (see `FR203_ARG0_DESTINATION_CATEGORIES`
+ * below) — this function itself stays category-blind, since it has no
+ * access to the site's decision/category and is also exercised directly,
+ * without a category, by this module's own unit tests.
+ */
+export function detectUnresolvedDestination(site) {
+  const callee = site.calleeExpr;
+  if (callee && typeof callee === 'object' && callee.kind === 'member' && typeof callee.prop === 'string' && !isPlainIdent(callee.object)) {
+    return { blockingExpression: `${renderExpr(callee.object)}.${callee.prop}`, via: 'receiver' };
+  }
+  const arg0 = (site.args ?? [])[0];
+  if (arg0 && typeof arg0 === 'object' && arg0.kind !== 'literal') {
+    return { blockingExpression: renderExpr(arg0), via: 'arg0' };
+  }
+  return null;
+}
+
+// Categories whose node kind genuinely has a "destination" concept — a
+// target system or location an argument/receiver could name. Excludes
+// 'sink' (http-response/declared — the destination IS the call itself,
+// always fixed) and 'log' (same reasoning). Mirrors sink-registry.js's own
+// CATEGORY_NODE_KIND vocabulary; not re-derived, just filtered against.
+// This is the RECEIVER signal's own eligibility set — the receiver is the
+// destination handle in every one of these (an SDK client, a DB cursor, a
+// queue channel), so the receiver check applies to all three.
+//
+// 'queue' is currently unreachable in practice: no `sink-registry.js`
+// `CWE_MAP` row maps to `queue` (only `PRIVACY_CATEGORY_MAP`'s `queues` row
+// does, and privacy-catalog sites are excluded above by the `vuln.cwe ===
+// undefined` guard) — kept for forward-compatibility with a future
+// CWE_MAP row, not a bug.
+const FR203_ELIGIBLE_KINDS = Object.freeze(['external', 'store', 'queue']);
+
+// The ARGUMENT signal's own, NARROWER eligibility set (MUST-FIX 1). Unlike
+// the receiver, the first argument only actually NAMES the destination for
+// these three categories (`fetch(url)`, `fs.writeFile(path, data)`,
+// `s3.putObject(key, body)`) — everywhere else in `FR203_ELIGIBLE_KINDS`
+// (overwhelmingly `database`/`client-storage`), the first argument is the
+// PAYLOAD being sent TO an already-resolved destination named by the
+// receiver (`cursor.execute(sql)`, `document.write(html)`), so treating a
+// non-literal payload as "destination unresolved" is a false positive —
+// measured live: 54 of 86 FR-203-eligible catalog entries (63%) are
+// `database`(48)/`client-storage`(6), where the payload argument is
+// non-literal by construction, so the un-gated arg0 signal fired
+// unconditionally there and carried no information.
+// `object-storage` is currently unreachable via `CWE_MAP` today (like
+// `queue` above) — kept for forward-compatibility with a future row that
+// maps to it, not a bug.
+export const FR203_ARG0_DESTINATION_CATEGORIES = Object.freeze(['external-api', 'file', 'object-storage']);
+
+/**
+ * The exact shape `buildDataFlowGraph`'s `opts.resolveSiteDecision` hook
+ * expects: `(site) -> decision | undefined`. Composes with §4.3's
+ * multi-candidate ambiguity resolution rather than silently discarding it
+ * — see the Global Constraints note in this plan and the comment below.
+ */
+export function resolveSiteDecision(site) {
+  // Privacy-catalog entries are identified by carrying their own `category`
+  // field — the literal field `reclassifyPrivacySink` keys on, and one no
+  // general CATALOG sink entry ever has (sink-registry.js's own `D1/8b`
+  // pins this for the general side; independently re-confirmed live: 0 of
+  // 194 general sink entries carry `category`). `reclassifySink`'s `opts`
+  // parameter is specified only for the general (CWE-keyed) catalog
+  // (sink-registry.js's own disclosed asymmetry) — never applied here.
+  //
+  // CORRECTED (hotfix, 2026-08-31): the original guard checked
+  // `site.entry?.vuln?.cwe === undefined`, on the assumption that
+  // privacy-catalog entries carry no `vuln.cwe`. Measured, live: ALL 18 of
+  // 18 PRIVACY_SINK_CATALOG entries carry `vuln.cwe: 'CWE-359'` — the
+  // guard's premise was false for every single entry, so it excluded
+  // nothing. Since `'CWE-359'` has no `CWE_MAP` row, every privacy-catalog
+  // site that also triggered FR-203's heuristic silently fell through
+  // `reclassifySink`'s "unreachable from live data" fallback branch,
+  // corrupting a real store/external/queue-kind node into
+  // process/null/unsupported. Found and root-caused during Sub-project F's
+  // own corpus-authoring review; see
+  // docs/superpowers/plans/2026-08-31-lineage-coverage-privacy-catalog-fr203-hotfix.md.
+  if (typeof site.entry?.category === 'string') return undefined;
+  // Defensive: `resolveSiteDecision` is exported as a hook contract (passed
+  // straight into `buildDataFlowGraph`'s `opts.resolveSiteDecision`), so it
+  // should be as defensive against a malformed site as
+  // `detectUnresolvedDestination`/`renderExpr` already are — a site with no
+  // `.decision` at all must not throw here.
+  if (!site.decision) return undefined;
+  // A null-category (unsupported/process) decision has no category to
+  // retain — reclassifySink's own guard already refuses this combination;
+  // checking it here too avoids computing a heuristic result that would
+  // just be thrown away.
+  if (site.decision.category === null) return undefined;
+  if (!FR203_ELIGIBLE_KINDS.includes(site.decision.kind)) return undefined;
+
+  const unresolved = detectUnresolvedDestination(site);
+  if (!unresolved) return undefined;
+  // MUST-FIX 1: the arg0 signal only actually names a destination for the
+  // narrower FR203_ARG0_DESTINATION_CATEGORIES set — see that constant's
+  // own comment. The receiver signal has no such extra gate (it's eligible
+  // for everything FR203_ELIGIBLE_KINDS already allowed above).
+  if (unresolved.via === 'arg0' && !FR203_ARG0_DESTINATION_CATEGORIES.includes(site.decision.category)) return undefined;
+
+  const fr203 = reclassifySink(site.entry, {
+    destinationUnresolved: true,
+    blockingExpression: unresolved.blockingExpression,
+  });
+
+  // §4.3's plurality resolution already demoted `site.decision.coverageStatus`
+  // to 'partial' and appended an "AMBIGUOUS..." reason, entirely at the SITE
+  // level — `site.entry` is only the winning candidate's raw entry, so a
+  // bare `reclassifySink(site.entry, opts)` call knows nothing about that
+  // demotion and would silently produce `fr203.coverageStatus` from
+  // CWE_MAP fresh, discarding it. Carry the site-level adjustment forward
+  // when it happened; otherwise `fr203`'s own values already agree with
+  // `site.decision`'s (nothing to carry).
+  const ambiguityAdjusted = site.ambiguity?.resolvedBy === 'plurality';
+  return {
+    ...fr203,
+    coverageStatus: ambiguityAdjusted ? site.decision.coverageStatus : fr203.coverageStatus,
+    reason: ambiguityAdjusted ? `${fr203.reason} (site: ${site.decision.reason})` : fr203.reason,
+  };
+}
+
+// =========================================================================
+// The coverage ledger (§10).
+// =========================================================================
+
+// Worst-wins precedence when a category's sites/seeds carry more than one
+// coverageStatus — mirrors protection.js's aggregateVerdicts() and
+// flow-grade.js's _PRECEDENCE risk-precedence-reduction convention, the
+// established pattern in this package for "one summary value from several
+// individually-graded inputs, worst wins".
+const STATUS_PRECEDENCE = Object.freeze(['unsupported', 'candidate', 'partial', 'modeled']);
+function worstStatus(a, b) {
+  const ia = STATUS_PRECEDENCE.indexOf(a);
+  const ib = STATUS_PRECEDENCE.indexOf(b);
+  if (ia === -1) return b;
+  if (ib === -1) return a;
+  return ia <= ib ? a : b;
+}
+
+function byCategorySorted(build) {
+  const out = {};
+  for (const key of [...build.keys()].sort()) out[key] = build.get(key);
+  return out;
+}
+
+/** §10's `sources.byCategory` — from `built.seeds` (already category- and
+ * coverageStatus-tagged by source-registry.js's `reclassifySource`, per
+ * `source-seeding.js`'s own seed shape). Null-category seeds are excluded
+ * — the source registry's own tests already prove every source category
+ * is non-null (source-registry.js has no `unsupported` tier, D2's own
+ * measured 84/14/82/0 split), so this is a defensive exclusion, not a
+ * documented real case. */
+function sourcesByCategory(seeds) {
+  const m = new Map();
+  for (const s of seeds) {
+    if (s.category == null) continue;
+    if (!m.has(s.category)) m.set(s.category, { sites: 0, coverageStatus: s.coverageStatus });
+    const e = m.get(s.category);
+    e.sites += 1;
+    e.coverageStatus = worstStatus(e.coverageStatus, s.coverageStatus);
+  }
+  return byCategorySorted(m);
+}
+
+/** §10's `sinks.byCategory` — from `built.sites` (post any
+ * `opts.resolveSiteDecision` override, and post Task 1's `site.connected`
+ * stamp). Null-category (process/unsupported) sites are excluded — their
+ * existence is already guaranteed visible via AC-11's coarse half (every
+ * discovered sink becomes a node, `kind: 'process'`), so a per-category
+ * breakdown for a category that by definition doesn't exist would be
+ * misleading, not informative. */
+function sinksByCategory(sites) {
+  const m = new Map();
+  for (const s of sites) {
+    if (s.decision.category == null) continue;
+    if (!m.has(s.decision.category)) m.set(s.decision.category, { sites: 0, connected: 0, coverageStatus: s.decision.coverageStatus });
+    const e = m.get(s.decision.category);
+    e.sites += 1;
+    if (s.connected) e.connected += 1;
+    e.coverageStatus = worstStatus(e.coverageStatus, s.decision.coverageStatus);
+  }
+  return byCategorySorted(m);
+}
+
+// Language dispatch — mirrors ir/index.js's own extension-based dispatch
+// (never imported directly: that module has no exported "which language is
+// this file" function, only its own internal parse dispatch, and importing
+// ir/index.js here would cross a reuse boundary no other src/lineage/
+// module crosses). A small, stable, independently-testable duplicate.
+const LANGUAGE_EXT_PATTERNS = Object.freeze([
+  [/\.(?:js|jsx|ts|tsx|mjs|cjs|mts|cts)$/i, 'js'],
+  [/\.py$/i, 'python'],
+  [/\.java$/i, 'java'],
+  [/\.cs$/i, 'csharp'],
+  [/\.kt$/i, 'kotlin'],
+  [/\.go$/i, 'go'],
+  [/\.(?:php|phtml)$/i, 'php'],
+  [/\.rb$/i, 'ruby'],
+  [/\.(?:c|cc|cpp|cxx|h|hh|hpp|hxx)$/i, 'cpp'],
+  // Milestone 5, language coverage-tier disclosure: these 4 have ZERO
+  // lineage/taint wiring (tree-sitter-pattern-only, sast/tree-sitter-sinks.js
+  // only) — added here purely so a coverage-ledger `languages[]` entry can
+  // honestly attribute their files to a real language bucket, distinct from
+  // a genuinely unrecognized extension, rather than silently folding them
+  // into the shared 'unknown' fallback below.
+  [/\.rs$/i, 'rust'],
+  [/\.sol$/i, 'solidity'],
+  [/\.swift$/i, 'swift'],
+  [/\.dart$/i, 'dart'],
+]);
+function languageForFile(file) {
+  for (const [re, lang] of LANGUAGE_EXT_PATTERNS) if (re.test(file)) return lang;
+  return 'unknown';
+}
+
+/**
+ * §10's finished coverage-ledger contract. `built` is `buildDataFlowGraph`'s
+ * own return value (`{graph, store, hops, seeds, unseedable, sites,
+ * nonStatementSites, degraded, stats, decisionsByNodeId}`) — this function
+ * reads it, never rebuilds any of it.
+ *
+ * @param {object} built
+ * @param {object} [opts]
+ * @param {Record<string, object>} [opts.perFile] the same `{file: irRecord}`
+ *   map `runScan`'s `_sharedIR.perFile` holds — used ONLY to count
+ *   successfully-analyzed files per language. Optional: a caller with no
+ *   file list (e.g. a unit test building a callGraph by hand) gets
+ *   `languages: []`, honestly empty, never fabricated.
+ * @param {Array<{file: string, language?: string, message?: string}>} [opts.parseFailures]
+ *   per-file parse-failure records. A `callGraph`-only builder cannot see
+ *   these itself (a parse failure never reaches `callGraph` at all —
+ *   DESIGN_GRAPH_BUILDER.md §9.4 item 5b's own note); a caller with the
+ *   real file list (E5/`runScan`) supplies them. Optional, defaults to `[]`.
+ *   NOTE for that future caller: `ir/index.js`'s own parse-failure tracking
+ *   (`irParseFailures().byLanguage`) keys by raw extension (`'py'`, `'ts'`,
+ *   `'java'`), not this module's normalized `languageForFile` vocabulary
+ *   (`'python'`, `'js'`) — feed `irParseFailures()`'s entries through
+ *   `languageForFile(file)` (or supply an explicit `language`) rather than
+ *   its raw extension key, or `languages[]` will report split/duplicated
+ *   buckets for the same language.
+ * @param {object} [opts.budget] the same budget object passed to
+ *   `buildDataFlowGraph`'s own `opts.budget` — used only to report which
+ *   values were ACTUALLY in effect (merged over path-query.js's DEFAULTS,
+ *   the same way `reconstructPaths` itself merges them).
+ */
+export function buildCoverageLedger(built, opts = {}) {
+  const perFile = opts.perFile ?? {};
+  const parseFailures = (opts.parseFailures ?? []).map((f) => ({
+    file: f.file, language: f.language ?? languageForFile(f.file), message: f.message ?? null,
+  }));
+
+  const filesAnalyzedByLang = new Map();
+  for (const file of Object.keys(perFile)) {
+    const lang = languageForFile(file);
+    filesAnalyzedByLang.set(lang, (filesAnalyzedByLang.get(lang) ?? 0) + 1);
+  }
+  const filesFailedByLang = new Map();
+  for (const f of parseFailures) filesFailedByLang.set(f.language, (filesFailedByLang.get(f.language) ?? 0) + 1);
+  const allLangs = new Set([...filesAnalyzedByLang.keys(), ...filesFailedByLang.keys()]);
+  const languages = [...allLangs].sort().map((language) => {
+    const filesAnalyzed = filesAnalyzedByLang.get(language) ?? 0;
+    const base = { language, filesExpected: filesAnalyzed + (filesFailedByLang.get(language) ?? 0), filesAnalyzed };
+    // Milestone 5, language coverage-tier disclosure: coverageTierForLanguage
+    // never fabricates — a language with no curated entry (including the
+    // shared 'unknown' bucket for anything languageForFile can't recognize)
+    // gets tier: 'unknown' and no recall/measuredAt/source fields at all,
+    // never a guessed or zeroed-out number.
+    const tierEntry = coverageTierForLanguage(language);
+    if (!tierEntry) return { ...base, tier: 'unknown' };
+    const { tier, irTaintRecallPct, measuredAt, source } = tierEntry;
+    return irTaintRecallPct == null ? { ...base, tier } : { ...base, tier, irTaintRecallPct, measuredAt, source };
+  });
+
+  const unresolvedDestinations = built.sites.filter((s) => s.decision.kind === 'unresolved').length;
+  const storeStats = built.store.stats();
+
+  return {
+    languages, parseFailures,
+    destinationResolutionStatus: 'not-attempted', // FR-202 is Milestone 2 — unchanged from E3's sketch
+    pathBudgetTruncation: built.stats.truncatedQueries > 0,
+
+    sources: {
+      matched: built.seeds.length,
+      unseedable: built.unseedable.length,
+      dataElements: built.graph.dataElements.length,
+      byCategory: sourcesByCategory(built.seeds),
+    },
+    sinks: {
+      callStatementSites: built.sites.length,
+      connected: built.stats.connectedSinkSites,
+      disconnected: built.sites.length - built.stats.connectedSinkSites,
+      nonStatementSitesNotEnumerable: built.nonStatementSites.length,
+      // §10's own rule ("a node dropped and a node with no path must be
+      // distinguishable") applies to the reconciliation gap too: sites
+      // with a null category (kind:'process', AC-11's coarse half) are
+      // deliberately excluded from `byCategory` (see `sinksByCategory`'s
+      // own doc comment) but must not just vanish from the totals a reader
+      // sums — this count is the named residual, so
+      // `unsupportedSites + Σ byCategory[*].sites === callStatementSites`
+      // always holds.
+      unsupportedSites: built.sites.filter((s) => s.decision.category == null).length,
+      byCategory: sinksByCategory(built.sites),
+    },
+
+    degradedTerminals: built.degraded.length,
+    unresolvedDestinations,
+
+    paths: { enumerated: built.stats.pathsEnumerated, projected: built.stats.pathsProjected, truncatedQueries: built.stats.truncatedQueries },
+    budgets: { ...PATH_QUERY_DEFAULTS, ...(opts.budget ?? {}) },
+
+    provenance: { hops: built.hops.length, pnodes: storeStats.nodes, pedges: storeStats.edges },
+  };
+}
+
+/**
+ * Convenience entry point: `buildDataFlowGraph` with FR-203 closed by
+ * default and the finished coverage ledger in place of E3's sketch.
+ * Returns the same shape `buildDataFlowGraph` returns — `built.graph.coverage`
+ * is the only field this function changes.
+ *
+ * @param {object} [opts.transitEvidenceByFile] Milestone 2, Sub-project B,
+ *   increment 2: a pre-computed `Map<file, findings[]>` — the SAME `Map`
+ *   `scanTransitEvidence` returns, computed exactly once by the caller
+ *   (`index.js`'s `buildLineageGraph`), never raw `fileContents`. This
+ *   function never calls `scanTransitEvidence`/`scanCryptoProtocol` itself
+ *   — see `index.js`'s own header for why the computation must happen
+ *   exactly once, in exactly one place.
+ * @param {object} [opts.privacySinkPolicy] Milestone 2, Sub-project G,
+ *   increment 1: a pre-loaded `dataflow/privacy-sink-policy.js` policy
+ *   object (`{allow: [...]}`), computed exactly once by the caller
+ *   (`index.js`'s `buildLineageGraph`, mirroring `transitEvidenceByFile`'s
+ *   own single-computation discipline). This function never reads the
+ *   filesystem itself — it is spread straight through to
+ *   `buildDataFlowGraph` via `...opts` below, unchanged, since this
+ *   convenience wrapper has no default of its own to compose it with (only
+ *   `resolveSiteDecision`/`resolveDestination`/`resolveTransitProtection`
+ *   need one). `undefined` (never coerced to `{allow: []}` anywhere in this
+ *   file) means "no policy evaluation was attempted" — see
+ *   `graph-builder.js`'s own `policyLoaded` gate for why that distinction
+ *   is load-bearing.
+ * @param {string} [opts.environment] optional deployment-environment
+ *   override for policy evaluation's environment-scoped rules — also
+ *   spread straight through, unchanged.
+ * @param {object} [opts.recipientConfig] Milestone 4, FR-506: a pre-loaded
+ *   `recipient-registry.js`'s `loadRecipientConfig` return shape
+ *   (`{recipients: {...}}`), computed exactly once by the caller
+ *   (`index.js`'s `buildLineageGraph`, mirroring `transitEvidenceByFile`'s/
+ *   `privacySinkPolicy`'s own single-computation discipline). This function
+ *   never reads the filesystem itself — it only closes over this value for
+ *   `opts.buildRecipientProfile`'s own default hook, below.
+ * @param {Array<object>} [opts.runtimeObservations] M5 deliverable #7
+ *   (FR-505/AC-29): a PRE-LOADED `RuntimeObservation[]` array — never a
+ *   path, the read happens once, upstream, in `index.js`'s
+ *   `buildLineageGraph` (mirroring `opts.recipientConfig`'s own wording).
+ *   `undefined` means "no observation store was consulted" (`index.js`'s
+ *   own `existsSync` gate against `.agentic-security/runtime-observations/`
+ *   never found the directory) and installs NO default
+ *   `opts.correlateObservations` hook at all, so `graph.runtimeCorroboration`
+ *   stays genuinely absent — the `not_evaluated` state. `[]` means "a store
+ *   was consulted and is genuinely empty" and DOES install the default
+ *   hook, producing a real correlation result whose every flow reads
+ *   `not_observed_in_window` — the `opts.privacySinkPolicy`
+ *   `undefined`-vs-`[]` precedent (`index.js:129-150`) applied to
+ *   observations.
+ * @param {string} [opts.observationWindowStart] optional ISO-8601 lower
+ *   bound for the correlation window, threaded verbatim into
+ *   `correlateObservations`'s own `opts.windowStart`.
+ * @param {string} [opts.observationWindowEnd] optional ISO-8601 upper
+ *   bound for the correlation window, threaded verbatim into
+ *   `correlateObservations`'s own `opts.windowEnd`.
+ * @param {Array<object>} [opts.crossRepoLinkRecords] M5 deliverable #8
+ *   (FR-304 "declared" half): a PRE-LOADED `CrossRepoLink[]` array —
+ *   never a path, the read happens once, upstream, in `index.js`'s
+ *   `buildLineageGraph` (mirroring `opts.recipientConfig`'s own
+ *   wording). `undefined` means "no cross-repo-links.json was
+ *   consulted" (`index.js`'s own `existsSync` gate never found the
+ *   file) and installs NO default `opts.crossRepoLinks` hook at all —
+ *   `graph.crossRepoLinks` still reads `[]` either way (the same
+ *   visible OUTCOME as "consulted and genuinely empty"), unlike
+ *   `opts.runtimeObservations`'s own `undefined`-vs-`[]` distinction,
+ *   because a CrossRepoLink array carries no `not_evaluated` state to
+ *   preserve the way runtime corroboration does (see `graph-builder.js`'s
+ *   own comment on this hook for the full reasoning). The default hook,
+ *   when installed, DROPS any record whose `local.nodeId` is not present
+ *   in the graph's own current `nodes[]` (a stale declaration from
+ *   before a rescan), reporting each dropped id via `console.error`
+ *   rather than silently keeping it.
+ */
+export function buildGraphWithCoverage(callGraph, opts = {}) {
+  // NITPICK 4: compose with a caller-supplied `opts.resolveSiteDecision`
+  // rather than silently clobbering it — a caller's own hook always wins,
+  // matching `buildDataFlowGraph`'s own "the hook, when present, replaces
+  // `site.decision`" contract rather than this convenience wrapper quietly
+  // overriding that caller's choice.
+  // Milestone 2, Sub-project A, increment 1: identical composition pattern
+  // for `opts.resolveDestination` — a caller-supplied hook always wins.
+  // Milestone 2, Sub-project B, increment 2: identical composition pattern
+  // for `opts.resolveTransitProtection` — a caller-supplied hook always
+  // wins over this module's own default, which closes over
+  // `opts.transitEvidenceByFile` (honestly empty, via the `?? new Map()`
+  // fallback, when the caller supplies neither — never re-derived from
+  // `opts.fileContents`, which this function never reads).
+  const built = buildDataFlowGraph(callGraph, {
+    ...opts,
+    resolveSiteDecision: opts.resolveSiteDecision ?? resolveSiteDecision,
+    resolveDestination: opts.resolveDestination ?? resolveDestination,
+    resolveTransitProtection: opts.resolveTransitProtection
+      ?? ((site) => resolveTransitProtectionForSite(site, opts.transitEvidenceByFile ?? new Map())),
+    // Milestone 4, FR-506: identical composition pattern — a caller-supplied
+    // hook always wins over this module's own default, which closes over
+    // `opts.recipientConfig` (honestly `undefined`, via `buildRecipientProfile`'s
+    // own `opts.recipientConfig` fallback, when the caller supplies none —
+    // never re-derived from the filesystem here).
+    buildRecipientProfile: opts.buildRecipientProfile
+      ?? ((site, graph) => buildRecipientProfile(site, graph, { recipientConfig: opts.recipientConfig })),
+    // Deliverable #10 (DFG-020): opts.resolveGovernanceRefs, composed the
+    // same way every sibling hook is — a caller-supplied hook always wins.
+    // The default closes over opts.privacyGovernanceConfig, a PRE-LOADED
+    // config object (mirroring opts.transitEvidenceByFile's own
+    // single-computation-per-buildLineageGraph-call discipline — never
+    // read the filesystem itself here).
+    resolveGovernanceRefs: opts.resolveGovernanceRefs
+      ?? ((dataClasses) => {
+        // Task-1 review finding (non-blocking, fixed): a flow whose
+        // dataElement classified into NO named class (dataClasses: [])
+        // used to fall straight through this loop and return {} — no
+        // per-field MANUAL_REQUIRED at all. Privacy View's own rendering
+        // (`if (key in row.governanceRefs)`) then shows ZERO governance
+        // badges for such a flow, indistinguishable from a genuine
+        // nothing-to-disclose case — in tension with this codebase's own "missing
+        // evidence renders as unknown, never as not-applicable"
+        // convention (e.g. OSCAL's "an unassessed control gets no
+        // finding" is the SAME direction, never the reverse: absence of
+        // assessment must never read as absence of obligation). An
+        // unclassified data element still deserves the same governance
+        // scrutiny an operator-classified one does — its purpose/lawful
+        // basis/etc. are still real open questions, not inapplicable
+        // ones — so the honest answer is the full field set, all
+        // MANUAL_REQUIRED (or whatever the operator's scan-wide
+        // `config.default` supplies), never an empty object.
+        // `governanceRecordFor('(unclassified)', ...)` achieves this for
+        // free: an unmatched class key already falls through to
+        // `config.default`/MANUAL_REQUIRED in governanceRecordFor's own
+        // logic — no special-casing needed here.
+        const classesToResolve = dataClasses.length ? dataClasses : ['(unclassified)'];
+        const record = {};
+        for (const cls of classesToResolve) {
+          const clsRecord = governanceRecordFor(cls, opts.privacyGovernanceConfig ?? null);
+          for (const field of GOVERNANCE_FIELDS) {
+            // Worst-case-wins across multiple data classes on one flow,
+            // mirroring this package's own established
+            // aggregateVerdicts()-style precedent (protection.js) rather
+            // than silently picking whichever data class happened to be
+            // iterated last: an operator-provided value only wins over an
+            // already-recorded operator-provided value for the SAME field
+            // if this is the first class seen; MANUAL_REQUIRED never
+            // overwrites an already-resolved operator-provided value.
+            if (!record[field] || record[field].source === 'manual_required') {
+              record[field] = clsRecord[field];
+            }
+          }
+        }
+        return record;
+      }),
+    // M5 deliverable #7 (FR-505/AC-29): identical composition pattern — a
+    // caller-supplied hook always wins. The default is installed ONLY when
+    // `opts.runtimeObservations` is genuinely defined; when it is `undefined`
+    // (no store on disk, per index.js's own existsSync gate) NO hook is
+    // installed at all, so `graph.runtimeCorroboration` stays absent and reads
+    // as `not_evaluated`. This is exactly the `undefined`-vs-`[]` distinction
+    // `opts.privacySinkPolicy` already draws for a missing privacy-policy.json,
+    // and collapsing the two would make "we never looked" indistinguishable
+    // from a genuine "we looked and saw nothing" — PRD line 2098's own prohibition.
+    correlateObservations: opts.correlateObservations
+      ?? (opts.runtimeObservations !== undefined
+        ? ((graph) => correlateObservations(graph, opts.runtimeObservations, {
+          // I3 (final review): this default hook used to resolve
+          // opts.environment ?? null with no environment-variable
+          // fallback, unlike the sibling flow.policyVerdict path
+          // (graph-builder.js's own opts.environment || process.env
+          // .AGENTIC_SECURITY_ENVIRONMENT || null) — so a scan run under
+          // AGENTIC_SECURITY_ENVIRONMENT=production correlated runtime
+          // observations with NO environment filter at all, letting a
+          // stale/wrong-environment observation corroborate a flow in the
+          // signed production graph. Matches graph-builder.js's own
+          // established convention exactly.
+          environment: opts.environment || process.env.AGENTIC_SECURITY_ENVIRONMENT || null,
+          windowStart: opts.observationWindowStart ?? null,
+          windowEnd: opts.observationWindowEnd ?? null,
+        }))
+        : undefined),
+    // M5 deliverable #8 (FR-304 "declared" half): identical composition
+    // pattern to `opts.correlateObservations` immediately above — a
+    // caller-supplied hook always wins. The default is installed ONLY when
+    // `opts.crossRepoLinkRecords` is genuinely defined (`index.js`'s own
+    // `existsSync` gate against `.agentic-security/cross-repo-links.json`
+    // found the file); when it is `undefined`, NO hook is installed and
+    // `graph.crossRepoLinks` stays `[]` via `graph-builder.js`'s own
+    // unconditional default — there is no `not_evaluated` state for this
+    // array to preserve, unlike `correlateObservations`'s own
+    // `undefined`-vs-`[]` distinction. When installed, the default hook
+    // drops any record whose `local.nodeId` no longer resolves against the
+    // CURRENT graph's own real node set (a stale declaration from before a
+    // rescan renamed/removed the node) rather than silently keeping it —
+    // matching `applyScenario`'s own "skippedOperations, never thrown"
+    // honesty precedent — and reports every drop via `console.error`.
+    crossRepoLinks: opts.crossRepoLinks
+      ?? (opts.crossRepoLinkRecords !== undefined
+        ? ((graph) => {
+          const nodeIds = new Set((graph.nodes ?? []).map((n) => n.id));
+          const kept = [];
+          const dropped = [];
+          for (const record of opts.crossRepoLinkRecords) {
+            if (record && record.local && nodeIds.has(record.local.nodeId)) kept.push(record);
+            else dropped.push(record);
+          }
+          if (dropped.length > 0) {
+            console.error(`agentic-security: dropped ${dropped.length} stale cross-repo link${dropped.length === 1 ? '' : 's'} (local.nodeId not found in the current graph): ${dropped.map((r) => (r && r.id) || '(malformed)').join(', ')}`);
+          }
+          return kept;
+        })
+        : undefined),
+  });
+  built.graph.coverage = buildCoverageLedger(built, opts);
+  return built;
+}