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

package/dist/frontend/src/views/inventory-view.js

@@ -0,0 +1,292 @@
+// Inventory View: PRD §7.6's 11 required inventory categories. Split into
+// pure computeInventoryViewModel() (each per-category compute function
+// producing {columns, rows}) and thin renderInventoryView() (DOM-building
+// via el()/clear()), mirroring every other view in src/views/.
+
+import { worstVerdict } from '../lib/protection-visual.js';
+import { AI_SUBTYPES } from '../lib/flow-path.js';
+import { INVENTORY_TABLES } from '../lib/state.js';
+import { el, clear } from '../lib/dom.js';
+import { matchesFilters } from '../lib/row-filters.js';
+
+const TABLE_LABELS = {
+  sources: 'Sources',
+  sinks: 'Sinks',
+  fields: 'Fields / data elements',
+  externalDestinations: 'External destinations',
+  stores: 'Stores',
+  aiSystems: 'AI systems & processing contexts',
+  transformations: 'Transformations',
+  unprotectedEdges: 'Unprotected or unknown edges',
+  policyPermittedFlows: 'Policy-permitted flows',
+  manualGovernanceGaps: 'Manual governance gaps',
+  unsupportedCandidates: 'Unsupported or unresolved candidates',
+};
+
+const UNPROTECTED_TIERS = new Set(['unprotected', 'mixed', 'unknown']);
+
+function edgeWorstVerdict(edge) {
+  return worstVerdict([edge.protection.transit.verdict, edge.protection.atRest.verdict, edge.protection.handling.verdict]);
+}
+
+function nodeLabelFor(graph, nodeId) {
+  return graph.nodes.find((n) => n.id === nodeId)?.label ?? 'unknown';
+}
+
+// The same per-flow filter-facet properties privacy-view.js's
+// computePrivacyRow() attaches, computed the same way (this flow's own
+// resolved edges, aggregated per-dimension via worstVerdict()), for
+// Inventory's two flow-shaped categories (policyPermittedFlows,
+// manualGovernanceGaps' "Flow"-subject rows) only. worstVerdict() always
+// returns a real verdict string (never null/undefined, even for an empty
+// edge list), so the three verdict properties are always set
+// unconditionally; sourceCategory/sinkCategory/destinationExternality are
+// only set when a real, non-null value exists, per the same rule
+// computePrivacyRow() follows.
+function computeFlowFilterProperties(graph, flow) {
+  const pathEdges = flow.edgeIds.map((edgeId) => graph.edges.find((e) => e.id === edgeId)).filter(Boolean);
+  const sourceNode = graph.nodes.find((n) => n.id === flow.source);
+  const sinkNode = graph.nodes.find((n) => n.id === flow.sink);
+  return {
+    transitVerdict: worstVerdict(pathEdges.map((e) => e.protection.transit.verdict)),
+    atRestVerdict: worstVerdict(pathEdges.map((e) => e.protection.atRest.verdict)),
+    handlingVerdict: worstVerdict(pathEdges.map((e) => e.protection.handling.verdict)),
+    policyVerdict: flow.policyVerdict,
+    ...(sourceNode?.subtype ? { sourceCategory: sourceNode.subtype } : {}),
+    ...(sinkNode?.subtype ? { sinkCategory: sinkNode.subtype } : {}),
+    ...(sinkNode?.externality?.value ? { destinationExternality: sinkNode.externality.value } : {}),
+  };
+}
+
+const TABLE_COMPUTE = {
+  sources: (graph) => ({
+    columns: ['Label', 'Category', 'Coverage', 'Externality'],
+    rows: graph.nodes.filter((n) => n.kind === 'source').map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: [n.label, n.subtype ?? '—', n.coverageStatus, n.externality?.value ?? 'unknown'],
+    })),
+  }),
+  sinks: (graph) => ({
+    columns: ['Label', 'Category', 'Coverage', 'Externality'],
+    rows: graph.nodes.filter((n) => n.kind === 'sink').map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: [n.label, n.subtype ?? '—', n.coverageStatus, n.externality?.value ?? 'unknown'],
+    })),
+  }),
+  fields: (graph) => ({
+    columns: ['Name', 'Data classes', 'AI contexts'],
+    rows: graph.dataElements.map((d) => ({
+      id: d.id, selectableId: d.id,
+      cells: [d.name, (d.dataClasses ?? []).join(', ') || '—', (d.aiContexts ?? []).join(', ') || '—'],
+      dataClasses: d.dataClasses ?? [],
+    })),
+  }),
+  externalDestinations: (graph) => ({
+    columns: ['Label', 'Kind', 'Resolution status', 'Literal value'],
+    rows: graph.nodes.filter((n) => n.externality?.value === 'external').map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: [n.label, n.kind, n.destination?.resolutionStatus ?? 'unknown', n.destination?.literalValue ?? '—'],
+    })),
+  }),
+  stores: (graph) => ({
+    columns: ['Label', 'Operation', 'Columns'],
+    rows: graph.nodes.filter((n) => n.kind === 'store').map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: [n.label, n.storeDetail?.operation ?? 'unknown', (n.storeDetail?.columns ?? []).join(', ') || '—'],
+    })),
+  }),
+  aiSystems: (graph) => {
+    const aiNodes = graph.nodes.filter((n) => n.subtype && AI_SUBTYPES.has(n.subtype)).map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: ['Node', n.label, n.subtype],
+    }));
+    const aiDataElements = graph.dataElements.filter((d) => (d.aiContexts ?? []).length > 0).map((d) => ({
+      id: d.id, selectableId: d.id,
+      cells: ['Data element', d.name, (d.aiContexts ?? []).join(', ')],
+    }));
+    return { columns: ['Subject', 'Label', 'Category / context'], rows: [...aiNodes, ...aiDataElements] };
+  },
+  transformations: (graph) => ({
+    columns: ['Kind', 'Reversibility'],
+    rows: graph.transformations.map((t) => ({
+      id: t.id, selectableId: t.id,
+      cells: [t.kind, t.reversibility],
+    })),
+  }),
+  unprotectedEdges: (graph) => ({
+    columns: ['From', 'To', 'Transit', 'At rest', 'Handling', 'Worst verdict'],
+    rows: graph.edges.filter((e) => UNPROTECTED_TIERS.has(edgeWorstVerdict(e))).map((e) => ({
+      id: e.id, selectableId: e.id,
+      cells: [nodeLabelFor(graph, e.from), nodeLabelFor(graph, e.to), e.protection.transit.verdict, e.protection.atRest.verdict, e.protection.handling.verdict, edgeWorstVerdict(e)],
+    })),
+  }),
+  policyPermittedFlows: (graph) => ({
+    columns: ['Field', 'Source', 'Sink', 'Policy verdict'],
+    rows: graph.flows.filter((f) => f.policyVerdict === 'permitted').map((f) => {
+      const dataElement = graph.dataElements.find((d) => f.dataElementIds.includes(d.id));
+      return {
+        id: f.id, selectableId: f.id,
+        cells: [dataElement?.name ?? 'unknown field', nodeLabelFor(graph, f.source), nodeLabelFor(graph, f.sink), f.policyVerdict],
+        dataClasses: dataElement?.dataClasses ?? [],
+        protectionSummary: f.protectionSummary,
+        ...computeFlowFilterProperties(graph, f),
+      };
+    }),
+  }),
+  manualGovernanceGaps: (graph) => {
+    const manualFlows = graph.flows.filter((f) => f.policyVerdict === 'manual_review_required').map((f) => {
+      const dataElement = graph.dataElements.find((d) => f.dataElementIds.includes(d.id));
+      return {
+        id: f.id, selectableId: f.id,
+        cells: ['Flow', dataElement?.name ?? 'unknown field', 'policyVerdict: manual_review_required'],
+        dataClasses: dataElement?.dataClasses ?? [],
+        protectionSummary: f.protectionSummary,
+        ...computeFlowFilterProperties(graph, f),
+      };
+    });
+    const manualNodes = graph.nodes.filter((n) => n.coverageStatus === 'manual').map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: ['Node', n.label, 'coverageStatus: manual'],
+    }));
+    const manualEdges = graph.edges.filter((e) => e.coverageStatus === 'manual').map((e) => ({
+      id: e.id, selectableId: e.id,
+      cells: ['Edge', `${nodeLabelFor(graph, e.from)} → ${nodeLabelFor(graph, e.to)}`, 'coverageStatus: manual'],
+    }));
+    return { columns: ['Subject', 'Label', 'Reason'], rows: [...manualFlows, ...manualNodes, ...manualEdges] };
+  },
+  unsupportedCandidates: (graph) => ({
+    columns: ['Label', 'Kind', 'Coverage status', 'Reason'],
+    rows: graph.nodes.filter((n) => n.kind === 'unresolved' || n.coverageStatus === 'unsupported' || n.coverageStatus === 'candidate').map((n) => ({
+      id: n.id, selectableId: n.id,
+      cells: [n.label, n.kind, n.coverageStatus, n.coverageReason ?? '—'],
+    })),
+  }),
+};
+
+// Categories whose rows carry the properties filter-rail.js's three chip
+// groups filter on (dataClasses / protectionSummary / AI relevance). Wired
+// per docs/superpowers/plans/2026-09-01-data-flow-explorer-m3-inventory-scoping.md's
+// decision 4 — deliberately not every category; see that doc before
+// changing this set.
+const FILTERABLE_TABLES = new Set(['fields', 'policyPermittedFlows', 'manualGovernanceGaps']);
+
+// Milestone 3, sub-project M3-UX-Query, Task 4. The query language's
+// compileQuery predicate is fundamentally FLOW-scoped (query-language.js's
+// own header comment: "the predicate operates on a FLOW"), but Inventory's
+// 11 categories are a mix of flow/node/edge/dataElement/transformation rows.
+// Rather than special-case each category, this looks up a real flow by the
+// row's own id — which only resolves for rows whose `id` genuinely IS a
+// flow id (policyPermittedFlows' rows, and manualGovernanceGaps' "Flow"-
+// subject rows, both of which use `id: f.id`). A row with no corresponding
+// flow (a source/sink/store/dataElement/transformation/node/edge row) has
+// nothing for the query predicate to test against, so the query has no
+// effect there and the row's visibility is governed only by the existing
+// dataClass/protection filters — an honest, disclosed scope limitation, not
+// a bug: this DSL was never designed to describe a bare node or edge.
+function rowMatchesQuery(graph, row, queryPredicate) {
+  if (!queryPredicate) return true;
+  const flow = graph.flows.find((f) => f.id === row.id);
+  if (!flow) return true;
+  return queryPredicate(flow);
+}
+
+/**
+ * @param {object} graph
+ * @param {object} state
+ * @param {((flow: object) => boolean) | null} [queryPredicate] - see
+ *   rowMatchesQuery's own comment above. Applied as an ADDITIONAL condition
+ *   alongside the existing dataClass/protection filters, independent of
+ *   whether the active table is in FILTERABLE_TABLES (query narrowing is
+ *   orthogonal to the filter-rail's own chip-based facets). Omitted/null
+ *   (every pre-existing caller/test) matches every row, so behavior is
+ *   unchanged for anyone not passing it.
+ */
+export function computeInventoryViewModel(graph, state, queryPredicate = null) {
+  const activeTable = INVENTORY_TABLES.includes(state.table) ? state.table : INVENTORY_TABLES[0];
+  const tables = INVENTORY_TABLES.map((id) => ({
+    id, label: TABLE_LABELS[id],
+    count: TABLE_COMPUTE[id](graph).rows.length,
+  }));
+
+  const { columns, rows: rawRows } = TABLE_COMPUTE[activeTable](graph);
+  const filterable = FILTERABLE_TABLES.has(activeTable);
+  const rows = rawRows.map((row) => ({
+    ...row,
+    selected: row.id === state.selectedId,
+    visible: (filterable ? matchesFilters(row, state.filters ?? {}) : true) && rowMatchesQuery(graph, row, queryPredicate),
+  }));
+
+  return { tables, activeTable, columns, rows, filterable };
+}
+
+function renderSubNav(viewModel, onTableChange) {
+  const buttons = viewModel.tables.map((t) =>
+    el(
+      'button',
+      {
+        class: 'inventory-subnav-button',
+        'data-table-id': t.id,
+        'data-active': String(t.id === viewModel.activeTable),
+        'aria-pressed': String(t.id === viewModel.activeTable),
+        onClick: () => onTableChange(t.id),
+      },
+      `${t.label} (${t.count})`,
+    ),
+  );
+  return el('div', { class: 'inventory-subnav' }, buttons);
+}
+
+function renderRow(row, onSelect) {
+  return el(
+    'tr',
+    {
+      class: 'inventory-row',
+      'data-selected': String(row.selected),
+      'data-visible': String(row.visible),
+      tabindex: '0',
+      role: 'button',
+      'aria-label': `${row.cells[0]}${row.selected ? ', selected' : ''}`,
+      onClick: () => row.selectableId && onSelect(row.selectableId),
+      onKeydown: (evt) => {
+        if ((evt.key === 'Enter' || evt.key === ' ') && row.selectableId) {
+          evt.preventDefault();
+          onSelect(row.selectableId);
+        }
+      },
+    },
+    row.cells.map((cellText) => el('td', {}, cellText)),
+  );
+}
+
+function sortRows(rows, columnIndex, direction) {
+  const sorted = [...rows].sort((a, b) => {
+    const cmp = String(a.cells[columnIndex]).localeCompare(String(b.cells[columnIndex]));
+    return direction === 'asc' ? cmp : -cmp;
+  });
+  return sorted;
+}
+
+/**
+ * @param {ReturnType<typeof computeInventoryViewModel>} viewModel
+ * @param {HTMLElement} canvasEl
+ * @param {(selectableId: string) => void} onSelect
+ * @param {(tableId: string) => void} onTableChange
+ */
+export function renderInventoryView(viewModel, canvasEl, onSelect, onTableChange) {
+  clear(canvasEl);
+
+  const subNav = renderSubNav(viewModel, onTableChange);
+
+  let sortState = { columnIndex: null, direction: 'asc' };
+  const headerRow = el('tr', {}, viewModel.columns.map((col, i) =>
+    el('th', { onClick: () => {
+      sortState = sortState.columnIndex === i ? { columnIndex: i, direction: sortState.direction === 'asc' ? 'desc' : 'asc' } : { columnIndex: i, direction: 'asc' };
+      const sortedRows = sortRows(viewModel.rows, sortState.columnIndex, sortState.direction);
+      renderInventoryView({ ...viewModel, rows: sortedRows }, canvasEl, onSelect, onTableChange);
+    } }, col),
+  ));
+  const bodyRows = viewModel.rows.map((row) => renderRow(row, onSelect));
+  const table = el('table', { class: 'inventory-table' }, [el('thead', {}, headerRow), el('tbody', {}, bodyRows)]);
+
+  canvasEl.appendChild(el('div', { class: 'inventory-view' }, [subNav, table]));
+}

package/dist/frontend/src/views/privacy-view.js

@@ -0,0 +1,172 @@
+import { flowPathNodeIds, isAiRelevantFlow } from '../lib/flow-path.js';
+import { el, clear } from '../lib/dom.js';
+import { protectionVisual, worstVerdict } from '../lib/protection-visual.js';
+import { matchesFilters } from '../lib/row-filters.js';
+
+export const LIFECYCLE_STAGES = Object.freeze(['collection', 'processing', 'storage', 'sharing', 'retention', 'deletion']);
+
+export function stageForNode(node) {
+  return LIFECYCLE_STAGES.includes(node.lifecycleStages?.[0]) ? node.lifecycleStages[0] : 'processing';
+}
+
+export function computePrivacyRow(graph, flow) {
+  const dataElement = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+  const pathNodeIds = flowPathNodeIds(graph, flow);
+  const pathNodes = graph.nodes.filter((n) => pathNodeIds.has(n.id));
+  // This flow's own resolved edges — the same per-edgeId lookup
+  // flowPathNodeIds() already performs internally, applied here to keep the
+  // edge objects (rather than just the node ids) so the three protection
+  // dimensions below can be aggregated per-flow via worstVerdict().
+  const pathEdges = flow.edgeIds.map((edgeId) => graph.edges.find((e) => e.id === edgeId)).filter(Boolean);
+
+  const stageCells = LIFECYCLE_STAGES.map((stage) => ({
+    stage,
+    nodeLabels: pathNodes.filter((n) => stageForNode(n) === stage).map((n) => n.label),
+  }));
+
+  const sourceNode = graph.nodes.find((n) => n.id === flow.source);
+  const sinkNode = graph.nodes.find((n) => n.id === flow.sink);
+
+  return {
+    flowId: flow.id,
+    dataElementName: dataElement?.name ?? 'unknown field',
+    dataClasses: dataElement?.dataClasses ?? [],
+    stageCells,
+    governanceRefs: flow.governanceRefs ?? {},
+    protectionSummary: flow.protectionSummary,
+    policyVerdict: flow.policyVerdict,
+    isAiRelevant: isAiRelevantFlow(graph, flow),
+    // worstVerdict() always returns a real verdict string (falling back to
+    // 'not_assessed', never null/undefined) even for an empty edge list, so
+    // these three are always set unconditionally — unlike sourceCategory/
+    // sinkCategory/destinationExternality below, there is no genuinely-absent
+    // case to guard against.
+    transitVerdict: worstVerdict(pathEdges.map((e) => e.protection.transit.verdict)),
+    atRestVerdict: worstVerdict(pathEdges.map((e) => e.protection.atRest.verdict)),
+    handlingVerdict: worstVerdict(pathEdges.map((e) => e.protection.handling.verdict)),
+    // Only set when a real, non-null value exists — keeps matchesFilters's
+    // own "property absent = unaffected, never a hide" semantics clean
+    // rather than introducing a third (present-but-null) state.
+    ...(sourceNode?.subtype ? { sourceCategory: sourceNode.subtype } : {}),
+    ...(sinkNode?.subtype ? { sinkCategory: sinkNode.subtype } : {}),
+    ...(sinkNode?.externality?.value ? { destinationExternality: sinkNode.externality.value } : {}),
+  };
+}
+
+/**
+ * @param {object} graph
+ * @param {object} state
+ * @param {((flow: object) => boolean) | null} [queryPredicate] - Milestone 3,
+ *   sub-project M3-UX-Query, Task 4: the query language's compiled predicate
+ *   (lib/query-language.js's `compileQuery`), applied here as an ADDITIONAL
+ *   condition alongside the existing dataClass/protection/ai filters — a row
+ *   must pass BOTH to stay visible. Omitted/null (every pre-existing
+ *   caller/test) means "no query active," matching every row, so behavior
+ *   is unchanged for anyone not passing it.
+ */
+export function computePrivacyViewModel(graph, state, queryPredicate = null) {
+  const matchesQuery = queryPredicate ?? (() => true);
+  const rows = graph.flows.map((flow) => {
+    const row = computePrivacyRow(graph, flow);
+    return {
+      ...row,
+      selected: row.flowId === state.selectedId,
+      visible: matchesFilters(row, state.filters ?? {}) && matchesQuery(flow),
+    };
+  });
+  return { stages: LIFECYCLE_STAGES, rows };
+}
+
+const CLASS_BADGE_COLOR_VAR = { PII: '--class-pii', PHI: '--class-phi', PCI: '--class-pci' };
+
+/**
+ * @param {ReturnType<typeof computePrivacyViewModel>} viewModel
+ * @param {HTMLElement} canvasEl
+ * @param {(flowId: string) => void} onSelectFlow
+ */
+export function renderPrivacyView(viewModel, canvasEl, onSelectFlow) {
+  clear(canvasEl);
+
+  const headerRow = el('tr', {}, [
+    el('th', {}, 'Field'),
+    el('th', {}, 'Protection'),
+    ...viewModel.stages.map((stage) => el('th', {}, stage.charAt(0).toUpperCase() + stage.slice(1))),
+  ]);
+
+  const bodyRows = viewModel.rows.map((row) => renderPrivacyRow(row, onSelectFlow));
+
+  const table = el('table', { class: 'privacy-table' }, [el('thead', {}, headerRow), el('tbody', {}, bodyRows)]);
+
+  canvasEl.appendChild(el('div', { class: 'privacy-view' }, table));
+}
+
+function renderPrivacyRow(row, onSelectFlow) {
+  const classBadges = row.dataClasses.map((cls) =>
+    el('span', { class: 'privacy-class-badge', style: `color: var(${CLASS_BADGE_COLOR_VAR[cls] ?? '--text-secondary'}); border-color: var(${CLASS_BADGE_COLOR_VAR[cls] ?? '--border-default'})` }, cls),
+  );
+
+  const fieldCell = el('td', { class: 'privacy-field-cell' }, [
+    el('div', {}, row.dataElementName),
+    el('div', {}, classBadges),
+    row.isAiRelevant ? el('span', { class: 'privacy-governance-badge', style: 'border-color: var(--context-ai); color: var(--context-ai)' }, 'AI processing') : null,
+  ]);
+
+  const visual = protectionVisual(row.protectionSummary);
+  const protectionCell = el(
+    'td',
+    { class: 'privacy-protection-cell' },
+    el('span', { style: `border-color: var(${visual.colorVar}); color: var(${visual.colorVar})` }, `${visual.glyph} ${visual.label}`),
+  );
+
+  const stageCells = row.stageCells.map((cell) => renderStageCell(cell, row));
+
+  return el(
+    'tr',
+    {
+      class: 'privacy-row',
+      'data-selected': String(row.selected),
+      'data-visible': String(row.visible),
+      tabindex: '0',
+      role: 'button',
+      'aria-label': `${row.dataElementName} lifecycle, ${row.protectionSummary}${row.selected ? ', selected' : ''}`,
+      onClick: () => onSelectFlow(row.flowId),
+      onKeydown: (evt) => {
+        if (evt.key === 'Enter' || evt.key === ' ') {
+          evt.preventDefault();
+          onSelectFlow(row.flowId);
+        }
+      },
+    },
+    [fieldCell, protectionCell, ...stageCells],
+  );
+}
+
+function renderStageCell(cell, row) {
+  const children = [];
+  if (cell.nodeLabels.length > 0) {
+    children.push(el('div', {}, cell.nodeLabels.join(', ')));
+  } else {
+    children.push(el('div', { class: 'privacy-stage-cell-empty-label' }, '—'));
+  }
+
+  // Governance facts are shown once, on whichever stage cell is the most
+  // relevant home for them — sharing (recipient/purpose/lawfulBasis/transfer)
+  // or retention/deletion — rather than repeating them on every cell. This
+  // loop runs unconditionally (independent of whether nodeLabels is empty)
+  // so a fact like deletion:not_found is never structurally unreachable just
+  // because a flow's path happens not to touch a deletion-stage node.
+  const governanceKeysForStage = {
+    sharing: ['recipient', 'purpose', 'lawfulBasis', 'transfer'],
+    retention: ['retention'],
+    deletion: ['deletion'],
+  };
+  const relevantKeys = governanceKeysForStage[cell.stage] ?? [];
+  for (const key of relevantKeys) {
+    if (key in row.governanceRefs) {
+      const value = row.governanceRefs[key];
+      children.push(el('div', { class: 'privacy-governance-badge' }, `${key}: ${value}`));
+    }
+  }
+
+  return el('td', { class: cell.nodeLabels.length === 0 ? 'privacy-stage-cell privacy-stage-cell-empty' : 'privacy-stage-cell' }, children);
+}

package/dist/frontend/src/views/trace-view.js

@@ -0,0 +1,206 @@
+import { el, clear } from '../lib/dom.js';
+import { protectionVisual } from '../lib/protection-visual.js';
+
+export function computeTraceSteps(graph, flow) {
+  const steps = [];
+  const sourceNode = graph.nodes.find((n) => n.id === flow.source);
+  const dataElement = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+
+  steps.push({
+    kind: 'source',
+    fieldName: dataElement?.name ?? 'unknown field',
+    node: sourceNode?.label ?? 'unknown source',
+  });
+
+  const edges = flow.edgeIds.map((id) => graph.edges.find((e) => e.id === id)).filter(Boolean);
+  for (const edge of edges) {
+    const toNode = graph.nodes.find((n) => n.id === edge.to);
+    const mappings = edge.fieldMappings ?? [];
+
+    if (mappings.length === 0) {
+      steps.push({
+        kind: 'hop',
+        node: toNode?.label ?? 'unknown',
+        fromNodeId: edge.from,
+        protection: edge.protection,
+        evidenceRefs: edge.evidenceRefs ?? [],
+      });
+      continue;
+    }
+
+    for (const mapping of mappings) {
+      const transformations = (mapping.transformationIds ?? [])
+        .map((tid) => graph.transformations.find((t) => t.id === tid))
+        .filter(Boolean);
+      steps.push({
+        kind: transformations.length > 0 ? 'transformation' : 'propagation',
+        fromPath: mapping.fromPath,
+        toPath: mapping.toPath,
+        mappingType: mapping.mappingType,
+        transformations,
+        node: toNode?.label ?? 'unknown',
+        fromNodeId: edge.from,
+        boundaryCrossing: (edge.boundaryCrossings ?? []).length > 0,
+        protection: edge.protection,
+        evidenceRefs: edge.evidenceRefs ?? [],
+      });
+    }
+  }
+
+  const sinkNode = graph.nodes.find((n) => n.id === flow.sink);
+  steps.push({
+    kind: 'sink',
+    node: sinkNode?.label ?? 'unknown destination',
+    externality: sinkNode?.externality?.value ?? 'unknown',
+    protectionSummary: flow.protectionSummary,
+  });
+
+  return steps;
+}
+
+export function computeTraceStepGroups(steps) {
+  const middleSteps = steps.filter((s) => s.kind !== 'source' && s.kind !== 'sink');
+  const sourceStep = steps.find((s) => s.kind === 'source');
+  const sinkStep = steps.find((s) => s.kind === 'sink');
+
+  const groupsByFrom = new Map();
+  for (const step of middleSteps) {
+    if (!groupsByFrom.has(step.fromNodeId)) groupsByFrom.set(step.fromNodeId, []);
+    groupsByFrom.get(step.fromNodeId).push(step);
+  }
+
+  const groups = [];
+  if (sourceStep) groups.push({ type: 'source', step: sourceStep });
+  for (const groupSteps of groupsByFrom.values()) {
+    if (groupSteps.length > 1) {
+      groups.push({ type: 'branch', steps: groupSteps });
+    } else {
+      groups.push({ type: 'sequential', step: groupSteps[0] });
+    }
+  }
+  if (sinkStep) groups.push({ type: 'sink', step: sinkStep });
+  return groups;
+}
+
+export function computeAlternatePaths(graph, flow) {
+  return graph.flows
+    .filter((f) => f.id !== flow.id && f.dataElementIds.some((id) => flow.dataElementIds.includes(id)))
+    .map((f) => ({
+      flowId: f.id,
+      destinationLabel: graph.nodes.find((n) => n.id === f.sink)?.label ?? 'unknown',
+      protectionSummary: f.protectionSummary,
+    }));
+}
+
+export function computeTraceViewModel(graph, state) {
+  if (!state.selectedId) return null;
+  const flow = graph.flows.find((f) => f.id === state.selectedId);
+  if (!flow) return null;
+  return {
+    flow,
+    steps: computeTraceSteps(graph, flow),
+    alternatePaths: computeAlternatePaths(graph, flow),
+  };
+}
+
+/**
+ * @param {ReturnType<typeof computeTraceViewModel>} viewModel
+ * @param {HTMLElement} canvasEl
+ * @param {(flowId: string) => void} onSelectAlternate
+ */
+export function renderTraceView(viewModel, canvasEl, onSelectAlternate) {
+  clear(canvasEl);
+
+  if (!viewModel) {
+    canvasEl.appendChild(el('p', { class: 'trace-empty' }, 'Select a flow from Privacy View (or click a node/edge in Architecture View that resolves to a flow) to trace it.'));
+    return;
+  }
+
+  const container = el('div', { class: 'trace-view' });
+  const groups = computeTraceStepGroups(viewModel.steps);
+  let stepNumber = 0;
+  for (const group of groups) {
+    stepNumber += 1;
+    if (group.type === 'branch') {
+      container.appendChild(renderTraceBranchGroup(group.steps, stepNumber));
+    } else {
+      container.appendChild(renderTraceStep(group.step, String(stepNumber)));
+    }
+  }
+
+  if (viewModel.alternatePaths.length > 0) {
+    const items = viewModel.alternatePaths.map((alt) => {
+      const visual = protectionVisual(alt.protectionSummary);
+      return el(
+        'div',
+        {
+          class: 'trace-alternate-item',
+          tabindex: '0',
+          role: 'button',
+          onClick: () => onSelectAlternate(alt.flowId),
+          onKeydown: (evt) => {
+            if (evt.key === 'Enter' || evt.key === ' ') {
+              evt.preventDefault();
+              onSelectAlternate(alt.flowId);
+            }
+          },
+        },
+        `${visual.glyph} ${alt.destinationLabel} — ${visual.label}`,
+      );
+    });
+    container.appendChild(el('div', { class: 'trace-alternates' }, [el('h4', {}, 'Alternate destinations'), ...items]));
+  }
+
+  canvasEl.appendChild(container);
+}
+
+function renderTraceBranchGroup(steps, number) {
+  const letters = 'abcdefghijklmnopqrstuvwxyz';
+  const items = steps.map((step, i) => renderTraceStep(step, `${number}${letters[i]}`));
+  return el('div', { class: 'trace-branch-group' }, [
+    el('div', { class: 'trace-branch-label' }, `${steps.length} branches from here`),
+    ...items,
+  ]);
+}
+
+function renderTraceStep(step, label) {
+  const bodyChildren = [el('div', { class: 'trace-step-kind' }, step.kind)];
+
+  if (step.kind === 'source') {
+    bodyChildren.push(el('div', { class: 'trace-step-mapping' }, step.fieldName));
+  } else if (step.kind === 'transformation' || step.kind === 'propagation') {
+    bodyChildren.push(el('div', { class: 'trace-step-mapping' }, `${step.fromPath} → ${step.toPath} (${step.mappingType})`));
+    for (const t of step.transformations) {
+      bodyChildren.push(el('div', { class: 'trace-step-mapping' }, `${t.callee}() — ${t.kind}, ${t.reversibility}`));
+    }
+  }
+
+  bodyChildren.push(el('div', { class: 'trace-step-node' }, step.node));
+
+  if (step.boundaryCrossing) {
+    bodyChildren.push(el('span', { class: 'trace-step-boundary' }, 'Trust boundary crossing'));
+  }
+
+  if (step.protection) {
+    const dims = [
+      ['Transit', step.protection.transit.verdict],
+      ['At rest', step.protection.atRest.verdict],
+      ['Handling', step.protection.handling.verdict],
+    ];
+    for (const [label, verdict] of dims) {
+      const visual = protectionVisual(verdict);
+      bodyChildren.push(el('div', { class: 'trace-step-mapping' }, `${visual.glyph} ${label}: ${visual.label}`));
+    }
+  }
+
+  if (step.evidenceRefs?.length > 0) {
+    bodyChildren.push(el('div', { class: 'trace-step-mapping' }, `${step.evidenceRefs.length} evidence reference(s)`));
+  }
+
+  if (step.kind === 'sink') {
+    const visual = protectionVisual(step.protectionSummary);
+    bodyChildren.push(el('div', { class: 'trace-step-mapping' }, `${visual.glyph} Overall: ${visual.label} · ${step.externality} destination`));
+  }
+
+  return el('div', { class: 'trace-step' }, [el('div', { class: 'trace-step-number' }, label), el('div', { class: 'trace-step-body' }, bodyChildren)]);
+}