@transitrix/diagrams 1.0.0

package/src/compliance/index.ts

@@ -0,0 +1,56 @@
+export { buildComplianceIndex } from './reverse-index.js';
+export { buildLawTree, buildProductView } from './views.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 { 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, computeDeadlineStatus } from './impact.js';
+export type {
+  ImpactCell,
+  ImpactColumn,
+  ImpactEmptyCellLabels,
+  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,
+  CoverageMetricScope,
+  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';

package/src/compliance/markdown.ts

@@ -0,0 +1,135 @@
+// Markdown renderers for the compliance views (vkgeorgia/strategy#84 Phase 5).
+// Pure string builders consumed by the `transitrix export-compliance` CLI.
+// PDF rendering lives in `html.ts` (HTML doc fed to WeasyPrint by the CLI).
+
+import { buildComplianceMatrix } from '../compliance-matrix/index.js';
+import { buildComplianceIndex } from './reverse-index.js';
+import { buildLawTree, buildProductView } from './views.js';
+import { buildGapReport } from './gap-report.js';
+import type { ComplianceCanon } from './classify.js';
+import type { AssertionStatus } from '../assertion/types.js';
+
+const STATUS_LABELS: Record<AssertionStatus, string> = {
+  compliant: 'Compliant',
+  partial: 'Partial',
+  non_compliant: 'Non-compliant',
+  under_review: 'Under review',
+  n_a: 'N/A',
+};
+
+/** Escapes a value for a Markdown table cell (pipes + newlines). */
+function cell(s: string): string {
+  return s.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+export type ReportScope =
+  | { mode: 'matrix' }
+  | { mode: 'law'; id: string }
+  | { mode: 'product'; id: string }
+  | { mode: 'gap' };
+
+export interface MarkdownOptions {
+  /** Today as ISO YYYY-MM-DD — enables the gap dashboard's stale-assertion list. */
+  today?: string;
+}
+
+/** Renders the requested compliance view from a scanned canon to Markdown. */
+export function renderComplianceMarkdown(canon: ComplianceCanon, scope: ReportScope, options: MarkdownOptions = {}): string {
+  switch (scope.mode) {
+    case 'matrix': return matrixMarkdown(canon);
+    case 'law': return lawMarkdown(canon, scope.id);
+    case 'product': return productMarkdown(canon, scope.id);
+    case 'gap': return gapMarkdown(canon, options.today);
+  }
+}
+
+function matrixMarkdown(canon: ComplianceCanon): string {
+  const m = buildComplianceMatrix({ products: canon.products, requirements: canon.requirements, assertions: canon.assertions });
+  const out: string[] = ['# Compliance Matrix', ''];
+  out.push(`_${m.summary.products} products × ${m.summary.requirements} requirements · ${m.summary.gaps} gaps · ${m.summary.assertions} assertions_`, '');
+  if (m.products.length === 0 || m.requirements.length === 0) {
+    out.push('_No products or requirements found in the scanned canon._', '');
+    return out.join('\n');
+  }
+  out.push(`| Product \\ Requirement | ${m.requirements.map(r => cell(r.name)).join(' | ')} |`);
+  out.push(`|---|${m.requirements.map(() => '---').join('|')}|`);
+  m.products.forEach((p, ri) => {
+    const cells = m.requirements.map((_r, ci) => {
+      const c = m.cells[ri][ci];
+      return c.status ? STATUS_LABELS[c.status] : '—';
+    });
+    const name = cell(p.name) + (p.unresolved ? ' ⚠' : '');
+    out.push(`| ${name} | ${cells.join(' | ')} |`);
+  });
+  out.push('');
+  return out.join('\n');
+}
+
+function lawMarkdown(canon: ComplianceCanon, lawId: string): string {
+  const index = buildComplianceIndex({ requirements: canon.requirements, assertions: canon.assertions });
+  const tree = buildLawTree(lawId, index);
+  const law = canon.codex.find(c => c.id === lawId);
+  const out: string[] = [`# Compliance — ${law ? law.name : lawId}`, ''];
+  out.push(`\`${lawId}\` · ${tree.requirements.length} requirement(s)`, '');
+  if (tree.requirements.length === 0) {
+    out.push(`_No requirements derive from \`${lawId}\`._`, '');
+    return out.join('\n');
+  }
+  for (const node of tree.requirements) {
+    const sev = node.requirement.severity ? ` — severity: ${node.requirement.severity}` : '';
+    out.push(`## ${node.requirement.name} (\`${node.requirement.id}\`)${sev}`, '');
+    if (node.assertions.length === 0) {
+      out.push('_No assertion — compliance gap._', '');
+      continue;
+    }
+    for (const a of node.assertions) {
+      const meta = [a.assessed_at ? `assessed ${a.assessed_at}` : null, a.next_review_at ? `review by ${a.next_review_at}` : null].filter(Boolean).join(', ');
+      out.push(`- **${STATUS_LABELS[a.status]}** — \`${a.id}\` (subject \`${a.subject}\`${meta ? `; ${meta}` : ''})`);
+    }
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+function productMarkdown(canon: ComplianceCanon, productId: string): string {
+  const index = buildComplianceIndex({ requirements: canon.requirements, assertions: canon.assertions });
+  const view = buildProductView(productId, index);
+  const product = canon.products.find(p => p.id === productId);
+  const out: string[] = [`# Compliance — ${product ? product.name : productId}`, ''];
+  out.push(`\`${productId}\` · ${view.requirements.length} requirement(s) asserted`, '');
+  if (view.requirements.length === 0) {
+    out.push('_No assertion names this product as its subject._', '');
+    return out.join('\n');
+  }
+  out.push('| Requirement | Status | Assertion | Next review |', '|---|---|---|---|');
+  for (const { requirement, assertion } of view.requirements) {
+    out.push(`| ${cell(requirement.name)} (\`${requirement.id}\`) | ${STATUS_LABELS[assertion.status]} | \`${assertion.id}\` | ${assertion.next_review_at ?? '—'} |`);
+  }
+  out.push('');
+  return out.join('\n');
+}
+
+function gapMarkdown(canon: ComplianceCanon, today?: string): string {
+  const index = buildComplianceIndex({ requirements: canon.requirements, assertions: canon.assertions });
+  const report = buildGapReport(index, { today });
+  const total = report.requirementsWithoutAssertions.length + report.assertionsWithoutEvidence.length + report.staleAssertions.length + report.pastDeadlineRequirements.length;
+  const out: string[] = ['# Compliance Gap Dashboard', '', `_${total} gap(s) across 4 checks_`, ''];
+
+  out.push(`## Requirements without assertions (${report.requirementsWithoutAssertions.length})`, '');
+  if (report.requirementsWithoutAssertions.length === 0) out.push('_✓ none_', '');
+  else { for (const r of report.requirementsWithoutAssertions) out.push(`- [ ] \`${r.id}\` ${r.name}${r.severity ? ` — severity: ${r.severity}` : ''}${r.deadline ? ` — deadline: ${r.deadline}` : ''}`); out.push(''); }
+
+  out.push(`## Assertions without evidence — ASSERT-007 (${report.assertionsWithoutEvidence.length})`, '');
+  if (report.assertionsWithoutEvidence.length === 0) out.push('_✓ none_', '');
+  else { for (const a of report.assertionsWithoutEvidence) out.push(`- [ ] \`${a.id}\` — about \`${a.about}\`, subject \`${a.subject}\`, status ${a.status}`); out.push(''); }
+
+  out.push(`## Stale assertions — ASSERT-008 (${report.staleAssertions.length})`, '');
+  if (report.staleAssertions.length === 0) out.push('_✓ none_', '');
+  else { for (const a of report.staleAssertions) out.push(`- [ ] \`${a.id}\` — review due ${a.next_review_at ?? '—'}, subject \`${a.subject}\``); out.push(''); }
+
+  out.push(`## Past-deadline requirements — CV-5 (${report.pastDeadlineRequirements.length})`, '');
+  if (report.pastDeadlineRequirements.length === 0) out.push('_✓ none_', '');
+  else { for (const r of report.pastDeadlineRequirements) out.push(`- [ ] \`${r.id}\` ${r.name} — deadline: ${r.deadline ?? '—'}${r.severity ? `, severity: ${r.severity}` : ''}`); out.push(''); }
+
+  return out.join('\n');
+}

package/src/compliance/reverse-index.ts

@@ -0,0 +1,33 @@
+// Reverse-index builder (vkgeorgia/strategy#84 Phase 3).
+
+import type { ComplianceIndex, ComplianceIndexInput, IndexAssertion, IndexRequirement } from './types.js';
+
+function push<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const list = map.get(key);
+  if (list) list.push(value);
+  else map.set(key, [value]);
+}
+
+/**
+ * Builds the reverse indexes used by every compliance view. Pure; the input
+ * arrays are read, not mutated. Requirements with no `derived_from` simply do
+ * not appear under any law; assertions are indexed by both their requirement
+ * (`about`) and their subject.
+ */
+export function buildComplianceIndex(input: ComplianceIndexInput): ComplianceIndex {
+  const requirementById = new Map<string, IndexRequirement>();
+  const requirementsByLaw = new Map<string, IndexRequirement[]>();
+  const assertionsByRequirement = new Map<string, IndexAssertion[]>();
+  const assertionsBySubject = new Map<string, IndexAssertion[]>();
+
+  for (const r of input.requirements) {
+    requirementById.set(r.id, r);
+    for (const law of r.derived_from ?? []) push(requirementsByLaw, law, r);
+  }
+  for (const a of input.assertions) {
+    push(assertionsByRequirement, a.about, a);
+    push(assertionsBySubject, a.subject, a);
+  }
+
+  return { requirementById, requirementsByLaw, assertionsByRequirement, assertionsBySubject };
+}

package/src/compliance/types.ts

@@ -0,0 +1,120 @@
+// Shared compliance reverse-index + derived views (vkgeorgia/strategy#84
+// Phase 3). The reverse-index pass (Law → Requirements, Requirement →
+// Assertions, Subject → Assertions) backs the single-law tree and the
+// single-product view here, and the gap dashboard in Phase 4.
+
+import type { AssertionStatus } from '../assertion/types.js';
+
+/** Projection of a REQUIREMENT the compliance views need. */
+export interface IndexRequirement {
+  id: string;
+  name: string;
+  severity?: string;
+  /** Typed IDs of the codex sources this requirement derives from. */
+  derived_from?: string[];
+  /** Admission date (CONTRACT §6) — feeds DQ-1 freshness decay. */
+  admitted_at?: string;
+  /**
+   * Compliance deadline (ISO 8601 date, YYYY-MM-DD).
+   * When a gap exists on a cell whose requirement carries a deadline that is
+   * past or imminent, CV-3 renders an urgent decoration on the cell.
+   */
+  deadline?: string;
+}
+
+// ── Temporal status (CV-3) ──────────────────────────────────────────────────
+
+/**
+ * Temporal status of a requirement deadline relative to today.
+ *
+ * - `past_due`  — deadline has already passed (`deadline < today`).
+ * - `in_force`  — deadline is within the next 30 days.
+ * - `upcoming`  — deadline is more than 30 days away.
+ * - `none`      — no deadline set.
+ */
+export type DeadlineStatus = 'past_due' | 'in_force' | 'upcoming' | 'none';
+
+/** Projection of an ASSERTION the compliance views need. */
+export interface IndexAssertion {
+  id: string;
+  about: string;
+  subject: string;
+  status: AssertionStatus;
+  assessed_at?: string;
+  next_review_at?: string;
+  /** Number of evidence entries — feeds the Phase 4 "no evidence" gap. */
+  evidenceCount?: number;
+  /** Admission date (CONTRACT §6) — feeds DQ-1 freshness decay. */
+  admitted_at?: string;
+  /**
+   * Typed IDs of the stages / tasks where the requirement is realised for
+   * the subject (16-assertion.md §2 `realised_via`). Populated when the
+   * assertion carries granular evidence; absent when the claim covers the
+   * entire subject without stage decomposition. CV-3a uses this to fill
+   * stage-grouped matrix cells.
+   */
+  realised_via?: string[];
+}
+
+// ── Stage grouping (CV-3a) ──────────────────────────────────────────────────
+
+/** One detail-level element of a business object, used as a matrix sub-column. */
+export interface ObjectDetailDef {
+  id: string;
+  name: string;
+}
+
+/**
+ * Maps a business object to its ordered detail elements.
+ * Passed into `buildImpactMatrix` when `grouping.columns` is
+ * `object-details`. The details can be process stages, product
+ * components, capability modules, etc. — whatever sub-structure the object
+ * exposes. Typically extracted from a process-blueprint via`extractObjectDetails`.
+ */
+export interface ObjectDetailInput {
+  objectId: string;
+  details: ObjectDetailDef[];
+}
+
+export interface ComplianceIndexInput {
+  requirements: IndexRequirement[];
+  assertions: IndexAssertion[];
+}
+
+/** The reverse-index — all maps are keyed by canonical id. */
+export interface ComplianceIndex {
+  requirementById: Map<string, IndexRequirement>;
+  /** Codex artefact id → requirements whose `derived_from` names it. */
+  requirementsByLaw: Map<string, IndexRequirement[]>;
+  /** Requirement id → assertions whose `about` names it. */
+  assertionsByRequirement: Map<string, IndexAssertion[]>;
+  /** Subject id (product / process / capability) → assertions about it. */
+  assertionsBySubject: Map<string, IndexAssertion[]>;
+}
+
+// ── Single-law tree ─────────────────────────────────────────────────────────
+
+export interface LawTreeRequirement {
+  requirement: IndexRequirement;
+  /** Assertions targeting this requirement, id-sorted. */
+  assertions: IndexAssertion[];
+}
+export interface LawTree {
+  lawId: string;
+  /** Requirements derived from the law, id-sorted. */
+  requirements: LawTreeRequirement[];
+}
+
+// ── Single-product view ─────────────────────────────────────────────────────
+
+export interface ProductRequirementStatus {
+  /** The requirement the assertion is about. `name` falls back to the id when
+   *  the requirement is not present in the scan (dangling `about`). */
+  requirement: IndexRequirement;
+  assertion: IndexAssertion;
+}
+export interface ProductView {
+  productId: string;
+  /** Requirements bound to the product via an assertion, requirement-id-sorted. */
+  requirements: ProductRequirementStatus[];
+}

package/src/compliance/views.ts

@@ -0,0 +1,46 @@
+// Single-law tree + single-product view builders (vkgeorgia/strategy#84 Phase 3).
+
+import type {
+  ComplianceIndex,
+  IndexRequirement,
+  LawTree,
+  ProductView,
+} from './types.js';
+
+function byId<T extends { id: string }>(a: T, b: T): number {
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+/**
+ * Law → Requirements → Assertions. Requirements are those whose `derived_from`
+ * names `lawId`; each carries the assertions targeting it. An unknown law (no
+ * requirement derives from it) yields an empty tree.
+ */
+export function buildLawTree(lawId: string, index: ComplianceIndex): LawTree {
+  const requirements = [...(index.requirementsByLaw.get(lawId) ?? [])].sort(byId);
+  return {
+    lawId,
+    requirements: requirements.map(requirement => ({
+      requirement,
+      assertions: [...(index.assertionsByRequirement.get(requirement.id) ?? [])].sort(byId),
+    })),
+  };
+}
+
+/**
+ * Product → the Requirements it has an assertion about, with each assertion's
+ * status. The requirement is resolved from the index; a dangling `about`
+ * (assertion references a requirement not in the scan) falls back to a stub
+ * carrying the id as its name, so the binding still shows.
+ */
+export function buildProductView(productId: string, index: ComplianceIndex): ProductView {
+  const assertions = [...(index.assertionsBySubject.get(productId) ?? [])];
+  const requirements = assertions
+    .map(assertion => {
+      const requirement: IndexRequirement =
+        index.requirementById.get(assertion.about) ?? { id: assertion.about, name: assertion.about };
+      return { requirement, assertion };
+    })
+    .sort((a, b) => byId(a.requirement, b.requirement));
+  return { productId, requirements };
+}

package/src/compliance-matrix/__tests__/build.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect } from 'vitest';
+import { buildComplianceMatrix, filterComplianceMatrix } from '../build.js';
+import type { ComplianceMatrixInput } from '../types.js';
+
+function input(over: Partial<ComplianceMatrixInput> = {}): ComplianceMatrixInput {
+  return {
+    products: [
+      { id: 'PRODUCT-ECOMM-1', name: 'E-Commerce' },
+      { id: 'PRODUCT-SUPPORT-1', name: 'Support' },
+    ],
+    requirements: [
+      { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high' },
+      { id: 'REQUIREMENT-AUDIT-LOG-RETENTION-1', name: 'Audit logs', severity: 'medium' },
+    ],
+    assertions: [
+      { id: 'ASSERTION-1', about: 'REQUIREMENT-DATA-ERASURE-1', subject: 'PRODUCT-ECOMM-1', status: 'compliant' },
+    ],
+    ...over,
+  };
+}
+
+describe('buildComplianceMatrix', () => {
+  it('sorts products as rows and requirements as columns by id', () => {
+    const m = buildComplianceMatrix(input());
+    expect(m.products.map(p => p.id)).toEqual(['PRODUCT-ECOMM-1', 'PRODUCT-SUPPORT-1']);
+    expect(m.requirements.map(r => r.id)).toEqual([
+      'REQUIREMENT-AUDIT-LOG-RETENTION-1',
+      'REQUIREMENT-DATA-ERASURE-1',
+    ]);
+  });
+
+  it('places an assertion status in the (product, requirement) cell and gaps elsewhere', () => {
+    const m = buildComplianceMatrix(input());
+    // row 0 = ECOMM; col 1 = DATA-ERASURE (after the sort)
+    expect(m.cells[0][1]).toMatchObject({ status: 'compliant', assertionId: 'ASSERTION-1' });
+    expect(m.cells[0][0].status).toBeUndefined(); // ECOMM × AUDIT-LOG → gap
+    expect(m.cells[1][1].status).toBeUndefined(); // SUPPORT × DATA-ERASURE → gap
+    expect(m.summary).toMatchObject({ products: 2, requirements: 2, assertions: 1, gaps: 3 });
+  });
+
+  it('adds a product-typed assertion subject with no product file as an unresolved row', () => {
+    const m = buildComplianceMatrix(input({
+      assertions: [
+        { id: 'A1', about: 'REQUIREMENT-DATA-ERASURE-1', subject: 'PRODUCT-MOBILE-1', status: 'partial' },
+      ],
+    }));
+    const mobile = m.products.find(p => p.id === 'PRODUCT-MOBILE-1');
+    expect(mobile).toMatchObject({ unresolved: true });
+    const col = m.requirements.findIndex(r => r.id === 'REQUIREMENT-DATA-ERASURE-1');
+    const row = m.products.findIndex(p => p.id === 'PRODUCT-MOBILE-1');
+    expect(m.cells[row][col].status).toBe('partial');
+  });
+
+  it('ignores assertions whose subject is not a PRODUCT', () => {
+    const m = buildComplianceMatrix(input({
+      assertions: [
+        { id: 'A1', about: 'REQUIREMENT-DATA-ERASURE-1', subject: 'CAPABILITY-V2', status: 'compliant' },
+        { id: 'A2', about: 'REQUIREMENT-DATA-ERASURE-1', subject: 'PROCESS-X-1', status: 'partial' },
+      ],
+    }));
+    expect(m.summary.assertions).toBe(0);
+    expect(m.products.map(p => p.id)).toEqual(['PRODUCT-ECOMM-1', 'PRODUCT-SUPPORT-1']);
+  });
+});
+
+describe('buildComplianceMatrix — jurisdiction resolution (F16)', () => {
+  it('resolves Requirement.jurisdictions from derived_from → codex', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'] },
+        { id: 'REQUIREMENT-AUDIT-LOG-RETENTION-1', name: 'Audit logs', severity: 'medium',
+          derived_from: ['LAW-AUDIT-2020-1', 'LAW-PERSONAL-DATA-2017-1'] },
+      ],
+      codex: [
+        { id: 'LAW-PERSONAL-DATA-2017-1', jurisdiction: 'ge' },
+        { id: 'LAW-AUDIT-2020-1', jurisdiction: 'eu' },
+      ],
+    }));
+    const erasure = m.requirements.find(r => r.id === 'REQUIREMENT-DATA-ERASURE-1')!;
+    const audit = m.requirements.find(r => r.id === 'REQUIREMENT-AUDIT-LOG-RETENTION-1')!;
+    expect(erasure.jurisdictions).toEqual(['ge']);
+    // Sorted, deduplicated union.
+    expect(audit.jurisdictions).toEqual(['eu', 'ge']);
+  });
+
+  it('leaves jurisdictions undefined when no codex source resolves', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-INTERNAL-1', name: 'Internal', severity: 'low' },
+        { id: 'REQUIREMENT-DANGLING-1', name: 'Dangling', severity: 'low',
+          derived_from: ['LAW-MISSING-1'] },
+      ],
+      codex: [{ id: 'LAW-OTHER-1', jurisdiction: 'us' }],
+    }));
+    expect(m.requirements.find(r => r.id === 'REQUIREMENT-INTERNAL-1')!.jurisdictions).toBeUndefined();
+    expect(m.requirements.find(r => r.id === 'REQUIREMENT-DANGLING-1')!.jurisdictions).toBeUndefined();
+  });
+
+  it('ignores codex entries with no jurisdiction (e.g. internal POLICY)', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high',
+          derived_from: ['POLICY-INTERNAL-1'] },
+      ],
+      codex: [{ id: 'POLICY-INTERNAL-1' }],
+    }));
+    expect(m.requirements[0].jurisdictions).toBeUndefined();
+  });
+
+  it('works with no codex input (backwards-compatible)', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'] },
+      ],
+    }));
+    expect(m.requirements[0].jurisdictions).toBeUndefined();
+  });
+});
+
+describe('filterComplianceMatrix', () => {
+  it('trims requirement columns by severity', () => {
+    const m = buildComplianceMatrix(input());
+    const f = filterComplianceMatrix(m, { severities: ['high'] });
+    expect(f.requirements.map(r => r.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+    expect(f.cells[0]).toHaveLength(1);
+    expect(f.cells[0][0]).toMatchObject({ status: 'compliant' });
+  });
+
+  it('blanks cells whose status is filtered out, preserving the grid shape', () => {
+    const m = buildComplianceMatrix(input());
+    const f = filterComplianceMatrix(m, { statuses: ['non_compliant'] });
+    // The compliant cell is now hidden (treated as a gap); columns unchanged.
+    expect(f.requirements).toHaveLength(2);
+    expect(f.cells[0][1].status).toBeUndefined();
+    expect(f.summary.assertions).toBe(0);
+  });
+
+  it('is a no-op when no filter dimension is set', () => {
+    const m = buildComplianceMatrix(input());
+    const f = filterComplianceMatrix(m, {});
+    expect(f.summary).toEqual(m.summary);
+  });
+
+  it('keeps only columns whose resolved jurisdiction is in the filter (F16)', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'] },
+        { id: 'REQUIREMENT-AUDIT-LOG-RETENTION-1', name: 'Audit logs', severity: 'medium',
+          derived_from: ['LAW-AUDIT-2020-1'] },
+      ],
+      codex: [
+        { id: 'LAW-PERSONAL-DATA-2017-1', jurisdiction: 'ge' },
+        { id: 'LAW-AUDIT-2020-1', jurisdiction: 'eu' },
+      ],
+    }));
+    const f = filterComplianceMatrix(m, { jurisdictions: ['ge'] });
+    expect(f.requirements.map(r => r.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+    expect(f.cells[0]).toHaveLength(1);
+  });
+
+  it('drops requirements with no resolved jurisdiction when the filter is active', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'] },
+        { id: 'REQUIREMENT-INTERNAL-1', name: 'Internal', severity: 'low' },
+      ],
+      codex: [{ id: 'LAW-PERSONAL-DATA-2017-1', jurisdiction: 'ge' }],
+    }));
+    const f = filterComplianceMatrix(m, { jurisdictions: ['ge'] });
+    expect(f.requirements.map(r => r.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+  });
+
+  it('combines jurisdiction filter with severity (intersection)', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-DATA-ERASURE-1', name: 'Erasure', severity: 'high',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'] },
+        { id: 'REQUIREMENT-DATA-PORTABILITY-1', name: 'Portability', severity: 'medium',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'] },
+      ],
+      codex: [{ id: 'LAW-PERSONAL-DATA-2017-1', jurisdiction: 'ge' }],
+    }));
+    const f = filterComplianceMatrix(m, { jurisdictions: ['ge'], severities: ['high'] });
+    expect(f.requirements.map(r => r.id)).toEqual(['REQUIREMENT-DATA-ERASURE-1']);
+  });
+
+  it('empty jurisdiction array is treated as no-filter on that dimension', () => {
+    const m = buildComplianceMatrix(input({
+      requirements: [
+        { id: 'REQUIREMENT-INTERNAL-1', name: 'Internal', severity: 'low' },
+      ],
+    }));
+    const f = filterComplianceMatrix(m, { jurisdictions: [] });
+    expect(f.requirements).toHaveLength(1);
+  });
+});

package/src/compliance-matrix/__tests__/example.test.ts

@@ -0,0 +1,57 @@
+// Conformance test — the compliance matrix on the acme_corp worked examples
+// (mirrored under tests/fixtures/notation-corpus/product, tests/fixtures/notation-corpus/requirement, tests/fixtures/notation-corpus/assertion).
+// Pins the #84 Phase 2 acceptance: the matrix renders correctly and gaps are
+// obvious.
+
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { buildComplianceMatrix } from '../build.js';
+import type { MatrixAssertionRef, MatrixProduct, MatrixRequirement } from '../types.js';
+
+const examples = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+function loadAll(dir: string): Record<string, unknown>[] {
+  const full = path.join(examples, dir);
+  return readdirSync(full)
+    .filter(f => f.endsWith('.yaml'))
+    .map(f => yaml.load(readFileSync(path.join(full, f), 'utf-8')) as Record<string, unknown>);
+}
+
+describe('compliance matrix — acme_corp worked examples', () => {
+  const products: MatrixProduct[] = loadAll('product').map(p => ({ id: String(p.id), name: String(p.name) }));
+  const requirements: MatrixRequirement[] = loadAll('requirement').map(r => ({
+    id: String(r.id), name: String(r.name), severity: r.severity as string | undefined,
+  }));
+  const assertions: MatrixAssertionRef[] = loadAll('assertion').map(a => ({
+    id: String(a.id), about: String(a.about), subject: String(a.subject),
+    status: a.status as MatrixAssertionRef['status'],
+    assessed_at: a.assessed_at as string | undefined,
+    next_review_at: a.next_review_at as string | undefined,
+  }));
+
+  const m = buildComplianceMatrix({ products, requirements, assertions });
+
+  it('rows = the two product files plus the dangling PRODUCT-MOBILE-1 subject', () => {
+    expect(m.products.map(p => p.id)).toEqual([
+      'PRODUCT-ECOMM-1', 'PRODUCT-MOBILE-1', 'PRODUCT-SUPPORT-1',
+    ]);
+    expect(m.products.find(p => p.id === 'PRODUCT-MOBILE-1')?.unresolved).toBe(true);
+  });
+
+  it('columns = the two requirements', () => {
+    expect(m.requirements.map(r => r.id)).toEqual([
+      'REQUIREMENT-AUDIT-LOG-RETENTION-1', 'REQUIREMENT-DATA-ERASURE-1',
+    ]);
+  });
+
+  it('the only product-subject assertion (mobile → data-erasure) is compliant; everything else is a gap', () => {
+    const row = m.products.findIndex(p => p.id === 'PRODUCT-MOBILE-1');
+    const col = m.requirements.findIndex(r => r.id === 'REQUIREMENT-DATA-ERASURE-1');
+    expect(m.cells[row][col]).toMatchObject({ status: 'compliant', assertionId: 'ASSERTION-MOBILE-DATA-ERASURE-1' });
+    // 3 products × 2 requirements = 6 cells; 1 filled → 5 gaps. The CRM
+    // (capability) and onboarding (process) assertions are not in the matrix.
+    expect(m.summary).toMatchObject({ products: 3, requirements: 2, assertions: 1, gaps: 5 });
+  });
+});

package/src/compliance-matrix/index.ts

@@ -0,0 +1,11 @@
+export { buildComplianceMatrix, filterComplianceMatrix } from './build.js';
+export type {
+  ComplianceMatrix,
+  ComplianceMatrixInput,
+  MatrixProduct,
+  MatrixRequirement,
+  MatrixAssertionRef,
+  MatrixCell,
+  MatrixCodexDoc,
+  MatrixFilter,
+} from './types.js';