@transitrix/diagrams 1.5.0 → 1.7.6

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/__tests__/view-resolution.test.d.ts

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

package/dist/compliance/__tests__/view-resolution.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { emptyCanon } from '../classify.js';
+import { catalogFromMap } from '../canon-catalog.js';
+import { collectImpactViewResolutionFindings } from '../impact.js';
+import { collectCoverageViewResolutionFindings } from '../coverage-metric.js';
+const catalog = catalogFromMap(new Map([
+    ['PRODUCT-ECOMM-1', 'PRODUCT'],
+    ['REQUIREMENT-GDPR-1', 'REQUIREMENT'],
+    ['LAW-GDPR-1', 'LAW'],
+]));
+const complianceCanon = emptyCanon();
+complianceCanon.products.push({ id: 'PRODUCT-ECOMM-1', name: 'E-Commerce' });
+complianceCanon.requirements.push({ id: 'REQUIREMENT-GDPR-1', name: 'GDPR req' });
+complianceCanon.codex.push({ id: 'LAW-GDPR-1', name: 'GDPR' });
+describe('collectImpactViewResolutionFindings', () => {
+    const base = {
+        id: 'test-impact',
+        name: 'Test',
+        subjects: { products: ['PRODUCT-ECOMM-1'], processes: [], capabilities: [] },
+        obligations: { filter: { derived_from_codex: ['LAW-GDPR-1'] } },
+        status_display: { show: ['compliant'] },
+        empty_cells: {},
+        order_rows_by: 'id',
+    };
+    it('passes when subjects and regimes resolve', () => {
+        expect(collectImpactViewResolutionFindings(base, catalog, complianceCanon)).toEqual([]);
+    });
+    it('flags unresolved subjects and regimes', () => {
+        const findings = collectImpactViewResolutionFindings({
+            ...base,
+            subjects: { products: ['PRODUCT-MISSING-1'], processes: [], capabilities: [] },
+            obligations: { include: ['REQUIREMENT-MISSING-1'], filter: { derived_from_codex: ['LAW-MISSING-1'] } },
+        }, catalog, complianceCanon);
+        expect(findings.some((f) => f.code === 'COMPIMP-REF' && f.message.includes('PRODUCT-MISSING-1'))).toBe(true);
+        expect(findings.some((f) => f.message.includes('REQUIREMENT-MISSING-1'))).toBe(true);
+        expect(findings.some((f) => f.message.includes('LAW-MISSING-1'))).toBe(true);
+    });
+});
+describe('collectCoverageViewResolutionFindings', () => {
+    const base = {
+        id: 'test-coverage',
+        name: 'Test',
+        thresholds: { green: 0.9, amber: 0.7 },
+        subjects: { products: ['PRODUCT-ECOMM-1'] },
+        regimes: { include: ['LAW-GDPR-1'] },
+    };
+    it('passes when products and regimes resolve', () => {
+        expect(collectCoverageViewResolutionFindings(base, catalog, complianceCanon)).toEqual([]);
+    });
+    it('flags unresolved product and regime refs', () => {
+        const findings = collectCoverageViewResolutionFindings({
+            ...base,
+            subjects: { products: ['PRODUCT-MISSING-1'] },
+            regimes: { include: ['LAW-MISSING-1'] },
+        }, catalog, complianceCanon);
+        expect(findings.some((f) => f.code === 'COVMET-REF')).toBe(true);
+        expect(findings).toHaveLength(2);
+    });
+});

package/dist/compliance/canon-catalog.d.ts

@@ -0,0 +1,19 @@
+import { type CanonCatalog } from '../typed-id.js';
+import { type ComplianceCanon } from './classify.js';
+export interface ScannedYamlDoc {
+    path: string;
+    data: unknown;
+}
+export interface ComplianceScanResult {
+    complianceCanon: ComplianceCanon;
+    catalog: CanonCatalog;
+    /** First path where each admitted id was seen (for gap-dashboard warnings). */
+    pathById: Map<string, string>;
+}
+/** Admit one parsed document into the id → TYPE map. */
+export declare function admitDocumentToCatalog(map: Map<string, string>, doc: unknown): string | undefined;
+/** Build a read-only `CanonCatalog` from a populated id → TYPE map. */
+export declare function catalogFromMap(map: Map<string, string>): CanonCatalog;
+/** Ingest compliance projections and admit cross-reference targets from a batch
+ *  of already-parsed YAML documents (no IO). */
+export declare function buildComplianceScan(docs: ScannedYamlDoc[]): ComplianceScanResult;

package/dist/compliance/canon-catalog.js

@@ -0,0 +1,59 @@
+// CanonCatalog builder — repo-scope cross-reference resolution (#518 Phase C3).
+//
+// Scans admitted YAML documents and builds the `{ typeOf }` catalogue that
+// `validateRequirement` / `validateAssertion` accept for REQ-002 and
+// ASSERT-002..005 resolution.
+import { typeOfId } from '../typed-id.js';
+import { emptyCanon, ingestComplianceDoc } from './classify.js';
+function strId(doc) {
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc))
+        return undefined;
+    const id = doc.id;
+    return typeof id === 'string' && id.trim() !== '' ? id.trim() : undefined;
+}
+/** Admit one parsed document into the id → TYPE map. */
+export function admitDocumentToCatalog(map, doc) {
+    const id = strId(doc);
+    if (!id)
+        return undefined;
+    const fromPrefix = typeOfId(id);
+    if (fromPrefix) {
+        map.set(id, fromPrefix);
+        return id;
+    }
+    if (doc !== null && typeof doc === 'object' && !Array.isArray(doc)) {
+        const d = doc;
+        if (d.zone === 'codex') {
+            const explicit = typeof d.type === 'string' ? d.type.trim().toUpperCase() : undefined;
+            if (explicit) {
+                map.set(id, explicit);
+                return id;
+            }
+        }
+    }
+    return undefined;
+}
+/** Build a read-only `CanonCatalog` from a populated id → TYPE map. */
+export function catalogFromMap(map) {
+    return { typeOf: (id) => map.get(id) };
+}
+/** Ingest compliance projections and admit cross-reference targets from a batch
+ *  of already-parsed YAML documents (no IO). */
+export function buildComplianceScan(docs) {
+    const complianceCanon = emptyCanon();
+    const catalogMap = new Map();
+    const pathById = new Map();
+    for (const { path, data } of docs) {
+        const ingested = ingestComplianceDoc(complianceCanon, data);
+        if (ingested)
+            pathById.set(ingested, path);
+        const admitted = admitDocumentToCatalog(catalogMap, data);
+        if (admitted && !pathById.has(admitted))
+            pathById.set(admitted, path);
+    }
+    return {
+        complianceCanon,
+        catalog: catalogFromMap(catalogMap),
+        pathById,
+    };
+}

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/coverage-metric.d.ts

@@ -1,4 +1,5 @@
 import type { ComplianceCanon } from './classify.js';
+import type { CanonCatalog } from '../typed-id.js';
 /** Declarative filter resolved at build time from the canon's codex catalogue. */
 export interface CoverageMetricRegimesFilter {
     jurisdiction?: string[];
@@ -73,6 +74,17 @@ export interface CoverageMatrix {
     rows: CoverageRow[];
     thresholds: CoverageMetricThresholds;
 }
+/** Repo-scope cross-reference finding for a coverage-metric view (#518 C3). */
+export interface CoverageViewFinding {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+}
+/**
+ * Repo-scope cross-reference checks for a parsed coverage-metric view config.
+ * Surfaces unresolved product and regime ids before `buildCoverageMatrix` runs.
+ */
+export declare function collectCoverageViewResolutionFindings(config: CoverageMetricConfig, catalog: CanonCatalog, complianceCanon: ComplianceCanon): CoverageViewFinding[];
 /**
  * Parse and validate a raw (YAML-parsed) document into a `CoverageMetricConfig`.
  *

package/dist/compliance/coverage-metric.js

@@ -5,6 +5,41 @@
 // across the scoped products, and what is the RAG status against the configured
 // thresholds.
 import { buildComplianceIndex } from './reverse-index.js';
+/**
+ * Repo-scope cross-reference checks for a parsed coverage-metric view config.
+ * Surfaces unresolved product and regime ids before `buildCoverageMatrix` runs.
+ */
+export function collectCoverageViewResolutionFindings(config, catalog, complianceCanon) {
+    const findings = [];
+    const codexIds = new Set(complianceCanon.codex.map((c) => c.id));
+    for (const id of config.subjects?.products ?? []) {
+        const t = catalog.typeOf(id);
+        if (t === undefined) {
+            findings.push({
+                code: 'COVMET-REF',
+                severity: 'error',
+                message: `subjects.products: "${id}" does not resolve to an admitted artefact.`,
+            });
+        }
+        else if (t !== 'PRODUCT') {
+            findings.push({
+                code: 'COVMET-REF',
+                severity: 'error',
+                message: `subjects.products: "${id}" resolves to ${t}, not PRODUCT.`,
+            });
+        }
+    }
+    for (const id of config.regimes?.include ?? []) {
+        if (!codexIds.has(id)) {
+            findings.push({
+                code: 'COVMET-REF',
+                severity: 'error',
+                message: `regimes.include: "${id}" does not resolve to an admitted codex artefact.`,
+            });
+        }
+    }
+    return findings;
+}
 // ── Parser ───────────────────────────────────────────────────────────────────
 function parseRegimes(raw) {
     const warnings = [];

package/dist/compliance/impact.d.ts

@@ -1,5 +1,6 @@
 import type { AssertionStatus } from '../assertion/types.js';
 import type { ComplianceCanon } from './classify.js';
+import type { CanonCatalog } from '../typed-id.js';
 import type { IndexAssertion, IndexRequirement, ObjectDetailInput, DeadlineStatus } from './types.js';
 /** Filter selecting REQUIREMENTs by codex source (jurisdiction / regime keys
  *  are accepted for forward compatibility but not yet honoured — the canon
@@ -57,12 +58,17 @@ export interface ImpactColumn {
      *  Used to enforce the subject type label invariant (§5.2, COMPIMP-010). */
     subjectType: 'product' | 'process' | 'capability';
 }
-/** A structural validation finding emitted by the matrix builder. */
 export interface ImpactFinding {
     code: string;
     severity: 'error' | 'warning';
     message: string;
 }
+/**
+ * Repo-scope cross-reference checks for a parsed compliance-impact view config
+ * (#518 Phase C3). Surfaces unresolved subject, obligation, and regime ids before
+ * `buildImpactMatrix` runs.
+ */
+export declare function collectImpactViewResolutionFindings(config: ImpactViewConfig, catalog: CanonCatalog, complianceCanon: ComplianceCanon): ImpactFinding[];
 /**
  * Grouping options for matrix columns.
  *

package/dist/compliance/impact.js

@@ -7,6 +7,59 @@
 // (`product` columns × `obligation` rows). Stage / task grouping is planned
 // for CV-3a and intentionally out of scope here.
 import { buildComplianceIndex } from './reverse-index.js';
+/**
+ * Repo-scope cross-reference checks for a parsed compliance-impact view config
+ * (#518 Phase C3). Surfaces unresolved subject, obligation, and regime ids before
+ * `buildImpactMatrix` runs.
+ */
+export function collectImpactViewResolutionFindings(config, catalog, complianceCanon) {
+    const findings = [];
+    const codexIds = new Set(complianceCanon.codex.map((c) => c.id));
+    const subjectChecks = [
+        { ids: config.subjects.products, expectedType: 'PRODUCT', path: 'subjects.products' },
+        { ids: config.subjects.processes, expectedType: 'PROCESS', path: 'subjects.processes' },
+        { ids: config.subjects.capabilities, expectedType: 'CAPABILITY', path: 'subjects.capabilities' },
+    ];
+    for (const { ids, expectedType, path } of subjectChecks) {
+        for (const id of ids ?? []) {
+            const t = catalog.typeOf(id);
+            if (t === undefined) {
+                findings.push({
+                    code: 'COMPIMP-REF',
+                    severity: 'error',
+                    message: `${path}: "${id}" does not resolve to an admitted artefact.`,
+                });
+            }
+            else if (t !== expectedType) {
+                findings.push({
+                    code: 'COMPIMP-REF',
+                    severity: 'error',
+                    message: `${path}: "${id}" resolves to ${t}, not ${expectedType}.`,
+                });
+            }
+        }
+    }
+    for (const id of config.obligations.include ?? []) {
+        const t = catalog.typeOf(id);
+        if (t === undefined || t !== 'REQUIREMENT') {
+            findings.push({
+                code: 'COMPIMP-REF',
+                severity: 'error',
+                message: `obligations.include: "${id}" does not resolve to an admitted REQUIREMENT.`,
+            });
+        }
+    }
+    for (const id of config.obligations.filter?.derived_from_codex ?? []) {
+        if (!codexIds.has(id)) {
+            findings.push({
+                code: 'COMPIMP-REF',
+                severity: 'error',
+                message: `obligations.filter.derived_from_codex: "${id}" does not resolve to an admitted codex artefact.`,
+            });
+        }
+    }
+    return findings;
+}
 // ── Pinned defaults ─────────────────────────────────────────────────────────
 /**
  * Explicit defaults for every optional field in ImpactViewConfig.

package/dist/compliance/index.d.ts

@@ -1,16 +1,19 @@
 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';
 export type { ComplianceCanon, ComplianceProduct, ComplianceCodexDoc } from './classify.js';
+export { admitDocumentToCatalog, buildComplianceScan, catalogFromMap, } from './canon-catalog.js';
+export type { ComplianceScanResult, ScannedYamlDoc } from './canon-catalog.js';
 export { renderComplianceMarkdown } from './markdown.js';
 export type { ReportScope, MarkdownOptions } from './markdown.js';
 export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
 export type { HtmlOptions, ImpactMatrixHtmlOptions } from './html.js';
-export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
-export type { ImpactCell, ImpactColumn, ImpactEmptyCellLabels, ImpactGrouping, ImpactMatrix, ImpactObligationFilter, ImpactStatusDisplay, ImpactSubjects, ImpactViewConfig, ParseImpactViewConfigResult, } from './impact.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, collectImpactViewResolutionFindings, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
+export type { ImpactCell, ImpactColumn, ImpactEmptyCellLabels, ImpactFinding, ImpactGrouping, ImpactMatrix, ImpactObligationFilter, ImpactStatusDisplay, ImpactSubjects, ImpactViewConfig, ParseImpactViewConfigResult, } from './impact.js';
 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 { parseCoverageMetricConfig, buildCoverageMatrix, collectCoverageViewResolutionFindings, } from './coverage-metric.js';
+export type { CoverageMetricConfig, CoverageMetricRegimes, CoverageMetricRegimesFilter, CoverageMetricSubjects, CoverageMetricThresholds, CoverageMatrix, CoverageRow, CoverageViewFinding, ParseCoverageMetricResult, RagStatus, } from './coverage-metric.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,9 +1,11 @@
 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 { admitDocumentToCatalog, buildComplianceScan, catalogFromMap, } from './canon-catalog.js';
 export { renderComplianceMarkdown } from './markdown.js';
 export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
-export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, collectImpactViewResolutionFindings, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
 export { assertionToScoringElement, complianceConfidenceHeader, requirementToScoringElement, scoreComplianceView, } from './confidence.js';
-export { parseCoverageMetricConfig, buildCoverageMatrix, } from './coverage-metric.js';
+export { parseCoverageMetricConfig, buildCoverageMatrix, collectCoverageViewResolutionFindings, } from './coverage-metric.js';

package/dist/compliance/reverse-index.js

@@ -17,14 +17,17 @@ export function buildComplianceIndex(input) {
     const requirementsByLaw = new Map();
     const assertionsByRequirement = new Map();
     const assertionsBySubject = new Map();
+    const requirementsByParent = new Map();
     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/dist/compliance/trace.d.ts

@@ -0,0 +1,26 @@
+import type { ComplianceIndex, RequirementTrace, TraceElementCatalog } from './types.js';
+import type { ComplianceCodexDoc } from './classify.js';
+/**
+ * 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 declare function buildRequirementTrace(requirementId: string, index: ComplianceIndex, catalog: TraceElementCatalog, codex?: ComplianceCodexDoc[]): RequirementTrace;
+/**
+ * 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 declare function buildTraceElementCatalog(products: Array<{
+    id: string;
+    name: string;
+}>, subjects: Array<{
+    id: string;
+    name: string;
+}>): TraceElementCatalog;

package/dist/compliance/trace.js

@@ -0,0 +1,89 @@
+// 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.
+function byId(a, b) {
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function resolveElement(id, catalog) {
+    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, index) {
+    const out = [];
+    const seen = new Set([requirement.id]);
+    let current = 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, index, catalog, codex = []) {
+    const requirement = index.requirementById.get(requirementId) ?? { id: requirementId, name: requirementId };
+    const codexById = new Map();
+    for (const c of codex)
+        codexById.set(c.id, c);
+    const sources = (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 = [...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, subjects) {
+    const nameById = new Map();
+    for (const p of products)
+        nameById.set(p.id, p.name);
+    for (const s of subjects)
+        nameById.set(s.id, s.name);
+    return { nameById };
+}