@transitrix/diagrams 1.4.0 → 1.6.0

package/dist/capability-map/dsm-mutations.js

@@ -0,0 +1,196 @@
+import { parseAddress, getLevel, getParentAddress, getFirstFreeAddress, isAddressTaken } from './address.js';
+function cloneMap(map) {
+    return {
+        organisation: map.organisation,
+        set_id: map.set_id,
+        capabilities: map.capabilities.map((c) => ({
+            ...c,
+            maturity: c.maturity ? c.maturity.map((m) => ({ ...m })) : undefined,
+        })),
+    };
+}
+function nextId(map) {
+    return Math.max(0, ...map.capabilities.map((c) => c.id)) + 1;
+}
+function refusalError(message) {
+    const err = { code: 'MUTATION_REFUSED', message };
+    return { ok: false, error: err };
+}
+/** True when `addr` sits anywhere under `ancestorAddr` in the address hierarchy. */
+function isDescendantAddress(addr, ancestorAddr) {
+    const [ax, ay, az] = parseAddress(addr);
+    const [px, py, pz] = parseAddress(ancestorAddr);
+    if (px !== ax)
+        return false;
+    if (py === 0)
+        return ay !== 0 || az !== 0; // ancestor is L1 — any L2/L3 under the same X
+    if (pz === 0)
+        return ay === py && az !== 0; // ancestor is L2 — only L3s under the same X.Y
+    return false; // ancestor is L3 — no descendants possible (max depth)
+}
+/** First unused top-level (L1) address — the "parent" for a promote-to-L1 reparent. */
+function firstFreeL1(capabilities) {
+    for (let x = 1; x < 1000; x++) {
+        const candidate = `${x}.0.0`;
+        if (!isAddressTaken(candidate, capabilities))
+            return candidate;
+    }
+    throw new Error('firstFreeL1: no free top-level address (searched 1..999)');
+}
+/**
+ * Move `sourceId` under `targetId` (or under the virtual root when
+ * `targetId` is 0 — the sentinel matching the goals module's `parent_id: 0`
+ * convention, since the root isn't itself a Capability with an id).
+ *
+ * Recomputes addresses for the whole moved branch (§5.1). The depth check is
+ * expressed once, generically, as "every descendant's new level must stay in
+ * 1..3" — this covers both directions the spec discusses explicitly (L2→L1
+ * promotion, where descendants move one level shallower) and the symmetric,
+ * unspecified case (L1→L2 demotion, where descendants move one level
+ * deeper) without needing separate per-direction rules: an L1 with L3
+ * grandchildren refuses demotion to L2 because that would need a 4th level,
+ * caught by the same check.
+ */
+export function reparent(map, sourceId, targetId) {
+    const clone = cloneMap(map);
+    const source = clone.capabilities.find((c) => c.id === sourceId);
+    if (!source || source.backlog)
+        return refusalError(`Capability ${sourceId} not found (use restoreFromBacklog for backlog items)`);
+    if (sourceId === targetId)
+        return refusalError('Cannot reparent to self');
+    const target = targetId === 0 ? null : clone.capabilities.find((c) => c.id === targetId);
+    if (targetId !== 0 && (!target || target.backlog))
+        return refusalError(`Target capability ${targetId} not found`);
+    if (target && isDescendantAddress(target.address, source.address)) {
+        return refusalError('Cannot reparent: target is a descendant of the source (would create a cycle)');
+    }
+    const sourceLevel = getLevel(source.address);
+    if (sourceLevel === 'backlog')
+        return refusalError(`Capability ${sourceId} has no on-diagram address`);
+    const targetLevel = target ? getLevel(target.address) : 0;
+    const newLevel = (typeof targetLevel === 'number' ? targetLevel : 0) + 1;
+    if (newLevel > 3)
+        return refusalError('Reparent would exceed max depth (L3)');
+    const levelDelta = newLevel - sourceLevel;
+    const originalSourceAddress = source.address;
+    // Snapshot descendants + their original address/level BEFORE anything is
+    // reassigned — both for the depth check and to resolve old-parent links
+    // while walking the branch top-down below.
+    const descendants = clone.capabilities
+        .filter((c) => !c.backlog && c.id !== sourceId && isDescendantAddress(c.address, originalSourceAddress))
+        .map((c) => ({ cap: c, originalAddress: c.address, originalLevel: getLevel(c.address) }));
+    for (const d of descendants) {
+        const newDescLevel = d.originalLevel + levelDelta;
+        if (newDescLevel > 3 || newDescLevel < 1) {
+            return refusalError(`Reparent would push descendant ${d.cap.id} to level ${newDescLevel}, outside 1..3`);
+        }
+    }
+    const oldAddressToId = new Map(clone.capabilities.filter((c) => !c.backlog).map((c) => [c.address, c.id]));
+    const newAddressById = new Map();
+    source.address = target ? getFirstFreeAddress(target.address, clone.capabilities) : firstFreeL1(clone.capabilities);
+    newAddressById.set(sourceId, source.address);
+    // Shallowest-first so each descendant's old parent has already been
+    // re-addressed (or is the source itself) by the time we reach it.
+    descendants.sort((a, b) => a.originalLevel - b.originalLevel);
+    for (const d of descendants) {
+        const oldParentAddress = getParentAddress(d.originalAddress);
+        const oldParentId = oldParentAddress ? oldAddressToId.get(oldParentAddress) : undefined;
+        const newParentAddress = oldParentId != null ? newAddressById.get(oldParentId) : undefined;
+        if (!newParentAddress) {
+            return refusalError(`Reparent could not resolve the new parent address for descendant ${d.cap.id}`);
+        }
+        const newAddress = getFirstFreeAddress(newParentAddress, clone.capabilities);
+        d.cap.address = newAddress;
+        newAddressById.set(d.cap.id, newAddress);
+    }
+    return { ok: true, result: clone };
+}
+export function addChild(map, parentId, newCap) {
+    const clone = cloneMap(map);
+    const parent = parentId === 0 ? null : clone.capabilities.find((c) => c.id === parentId);
+    if (parentId !== 0 && (!parent || parent.backlog))
+        return refusalError(`Parent capability ${parentId} not found`);
+    const parentLevel = parent ? getLevel(parent.address) : 0;
+    const newLevel = (typeof parentLevel === 'number' ? parentLevel : 0) + 1;
+    if (newLevel > 3)
+        return refusalError('New child would exceed max depth (L3)');
+    const address = parent ? getFirstFreeAddress(parent.address, clone.capabilities) : firstFreeL1(clone.capabilities);
+    const id = nextId(clone);
+    clone.capabilities.push({ ...newCap, id, address, backlog: false });
+    return { ok: true, result: clone };
+}
+export function deleteWithDescendants(map, id) {
+    const clone = cloneMap(map);
+    const target = clone.capabilities.find((c) => c.id === id);
+    if (!target)
+        return refusalError(`Capability ${id} not found`);
+    const toDelete = new Set([id]);
+    if (!target.backlog) {
+        for (const c of clone.capabilities) {
+            if (!c.backlog && isDescendantAddress(c.address, target.address))
+                toDelete.add(c.id);
+        }
+    }
+    clone.capabilities = clone.capabilities.filter((c) => !toDelete.has(c.id));
+    return { ok: true, result: clone };
+}
+/** Moves a whole branch to the backlog. Descendants move with it (a
+ *  backlogged capability's on-diagram children would otherwise dangle). */
+export function moveBranchToBacklog(map, id) {
+    const clone = cloneMap(map);
+    const target = clone.capabilities.find((c) => c.id === id);
+    if (!target)
+        return refusalError(`Capability ${id} not found`);
+    if (target.backlog)
+        return refusalError(`Capability ${id} is already in the backlog`);
+    const branch = [target, ...clone.capabilities.filter((c) => !c.backlog && isDescendantAddress(c.address, target.address))];
+    for (const c of branch) {
+        c.backlog = true;
+        c.address = '0.0.0';
+    }
+    return { ok: true, result: clone };
+}
+export function restoreFromBacklog(map, id, parentId) {
+    const clone = cloneMap(map);
+    const target = clone.capabilities.find((c) => c.id === id);
+    if (!target || !target.backlog)
+        return refusalError(`Capability ${id} is not in the backlog`);
+    const parent = parentId === 0 ? null : clone.capabilities.find((c) => c.id === parentId);
+    if (parentId !== 0 && (!parent || parent.backlog))
+        return refusalError(`Parent capability ${parentId} not found`);
+    const parentLevel = parent ? getLevel(parent.address) : 0;
+    const newLevel = (typeof parentLevel === 'number' ? parentLevel : 0) + 1;
+    if (newLevel > 3)
+        return refusalError('Restore would exceed max depth (L3)');
+    target.address = parent ? getFirstFreeAddress(parent.address, clone.capabilities) : firstFreeL1(clone.capabilities);
+    target.backlog = false;
+    return { ok: true, result: clone };
+}
+/**
+ * Repairs addresses that don't resolve to an existing parent (MISSING_PARENT_BY_ADDRESS):
+ * reassigns each such capability to the first free slot under its would-be
+ * parent's level, or moves it to the backlog when no such parent exists at all.
+ */
+export function normaliseAddresses(map) {
+    const clone = cloneMap(map);
+    const addressToId = new Map(clone.capabilities.filter((c) => !c.backlog).map((c) => [c.address, c.id]));
+    // Re-derive level-by-level (L1 first) so an L1 fixed up in this pass can
+    // already serve as a valid parent for an L2 processed right after it.
+    const byLevel = clone.capabilities
+        .filter((c) => !c.backlog)
+        .map((c) => ({ cap: c, level: getLevel(c.address) }))
+        .filter((e) => typeof e.level === 'number')
+        .sort((a, b) => a.level - b.level);
+    for (const { cap, level } of byLevel) {
+        if (level === 1)
+            continue; // L1 has no parent to validate against
+        const parentAddress = getParentAddress(cap.address);
+        if (parentAddress && addressToId.has(parentAddress))
+            continue; // already fine
+        // No resolvable parent: reassign to the backlog rather than guessing one.
+        addressToId.delete(cap.address);
+        cap.backlog = true;
+        cap.address = '0.0.0';
+    }
+    return clone;
+}

package/dist/capability-map/dsm-schema.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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/dist/capability-map/dsm-schema.js

@@ -0,0 +1,14 @@
+/**
+ * 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 {};

package/dist/capability-map/dsm-theme.d.ts

@@ -0,0 +1,20 @@
+/** 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 declare const DEFAULT_MATURITY_COLOURS: Record<number, string>;
+export declare const DEFAULT_THEME: Required<ThemeTokens>;
+export declare function resolveTheme(theme?: ThemeTokens): Required<ThemeTokens>;

package/dist/capability-map/dsm-theme.js

@@ -0,0 +1,36 @@
+/** 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 = {
+    1: '#ef4444',
+    2: '#f97316',
+    3: '#eab308',
+    4: '#84cc16',
+    5: '#22c55e',
+};
+export const DEFAULT_THEME = {
+    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) {
+    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/dist/capability-map/dsm-validate.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationResult } from './dsm-schema.js';
+export declare function validateCapabilityMapData(input: unknown): ValidationResult;

package/dist/capability-map/dsm-validate.js

@@ -0,0 +1,93 @@
+/** 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) {
+    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) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return { valid: false, errors: [{ code: 'SCHEMA_INVALID', message: 'Input must be an object' }], warnings: [] };
+    }
+    const raw = input;
+    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;
+    const idSet = new Set();
+    const addressToId = new Map();
+    const onDiagram = new Map();
+    for (let i = 0; i < map.capabilities.length; i++) {
+        const c = map.capabilities[i];
+        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;
+        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) {
+                const level = snap?.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/dist/capability-map/index.d.ts

@@ -4,3 +4,12 @@ export type { CapabilityTreeNode, CapabilityTreeEdge, CapabilityTreeLevelCounts,
 export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP, TREE_NODE_SEP } from './layout-tree.js';
 export type { RenderCapabilityTreeOptions } from './render-capability-tree.js';
 export { renderCapabilityTreeSvg } from './render-capability-tree.js';
+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/dist/capability-map/index.js

@@ -1,3 +1,9 @@
 export { validateCapabilityMap } from './validate.js';
 export { layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE_HEIGHT, TREE_RANK_SEP, TREE_NODE_SEP } from './layout-tree.js';
 export { renderCapabilityTreeSvg } from './render-capability-tree.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 { DEFAULT_MATURITY_COLOURS } from './dsm-theme.js';

package/dist/compliance/__tests__/trace.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compliance/__tests__/trace.test.js

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildRequirementTrace, buildTraceElementCatalog } from '../trace.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 = {
+    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 = [
+    { 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 = {
+            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 = {
+            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 = {
+            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 = {
+            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/dist/compliance/classify.js

@@ -32,7 +32,8 @@ export function ingestComplianceDoc(canon, doc) {
         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,
@@ -40,6 +41,11 @@ export function ingestComplianceDoc(canon, doc) {
             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/dist/compliance/index.d.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';
@@ -13,4 +14,4 @@ export type { ImpactCell, ImpactColumn, ImpactEmptyCellLabels, ImpactGrouping, I
 export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
 export { parseCoverageMetricConfig, buildCoverageMatrix, } from './coverage-metric.js';
 export type { CoverageMetricConfig, CoverageMetricRegimes, CoverageMetricRegimesFilter, CoverageMetricSubjects, CoverageMetricThresholds, CoverageMatrix, CoverageRow, ParseCoverageMetricResult, RagStatus, } from './coverage-metric.js';
-export type { ComplianceIndex, ComplianceIndexInput, DeadlineStatus, IndexRequirement, IndexAssertion, LawTree, LawTreeRequirement, ProductView, ProductRequirementStatus, ObjectDetailDef, ObjectDetailInput, } from './types.js';
+export type { ComplianceIndex, ComplianceIndexInput, DeadlineStatus, IndexRequirement, IndexAssertion, LawTree, LawTreeRequirement, ProductView, ProductRequirementStatus, ObjectDetailDef, ObjectDetailInput, RequirementTrace, TraceAssertionRow, TraceElementCatalog, TraceElementRef, TraceSourceRef, } from './types.js';

package/dist/compliance/index.js

@@ -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 { emptyCanon, ingestComplianceDoc } from './classify.js';
 export { renderComplianceMarkdown } from './markdown.js';