@transitrix/diagrams 1.0.0 → 1.0.1

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

@@ -1,95 +1,95 @@
-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 { renderComplianceMarkdown } from '../markdown.js';
-import { emptyCanon, ingestComplianceDoc, type ComplianceCanon } from '../classify.js';
-
-function synthetic(): ComplianceCanon {
-  const canon = emptyCanon();
-  ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-M-1', name: 'Mobile App' });
-  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-ERASURE-1', name: 'Erasure', severity: 'high', derived_from: ['LAW-X-1'] });
-  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-LOG-1', name: 'Logs', severity: 'low' });
-  ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-1', about: 'REQUIREMENT-ERASURE-1', subject: 'PRODUCT-M-1', status: 'compliant', evidence: [{ kind: 'note', text: 'x' }], next_review_at: '2026-09-01' });
-  ingestComplianceDoc(canon, { id: 'LAW-X-1', name: 'Privacy Law', zone: 'codex', type: 'LAW' });
-  return canon;
-}
-
-describe('renderComplianceMarkdown — matrix', () => {
-  it('renders a table with status cells and gap dashes', () => {
-    const md = renderComplianceMarkdown(synthetic(), { mode: 'matrix' });
-    expect(md).toContain('# Compliance Matrix');
-    expect(md).toContain('| Product \\ Requirement | Erasure | Logs |');
-    expect(md).toMatch(/\| Mobile App \| Compliant \| — \|/);
-  });
-});
-
-describe('renderComplianceMarkdown — law', () => {
-  it('renders the law name and its requirement with the assertion bullet', () => {
-    const md = renderComplianceMarkdown(synthetic(), { mode: 'law', id: 'LAW-X-1' });
-    expect(md).toContain('# Compliance — Privacy Law');
-    expect(md).toContain('## Erasure (`REQUIREMENT-ERASURE-1`) — severity: high');
-    expect(md).toContain('- **Compliant** — `ASSERTION-1`');
-  });
-});
-
-describe('renderComplianceMarkdown — product', () => {
-  it('renders the product table of asserted requirements', () => {
-    const md = renderComplianceMarkdown(synthetic(), { mode: 'product', id: 'PRODUCT-M-1' });
-    expect(md).toContain('# Compliance — Mobile App');
-    expect(md).toContain('| Requirement | Status | Assertion | Next review |');
-    expect(md).toMatch(/\| Erasure \(`REQUIREMENT-ERASURE-1`\) \| Compliant \| `ASSERTION-1` \| 2026-09-01 \|/);
-  });
-});
-
-describe('renderComplianceMarkdown — gap', () => {
-  it('lists the un-asserted requirement as a checklist item', () => {
-    const md = renderComplianceMarkdown(synthetic(), { mode: 'gap' }, { today: '2026-06-02' });
-    expect(md).toContain('## Requirements without assertions (1)');
-    expect(md).toContain('- [ ] `REQUIREMENT-LOG-1` Logs — severity: low');
-    expect(md).toContain('## Assertions without evidence — ASSERT-007 (0)');
-  });
-});
-
-// ── Conformance: build canon by ingesting the acme example files ────────────
-
-const examples = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
-function ingestDir(canon: ComplianceCanon, dir: string): void {
-  const full = path.join(examples, dir);
-  for (const f of readdirSync(full)) {
-    if (!f.endsWith('.yaml')) continue;
-    ingestComplianceDoc(canon, yaml.load(readFileSync(path.join(full, f), 'utf-8')));
-  }
-}
-
-describe('renderComplianceMarkdown — acme conformance', () => {
-  const canon = emptyCanon();
-  ingestDir(canon, 'product');
-  ingestDir(canon, 'requirement');
-  ingestDir(canon, 'assertion');
-
-  it('matrix marks the dangling PRODUCT-MOBILE-1 row and shows compliant + gaps', () => {
-    const md = renderComplianceMarkdown(canon, { mode: 'matrix' });
-    expect(md).toContain('PRODUCT-MOBILE-1 ⚠');
-    expect(md).toContain('Compliant');
-    expect(md).toContain('—'); // at least one gap dash
-  });
-
-  it('gap report surfaces the un-asserted audit-log requirement', () => {
-    const md = renderComplianceMarkdown(canon, { mode: 'gap' }, { today: '2026-06-02' });
-    expect(md).toContain('`REQUIREMENT-AUDIT-LOG-RETENTION-1`');
-  });
-});
-
-describe('gapMarkdown CV-5 pastDeadlineRequirements section', () => {
-  it('includes the 4th section in output', () => {
-    const canon = emptyCanon();
-    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-PD-1', name: 'Past', deadline: '2020-01-01' });
-    const md = renderComplianceMarkdown(canon, { mode: 'gap' }, { today: '2026-06-09' });
-    expect(md).toContain('Past-deadline requirements');
-    expect(md).toContain('REQ-PD-1');
-    expect(md).toContain('2020-01-01');
-    expect(md).toContain('4 checks');
-  });
+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 { renderComplianceMarkdown } from '../markdown.js';
+import { emptyCanon, ingestComplianceDoc, type ComplianceCanon } from '../classify.js';
+
+function synthetic(): ComplianceCanon {
+  const canon = emptyCanon();
+  ingestComplianceDoc(canon, { notation: 'product', id: 'PRODUCT-M-1', name: 'Mobile App' });
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-ERASURE-1', name: 'Erasure', severity: 'high', derived_from: ['LAW-X-1'] });
+  ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQUIREMENT-LOG-1', name: 'Logs', severity: 'low' });
+  ingestComplianceDoc(canon, { notation: 'assertion', id: 'ASSERTION-1', about: 'REQUIREMENT-ERASURE-1', subject: 'PRODUCT-M-1', status: 'compliant', evidence: [{ kind: 'note', text: 'x' }], next_review_at: '2026-09-01' });
+  ingestComplianceDoc(canon, { id: 'LAW-X-1', name: 'Privacy Law', zone: 'codex', type: 'LAW' });
+  return canon;
+}
+
+describe('renderComplianceMarkdown — matrix', () => {
+  it('renders a table with status cells and gap dashes', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'matrix' });
+    expect(md).toContain('# Compliance Matrix');
+    expect(md).toContain('| Product \\ Requirement | Erasure | Logs |');
+    expect(md).toMatch(/\| Mobile App \| Compliant \| — \|/);
+  });
+});
+
+describe('renderComplianceMarkdown — law', () => {
+  it('renders the law name and its requirement with the assertion bullet', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'law', id: 'LAW-X-1' });
+    expect(md).toContain('# Compliance — Privacy Law');
+    expect(md).toContain('## Erasure (`REQUIREMENT-ERASURE-1`) — severity: high');
+    expect(md).toContain('- **Compliant** — `ASSERTION-1`');
+  });
+});
+
+describe('renderComplianceMarkdown — product', () => {
+  it('renders the product table of asserted requirements', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'product', id: 'PRODUCT-M-1' });
+    expect(md).toContain('# Compliance — Mobile App');
+    expect(md).toContain('| Requirement | Status | Assertion | Next review |');
+    expect(md).toMatch(/\| Erasure \(`REQUIREMENT-ERASURE-1`\) \| Compliant \| `ASSERTION-1` \| 2026-09-01 \|/);
+  });
+});
+
+describe('renderComplianceMarkdown — gap', () => {
+  it('lists the un-asserted requirement as a checklist item', () => {
+    const md = renderComplianceMarkdown(synthetic(), { mode: 'gap' }, { today: '2026-06-02' });
+    expect(md).toContain('## Requirements without assertions (1)');
+    expect(md).toContain('- [ ] `REQUIREMENT-LOG-1` Logs — severity: low');
+    expect(md).toContain('## Assertions without evidence — ASSERT-007 (0)');
+  });
+});
+
+// ── Conformance: build canon by ingesting the acme example files ────────────
+
+const examples = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus');
+function ingestDir(canon: ComplianceCanon, dir: string): void {
+  const full = path.join(examples, dir);
+  for (const f of readdirSync(full)) {
+    if (!f.endsWith('.yaml')) continue;
+    ingestComplianceDoc(canon, yaml.load(readFileSync(path.join(full, f), 'utf-8')));
+  }
+}
+
+describe('renderComplianceMarkdown — acme conformance', () => {
+  const canon = emptyCanon();
+  ingestDir(canon, 'product');
+  ingestDir(canon, 'requirement');
+  ingestDir(canon, 'assertion');
+
+  it('matrix marks the dangling PRODUCT-MOBILE-1 row and shows compliant + gaps', () => {
+    const md = renderComplianceMarkdown(canon, { mode: 'matrix' });
+    expect(md).toContain('PRODUCT-MOBILE-1 ⚠');
+    expect(md).toContain('Compliant');
+    expect(md).toContain('—'); // at least one gap dash
+  });
+
+  it('gap report surfaces the un-asserted audit-log requirement', () => {
+    const md = renderComplianceMarkdown(canon, { mode: 'gap' }, { today: '2026-06-02' });
+    expect(md).toContain('`REQUIREMENT-AUDIT-LOG-RETENTION-1`');
+  });
+});
+
+describe('gapMarkdown CV-5 pastDeadlineRequirements section', () => {
+  it('includes the 4th section in output', () => {
+    const canon = emptyCanon();
+    ingestComplianceDoc(canon, { notation: 'requirement', id: 'REQ-PD-1', name: 'Past', deadline: '2020-01-01' });
+    const md = renderComplianceMarkdown(canon, { mode: 'gap' }, { today: '2026-06-09' });
+    expect(md).toContain('Past-deadline requirements');
+    expect(md).toContain('REQ-PD-1');
+    expect(md).toContain('2020-01-01');
+    expect(md).toContain('4 checks');
+  });
 });

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

@@ -1,64 +1,64 @@
-import { describe, it, expect } from 'vitest';
-import { buildComplianceIndex } from '../reverse-index.js';
-import { buildLawTree, buildProductView } from '../views.js';
-import type { ComplianceIndexInput } from '../types.js';
-
-const input: ComplianceIndexInput = {
-  requirements: [
-    { id: 'REQUIREMENT-A-1', name: 'A', severity: 'high', derived_from: ['LAW-X-1'] },
-    { id: 'REQUIREMENT-B-1', name: 'B', severity: 'low', derived_from: ['LAW-X-1', 'REGULATION-Y-1'] },
-    { id: 'REQUIREMENT-C-1', name: 'C' }, // internal-only, no law
-  ],
-  assertions: [
-    { id: 'ASSERTION-2', about: 'REQUIREMENT-A-1', subject: 'PRODUCT-M-1', status: 'compliant' },
-    { id: 'ASSERTION-1', about: 'REQUIREMENT-A-1', subject: 'CAPABILITY-V2', status: 'under_review' },
-    { id: 'ASSERTION-3', about: 'REQUIREMENT-B-1', subject: 'PRODUCT-M-1', status: 'partial' },
-  ],
-};
-
-describe('buildComplianceIndex', () => {
-  const idx = buildComplianceIndex(input);
-  it('indexes requirements by the laws they derive from', () => {
-    expect(idx.requirementsByLaw.get('LAW-X-1')?.map(r => r.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
-    expect(idx.requirementsByLaw.get('REGULATION-Y-1')?.map(r => r.id)).toEqual(['REQUIREMENT-B-1']);
-    expect(idx.requirementsByLaw.has('LAW-NONE-1')).toBe(false);
-  });
-  it('indexes assertions by requirement and by subject', () => {
-    expect(idx.assertionsByRequirement.get('REQUIREMENT-A-1')?.map(a => a.id).sort()).toEqual(['ASSERTION-1', 'ASSERTION-2']);
-    expect(idx.assertionsBySubject.get('PRODUCT-M-1')?.map(a => a.id).sort()).toEqual(['ASSERTION-2', 'ASSERTION-3']);
-  });
-});
-
-describe('buildLawTree', () => {
-  const idx = buildComplianceIndex(input);
-  it('lists requirements derived from the law, each with its id-sorted assertions', () => {
-    const tree = buildLawTree('LAW-X-1', idx);
-    expect(tree.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
-    expect(tree.requirements[0].assertions.map(a => a.id)).toEqual(['ASSERTION-1', 'ASSERTION-2']);
-    expect(tree.requirements[0].assertions.map(a => a.status)).toEqual(['under_review', 'compliant']);
-  });
-  it('returns an empty tree for an unknown law', () => {
-    expect(buildLawTree('LAW-NONE-1', idx).requirements).toEqual([]);
-  });
-});
-
-describe('buildProductView', () => {
-  const idx = buildComplianceIndex(input);
-  it('lists the requirements the product is asserted against, with status, requirement-id-sorted', () => {
-    const view = buildProductView('PRODUCT-M-1', idx);
-    expect(view.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
-    expect(view.requirements.map(r => r.assertion.status)).toEqual(['compliant', 'partial']);
-    expect(view.requirements[0].requirement.name).toBe('A');
-  });
-  it('falls back to the id as name when the requirement is not in the scan (dangling about)', () => {
-    const idx2 = buildComplianceIndex({
-      requirements: [],
-      assertions: [{ id: 'ASSERTION-9', about: 'REQUIREMENT-GONE-1', subject: 'PRODUCT-M-1', status: 'n_a' }],
-    });
-    const view = buildProductView('PRODUCT-M-1', idx2);
-    expect(view.requirements[0].requirement).toEqual({ id: 'REQUIREMENT-GONE-1', name: 'REQUIREMENT-GONE-1' });
-  });
-  it('returns an empty view for a product with no assertions', () => {
-    expect(buildProductView('PRODUCT-NONE-1', idx).requirements).toEqual([]);
-  });
-});
+import { describe, it, expect } from 'vitest';
+import { buildComplianceIndex } from '../reverse-index.js';
+import { buildLawTree, buildProductView } from '../views.js';
+import type { ComplianceIndexInput } from '../types.js';
+
+const input: ComplianceIndexInput = {
+  requirements: [
+    { id: 'REQUIREMENT-A-1', name: 'A', severity: 'high', derived_from: ['LAW-X-1'] },
+    { id: 'REQUIREMENT-B-1', name: 'B', severity: 'low', derived_from: ['LAW-X-1', 'REGULATION-Y-1'] },
+    { id: 'REQUIREMENT-C-1', name: 'C' }, // internal-only, no law
+  ],
+  assertions: [
+    { id: 'ASSERTION-2', about: 'REQUIREMENT-A-1', subject: 'PRODUCT-M-1', status: 'compliant' },
+    { id: 'ASSERTION-1', about: 'REQUIREMENT-A-1', subject: 'CAPABILITY-V2', status: 'under_review' },
+    { id: 'ASSERTION-3', about: 'REQUIREMENT-B-1', subject: 'PRODUCT-M-1', status: 'partial' },
+  ],
+};
+
+describe('buildComplianceIndex', () => {
+  const idx = buildComplianceIndex(input);
+  it('indexes requirements by the laws they derive from', () => {
+    expect(idx.requirementsByLaw.get('LAW-X-1')?.map(r => r.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
+    expect(idx.requirementsByLaw.get('REGULATION-Y-1')?.map(r => r.id)).toEqual(['REQUIREMENT-B-1']);
+    expect(idx.requirementsByLaw.has('LAW-NONE-1')).toBe(false);
+  });
+  it('indexes assertions by requirement and by subject', () => {
+    expect(idx.assertionsByRequirement.get('REQUIREMENT-A-1')?.map(a => a.id).sort()).toEqual(['ASSERTION-1', 'ASSERTION-2']);
+    expect(idx.assertionsBySubject.get('PRODUCT-M-1')?.map(a => a.id).sort()).toEqual(['ASSERTION-2', 'ASSERTION-3']);
+  });
+});
+
+describe('buildLawTree', () => {
+  const idx = buildComplianceIndex(input);
+  it('lists requirements derived from the law, each with its id-sorted assertions', () => {
+    const tree = buildLawTree('LAW-X-1', idx);
+    expect(tree.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
+    expect(tree.requirements[0].assertions.map(a => a.id)).toEqual(['ASSERTION-1', 'ASSERTION-2']);
+    expect(tree.requirements[0].assertions.map(a => a.status)).toEqual(['under_review', 'compliant']);
+  });
+  it('returns an empty tree for an unknown law', () => {
+    expect(buildLawTree('LAW-NONE-1', idx).requirements).toEqual([]);
+  });
+});
+
+describe('buildProductView', () => {
+  const idx = buildComplianceIndex(input);
+  it('lists the requirements the product is asserted against, with status, requirement-id-sorted', () => {
+    const view = buildProductView('PRODUCT-M-1', idx);
+    expect(view.requirements.map(r => r.requirement.id)).toEqual(['REQUIREMENT-A-1', 'REQUIREMENT-B-1']);
+    expect(view.requirements.map(r => r.assertion.status)).toEqual(['compliant', 'partial']);
+    expect(view.requirements[0].requirement.name).toBe('A');
+  });
+  it('falls back to the id as name when the requirement is not in the scan (dangling about)', () => {
+    const idx2 = buildComplianceIndex({
+      requirements: [],
+      assertions: [{ id: 'ASSERTION-9', about: 'REQUIREMENT-GONE-1', subject: 'PRODUCT-M-1', status: 'n_a' }],
+    });
+    const view = buildProductView('PRODUCT-M-1', idx2);
+    expect(view.requirements[0].requirement).toEqual({ id: 'REQUIREMENT-GONE-1', name: 'REQUIREMENT-GONE-1' });
+  });
+  it('returns an empty view for a product with no assertions', () => {
+    expect(buildProductView('PRODUCT-NONE-1', idx).requirements).toEqual([]);
+  });
+});

package/src/compliance/classify.ts

@@ -1,84 +1,100 @@
-// Canon-artefact classification (vkgeorgia/strategy#84). The single authority
-// for "what is a compliance artefact" — used by both the Studio extension scan
-// (webview previews) and the CLI scan (`export-compliance`), so the recognition
-// rules live once. Pure: takes a parsed YAML document, no IO.
-
-import type { AssertionStatus } from '../assertion/types.js';
-import type { IndexAssertion, IndexRequirement } from './types.js';
-
-export interface ComplianceProduct {
-  id: string;
-  name: string;
-}
-export interface ComplianceCodexDoc {
-  id: string;
-  name: string;
-  type?: string;
-  jurisdiction?: string;
-}
-
-/** The bucketed result of scanning a repo for compliance canon. */
-export interface ComplianceCanon {
-  products: ComplianceProduct[];
-  requirements: IndexRequirement[];
-  assertions: IndexAssertion[];
-  codex: ComplianceCodexDoc[];
-}
-
-export function emptyCanon(): ComplianceCanon {
-  return { products: [], requirements: [], assertions: [], codex: [] };
-}
-
-const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
-const strArray = (v: unknown): string[] | undefined =>
-  Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : undefined;
-
-/**
- * Classifies one parsed YAML document and, if it is a compliance artefact,
- * pushes its projection into `canon`. Products / requirements / assertions are
- * identified by their `notation` tag; codex source documents by `zone: codex`.
- * Returns the artefact id when ingested (so the caller can record its path), or
- * null when the document is not a (well-formed) compliance artefact.
- */
-export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): string | null {
-  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return null;
-  const d = doc as Record<string, unknown>;
-  const id = str(d.id);
-  if (!id) return null;
-
-  if (d.notation === 'product') {
-    canon.products.push({ id, name: str(d.name) ?? id });
-    return id;
-  }
-  if (d.notation === 'requirement') {
-    canon.requirements.push({
-      id,
-      name: str(d.name) ?? id,
-      severity: str(d.severity),
-      derived_from: strArray(d.derived_from),
-      admitted_at: str(d.admitted_at),
-      deadline: str(d.deadline),
-    });
-    return id;
-  }
-  if (d.notation === 'assertion') {
-    const about = str(d.about);
-    const subject = str(d.subject);
-    const status = str(d.status) as AssertionStatus | undefined;
-    if (!about || !subject || !status) return null;
-    canon.assertions.push({
-      id, about, subject, status,
-      assessed_at: str(d.assessed_at),
-      next_review_at: str(d.next_review_at),
-      evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
-      admitted_at: str(d.admitted_at),
-      realised_via: strArray(d.realised_via),
-    });
-    return id;
-  }
-  if (d.zone === 'codex') {
-    canon.codex.push({ id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) });
-    return id;
-  }
-  return null;
-}
+// Canon-artefact classification (vkgeorgia/strategy#84). The single authority
+// for "what is a compliance artefact" — used by both the Studio extension scan
+// (webview previews) and the CLI scan (`export-compliance`), so the recognition
+// rules live once. Pure: takes a parsed YAML document, no IO.
+
+import type { AssertionStatus } from '../assertion/types.js';
+import type { IndexAssertion, IndexRequirement } from './types.js';
+
+export interface ComplianceProduct {
+  id: string;
+  name: string;
+}
+export interface ComplianceCodexDoc {
+  id: string;
+  name: string;
+  type?: string;
+  jurisdiction?: string;
+}
+
+/** The bucketed result of scanning a repo for compliance canon. */
+export interface ComplianceCanon {
+  products: ComplianceProduct[];
+  requirements: IndexRequirement[];
+  assertions: IndexAssertion[];
+  codex: ComplianceCodexDoc[];
+  /**
+   * Named elements that can serve as assertion subjects beyond `products`:
+   * capabilities, processes, applications, and systems. Populated by
+   * `ingestComplianceDoc` for the corresponding notation values.
+   */
+  subjects: ComplianceProduct[];
+}
+
+export function emptyCanon(): ComplianceCanon {
+  return { products: [], requirements: [], assertions: [], codex: [], subjects: [] };
+}
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
+const strArray = (v: unknown): string[] | undefined =>
+  Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : undefined;
+
+/**
+ * Classifies one parsed YAML document and, if it is a compliance artefact,
+ * pushes its projection into `canon`. Products / requirements / assertions are
+ * identified by their `notation` tag; codex source documents by `zone: codex`.
+ * Returns the artefact id when ingested (so the caller can record its path), or
+ * null when the document is not a (well-formed) compliance artefact.
+ */
+export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): string | null {
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return null;
+  const d = doc as Record<string, unknown>;
+  const id = str(d.id);
+  if (!id) return null;
+
+  if (d.notation === 'product') {
+    canon.products.push({ id, name: str(d.name) ?? id });
+    return id;
+  }
+  if (
+    d.notation === 'capability' ||
+    d.notation === 'process' ||
+    d.notation === 'application' ||
+    d.notation === 'system'
+  ) {
+    canon.subjects.push({ id, name: str(d.name) ?? id });
+    return id;
+  }
+  if (d.notation === 'requirement') {
+    canon.requirements.push({
+      id,
+      name: str(d.name) ?? id,
+      severity: str(d.severity),
+      derived_from: strArray(d.derived_from),
+      admitted_at: str(d.admitted_at),
+      deadline: str(d.deadline),
+    });
+    return id;
+  }
+  if (d.notation === 'assertion') {
+    const about = str(d.about);
+    const subject = str(d.subject);
+    const status = str(d.status) as AssertionStatus | undefined;
+    if (!about || !subject || !status) return null;
+    canon.assertions.push({
+      id, about, subject, status,
+      assessed_at: str(d.assessed_at),
+      next_review_at: str(d.next_review_at),
+      evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
+      admitted_at: str(d.admitted_at),
+      realised_via: strArray(d.realised_via),
+      owner_to_confirm: str(d.owner_to_confirm),
+    });
+    return id;
+  }
+  if (d.zone === 'codex') {
+    canon.codex.push({ id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) });
+    return id;
+  }
+  return null;
+}