@transitrix/diagrams 1.0.0

package/src/capability-map/types.ts

@@ -0,0 +1,29 @@
+export type CapabilityType = 'domain' | 'supporting';
+
+export interface CapabilityNode {
+  id: string;
+  name: string;
+  type?: CapabilityType;
+  description?: string;
+  current_maturity: number;
+  target_maturity?: number;
+  target_date?: string;
+  owner_role?: string;
+  business_process?: string;
+  applications?: string[];
+  children?: CapabilityNode[];
+}
+
+export interface CapabilityMapHeader {
+  id: string;
+  name: string;
+  description?: string;
+  assessment_date: string;
+  capabilities: CapabilityNode[];
+}
+
+export interface CapabilityMapFile {
+  notation: string;
+  spec_version?: string;
+  capability_map: CapabilityMapHeader;
+}

package/src/capability-map/validate.ts

@@ -0,0 +1,127 @@
+import type { CapabilityType } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const VALID_TYPES = new Set<CapabilityType>(['domain', 'supporting']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Canonical form per `IDS_AND_REFERENCES.md` §2: `CAPABILITY-V…` /
+// `CAPABILITY-H…` with the dotted address (`V1`, `V1.2.1`, `H1`). The bare
+// legacy form (`V1`, `H1`) is still accepted so existing maps without the
+// canonical prefix do not break — migration is tracked under
+// vkgeorgia/strategy#36.
+const CAP_ID_RE = /^(CAPABILITY-)?(V|H)\d+(\.\d+)*$/;
+
+export function validateCapabilityMap(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'CMAP-001', message: 'Input must be an object' }], warnings };
+  }
+  const raw = input as Record<string, unknown>;
+
+  if (!('notation' in raw)) {
+    errors.push({ code: 'CMAP-001', message: 'Missing required field: notation' });
+  } else if (raw['notation'] !== 'capability-map') {
+    errors.push({ code: 'CMAP-001', message: `notation must be "capability-map", got "${raw['notation']}"` });
+  }
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const map = raw['capability_map'];
+  if (!map || typeof map !== 'object') {
+    errors.push({ code: 'CMAP-002', message: 'Missing required field: capability_map' });
+    return { valid: false, errors, warnings };
+  }
+  const m = map as Record<string, unknown>;
+
+  if (!m['id'] || typeof m['id'] !== 'string' || !(m['id'] as string).trim())
+    errors.push({ code: 'CMAP-002', message: 'capability_map.id is required' });
+  if (!m['name'] || typeof m['name'] !== 'string' || !(m['name'] as string).trim())
+    errors.push({ code: 'CMAP-002', message: 'capability_map.name is required' });
+  if (!m['assessment_date'] || typeof m['assessment_date'] !== 'string')
+    errors.push({ code: 'CMAP-002', message: 'capability_map.assessment_date is required' });
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  if (!DATE_RE.test(m['assessment_date'] as string))
+    errors.push({ code: 'CMAP-007', message: `capability_map.assessment_date must be YYYY-MM-DD, got "${m['assessment_date']}"` });
+
+  const caps = m['capabilities'];
+  if (!Array.isArray(caps)) {
+    errors.push({ code: 'CMAP-002', message: 'capability_map.capabilities must be an array' });
+    return { valid: false, errors, warnings };
+  }
+
+  const seenIds = new Set<string>();
+  validateCapabilityTree(caps, 'capabilities', errors, seenIds);
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateCapabilityTree(
+  nodes: unknown[],
+  pathPrefix: string,
+  errors: ValidationError[],
+  seenIds: Set<string>,
+): void {
+  for (let i = 0; i < nodes.length; i++) {
+    const rawNode = nodes[i];
+    const nodePath = `${pathPrefix}[${i}]`;
+
+    if (!rawNode || typeof rawNode !== 'object') {
+      errors.push({ code: 'CMAP-003', message: `${nodePath} must be an object` });
+      continue;
+    }
+    const node = rawNode as Record<string, unknown>;
+
+    if (!node['id'] || typeof node['id'] !== 'string' || !(node['id'] as string).trim()) {
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: id is required` });
+    } else {
+      const id = node['id'] as string;
+      if (seenIds.has(id)) {
+        errors.push({ code: 'CMAP-008', message: `Duplicate capability id: "${id}"` });
+      }
+      seenIds.add(id);
+      if (!CAP_ID_RE.test(id)) {
+        errors.push({ code: 'CMAP-009', message: `${nodePath}: id "${id}" must match the canonical pattern CAPABILITY-V[n] or CAPABILITY-H[n] with optional .n segments (e.g. CAPABILITY-V1, CAPABILITY-V1.2, CAPABILITY-H1.3); the bare V[n] / H[n] form is also accepted for legacy compatibility` });
+      }
+    }
+
+    if (!node['name'] || typeof node['name'] !== 'string' || !(node['name'] as string).trim())
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: name is required` });
+
+    if (node['current_maturity'] === undefined) {
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: current_maturity is required` });
+    } else {
+      const cm = node['current_maturity'];
+      if (typeof cm !== 'number' || !Number.isInteger(cm) || cm < 1 || cm > 5)
+        errors.push({ code: 'CMAP-005', message: `${nodePath}: current_maturity must be an integer 1–5, got "${cm}"` });
+    }
+
+    if (node['target_maturity'] !== undefined) {
+      const tm = node['target_maturity'];
+      if (typeof tm !== 'number' || !Number.isInteger(tm) || tm < 1 || tm > 5)
+        errors.push({ code: 'CMAP-006', message: `${nodePath}: target_maturity must be an integer 1–5, got "${tm}"` });
+    }
+
+    if (node['type'] !== undefined && !VALID_TYPES.has(node['type'] as CapabilityType))
+      errors.push({ code: 'CMAP-004', message: `${nodePath}: type "${node['type']}" must be one of: domain, supporting` });
+
+    if (node['target_date'] !== undefined) {
+      if (typeof node['target_date'] !== 'string' || !DATE_RE.test(node['target_date'] as string))
+        errors.push({ code: 'CMAP-007', message: `${nodePath}: target_date must be YYYY-MM-DD, got "${node['target_date']}"` });
+    }
+
+    if (node['applications'] !== undefined && !Array.isArray(node['applications']))
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: applications must be an array` });
+
+    if (node['children'] !== undefined) {
+      if (!Array.isArray(node['children'])) {
+        errors.push({ code: 'CMAP-003', message: `${nodePath}: children must be an array` });
+      } else {
+        validateCapabilityTree(node['children'] as unknown[], `${nodePath}.children`, errors, seenIds);
+      }
+    }
+  }
+}

package/src/change/__tests__/validate.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { validateChange } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'change',
+    id: 'CHANGE-EU-CRM-1',
+    name: 'Stand up EU-localised CRM and payment processing',
+    goals: ['GOAL-EU-1'],
+    description: 'The required delta to operate in EU markets.',
+    zone: 'canon',
+    admitted_at: '2026-05-29',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2026-05-26',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] => validateChange(input).errors.map(e => e.code);
+
+describe('validateChange — positive', () => {
+  it('accepts the worked-example CHANGE-EU-CRM-1', () => {
+    const r = validateChange(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('accepts a minimal change (no goals, no parent)', () => {
+    const r = valid();
+    delete r.goals;
+    expect(validateChange(r).valid).toBe(true);
+  });
+
+  it('accepts a child change with a CHANGE parent', () => {
+    expect(validateChange({ ...valid(), id: 'CHANGE-EU-CRM-DETAIL-1', parent: 'CHANGE-EU-CRM-1' }).valid).toBe(true);
+  });
+});
+
+describe('validateChange — CHANGE-001 (envelope / shape)', () => {
+  it('flags a non-object', () => {
+    expect(codes(null)).toEqual(['CHANGE-001']);
+  });
+
+  it('flags wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'gap' })).toContain('CHANGE-001');
+  });
+
+  it('flags an id with the wrong TYPE prefix', () => {
+    expect(codes({ ...valid(), id: 'ACTIVITY-DESIGN-1' })).toContain('CHANGE-001');
+  });
+
+  it('flags a missing admission field', () => {
+    const r = valid();
+    delete r.admitted_at;
+    expect(codes(r)).toContain('CHANGE-001');
+  });
+
+  it('flags a missing valid_to key', () => {
+    const r = valid();
+    delete r.valid_to;
+    expect(codes(r)).toContain('CHANGE-001');
+  });
+});
+
+describe('validateChange — CHANGE-002 (goals refs)', () => {
+  it('flags a non-GOAL typed id in goals', () => {
+    expect(codes({ ...valid(), goals: ['CHANGE-EU-CRM-1'] })).toContain('CHANGE-002');
+  });
+
+  it('flags a malformed entry in goals', () => {
+    expect(codes({ ...valid(), goals: ['not an id'] })).toContain('CHANGE-002');
+  });
+
+  it('flags goals when it is not an array', () => {
+    expect(codes({ ...valid(), goals: 'GOAL-EU-1' })).toContain('CHANGE-002');
+  });
+});
+
+describe('validateChange — CHANGE-003 (parent ref)', () => {
+  it('flags a non-CHANGE parent', () => {
+    expect(codes({ ...valid(), parent: 'GOAL-EU-1' })).toContain('CHANGE-003');
+  });
+
+  it('flags self-parenting', () => {
+    expect(codes({ ...valid(), parent: 'CHANGE-EU-CRM-1' })).toContain('CHANGE-003');
+  });
+});

package/src/change/index.ts

@@ -0,0 +1,2 @@
+export type { Change } from './types.js';
+export { validateChange } from './validate.js';

package/src/change/types.ts

@@ -0,0 +1,23 @@
+// CHANGE — implementation-layer gap primitive (ArchiMate Gap).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.3 + envelope §3.
+
+import type { GateChecks } from '../requirement/types.js';
+
+export interface Change {
+  notation: 'change';
+  id: string;
+  name: string;
+  /** GOAL-… IDs this change delivers. */
+  goals?: string[];
+  /** CHANGE-… — the higher-scale change this one decomposes from. */
+  parent?: string;
+  description?: string;
+
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/change/validate.ts

@@ -0,0 +1,61 @@
+// CHANGE validator — methodology notations/ELEMENT_PRIMITIVES.md §7.3.
+//
+// Implements CHANGE-001..003. Cross-cutting HDR-/LIFECYCLE- and the BDN
+// linkage rules across documents are owned elsewhere (CONTRACT.md §8) and
+// out of scope for this single-artefact validator.
+//
+// §7.3 defines no subtype vocabulary on `type`, so there is no enum gate here.
+
+import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
+import { typeOfId } from '../typed-id.js';
+import { validateElementEnvelope } from '../element-envelope.js';
+
+export function validateChange(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  const { record, errors: envErrors } = validateElementEnvelope(input, {
+    notation: 'change',
+    idType: 'CHANGE',
+    code: 'CHANGE-001',
+  });
+  errors.push(...envErrors);
+  if (!record) return { valid: false, errors, warnings };
+
+  // CHANGE-002 — goals[] must be a list of GOAL typed ids.
+  if (record.goals !== undefined) {
+    if (!Array.isArray(record.goals)) {
+      errors.push({ code: 'CHANGE-002', message: 'goals must be a list of typed GOAL IDs.', path: 'goals' });
+    } else {
+      record.goals.forEach((ref, i) => {
+        if (typeOfId(ref) !== 'GOAL') {
+          errors.push({
+            code: 'CHANGE-002',
+            message: `goals[${i}] "${String(ref)}" must be a GOAL typed ID.`,
+            path: `goals[${i}]`,
+          });
+        }
+      });
+    }
+  }
+
+  // CHANGE-003 — parent must be a CHANGE typed id (multi-scale decomposition).
+  if (record.parent !== undefined) {
+    if (typeof record.parent !== 'string' || typeOfId(record.parent) !== 'CHANGE') {
+      errors.push({
+        code: 'CHANGE-003',
+        message: `parent "${String(record.parent)}" must be a CHANGE typed ID.`,
+        path: 'parent',
+      });
+    } else if (record.parent === record.id) {
+      // A change cannot decompose from itself.
+      errors.push({
+        code: 'CHANGE-003',
+        message: `parent "${record.parent}" must not equal id (a change cannot be its own parent).`,
+        path: 'parent',
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

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

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { emptyCanon, ingestComplianceDoc } from '../classify.js';
+
+describe('ingestComplianceDoc', () => {
+  it('buckets each artefact kind by notation / zone', () => {
+    const canon = emptyCanon();
+    expect(ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-1', name: 'P' })).toBe('PRODUCT-1');
+    expect(ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-1', name: 'R', severity: 'high', derived_from: ['LAW-1'], admitted_at: '2026-05-28' })).toBe('REQUIREMENT-1');
+    expect(ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-1', about: 'REQUIREMENT-1', subject: 'PRODUCT-1', status: 'compliant', evidence: [{ kind: 'note', text: 'x' }], admitted_at: '2026-05-28' })).toBe('ASSERTION-1');
+    expect(ingestComplianceDoc(canon, { id: 'LAW-1', name: 'Law', type: 'LAW', zone: 'codex', jurisdiction: 'ge' })).toBe('LAW-1');
+
+    expect(canon.products).toEqual([{ id: 'PRODUCT-1', name: 'P' }]);
+    expect(canon.requirements[0]).toMatchObject({ id: 'REQUIREMENT-1', severity: 'high', derived_from: ['LAW-1'] });
+    expect(canon.assertions[0]).toMatchObject({ id: 'ASSERTION-1', status: 'compliant', evidenceCount: 1 });
+    expect(canon.codex[0]).toMatchObject({ id: 'LAW-1', type: 'LAW', jurisdiction: 'ge' });
+  });
+
+  it('returns null for non-artefacts, missing id, and malformed assertions', () => {
+    const canon = emptyCanon();
+    expect(ingestComplianceDoc(canon, { notation: 'goals', id: 'X-1' })).toBeNull();
+    expect(ingestComplianceDoc(canon, { notation: 'product' })).toBeNull(); // no id
+    expect(ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-2', about: 'R' })).toBeNull(); // missing subject/status
+    expect(ingestComplianceDoc(canon, null)).toBeNull();
+    expect(ingestComplianceDoc(canon, 'str')).toBeNull();
+    expect(canon.products).toEqual([]);
+  });
+});

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

@@ -0,0 +1,98 @@
+// Bridge from the compliance index projections to the DQ-1 confidence module
+// (vkgeorgia/strategy#162 — DQ-2). Pins that:
+//   • element TYPEs lift to REQUIREMENT / ASSERTION (decay lookup keys),
+//   • admitted_at flows through to the freshness curve,
+//   • the §11.6 header line matches the spec example shape,
+//   • an empty view suppresses the header (caller-controlled).
+
+import { describe, it, expect } from 'vitest';
+import {
+  assertionToScoringElement,
+  complianceConfidenceHeader,
+  requirementToScoringElement,
+  scoreComplianceView,
+} from '../confidence.js';
+import type { IndexAssertion, IndexRequirement } from '../types.js';
+
+const req = (over: Partial<IndexRequirement> = {}): IndexRequirement => ({
+  id: 'REQUIREMENT-1', name: 'R', admitted_at: '2026-05-01', ...over,
+});
+const ass = (over: Partial<IndexAssertion> = {}): IndexAssertion => ({
+  id: 'ASSERTION-1', about: 'REQUIREMENT-1', subject: 'PRODUCT-1',
+  status: 'compliant', admitted_at: '2026-05-01', ...over,
+});
+
+describe('requirementToScoringElement / assertionToScoringElement', () => {
+  it('lifts the index projection to a ScoringElement', () => {
+    expect(requirementToScoringElement(req())).toEqual({
+      type: 'REQUIREMENT', admitted_at: '2026-05-01',
+    });
+    expect(assertionToScoringElement(ass())).toEqual({
+      type: 'ASSERTION', admitted_at: '2026-05-01',
+    });
+  });
+
+  it('leaves sources undefined — v1 has no field-zone provenance to resolve', () => {
+    // Documents the §11.5 behaviour: until DSM/Studio ingest field-zone
+    // source_quality, every element scores unsourced and is counted separately.
+    expect(requirementToScoringElement(req()).sources).toBeUndefined();
+    expect(assertionToScoringElement(ass()).sources).toBeUndefined();
+  });
+
+  it('preserves an absent admitted_at as undefined', () => {
+    expect(requirementToScoringElement(req({ admitted_at: undefined })).admitted_at).toBeUndefined();
+  });
+});
+
+describe('scoreComplianceView', () => {
+  it('scores the union of requirements + assertions and reports today', () => {
+    const v = scoreComplianceView([req()], [ass()], '2026-06-07');
+    expect(v.today).toBe('2026-06-07');
+    expect(v.elements).toHaveLength(2);
+    expect(v.composite.element_count).toBe(2);
+    // Two fresh elements (37 days old, ≤ implicit fresh_days=180) → freshness=1.0,
+    // but no sources → source_trust=0.25 floor → confidence=0.25, band D.
+    for (const e of v.elements) {
+      expect(e.freshness).toBe(1.0);
+      expect(e.source_trust).toBe(0.25);
+      expect(e.confidence).toBe(0.25);
+      expect(e.sourced).toBe(false);
+    }
+    expect(v.composite.band).toBe('D');
+    expect(v.composite.coverage).toBe(0);
+    expect(v.composite.unsourced_count).toBe(2);
+  });
+
+  it('returns the degenerate composite for an empty view', () => {
+    const v = scoreComplianceView([], [], '2026-06-07');
+    expect(v.composite.element_count).toBe(0);
+    expect(v.elements).toHaveLength(0);
+  });
+
+  it('honours per-TYPE decay overrides from the manifest config', () => {
+    // ASSERTION decays faster than REQUIREMENT — exercise the by_type lookup.
+    const v = scoreComplianceView(
+      [req({ admitted_at: '2025-01-01' })],
+      [ass({ admitted_at: '2025-01-01' })],
+      '2026-06-07',
+      {
+        by_type: {
+          REQUIREMENT: { fresh_days: 1000, stale_days: 2000, floor: 0.5 },
+          ASSERTION:   { fresh_days: 30,   stale_days: 60,   floor: 0.1 },
+        },
+      },
+    );
+    // Requirement is still well within fresh_days=1000 → freshness 1.0.
+    expect(v.elements[0].freshness).toBe(1.0);
+    // Assertion is well past stale_days=60 → freshness floors at 0.1.
+    expect(v.elements[1].freshness).toBeCloseTo(0.1, 10);
+  });
+});
+
+describe('complianceConfidenceHeader', () => {
+  it('formats the §11.6 example shape and returns empty for an empty view', () => {
+    expect(complianceConfidenceHeader([], [], '2026-06-07')).toBe('');
+    const line = complianceConfidenceHeader([req()], [ass()], '2026-06-07');
+    expect(line).toMatch(/^Data confidence \(as of 2026-06-07\): D \(weakest link\) · 0\.25 mean · 0% sourced$/);
+  });
+});

package/src/compliance/__tests__/coverage-metric.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseCoverageMetricConfig,
+  buildCoverageMatrix,
+  type CoverageMetricConfig,
+} from '../coverage-metric.js';
+import { emptyCanon, ingestComplianceDoc } from '../classify.js';
+import type { ComplianceCanon } from '../classify.js';
+
+// ── parseCoverageMetricConfig ─────────────────────────────────────────────────
+
+describe('parseCoverageMetricConfig', () => {
+  it('rejects null', () => {
+    const r = parseCoverageMetricConfig(null);
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects missing id', () => {
+    const r = parseCoverageMetricConfig({ coverage_metric: { name: 'x' } });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.errors.some(e => e.includes('id'))).toBe(true);
+  });
+
+  it('parses minimal config', () => {
+    const r = parseCoverageMetricConfig({
+      coverage_metric: {
+        id: 'CM-1',
+        name: 'Test',
+      },
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.config.id).toBe('CM-1');
+      expect(r.config.name).toBe('Test');
+      expect(r.config.thresholds.green).toBe(0.8);
+      expect(r.config.thresholds.amber).toBe(0.5);
+    }
+  });
+
+  it('parses full config with scope and thresholds', () => {
+    const r = parseCoverageMetricConfig({
+      coverage_metric: {
+        id: 'CM-2',
+        name: 'EU Coverage',
+        description: 'desc',
+        scope: {
+          jurisdictions: ['EU'],
+          codex: ['LAW-GDPR-1'],
+          subjects: { products: ['PRODUCT-1'] },
+        },
+        thresholds: { green: 0.9, amber: 0.6 },
+      },
+    });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.config.scope.codex).toEqual(['LAW-GDPR-1']);
+      expect(r.config.scope.subjects?.products).toEqual(['PRODUCT-1']);
+      expect(r.config.thresholds.green).toBe(0.9);
+      expect(r.config.thresholds.amber).toBe(0.6);
+    }
+  });
+
+  it('accepts bare (unwrapped) object', () => {
+    const r = parseCoverageMetricConfig({ id: 'CM-3', name: 'Bare' });
+    expect(r.ok).toBe(true);
+  });
+});
+
+// ── buildCoverageMatrix ───────────────────────────────────────────────────────
+
+function makeCanon(): ComplianceCanon {
+  const canon = emptyCanon();
+  // Codex: GDPR law
+  ingestComplianceDoc(canon, { id: 'LAW-GDPR-1', name: 'GDPR', zone: 'codex', jurisdiction: 'EU' });
+  // Requirements
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-1', name: 'Lawful basis', derived_from: ['LAW-GDPR-1'] });
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-2', name: 'Data minimisation', derived_from: ['LAW-GDPR-1'] });
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-3', name: 'Breach notification', derived_from: ['LAW-GDPR-1'] });
+  // Products
+  ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-1', name: 'E-commerce' });
+  // Assertions
+  ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-1', about: 'REQ-1', subject: 'PRODUCT-1', status: 'compliant' });
+  ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-2', about: 'REQ-2', subject: 'PRODUCT-1', status: 'partial' });
+  // REQ-3 has no assertion → gap
+  return canon;
+}
+
+function makeConfig(overrides?: Partial<CoverageMetricConfig>): CoverageMetricConfig {
+  return {
+    id: 'CM-TEST-1',
+    name: 'Test Coverage',
+    scope: {
+      codex: ['LAW-GDPR-1'],
+      subjects: { products: ['PRODUCT-1'] },
+    },
+    thresholds: { green: 0.8, amber: 0.5 },
+    ...overrides,
+  };
+}
+
+describe('buildCoverageMatrix', () => {
+  it('returns correct row counts', () => {
+    const canon = makeCanon();
+    const config = makeConfig();
+    const matrix = buildCoverageMatrix(canon, config);
+
+    expect(matrix.rows).toHaveLength(1);
+    const row = matrix.rows[0];
+    expect(row.codexId).toBe('LAW-GDPR-1');
+    expect(row.totalRequirements).toBe(3);
+    expect(row.compliant).toBe(1);
+    expect(row.partial).toBe(1);
+    expect(row.gap).toBe(1);
+    expect(row.coveredCount).toBe(2);
+  });
+
+  it('computes coverage percentage correctly', () => {
+    const matrix = buildCoverageMatrix(makeCanon(), makeConfig());
+    const row = matrix.rows[0];
+    // 2 covered out of 3 → ~66.7%
+    expect(row.coveragePct).toBeCloseTo(2 / 3, 5);
+  });
+
+  it('assigns amber RAG status for ~67% coverage with green=0.80, amber=0.50', () => {
+    const matrix = buildCoverageMatrix(makeCanon(), makeConfig());
+    expect(matrix.rows[0].ragStatus).toBe('amber');
+  });
+
+  it('assigns green RAG when all requirements covered', () => {
+    const canon = makeCanon();
+    // Add assertion for REQ-3 so all 3 are covered
+    ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-3', about: 'REQ-3', subject: 'PRODUCT-1', status: 'compliant' });
+    const matrix = buildCoverageMatrix(canon, makeConfig());
+    expect(matrix.rows[0].ragStatus).toBe('green');
+    expect(matrix.rows[0].coveragePct).toBe(1);
+  });
+
+  it('assigns red RAG when coverage < amber threshold', () => {
+    const matrix = buildCoverageMatrix(makeCanon(), makeConfig({ thresholds: { green: 0.9, amber: 0.8 } }));
+    // ~67% < 80% → red
+    expect(matrix.rows[0].ragStatus).toBe('red');
+  });
+
+  it('returns no_data when codex has no requirements', () => {
+    const canon = emptyCanon();
+    ingestComplianceDoc(canon, { id: 'LAW-EMPTY-1', name: 'Empty Law', zone: 'codex', jurisdiction: 'XX' });
+    const config = makeConfig({ scope: { codex: ['LAW-EMPTY-1'] } });
+    const matrix = buildCoverageMatrix(canon, config);
+    expect(matrix.rows[0].ragStatus).toBe('no_data');
+    expect(matrix.rows[0].totalRequirements).toBe(0);
+  });
+
+  it('includes jurisdiction from scanned canon', () => {
+    const matrix = buildCoverageMatrix(makeCanon(), makeConfig());
+    expect(matrix.rows[0].jurisdiction).toBe('EU');
+  });
+
+  it('handles multiple codex entries', () => {
+    const canon = makeCanon();
+    ingestComplianceDoc(canon, { id: 'LAW-NIS2-1', name: 'NIS2', zone: 'codex', jurisdiction: 'EU' });
+    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-NIS-1', name: 'Incident reporting', derived_from: ['LAW-NIS2-1'] });
+    const config = makeConfig({ scope: { codex: ['LAW-GDPR-1', 'LAW-NIS2-1'] } });
+    const matrix = buildCoverageMatrix(canon, config);
+    expect(matrix.rows).toHaveLength(2);
+    expect(matrix.rows[1].codexId).toBe('LAW-NIS2-1');
+    expect(matrix.rows[1].gap).toBe(1);
+  });
+
+  it('respects product scope — ignores assertions for other products', () => {
+    const canon = makeCanon();
+    // Add another product with compliant assertion for REQ-3
+    ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-2', name: 'Support' });
+    ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-OUT', about: 'REQ-3', subject: 'PRODUCT-2', status: 'compliant' });
+    // config only scopes PRODUCT-1 → REQ-3 should still be a gap
+    const matrix = buildCoverageMatrix(canon, makeConfig({ scope: { codex: ['LAW-GDPR-1'], subjects: { products: ['PRODUCT-1'] } } }));
+    expect(matrix.rows[0].gap).toBe(1);
+  });
+
+  it('counts non_compliant separately', () => {
+    const canon = makeCanon();
+    ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-FAIL', about: 'REQ-3', subject: 'PRODUCT-1', status: 'non_compliant' });
+    const matrix = buildCoverageMatrix(canon, makeConfig());
+    expect(matrix.rows[0].non_compliant).toBe(1);
+    expect(matrix.rows[0].gap).toBe(0);
+    // non_compliant does not count as covered
+    expect(matrix.rows[0].coveredCount).toBe(2);
+  });
+});