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

package/src/lineage/export-csv.js

@@ -0,0 +1,62 @@
+// export-csv.js — Milestone 4, sub-project JSON/CSV export.
+//
+// One row per FLOW (not node, not edge — the closest analogue in this
+// domain to report/index.js's own toCSV's "one row per finding", per this
+// sub-project's own scoping doc decision 3). Node/edge CSV exports are
+// deferred, named explicitly in that doc, not attempted here.
+
+import { aggregateVerdicts } from './protection.js';
+
+// Same escaping convention as report/index.js's own toCSV — quote only
+// when a comma/quote/newline is present, double embedded quotes.
+function esc(v) {
+  if (v == null) return '';
+  const s = String(v);
+  return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+}
+
+// Join character for a flow's multiple `dataClasses` values in one CSV
+// cell: `;`, not `,`. Chosen (this module's own decision, not prescribed
+// by the plan) because `,` is CSV's own delimiter — joining multiple
+// classes with it would put a raw delimiter inside a single logical cell
+// value, forcing outer quoting for the ordinary multi-class case (e.g. a
+// field classified both PCI and PII). `;` never collides with the CSV
+// grammar, so the common case ("PCI;PII") never needs quoting at all.
+// `esc()` still quotes correctly if a comma ends up in cell content for
+// any other reason (see export-csv.test.js's own escaping test) — this
+// choice only avoids manufacturing that case in the common path.
+const DATA_CLASSES_JOIN = ';';
+
+function _dataClassesForFlow(flow, dataElementsById) {
+  const classes = new Set();
+  for (const deId of flow.dataElementIds ?? []) {
+    const de = dataElementsById.get(deId);
+    for (const c of de?.dataClasses ?? []) classes.add(c);
+  }
+  return [...classes].sort();
+}
+
+function _dimensionVerdict(flow, edgesById, dimension) {
+  const verdicts = (flow.edgeIds ?? [])
+    .map((id) => edgesById.get(id)?.protection?.[dimension]?.verdict)
+    .filter(Boolean);
+  return aggregateVerdicts(verdicts);
+}
+
+export function exportFlowsCSV(graph) {
+  const dataElementsById = new Map((graph.dataElements ?? []).map((d) => [d.id, d]));
+  const edgesById = new Map((graph.edges ?? []).map((e) => [e.id, e]));
+  const header = ['id', 'source', 'sink', 'dataClasses', 'transitVerdict', 'atRestVerdict', 'handlingVerdict', 'policyVerdict', 'coverageStatus'];
+  const rows = [header.join(',')];
+  for (const flow of graph.flows ?? []) {
+    rows.push([
+      esc(flow.id), esc(flow.source), esc(flow.sink),
+      esc(_dataClassesForFlow(flow, dataElementsById).join(DATA_CLASSES_JOIN)),
+      esc(_dimensionVerdict(flow, edgesById, 'transit')),
+      esc(_dimensionVerdict(flow, edgesById, 'atRest')),
+      esc(_dimensionVerdict(flow, edgesById, 'handling')),
+      esc(flow.policyVerdict), esc(flow.coverageStatus),
+    ].join(','));
+  }
+  return rows.join('\n');
+}

package/src/lineage/export-json.js

@@ -0,0 +1,238 @@
+// export-json.js — Milestone 4, sub-project JSON/CSV export.
+//
+// Deterministic JSON export of a DataFlowGraph v1 document, satisfying
+// PRD §17.5 (embed filtered-or-full graph; default-redacted; scan health/
+// scope/versions/limitations/generated timestamp; tamper-evident digest;
+// confidential-content disclosure) and AC-14 (export reproducibility).
+//
+// graph.graphId is scan-metadata-derived (dfg:<repo>:<commit>:<config>,
+// see ids.js's own `graphId()` — `dfg:${repo}:${commit}:${cfg}`), NOT a
+// content digest — confirmed by direct read before this module was
+// written. computeRunAttestation (posture/attestation.js) runs over
+// `findings: normalizeFindings(scan)` only, never `scan.lineageGraph` —
+// confirmed by direct read of both call sites in bin/agentic-security.js
+// (the `agentic-security scan` and `agentic-security ci` commands). This
+// module computes its own content digest instead of reusing either.
+
+import * as crypto from 'node:crypto';
+import { _redactGraph } from './redact-graph.js';
+
+// Canonicalization for the content digest.
+//
+// REVISED after the final whole-branch review of this sub-project found
+// the original hand-enumerated per-field allowlist (id/kind/subtype/
+// coverageStatus on a node, etc.) silently EXCLUDED most risk-bearing
+// content: mutating node.destination, node.externality, node.label,
+// flow.handling, edge.provenance, dataElement.aiContexts/.name, and
+// wiping graph.evidence/graph.transformations ENTIRELY all left the
+// digest unchanged — the worse of the two possible failure modes for a
+// "tamper-evident" claim (under-inclusion silently hides real tampering;
+// AC-14's own concern, over-inclusion breaking reproducibility on a
+// genuinely volatile field, is far easier to notice and fix, since it
+// fails the reproducibility test immediately rather than failing
+// silently in production).
+//
+// Rather than hand-list every field of every entity kind (exactly the
+// approach that produced the gap above — dataflow-graph.schema.json
+// alone declares 60+ distinct fields across 6 entity kinds, and a manual
+// list drifts the moment the schema gains a field), this canonicalizes
+// EVERYTHING in the graph via a small, explicit EXCLUDE list of the only
+// genuinely volatile/non-content fields in the schema (confirmed against
+// dataflow-graph.schema.json directly): `generatedAt` (graph-level,
+// explicitly excluded per AC-14's own wording), `scanHealth` (describes
+// the scan PROCESS — timing/duration-shaped, not the data content), and
+// `timestamp` (evidence-level, scan-time-of-observation, not content).
+// Everything else — every node/edge/flow/dataElement/evidence/
+// transformation field, including ones added to the schema after this
+// comment was written — is included by default, which is the safer
+// default for a tamper-evidence digest: a new field must be deliberately
+// ADDED to EXCLUDE_KEYS to be left out, rather than deliberately added to
+// an allowlist to be included.
+const EXCLUDE_KEYS = new Set(['generatedAt', 'scanHealth', 'timestamp']);
+const ENTITY_ARRAY_KEYS = new Set(['nodes', 'edges', 'flows', 'dataElements', 'evidence', 'transformations']);
+
+function _canon(value, keyHint) {
+  if (Array.isArray(value)) {
+    const mapped = value.map((v) => _canon(v));
+    // Only the six top-level entity arrays get sorted by id — they are
+    // graph-builder.js's own emission-sorted arrays (defensively re-sorted
+    // here rather than trusted), and sorting them makes the digest
+    // independent of array order. Nested arrays (edgeIds on a flow,
+    // fieldMappings on an edge, etc.) are NOT re-sorted: several are
+    // semantically ordered (a flow's edgeIds is a real path sequence,
+    // per ids.js's own pathId discriminator precedent) and re-sorting
+    // them would hide a genuine reordering of graph content.
+    if (keyHint && ENTITY_ARRAY_KEYS.has(keyHint)) {
+      mapped.sort((a, b) => {
+        const ai = a && typeof a === 'object' ? String(a.id ?? '') : String(a);
+        const bi = b && typeof b === 'object' ? String(b.id ?? '') : String(b);
+        // Plain codepoint comparison, not localeCompare — ICU-dependent
+        // collation can return 0 for genuinely distinct strings, which a
+        // digest sort must never do.
+        return ai < bi ? -1 : ai > bi ? 1 : 0;
+      });
+    }
+    return mapped;
+  }
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) {
+      if (EXCLUDE_KEYS.has(k)) continue;
+      out[k] = _canon(value[k], k);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function computeGraphDigest(graph) {
+  const canon = _canon(graph ?? {});
+  return crypto.createHash('sha256').update(JSON.stringify(canon)).digest('hex');
+}
+
+// --- Filter narrowing rule (the real design decision this module makes) ---
+//
+// `opts.filter` is `{nodeIds, edgeIds}` — the exact shape
+// `frontend/src/lib/focus-controls.js`'s nine graph-traversal functions
+// (showUpstream/showDownstream/showAllPaths/showShortestPath/
+// showExternalPathsOnly/showUnprotectedPathsOnly/showAliases/
+// showDisconnected) and `views/architecture-view.js`'s own
+// `resolveSelection` already produce and consume, confirmed by direct
+// read of `focus-controls.js` — reused verbatim rather than inventing a
+// third selection shape for export.
+//
+// nodes/edges narrow by direct id membership (the brief's own starter
+// code). flows/dataElements need their own rule, decided and grounded
+// here against the real flagship fixture (see export-json.test.js's
+// `filter narrows` tests):
+//
+//   FLOW survives iff BOTH (a) its `source` and `sink` node ids are
+//   still present in the filtered node set, AND (b) every id in its own
+//   `edgeIds[]` is still present in the filtered edge set (a full
+//   subset — not "at least one edge survives", not "some overlap").
+//
+//   Why not node-membership alone: the real fixture has two flows
+//   (flow:f7273b6e7b61, flow:154396169be8) sharing the identical
+//   source/sink pair (Web App -> Application Logs, the masked- and
+//   raw-log branches) but diverging on their SECOND edge. A filter
+//   admitting both endpoint nodes plus only ONE of the two flows' full
+//   edge sets must keep the flow whose edges are fully present and drop
+//   the other — node-membership alone cannot tell them apart, and would
+//   leave the dropped flow's own `edgeIds[]` naming an edge no longer in
+//   `graph.edges`, a dangling reference in the exported document.
+//   Why not edgeIds-subset alone: a flow's `source`/`sink` fields are
+//   themselves references into `graph.nodes`, independent of its edges
+//   (an edgeIds-only rule could keep a flow whose own declared source or
+//   sink node was filtered out). Requiring both is the only rule that
+//   guarantees every remaining flow is fully, referentially resolvable
+//   using only what's left in the filtered graph.
+//
+//   DATAELEMENTS narrow to the UNION of every id referenced by a
+//   surviving node's `dataElementIds[]` and every id referenced by a
+//   surviving flow's `dataElementIds[]` — not either alone. Node-only
+//   would leave a surviving flow's own `dataElementIds[]` dangling
+//   whenever a flow carries a data element none of its endpoint nodes'
+//   own list happens to name; flow-only would leave a surviving node's
+//   `dataElementIds[]` dangling whenever a filter keeps a node but drops
+//   every flow touching it (exactly the single-node filter test below,
+//   where zero flows survive but the one kept node still legitimately
+//   references three data elements). The union is the only rule that
+//   keeps every remaining reference resolvable.
+//
+//   `graph.transformations` is deliberately left UNFILTERED — out of
+//   scope for this decision (the brief names only flows/dataElements,
+//   and `frontend/src/lib/focus-controls.js` has no transformation-aware
+//   selection to mirror). An unfiltered transformation can end up
+//   referenced by nothing remaining (orphaned, not dangling — the
+//   opposite direction of the two problems narrowed above), a disclosed,
+//   deliberate non-goal of this filter, not an oversight.
+/**
+ * `validateFilterShape(filter) -> {valid, error}` — shape-validates an
+ * `opts.filter` value BEFORE it ever reaches `_filterGraph`. `_filterGraph`
+ * does `new Set(filter.nodeIds ?? [])`, and `new Set("not-an-array")`
+ * iterates a string as characters instead of throwing (a real JS
+ * foot-gun) — a malformed-but-truthy filter would otherwise silently
+ * produce an empty/wrong graph instead of a clear error. `undefined`
+ * (no filter at all) and `{}` (an empty, well-formed filter object) BOTH
+ * PASS VALIDATION — but they do NOT behave the same downstream. Final
+ * whole-branch review finding: `_filterGraph(graph, undefined)` returns
+ * the graph unchanged (`if (!filter) return graph;`), while
+ * `_filterGraph(graph, {})` narrows `nodeIds`/`edgeIds` to empty Sets and
+ * returns an EMPTY node/edge/flow/dataElement result — "valid shape" is
+ * not "equivalent meaning." Every caller of `validateFilterShape` must
+ * treat a validation pass as "safe to hand to `_filterGraph`," never as
+ * "produces the same result as omitting the filter."
+ * Extracted from `bin/agentic-security.js`'s own original inline
+ * `--filter` validation (verbatim logic, not rewritten) so the CLI,
+ * the `explore` server's new `POST /api/v1/query` endpoint, and the
+ * `dataflow_get_graph` MCP tool all share the identical protection
+ * rather than three independent, potentially-drifting copies.
+ */
+export function validateFilterShape(filter) {
+  if (filter === undefined) return { valid: true, error: null };
+  if (typeof filter !== 'object' || filter === null || Array.isArray(filter)
+    || (filter.nodeIds !== undefined && !Array.isArray(filter.nodeIds))
+    || (filter.edgeIds !== undefined && !Array.isArray(filter.edgeIds))) {
+    // Deliberately starts with "must be", not "filter must be" — the CLI
+    // wraps this with its own "--filter file \"X\"" prefix (see
+    // bin/agentic-security.js's own call site); the server/MCP call sites
+    // use it standalone, where "must be a JSON object..." already reads
+    // correctly with no file-path context needed.
+    return { valid: false, error: 'must be a JSON object of the form {"nodeIds":[...],"edgeIds":[...]} (both optional, but if present must be arrays)' };
+  }
+  return { valid: true, error: null };
+}
+
+export function _filterGraph(graph, filter) {
+  if (!filter) return graph;
+  const nodeIds = new Set(filter.nodeIds ?? []);
+  const edgeIds = new Set(filter.edgeIds ?? []);
+  const nodes = (graph.nodes ?? []).filter((n) => nodeIds.has(n.id));
+  const edges = (graph.edges ?? []).filter((e) => edgeIds.has(e.id));
+
+  const flows = (graph.flows ?? []).filter((f) => {
+    if (!nodeIds.has(f.source) || !nodeIds.has(f.sink)) return false;
+    return (f.edgeIds ?? []).every((id) => edgeIds.has(id));
+  });
+
+  const keptDataElementIds = new Set();
+  for (const n of nodes) for (const id of n.dataElementIds ?? []) keptDataElementIds.add(id);
+  for (const f of flows) for (const id of f.dataElementIds ?? []) keptDataElementIds.add(id);
+  const dataElements = (graph.dataElements ?? []).filter((d) => keptDataElementIds.has(d.id));
+
+  return { ...graph, nodes, edges, flows, dataElements };
+}
+
+export function exportGraphJSON(graph, opts = {}) {
+  const redact = opts.redact !== false;
+  const filtered = _filterGraph(graph, opts.filter);
+  const body = redact ? _redactGraph(filtered) : filtered;
+  return {
+    exportedAt: new Date().toISOString(),
+    schemaVersion: graph?.schemaVersion ?? null,
+    // Deliberate: the digest always identifies the SOURCE graph this
+    // export was taken from, never the filtered/redacted `graph:` body
+    // below — two different filters (or redact:true vs redact:false) of
+    // the same scan must report the same digest, since both are views
+    // of one underlying scan result, not independently-verifiable
+    // artifacts of their own. A caller wanting to verify `graph:`'s own
+    // content should re-filter/re-redact the source and compare, not
+    // treat this digest as a hash of the returned body.
+    digest: computeGraphDigest(graph),
+    // A SEPARATE digest of the emitted `graph:` body itself (final
+    // whole-branch review, M5 deliverable #8, B1) — this is the field a
+    // consumer that received ONLY this exported file (no access to the
+    // source graph) must compare against to detect tampering in transit.
+    // `digest` above cannot serve that purpose whenever redact/filter
+    // changed anything, which is the DEFAULT case (redact is on by
+    // default) — comparing `digest` against a recomputation over `body`
+    // is exactly the bug this field exists to prevent a future consumer
+    // from re-introducing.
+    bodyDigest: computeGraphDigest(body),
+    scope: graph?.scope ?? null,
+    coverage: graph?.coverage ?? null,
+    limitations: graph?.limitations ?? [],
+    confidential: true,
+    graph: body,
+  };
+}

package/src/lineage/export-privacy.js

@@ -0,0 +1,258 @@
+// export-privacy.js — Milestone 4 deliverable #10 (DFG-020): graph-derived
+// DPIA/RoPA export, migrating off the Layer-2 taint engine's
+// dataflow/privacy-taint.js#emitDpiaArtifact / privacy-governance.js#emitRopaArtifact
+// (which derive from piiFields, name-in-argument classification with no
+// path/alias/field-mapping precision) onto the real DataFlowGraph v1's
+// field-identity-tracked flows.
+//
+// Reuses frontend/src/views/privacy-view.js#computePrivacyViewModel
+// DIRECTLY (the first live scanner/ -> frontend/ module import in this
+// codebase, confirmed safe: that module only touches document/window
+// inside renderPrivacyView's own function body, never at module top
+// level, so importing it from plain Node never executes any DOM code)
+// rather than re-deriving lifecycle-stage/dataClass/protection-verdict
+// row computation a second time. This mirrors this package's own
+// established discipline of reusing an already-correct, already-tested
+// computation rather than a parallel copy that can drift.
+//
+// Both emit functions mirror their taint-engine-era predecessors'
+// structure/wording (GDPR Art. 35 framing for the DPIA, the
+// register-not-narrative RoPA table) but are populated from real graph
+// rows.
+//
+// Filter wiring: opts.filter is the SAME {nodeIds, edgeIds} shape every
+// other `dataflow export` format uses (export-json.js's own convention).
+// It filters the GRAPH itself, via export-json.js's _filterGraph, BEFORE
+// computePrivacyViewModel ever runs — never threaded into
+// computePrivacyViewModel's own state.filters parameter, which expects a
+// completely different shape (per-facet selected-value arrays, e.g.
+// {dataClass: [...]}) and would silently no-op if handed {nodeIds, edgeIds}.
+
+import { computePrivacyViewModel } from '../../../frontend/src/views/privacy-view.js';
+import { GOVERNANCE_FIELDS, MANUAL_REQUIRED } from '../dataflow/privacy-governance.js';
+import { _filterGraph } from './export-json.js';
+
+function _emptyState() {
+  return { selectedId: null };
+}
+
+/**
+ * Collapse embedded newlines to spaces. Every value interpolated into a
+ * Markdown line below can originate from operator-supplied prose (a
+ * governance field from .agentic-security/privacy-governance.json) or
+ * from source-derived identifiers — neither is trusted not to contain a
+ * literal newline, which would otherwise let the value break out of its
+ * line and inject arbitrary Markdown (e.g. a fake heading) mid-document.
+ */
+function _mdInline(value) {
+  return String(value).replace(/\r\n|\r|\n/g, ' ');
+}
+
+/** _mdInline, plus pipe-escaping for a Markdown table cell — an
+ * unescaped `|` in a cell value shifts every later column in that row.
+ * Backslashes are escaped FIRST: a value already containing a literal
+ * `\|` (e.g. a Windows path fragment, a regex snippet) would otherwise
+ * become `\\|` — in Markdown that reads as an escaped backslash followed
+ * by a still-live, still-unescaped `|` column delimiter. */
+function _mdCell(value) {
+  return _mdInline(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+
+/** Wrap a value in a Markdown inline-code span, safe even when the value
+ * itself contains backticks. CommonMark's own general rule: the fence
+ * must be one backtick longer than the longest run of consecutive
+ * backticks anywhere in the content, padded with a space on each side —
+ * a fixed double-backtick fence (this function's own earlier version)
+ * is not safe against a value containing 2+ CONSECUTIVE backticks, since
+ * the value's own run would then close the span early. */
+function _mdCode(value) {
+  const s = _mdInline(value);
+  const runs = s.match(/`+/g);
+  const maxRun = runs ? Math.max(...runs.map((r) => r.length)) : 0;
+  if (maxRun === 0) return `\`${s}\``;
+  const fence = '`'.repeat(maxRun + 1);
+  return `${fence} ${s} ${fence}`;
+}
+
+function _scopedViewModel(graph, filter) {
+  const scopedGraph = filter ? _filterGraph(graph, filter) : graph;
+  return computePrivacyViewModel(scopedGraph, _emptyState(), null);
+}
+
+/**
+ * Group computePrivacyViewModel's rows by data class, mirroring
+ * emitDpiaArtifact's own grouping.
+ *
+ * Task-2 review finding (non-blocking, fixed): the old taint-engine
+ * emitDpiaArtifact's identical grouping code was safe only because its
+ * input (piiFields) was pre-filtered to classified fields by
+ * construction — it never saw an unclassified field at all. This
+ * function draws from EVERY graph flow via computePrivacyViewModel, so a
+ * bare `for (const cls of row.dataClasses)` silently drops any flow
+ * whose dataClasses is [] from the whole document — not merely
+ * ungrouped, genuinely INVISIBLE, with no count, no mention, nothing —
+ * for a document whose entire purpose is a complete inventory. RoPA's
+ * own sibling loop already falls back to a '(unclassified)' bucket
+ * (mirroring the same sentinel resolveGovernanceRefs's default hook
+ * uses in coverage.js, Task 1's own fix round); mirrored here so the two
+ * artifacts never disagree about how many real flows exist in scope.
+ */
+function _groupRowsByClass(rows) {
+  const grouped = new Map();
+  for (const row of rows) {
+    const classes = row.dataClasses.length ? row.dataClasses : ['(unclassified)'];
+    for (const cls of classes) {
+      let g = grouped.get(cls);
+      if (!g) { g = []; grouped.set(cls, g); }
+      g.push(row);
+    }
+  }
+  return grouped;
+}
+
+/**
+ * Graph-derived DPIA (Data Protection Impact Assessment) — narrative
+ * Markdown, mirroring dataflow/privacy-taint.js#emitDpiaArtifact's own
+ * structure. opts.filter scopes to a subset of the graph (the "filtered
+ * ... from the selected graph scope" requirement, PRD 7.4).
+ */
+export function emitGraphDpiaArtifact(graph, opts = {}) {
+  const viewModel = _scopedViewModel(graph, opts.filter);
+  const visibleRows = viewModel.rows.filter((r) => r.visible !== false);
+  const grouped = _groupRowsByClass(visibleRows);
+
+  const lines = [];
+  lines.push('# Data Protection Impact Assessment (DPIA)');
+  lines.push('');
+  lines.push(`Generated by agentic-security scanner (graph-derived) on ${(opts.generatedAt ?? new Date().toISOString()).slice(0, 10)}.`);
+  lines.push('');
+  lines.push('This is an automated DPIA scaffold derived from real data-flow analysis');
+  lines.push('(field identity, path provenance, and protection verdicts). It must be');
+  lines.push('reviewed and completed by a privacy officer before use.');
+  lines.push('');
+  lines.push('Governance fields reflect .agentic-security/privacy-governance.json as');
+  lines.push('of the scan that produced this graph, not as of the moment this document');
+  lines.push('was exported — re-scan (with lineage deep mode enabled) after editing');
+  lines.push('that config, then re-export, to pick up the change.');
+  lines.push('');
+  if (grouped.size === 0) {
+    lines.push('No regulated data classes were identified in this graph scope.');
+    return lines.join('\n');
+  }
+  lines.push('## Data classes identified');
+  lines.push('');
+  for (const [cls, rows] of grouped) {
+    lines.push(`### ${_mdInline(cls)} (${rows.length} flow(s))`);
+    lines.push('');
+    for (const row of rows.slice(0, 20)) {
+      const crossClassNote = row.dataClasses.length > 1 ? ` (also: ${row.dataClasses.filter((c) => c !== cls).map(_mdInline).join(', ')})` : '';
+      lines.push(`- ${_mdCode(row.dataElementName)} — ${_mdInline(row.sourceCategory ?? 'unknown source')} -> ${_mdInline(row.sinkCategory ?? 'unknown sink')} (protection: ${_mdInline(row.protectionSummary)})${crossClassNote}`);
+    }
+    if (rows.length > 20) lines.push(`- ... and ${rows.length - 20} more`);
+    lines.push('');
+    lines.push(`**Governance fields for ${_mdInline(cls)}:**`);
+    lines.push('');
+    // Worst-case-wins across this class's own rows, the same tie-break
+    // Task 1's resolveGovernanceRefs default uses — never silently pick
+    // whichever row happened to be iterated last.
+    const merged = {};
+    for (const row of rows) {
+      for (const field of GOVERNANCE_FIELDS) {
+        const r = row.governanceRefs?.[field];
+        if (!r) continue;
+        if (!merged[field] || merged[field].source === 'manual_required') merged[field] = r;
+      }
+    }
+    // A flow with >1 dataClasses already carries a single governanceRefs
+    // record merged (worst-case-wins) across ALL of its own classes back
+    // at mint time (coverage.js#resolveGovernanceRefs) — this section can
+    // only re-merge that already-merged record across rows, never recover
+    // per-class distinctness that was lost earlier. Disclose it rather
+    // than silently presenting a cross-class value as if it were specific
+    // to this one class.
+    if (rows.some((row) => row.dataClasses.length > 1)) {
+      lines.push(`_Note: some flows in this section also belong to other data classes; the governance values below are each flow's own record merged across ALL of its classes, not verified as specific to ${_mdInline(cls)} alone._`);
+      lines.push('');
+    }
+    for (const field of GOVERNANCE_FIELDS) {
+      const r = merged[field] ?? { value: MANUAL_REQUIRED, source: 'manual_required' };
+      lines.push(`- ${field}: ${_mdCode(r.value)}${r.source === 'operator_provided' ? ' (operator-provided)' : ''}`);
+    }
+    lines.push('');
+  }
+  lines.push('## Regulatory framework mapping');
+  lines.push('');
+  lines.push('- **GDPR Art. 35** — DPIA required when processing is likely to result in high risk to data subjects.');
+  lines.push('- **CCPA 1798.130** — Notice + access rights for collected personal information.');
+  if (grouped.has('PHI')) lines.push('- **HIPAA 164.308** — Administrative safeguards for ePHI access.');
+  if (grouped.has('PCI')) lines.push('- **PCI DSS Req. 3** — Protect stored cardholder data.');
+  lines.push('');
+  lines.push('This document organizes automated technical assessment evidence. It does');
+  lines.push("not certify compliance and is not a legal determination — see the graph's");
+  lines.push('own `disclaimer`/`limitations` fields for the full caveat.');
+  return lines.join('\n');
+}
+
+/**
+ * Graph-derived RoPA (Record of Processing Activities, GDPR Art. 30) —
+ * tabular Markdown register, mirroring
+ * dataflow/privacy-governance.js#emitRopaArtifact's own format, but ONE
+ * ROW PER (dataClass x flow) rather than per dataClass alone — a real,
+ * disclosed precision improvement the graph's own per-flow sink/
+ * destination resolution makes possible (the taint-engine version has no
+ * per-flow destination-resolution concept at all).
+ */
+export function emitGraphRopaArtifact(graph, opts = {}) {
+  const viewModel = _scopedViewModel(graph, opts.filter);
+  const visibleRows = viewModel.rows.filter((r) => r.visible !== false);
+
+  const lines = [];
+  lines.push('# Record of Processing Activities (RoPA) — GDPR Art. 30, graph-derived');
+  lines.push('');
+  lines.push(`Generated by agentic-security scanner (graph-derived) on ${(opts.generatedAt ?? new Date().toISOString()).slice(0, 10)}. Every governance`);
+  lines.push('field below is either supplied by an operator');
+  lines.push('(.agentic-security/privacy-governance.json) or marked');
+  lines.push(`\`${MANUAL_REQUIRED}\` — none are inferable from source code, and none are`);
+  lines.push(`guessed. A privacy officer must fill in every \`${MANUAL_REQUIRED}\` cell`);
+  lines.push('before this document is usable as a real RoPA.');
+  lines.push('');
+  lines.push('Governance fields reflect .agentic-security/privacy-governance.json as');
+  lines.push('of the scan that produced this graph, not as of the moment this document');
+  lines.push('was exported — re-scan (with lineage deep mode enabled) after editing');
+  lines.push('that config, then re-export, to pick up the change.');
+  lines.push('');
+  if (visibleRows.length === 0) {
+    lines.push('No regulated data flows were identified in this graph scope.');
+    return lines.join('\n');
+  }
+  const header = ['Data class', 'Field', 'Source', 'Destination', 'Protection', ...GOVERNANCE_FIELDS];
+  lines.push(`| ${header.join(' | ')} |`);
+  lines.push(`|${header.map(() => '---').join('|')}|`);
+  let gapCount = 0;
+  let rowCount = 0;
+  let crossClassRows = false;
+  for (const row of visibleRows) {
+    for (const cls of row.dataClasses.length ? row.dataClasses : ['(unclassified)']) {
+      rowCount++;
+      const fieldValues = GOVERNANCE_FIELDS.map((f) => {
+        const r = row.governanceRefs?.[f] ?? { value: MANUAL_REQUIRED, source: 'manual_required' };
+        if (r.source === 'manual_required') gapCount++;
+        return r.value;
+      });
+      const isCrossClass = row.dataClasses.length > 1;
+      if (isCrossClass) crossClassRows = true;
+      const clsCell = isCrossClass ? `${cls}*` : cls;
+      const cells = [clsCell, row.dataElementName, row.sourceCategory ?? 'unknown source', row.sinkCategory ?? 'unknown destination', row.protectionSummary, ...fieldValues];
+      lines.push(`| ${cells.map(_mdCell).join(' | ')} |`);
+    }
+  }
+  lines.push('');
+  if (crossClassRows) {
+    lines.push('\\* This flow also belongs to other data classes; governance fields are');
+    lines.push("this flow's own record merged across ALL of its classes, not verified as");
+    lines.push('specific to the data class shown in this row alone.');
+    lines.push('');
+  }
+  lines.push(`${gapCount} field(s) across ${rowCount} row(s) (${visibleRows.length} flow(s)) require manual input.`);
+  return lines.join('\n');
+}