@transitrix/diagrams 1.5.0 → 1.6.0

package/src/capability-map/dsm-schema.ts

@@ -0,0 +1,80 @@
+/**
+ * Types for the DSM-migration capability map (docs/extraction/capability-map.md).
+ *
+ * Distinct from `./types.ts` (`CapabilityNode`/`CapabilityMapFile`), which is
+ * Transitrix's own native `*.capability-map.transitrix.yaml` notation — a
+ * nested-children tree, statically rendered to SVG. This module is a
+ * separate, flat, address-triple data model matching DSM's internal
+ * capability editor, for the interactive `CapabilityMapView` component. The
+ * two coexist in this folder by design (see the address-helper/component
+ * deliverables in the extraction spec); only the validator function name
+ * collided, so it's `validateCapabilityMapData` here, not
+ * `validateCapabilityMap` (already taken by `./validate.ts`).
+ */
+
+export interface MaturitySnapshot {
+  date: string;
+  level: number;
+}
+
+export interface Capability {
+  id: number;
+  name: string;
+  /** 'X.Y.Z' triple. X=0 or backlog=true means "not on the diagram". */
+  address: string;
+  backlog?: boolean;
+  description?: string;
+  maturity?: MaturitySnapshot[];
+}
+
+export interface CapabilityMap {
+  organisation: string;
+  set_id: string;
+  capabilities: Capability[];
+}
+
+export type {
+  ValidationError,
+  ValidationWarning,
+  ValidationResult,
+} from '../validation-types.js';
+
+import type { ValidationError } from '../validation-types.js';
+
+export interface MutationResult<T> {
+  ok: boolean;
+  result?: T;
+  error?: ValidationError;
+}
+
+export interface LayoutOptions {
+  rankdir?: 'LR' | 'TB';
+  nodeWidth?: number;
+  nodeHeight?: number;
+  rankSep?: number;
+  nodeSep?: number;
+  hideCollapsed?: number[];
+  organisationLabel?: string;
+}
+
+export interface LaidOutNode {
+  id: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  data: Capability | null;
+  hasHiddenChildren: boolean;
+}
+
+export interface LaidOutEdge {
+  source: number | 'root';
+  target: number;
+}
+
+export interface CapabilityMapLayout {
+  rootNode: LaidOutNode;
+  nodes: LaidOutNode[];
+  edges: LaidOutEdge[];
+  bounds: { x: number; y: number; width: number; height: number };
+}

package/src/capability-map/dsm-theme.ts

@@ -0,0 +1,53 @@
+/** Theme tokens for CapabilityMapView — same host-agnostic-prop pattern as
+ *  the goals module's ThemeTokens (see ../goals/theme.ts). */
+export interface ThemeTokens {
+  cardFill?: string;
+  cardBorderColor?: string;
+  cardBorderWidth?: number;
+  cardTextColor?: string;
+  cardMetaColor?: string;
+  edgeColor?: string;
+  edgeWidth?: number;
+  dropTargetBorderColor?: string;
+  rootFill?: string;
+  rootTextColor?: string;
+}
+
+/** Default 1..5 maturity-dot colour scale — overridable via the
+ *  `maturityColours` prop (spec §6.2), which is separate from ThemeTokens
+ *  since it's keyed by maturity level, not a fixed named token. */
+export const DEFAULT_MATURITY_COLOURS: Record<number, string> = {
+  1: '#ef4444',
+  2: '#f97316',
+  3: '#eab308',
+  4: '#84cc16',
+  5: '#22c55e',
+};
+
+export const DEFAULT_THEME: Required<ThemeTokens> = {
+  cardFill: '#eff6ff',
+  cardBorderColor: '#94a3b8',
+  cardBorderWidth: 1,
+  cardTextColor: '#0f172a',
+  cardMetaColor: '#64748b',
+  edgeColor: '#94a3b8',
+  edgeWidth: 1.5,
+  dropTargetBorderColor: '#2563eb',
+  rootFill: '#e2e8f0',
+  rootTextColor: '#0f172a',
+};
+
+export function resolveTheme(theme?: ThemeTokens): Required<ThemeTokens> {
+  return {
+    cardFill: theme?.cardFill ?? DEFAULT_THEME.cardFill,
+    cardBorderColor: theme?.cardBorderColor ?? DEFAULT_THEME.cardBorderColor,
+    cardBorderWidth: theme?.cardBorderWidth ?? DEFAULT_THEME.cardBorderWidth,
+    cardTextColor: theme?.cardTextColor ?? DEFAULT_THEME.cardTextColor,
+    cardMetaColor: theme?.cardMetaColor ?? DEFAULT_THEME.cardMetaColor,
+    edgeColor: theme?.edgeColor ?? DEFAULT_THEME.edgeColor,
+    edgeWidth: theme?.edgeWidth ?? DEFAULT_THEME.edgeWidth,
+    dropTargetBorderColor: theme?.dropTargetBorderColor ?? DEFAULT_THEME.dropTargetBorderColor,
+    rootFill: theme?.rootFill ?? DEFAULT_THEME.rootFill,
+    rootTextColor: theme?.rootTextColor ?? DEFAULT_THEME.rootTextColor,
+  };
+}

package/src/capability-map/dsm-validate.ts

@@ -0,0 +1,103 @@
+import type { CapabilityMap, ValidationResult, ValidationError, ValidationWarning } from './dsm-schema.js';
+
+/** Parses an address string loosely enough to tell "wrong shape"
+ *  (INVALID_ADDRESS_FORMAT) apart from "right shape, too many levels"
+ *  (MAX_DEPTH_EXCEEDED, e.g. '1.2.3.4') — a strict 3-segment regex would
+ *  reject both identically and lose that distinction. */
+function parseLoose(address: string): { triple: [number, number, number] } | { tooDeep: true } | null {
+  const parts = address.trim().split('.');
+  if (parts.length < 3 || !parts.every((p) => /^\d+$/.test(p))) return null;
+  if (parts.length > 3) return { tooDeep: true };
+  return { triple: [Number(parts[0]), Number(parts[1]), Number(parts[2])] };
+}
+
+export function validateCapabilityMapData(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'SCHEMA_INVALID', message: 'Input must be an object' }], warnings: [] };
+  }
+
+  const raw = input as Record<string, unknown>;
+  if (!Array.isArray(raw.capabilities)) {
+    errors.push({ code: 'SCHEMA_INVALID', message: 'capabilities must be an array', path: 'capabilities' });
+    return { valid: false, errors, warnings };
+  }
+
+  const map = raw as unknown as CapabilityMap;
+  const idSet = new Set<number>();
+  const addressToId = new Map<string, number>();
+  const onDiagram = new Map<number, [number, number, number]>();
+
+  for (let i = 0; i < map.capabilities.length; i++) {
+    const c = map.capabilities[i] as unknown;
+    const path = `capabilities[${i}]`;
+
+    if (!c || typeof c !== 'object') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'capability entry must be an object', path });
+      continue;
+    }
+    const cap = c as { id?: unknown; name?: unknown; address?: unknown; backlog?: unknown; maturity?: unknown };
+
+    if (typeof cap.id !== 'number') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'capability id must be a number', path });
+      continue;
+    }
+    if (idSet.has(cap.id)) {
+      errors.push({ code: 'DUPLICATE_ID', message: `Duplicate capability id: ${cap.id}`, path });
+    } else {
+      idSet.add(cap.id);
+    }
+
+    if (!cap.name || typeof cap.name !== 'string' || cap.name.trim() === '') {
+      errors.push({ code: 'EMPTY_NAME', message: `Capability ${cap.id} has empty name`, path });
+    }
+
+    if (typeof cap.address !== 'string') {
+      errors.push({ code: 'INVALID_ADDRESS_FORMAT', message: `Capability ${cap.id} address must be a string`, path });
+      continue;
+    }
+    const parsed = parseLoose(cap.address);
+    if (parsed === null) {
+      errors.push({ code: 'INVALID_ADDRESS_FORMAT', message: `Capability ${cap.id} address "${cap.address}" is not in 'X.Y.Z' form`, path });
+      continue;
+    }
+    if ('tooDeep' in parsed) {
+      errors.push({ code: 'MAX_DEPTH_EXCEEDED', message: `Capability ${cap.id} address "${cap.address}" has more than 3 levels`, path });
+      continue;
+    }
+    const triple = parsed.triple;
+    const isBacklog = cap.backlog === true || triple[0] === 0;
+
+    if (!isBacklog) {
+      if (addressToId.has(cap.address)) {
+        errors.push({ code: 'DUPLICATE_ADDRESS', message: `Duplicate address "${cap.address}" (capability ${cap.id})`, path });
+      } else {
+        addressToId.set(cap.address, cap.id);
+      }
+      onDiagram.set(cap.id, triple);
+    }
+
+    if (Array.isArray(cap.maturity)) {
+      for (const snap of cap.maturity as unknown[]) {
+        const level = (snap as { level?: unknown } | null)?.level;
+        if (typeof level === 'number' && (level < 1 || level > 5)) {
+          warnings.push({ code: 'INVALID_MATURITY_LEVEL', message: `Capability ${cap.id} has maturity level ${level} outside 1..5`, path });
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  for (const [id, [x, y, z]] of onDiagram) {
+    if (z !== 0 && !addressToId.has(`${x}.${y}.0`)) {
+      warnings.push({ code: 'MISSING_PARENT_BY_ADDRESS', message: `Capability ${id} (${x}.${y}.${z}) has no L2 parent at ${x}.${y}.0` });
+    } else if (y !== 0 && z === 0 && !addressToId.has(`${x}.0.0`)) {
+      warnings.push({ code: 'MISSING_PARENT_BY_ADDRESS', message: `Capability ${id} (${x}.${y}.0) has no L1 parent at ${x}.0.0` });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/capability-map/index.ts

@@ -17,3 +17,38 @@ export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP,
 
 export type { RenderCapabilityTreeOptions } from './render-capability-tree.js';
 export { renderCapabilityTreeSvg } from './render-capability-tree.js';
+
+// ── DSM-migration capability map (docs/extraction/capability-map.md) ───────
+// A separate, flat, address-triple data model from CapabilityNode above —
+// see dsm-schema.ts for why the two coexist in this folder. Named
+// `validateCapabilityMapData` rather than `validateCapabilityMap` because
+// that name is already taken by the native-notation validator on line 8.
+
+export type {
+  Capability,
+  CapabilityMap,
+  MaturitySnapshot,
+  MutationResult,
+  LayoutOptions,
+  LaidOutNode,
+  LaidOutEdge,
+  CapabilityMapLayout,
+} from './dsm-schema.js';
+
+export {
+  parseAddress,
+  formatAddress,
+  getLevel,
+  getParentAddress,
+  getFirstFreeAddress,
+  isAddressTaken,
+} from './address.js';
+
+export { validateCapabilityMapData } from './dsm-validate.js';
+export { layoutCapabilityMap } from './dsm-layout.js';
+export { reparent, addChild, deleteWithDescendants, moveBranchToBacklog, restoreFromBacklog, normaliseAddresses } from './dsm-mutations.js';
+
+export { CapabilityMapView } from './CapabilityMapView.js';
+export type { CapabilityMapViewProps, CapabilityMapChange } from './CapabilityMapView.js';
+export type { ThemeTokens } from './dsm-theme.js';
+export { DEFAULT_MATURITY_COLOURS } from './dsm-theme.js';

package/src/compliance/__tests__/trace.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect } from 'vitest';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildRequirementTrace, buildTraceElementCatalog } from '../trace.js';
+import type { ComplianceIndexInput } from '../types.js';
+import type { ComplianceCodexDoc } from '../classify.js';
+
+// Requirement traceability + hierarchy view.
+//
+// The two halves the view exposes:
+//   1. Trace chain — derived_from → REQUIREMENT → ASSERTION → subject +
+//      realised_via.
+//   2. Hierarchy — parent chain + children via the `parent` field
+//      (15-requirement.md §2.4 / ELEMENT_PRIMITIVES.md §7.13).
+
+const input: ComplianceIndexInput = {
+  requirements: [
+    // A broad legislative parent decomposed into two child requirements.
+    { id: 'REQUIREMENT-DATA-PROTECTION-1', name: 'Personal-data protection', origin: 'legislative', derived_from: ['REGULATION-GDPR-2016-1'], element_kind: 'requirement' },
+    { id: 'REQUIREMENT-DATA-ERASURE-1',    name: 'Erase on request within 30 days', origin: 'legislative', parent: 'REQUIREMENT-DATA-PROTECTION-1', derived_from: ['REGULATION-GDPR-2016-1'], element_kind: 'requirement' },
+    { id: 'REQUIREMENT-DATA-CONSENT-1',    name: 'Obtain consent before processing', origin: 'legislative', parent: 'REQUIREMENT-DATA-PROTECTION-1', element_kind: 'requirement' },
+    // A process-product sub-requirement below the erasure duty (cross-origin).
+    { id: 'REQUIREMENT-ERASURE-SLA-1',     name: 'Erasure SOP — 30d target', origin: 'process-product', parent: 'REQUIREMENT-DATA-ERASURE-1', element_kind: 'requirement' },
+    // Constraint hierarchy (mirror pattern).
+    { id: 'CONSTRAINT-EEA-TRANSFER-1',     name: 'No transfer outside EEA without safeguards', element_kind: 'constraint' },
+    { id: 'CONSTRAINT-EEA-ANALYTICS-1',    name: 'No PII in analytics logs', parent: 'CONSTRAINT-EEA-TRANSFER-1', element_kind: 'constraint' },
+    // Internal-only requirement — no source, no parent — for the empty-case sanity check.
+    { id: 'REQUIREMENT-INTERNAL-1',        name: 'Internal-only', element_kind: 'requirement' },
+  ],
+  assertions: [
+    { id: 'ASSERTION-1', about: 'REQUIREMENT-DATA-ERASURE-1', subject: 'PRODUCT-MOBILE-1', realised_via: ['CAPABILITY-V1', 'PROCESS-PURGE-1'], status: 'compliant' },
+    { id: 'ASSERTION-2', about: 'REQUIREMENT-DATA-ERASURE-1', subject: 'PRODUCT-WEB-1',    status: 'partial' },
+    { id: 'ASSERTION-3', about: 'REQUIREMENT-DATA-CONSENT-1', subject: 'PRODUCT-WEB-1',    status: 'compliant' },
+  ],
+};
+
+const codex: ComplianceCodexDoc[] = [
+  { id: 'REGULATION-GDPR-2016-1', name: 'GDPR', type: 'REGULATION', jurisdiction: 'EU' },
+];
+
+const catalog = buildTraceElementCatalog(
+  [{ id: 'PRODUCT-MOBILE-1', name: 'Mobile app' }, { id: 'PRODUCT-WEB-1', name: 'Web app' }],
+  [{ id: 'CAPABILITY-V1', name: 'Erasure capability v1' }, { id: 'PROCESS-PURGE-1', name: 'Purge process' }],
+);
+
+describe('buildComplianceIndex — requirementsByParent', () => {
+  const idx = buildComplianceIndex(input);
+  it('groups children of the same parent', () => {
+    const children = idx.requirementsByParent.get('REQUIREMENT-DATA-PROTECTION-1');
+    expect(children?.map(r => r.id).sort()).toEqual(['REQUIREMENT-DATA-CONSENT-1', 'REQUIREMENT-DATA-ERASURE-1']);
+  });
+  it('groups CONSTRAINT children the same way (element_kind-agnostic)', () => {
+    const children = idx.requirementsByParent.get('CONSTRAINT-EEA-TRANSFER-1');
+    expect(children?.map(r => r.id)).toEqual(['CONSTRAINT-EEA-ANALYTICS-1']);
+  });
+  it('returns undefined for a leaf with no children', () => {
+    expect(idx.requirementsByParent.has('REQUIREMENT-INTERNAL-1')).toBe(false);
+  });
+});
+
+describe('buildRequirementTrace — trace chain', () => {
+  const idx = buildComplianceIndex(input);
+  it('resolves derived_from codex artefacts on the sources block', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-DATA-ERASURE-1', idx, catalog, codex);
+    expect(trace.sources).toHaveLength(1);
+    expect(trace.sources[0].id).toBe('REGULATION-GDPR-2016-1');
+    expect(trace.sources[0].codex?.jurisdiction).toBe('EU');
+  });
+  it('keeps a dangling derived_from ref with no codex when the artefact is missing', () => {
+    const local: ComplianceIndexInput = {
+      requirements: [{ id: 'REQUIREMENT-X-1', name: 'X', derived_from: ['LAW-MISSING-1'] }],
+      assertions: [],
+    };
+    const trace = buildRequirementTrace('REQUIREMENT-X-1', buildComplianceIndex(local), catalog);
+    expect(trace.sources).toEqual([{ id: 'LAW-MISSING-1' }]);
+  });
+  it('lists ASSERTIONs id-sorted, each with resolved subject + realised_via names', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-DATA-ERASURE-1', idx, catalog, codex);
+    expect(trace.assertions.map(a => a.assertion.id)).toEqual(['ASSERTION-1', 'ASSERTION-2']);
+    expect(trace.assertions[0].subject).toEqual({ id: 'PRODUCT-MOBILE-1', name: 'Mobile app' });
+    expect(trace.assertions[0].realisedVia.map(r => r.name)).toEqual(['Erasure capability v1', 'Purge process']);
+  });
+  it('returns an empty assertions list for a REQUIREMENT with no filed claim', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-DATA-PROTECTION-1', idx, catalog);
+    expect(trace.assertions).toEqual([]);
+  });
+  it('returns an empty assertions list for a CONSTRAINT (16-assertion.md §1 — CONSTRAINT-side out of v1)', () => {
+    const trace = buildRequirementTrace('CONSTRAINT-EEA-TRANSFER-1', idx, catalog);
+    expect(trace.assertions).toEqual([]);
+  });
+  it('falls back to id when the subject / realised_via element is not in the catalog (dangling ref)', () => {
+    const local: ComplianceIndexInput = {
+      requirements: [{ id: 'REQUIREMENT-Y-1', name: 'Y' }],
+      assertions: [{ id: 'ASSERTION-9', about: 'REQUIREMENT-Y-1', subject: 'PRODUCT-GONE-1', realised_via: ['CAPABILITY-GONE-1'], status: 'n_a' }],
+    };
+    const trace = buildRequirementTrace('REQUIREMENT-Y-1', buildComplianceIndex(local), catalog);
+    expect(trace.assertions[0].subject).toEqual({ id: 'PRODUCT-GONE-1' });
+    expect(trace.assertions[0].realisedVia).toEqual([{ id: 'CAPABILITY-GONE-1' }]);
+  });
+});
+
+describe('buildRequirementTrace — hierarchy', () => {
+  const idx = buildComplianceIndex(input);
+  it('walks ancestors: immediate parent first, root last', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-ERASURE-SLA-1', idx, catalog);
+    expect(trace.ancestors.map(r => r.id)).toEqual([
+      'REQUIREMENT-DATA-ERASURE-1',
+      'REQUIREMENT-DATA-PROTECTION-1',
+    ]);
+  });
+  it('lists direct children id-sorted', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-DATA-PROTECTION-1', idx, catalog);
+    expect(trace.children.map(r => r.id)).toEqual([
+      'REQUIREMENT-DATA-CONSENT-1',
+      'REQUIREMENT-DATA-ERASURE-1',
+    ]);
+  });
+  it('handles a top-level requirement (no ancestors) with no children', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-INTERNAL-1', idx, catalog);
+    expect(trace.ancestors).toEqual([]);
+    expect(trace.children).toEqual([]);
+  });
+  it('supports CONSTRAINT hierarchy the same way', () => {
+    const trace = buildRequirementTrace('CONSTRAINT-EEA-ANALYTICS-1', idx, catalog);
+    expect(trace.ancestors.map(r => r.id)).toEqual(['CONSTRAINT-EEA-TRANSFER-1']);
+  });
+  it('terminates at a missing parent without throwing (broken model)', () => {
+    const local: ComplianceIndexInput = {
+      requirements: [{ id: 'REQUIREMENT-ORPHAN-1', name: 'Orphan', parent: 'REQUIREMENT-GONE-1' }],
+      assertions: [],
+    };
+    const trace = buildRequirementTrace('REQUIREMENT-ORPHAN-1', buildComplianceIndex(local), catalog);
+    expect(trace.ancestors).toEqual([]);
+  });
+  it('breaks a parent cycle rather than looping', () => {
+    // A → B → A (misauthored).
+    const local: ComplianceIndexInput = {
+      requirements: [
+        { id: 'REQUIREMENT-A-1', name: 'A', parent: 'REQUIREMENT-B-1' },
+        { id: 'REQUIREMENT-B-1', name: 'B', parent: 'REQUIREMENT-A-1' },
+      ],
+      assertions: [],
+    };
+    const trace = buildRequirementTrace('REQUIREMENT-A-1', buildComplianceIndex(local), catalog);
+    expect(trace.ancestors.map(r => r.id)).toEqual(['REQUIREMENT-B-1']);
+  });
+});
+
+describe('buildRequirementTrace — dangling target', () => {
+  it('returns a stub carrying the id as name when the requirement is not scanned', () => {
+    const trace = buildRequirementTrace('REQUIREMENT-UNKNOWN-1', buildComplianceIndex({ requirements: [], assertions: [] }), catalog);
+    expect(trace.requirement).toEqual({ id: 'REQUIREMENT-UNKNOWN-1', name: 'REQUIREMENT-UNKNOWN-1' });
+    expect(trace.sources).toEqual([]);
+    expect(trace.assertions).toEqual([]);
+    expect(trace.ancestors).toEqual([]);
+    expect(trace.children).toEqual([]);
+  });
+});

package/src/compliance/classify.ts

@@ -65,7 +65,8 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
     canon.subjects.push({ id, name: str(d.name) ?? id });
     return id;
   }
-  if (d.notation === 'requirement') {
+  if (d.notation === 'requirement' || d.notation === 'constraint') {
+    const origin = str(d.origin);
     canon.requirements.push({
       id,
       name: str(d.name) ?? id,
@@ -73,6 +74,11 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
       derived_from: strArray(d.derived_from),
       admitted_at: str(d.admitted_at),
       deadline: str(d.deadline),
+      origin: origin === 'legislative' || origin === 'process-product' || origin === 'project-product' ? origin : undefined,
+      parent: str(d.parent),
+      element_kind: d.notation,
+      description: str(d.description),
+      next_review_at: str(d.next_review_at),
     });
     return id;
   }

package/src/compliance/index.ts

@@ -1,5 +1,6 @@
 export { buildComplianceIndex } from './reverse-index.js';
 export { buildLawTree, buildProductView } from './views.js';
+export { buildRequirementTrace, buildTraceElementCatalog } from './trace.js';
 export { buildGapReport } from './gap-report.js';
 export type { GapReport, GapReportOptions } from './gap-report.js';
 export { emptyCanon, ingestComplianceDoc } from './classify.js';
@@ -54,4 +55,9 @@ export type {
   ProductRequirementStatus,
   ObjectDetailDef,
   ObjectDetailInput,
+  RequirementTrace,
+  TraceAssertionRow,
+  TraceElementCatalog,
+  TraceElementRef,
+  TraceSourceRef,
 } from './types.js';

package/src/compliance/reverse-index.ts

@@ -19,15 +19,17 @@ export function buildComplianceIndex(input: ComplianceIndexInput): ComplianceInd
   const requirementsByLaw = new Map<string, IndexRequirement[]>();
   const assertionsByRequirement = new Map<string, IndexAssertion[]>();
   const assertionsBySubject = new Map<string, IndexAssertion[]>();
+  const requirementsByParent = new Map<string, IndexRequirement[]>();
 
   for (const r of input.requirements) {
     requirementById.set(r.id, r);
     for (const law of r.derived_from ?? []) push(requirementsByLaw, law, r);
+    if (r.parent) push(requirementsByParent, r.parent, r);
   }
   for (const a of input.assertions) {
     push(assertionsByRequirement, a.about, a);
     push(assertionsBySubject, a.subject, a);
   }
 
-  return { requirementById, requirementsByLaw, assertionsByRequirement, assertionsBySubject };
+  return { requirementById, requirementsByLaw, assertionsByRequirement, assertionsBySubject, requirementsByParent };
 }

package/src/compliance/trace.ts

@@ -0,0 +1,118 @@
+// Requirement traceability + hierarchy builder.
+//
+// Two halves, both origin-agnostic per 15-requirement.md §2.1:
+//
+//   1. Trace chain — `derived_from` sources → the REQUIREMENT / CONSTRAINT
+//      itself → any ASSERTION targeting it (`about`) → the asserted `subject`
+//      + `realised_via` elements. Assertion coverage applies to REQUIREMENT
+//      only (16-assertion.md §1); CONSTRAINT trace shows sources + hierarchy
+//      only.
+//
+//   2. Hierarchy — the `parent` chain (ancestors, root last) plus the direct
+//      children (elements whose `parent` names this one). Same-TYPE only per
+//      15-requirement.md §2.4; the chain terminates at the first missing or
+//      cyclic parent so a broken model still renders something useful.
+//
+// Pure: takes the reverse index + a name-resolution map + optional codex list;
+// no IO. `ComplianceCodexDoc` comes from the scanner so we get jurisdiction
+// alongside the codex id in the sources block.
+
+import type {
+  ComplianceIndex,
+  IndexRequirement,
+  RequirementTrace,
+  TraceAssertionRow,
+  TraceElementCatalog,
+  TraceElementRef,
+  TraceSourceRef,
+} from './types.js';
+import type { ComplianceCodexDoc } from './classify.js';
+
+function byId<T extends { id: string }>(a: T, b: T): number {
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+function resolveElement(id: string, catalog: TraceElementCatalog): TraceElementRef {
+  const name = catalog.nameById.get(id);
+  return name ? { id, name } : { id };
+}
+
+/**
+ * Walk the `parent` chain upward from `requirement`, stopping at the first
+ * missing or already-seen parent (cycle guard). Returns immediate parent first,
+ * root last. Empty array when the element has no `parent`.
+ */
+function collectAncestors(
+  requirement: IndexRequirement,
+  index: ComplianceIndex,
+): IndexRequirement[] {
+  const out: IndexRequirement[] = [];
+  const seen = new Set<string>([requirement.id]);
+  let current: IndexRequirement | undefined = requirement;
+  while (current?.parent && !seen.has(current.parent)) {
+    seen.add(current.parent);
+    const next = index.requirementById.get(current.parent);
+    if (!next) break;
+    out.push(next);
+    current = next;
+  }
+  return out;
+}
+
+/**
+ * Builds the REQUIREMENT / CONSTRAINT traceability view.
+ *
+ * @param requirementId typed id of the element to trace
+ * @param index         reverse index built by `buildComplianceIndex`
+ * @param catalog       name-resolution map for subject / realised_via refs
+ * @param codex         optional codex artefact list (from the scanner); when
+ *                      supplied, `sources[].codex` is populated with the
+ *                      resolved codex artefact for jurisdiction display
+ */
+export function buildRequirementTrace(
+  requirementId: string,
+  index: ComplianceIndex,
+  catalog: TraceElementCatalog,
+  codex: ComplianceCodexDoc[] = [],
+): RequirementTrace {
+  const requirement: IndexRequirement =
+    index.requirementById.get(requirementId) ?? { id: requirementId, name: requirementId };
+
+  const codexById = new Map<string, ComplianceCodexDoc>();
+  for (const c of codex) codexById.set(c.id, c);
+
+  const sources: TraceSourceRef[] = (requirement.derived_from ?? []).map(sid => {
+    const c = codexById.get(sid);
+    return c ? { id: sid, codex: c } : { id: sid };
+  });
+
+  const rawAssertions = index.assertionsByRequirement.get(requirementId) ?? [];
+  const assertions: TraceAssertionRow[] = [...rawAssertions]
+    .sort(byId)
+    .map(assertion => ({
+      assertion,
+      subject: resolveElement(assertion.subject, catalog),
+      realisedVia: (assertion.realised_via ?? []).map(rid => resolveElement(rid, catalog)),
+    }));
+
+  const ancestors = collectAncestors(requirement, index);
+  const children = [...(index.requirementsByParent.get(requirementId) ?? [])].sort(byId);
+
+  return { requirement, sources, assertions, ancestors, children };
+}
+
+/**
+ * Convenience: build a `TraceElementCatalog` from the scanned canon's product
+ * and subject buckets. Requirements/assertions are excluded — they are indexed
+ * separately by `buildComplianceIndex`; the catalog is only for resolving the
+ * elements a trace references (subjects + realised_via).
+ */
+export function buildTraceElementCatalog(
+  products: Array<{ id: string; name: string }>,
+  subjects: Array<{ id: string; name: string }>,
+): TraceElementCatalog {
+  const nameById = new Map<string, string>();
+  for (const p of products) nameById.set(p.id, p.name);
+  for (const s of subjects) nameById.set(s.id, s.name);
+  return { nameById };
+}