@transitrix/diagrams 1.0.0 → 1.1.0

package/src/applications/validate.ts

@@ -1,131 +1,131 @@
-import type { ApplicationsCatalogueFile, ApplicationType, ApplicationStatus, IntegrationDirection } from './types.js';
-import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
-
-export type { ValidationError, ValidationWarning, ValidationResult };
-
-const VALID_TYPES = new Set<ApplicationType>(['application', 'integration', 'platform', 'data_store']);
-const VALID_STATUSES = new Set<ApplicationStatus>(['Draft', 'Active', 'Deprecated', 'Decommissioning']);
-const VALID_DIRECTIONS = new Set<IntegrationDirection>(['inbound', 'outbound', 'bidirectional']);
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-
-export function validateApplicationsCatalogue(input: unknown): ValidationResult {
-  const errors: ValidationError[] = [];
-  const warnings: ValidationWarning[] = [];
-
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'APP-001', message: 'Input must be an object' }], warnings };
-  }
-
-  const raw = input as Record<string, unknown>;
-
-  // APP-001: notation header
-  if (!('notation' in raw)) {
-    errors.push({ code: 'APP-001', message: 'Missing required field: notation' });
-  } else if (raw['notation'] !== 'applications') {
-    errors.push({ code: 'APP-001', message: `notation must be "applications", got "${raw['notation']}"` });
-  }
-
-  if (errors.length > 0) return { valid: false, errors, warnings };
-
-  // APP-002: catalogue header fields
-  if (!raw['applications_catalogue'] || typeof raw['applications_catalogue'] !== 'object') {
-    errors.push({ code: 'APP-002', message: 'Missing required field: applications_catalogue' });
-    return { valid: false, errors, warnings };
-  }
-
-  const cat = raw['applications_catalogue'] as Record<string, unknown>;
-
-  if (!cat['id'] || typeof cat['id'] !== 'string' || !(cat['id'] as string).trim()) {
-    errors.push({ code: 'APP-002', message: 'applications_catalogue.id is required' });
-  }
-  if (!cat['name'] || typeof cat['name'] !== 'string' || !(cat['name'] as string).trim()) {
-    errors.push({ code: 'APP-002', message: 'applications_catalogue.name is required' });
-  }
-  if (!cat['updated_at'] || typeof cat['updated_at'] !== 'string') {
-    errors.push({ code: 'APP-002', message: 'applications_catalogue.updated_at is required' });
-  }
-
-  if (errors.length > 0) return { valid: false, errors, warnings };
-
-  // APP-007: updated_at format
-  if (!DATE_RE.test(cat['updated_at'] as string)) {
-    errors.push({ code: 'APP-007', message: `applications_catalogue.updated_at must be YYYY-MM-DD, got "${cat['updated_at']}"` });
-  }
-
-  const applications = cat['applications'];
-  if (!Array.isArray(applications)) {
-    errors.push({ code: 'APP-002', message: 'applications_catalogue.applications must be an array' });
-    return { valid: false, errors, warnings };
-  }
-
-  // APP-008: unique app_id
-  const seenIds = new Set<string>();
-
-  for (let i = 0; i < applications.length; i++) {
-    const rawApp = applications[i];
-    const idx = `applications[${i}]`;
-
-    if (!rawApp || typeof rawApp !== 'object') {
-      errors.push({ code: 'APP-003', message: `${idx} must be an object` });
-      continue;
-    }
-    const a = rawApp as Record<string, unknown>;
-
-    // APP-003: required per-application fields
-    if (!a['app_id'] || typeof a['app_id'] !== 'string' || !(a['app_id'] as string).trim()) {
-      errors.push({ code: 'APP-003', message: `${idx}: app_id is required` });
-    } else {
-      const aid = a['app_id'] as string;
-      if (seenIds.has(aid)) {
-        errors.push({ code: 'APP-008', message: `Duplicate app_id: "${aid}"` });
-      }
-      seenIds.add(aid);
-    }
-
-    if (!a['name'] || typeof a['name'] !== 'string' || !(a['name'] as string).trim()) {
-      errors.push({ code: 'APP-003', message: `${idx}: name is required` });
-    }
-    if (!a['type']) {
-      errors.push({ code: 'APP-003', message: `${idx}: type is required` });
-    }
-    if (!a['status']) {
-      errors.push({ code: 'APP-003', message: `${idx}: status is required` });
-    }
-
-    // APP-004: type enum
-    if (a['type'] && !VALID_TYPES.has(a['type'] as ApplicationType)) {
-      errors.push({ code: 'APP-004', message: `${idx}: type "${a['type']}" must be one of: application, integration, platform, data_store` });
-    }
-
-    // APP-005: status enum (4 values)
-    if (a['status'] && !VALID_STATUSES.has(a['status'] as ApplicationStatus)) {
-      errors.push({ code: 'APP-005', message: `${idx}: status "${a['status']}" must be one of: Draft, Active, Deprecated, Decommissioning` });
-    }
-
-    // APP-006: maturity range
-    if (a['maturity'] !== undefined) {
-      const m = a['maturity'];
-      if (typeof m !== 'number' || !Number.isInteger(m) || m < 1 || m > 5) {
-        errors.push({ code: 'APP-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
-      }
-    }
-
-    // APP-009: integrations[].direction enum
-    if (Array.isArray(a['integrations'])) {
-      const integrations = a['integrations'] as unknown[];
-      for (let j = 0; j < integrations.length; j++) {
-        const rawIntg = integrations[j];
-        if (!rawIntg || typeof rawIntg !== 'object') {
-          errors.push({ code: 'APP-009', message: `${idx}.integrations[${j}] must be an object` });
-          continue;
-        }
-        const intg = rawIntg as Record<string, unknown>;
-        if (intg['direction'] !== undefined && !VALID_DIRECTIONS.has(intg['direction'] as IntegrationDirection)) {
-          errors.push({ code: 'APP-009', message: `${idx}.integrations[${j}]: direction "${intg['direction']}" must be one of: inbound, outbound, bidirectional` });
-        }
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
+import type { ApplicationsCatalogueFile, ApplicationType, ApplicationStatus, IntegrationDirection } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const VALID_TYPES = new Set<ApplicationType>(['application', 'integration', 'platform', 'data_store']);
+const VALID_STATUSES = new Set<ApplicationStatus>(['Draft', 'Active', 'Deprecated', 'Decommissioning']);
+const VALID_DIRECTIONS = new Set<IntegrationDirection>(['inbound', 'outbound', 'bidirectional']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function validateApplicationsCatalogue(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'APP-001', message: 'Input must be an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  // APP-001: notation header
+  if (!('notation' in raw)) {
+    errors.push({ code: 'APP-001', message: 'Missing required field: notation' });
+  } else if (raw['notation'] !== 'applications') {
+    errors.push({ code: 'APP-001', message: `notation must be "applications", got "${raw['notation']}"` });
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // APP-002: catalogue header fields
+  if (!raw['applications_catalogue'] || typeof raw['applications_catalogue'] !== 'object') {
+    errors.push({ code: 'APP-002', message: 'Missing required field: applications_catalogue' });
+    return { valid: false, errors, warnings };
+  }
+
+  const cat = raw['applications_catalogue'] as Record<string, unknown>;
+
+  if (!cat['id'] || typeof cat['id'] !== 'string' || !(cat['id'] as string).trim()) {
+    errors.push({ code: 'APP-002', message: 'applications_catalogue.id is required' });
+  }
+  if (!cat['name'] || typeof cat['name'] !== 'string' || !(cat['name'] as string).trim()) {
+    errors.push({ code: 'APP-002', message: 'applications_catalogue.name is required' });
+  }
+  if (!cat['updated_at'] || typeof cat['updated_at'] !== 'string') {
+    errors.push({ code: 'APP-002', message: 'applications_catalogue.updated_at is required' });
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // APP-007: updated_at format
+  if (!DATE_RE.test(cat['updated_at'] as string)) {
+    errors.push({ code: 'APP-007', message: `applications_catalogue.updated_at must be YYYY-MM-DD, got "${cat['updated_at']}"` });
+  }
+
+  const applications = cat['applications'];
+  if (!Array.isArray(applications)) {
+    errors.push({ code: 'APP-002', message: 'applications_catalogue.applications must be an array' });
+    return { valid: false, errors, warnings };
+  }
+
+  // APP-008: unique app_id
+  const seenIds = new Set<string>();
+
+  for (let i = 0; i < applications.length; i++) {
+    const rawApp = applications[i];
+    const idx = `applications[${i}]`;
+
+    if (!rawApp || typeof rawApp !== 'object') {
+      errors.push({ code: 'APP-003', message: `${idx} must be an object` });
+      continue;
+    }
+    const a = rawApp as Record<string, unknown>;
+
+    // APP-003: required per-application fields
+    if (!a['app_id'] || typeof a['app_id'] !== 'string' || !(a['app_id'] as string).trim()) {
+      errors.push({ code: 'APP-003', message: `${idx}: app_id is required` });
+    } else {
+      const aid = a['app_id'] as string;
+      if (seenIds.has(aid)) {
+        errors.push({ code: 'APP-008', message: `Duplicate app_id: "${aid}"` });
+      }
+      seenIds.add(aid);
+    }
+
+    if (!a['name'] || typeof a['name'] !== 'string' || !(a['name'] as string).trim()) {
+      errors.push({ code: 'APP-003', message: `${idx}: name is required` });
+    }
+    if (!a['type']) {
+      errors.push({ code: 'APP-003', message: `${idx}: type is required` });
+    }
+    if (!a['status']) {
+      errors.push({ code: 'APP-003', message: `${idx}: status is required` });
+    }
+
+    // APP-004: type enum
+    if (a['type'] && !VALID_TYPES.has(a['type'] as ApplicationType)) {
+      errors.push({ code: 'APP-004', message: `${idx}: type "${a['type']}" must be one of: application, integration, platform, data_store` });
+    }
+
+    // APP-005: status enum (4 values)
+    if (a['status'] && !VALID_STATUSES.has(a['status'] as ApplicationStatus)) {
+      errors.push({ code: 'APP-005', message: `${idx}: status "${a['status']}" must be one of: Draft, Active, Deprecated, Decommissioning` });
+    }
+
+    // APP-006: maturity range
+    if (a['maturity'] !== undefined) {
+      const m = a['maturity'];
+      if (typeof m !== 'number' || !Number.isInteger(m) || m < 1 || m > 5) {
+        errors.push({ code: 'APP-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
+      }
+    }
+
+    // APP-009: integrations[].direction enum
+    if (Array.isArray(a['integrations'])) {
+      const integrations = a['integrations'] as unknown[];
+      for (let j = 0; j < integrations.length; j++) {
+        const rawIntg = integrations[j];
+        if (!rawIntg || typeof rawIntg !== 'object') {
+          errors.push({ code: 'APP-009', message: `${idx}.integrations[${j}] must be an object` });
+          continue;
+        }
+        const intg = rawIntg as Record<string, unknown>;
+        if (intg['direction'] !== undefined && !VALID_DIRECTIONS.has(intg['direction'] as IntegrationDirection)) {
+          errors.push({ code: 'APP-009', message: `${idx}.integrations[${j}]: direction "${intg['direction']}" must be one of: inbound, outbound, bidirectional` });
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/assertion/__tests__/example.test.ts

@@ -1,37 +1,37 @@
-// Conformance test for the shipped ASSERTION worked examples — the acme_corp
-// canon files mirrored under `tests/fixtures/notation-corpus/assertion/`. Pins the success signal of
-// vkgeorgia/strategy#84 Phase 1: the library consumes the canonical example
-// files without error.
-
-import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-import yaml from 'js-yaml';
-import { validateAssertion } from '../validate.js';
-
-const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/assertion');
-const load = (f: string): unknown => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
-
-// Fixed reference date so the ASSERT-008 staleness check is deterministic; all
-// three examples have a future review date relative to it.
-const today = '2026-06-02';
-
-describe('assertion worked examples (acme_corp)', () => {
-  for (const f of [
-    'ASSERTION-MOBILE-DATA-ERASURE-1.yaml',
-    'ASSERTION-CRM-DATA-ERASURE-1.yaml',
-    'ASSERTION-ONBOARD-DATA-ERASURE-1.yaml',
-  ]) {
-    it(`validates ${f} without error`, () => {
-      const v = validateAssertion(load(f), { today });
-      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
-      expect(v.errors).toHaveLength(0);
-    });
-  }
-
-  it('does not raise ASSERT-007 for the under_review assertion with empty evidence', () => {
-    const v = validateAssertion(load('ASSERTION-CRM-DATA-ERASURE-1.yaml'), { today });
-    expect(v.warnings.map(w => w.code)).not.toContain('ASSERT-007');
-  });
-});
+// Conformance test for the shipped ASSERTION worked examples — the acme_corp
+// canon files mirrored under `tests/fixtures/notation-corpus/assertion/`. Pins the success signal of
+// vkgeorgia/strategy#84 Phase 1: the library consumes the canonical example
+// files without error.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateAssertion } from '../validate.js';
+
+const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/assertion');
+const load = (f: string): unknown => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
+
+// Fixed reference date so the ASSERT-008 staleness check is deterministic; all
+// three examples have a future review date relative to it.
+const today = '2026-06-02';
+
+describe('assertion worked examples (acme_corp)', () => {
+  for (const f of [
+    'ASSERTION-MOBILE-DATA-ERASURE-1.yaml',
+    'ASSERTION-CRM-DATA-ERASURE-1.yaml',
+    'ASSERTION-ONBOARD-DATA-ERASURE-1.yaml',
+  ]) {
+    it(`validates ${f} without error`, () => {
+      const v = validateAssertion(load(f), { today });
+      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+      expect(v.errors).toHaveLength(0);
+    });
+  }
+
+  it('does not raise ASSERT-007 for the under_review assertion with empty evidence', () => {
+    const v = validateAssertion(load('ASSERTION-CRM-DATA-ERASURE-1.yaml'), { today });
+    expect(v.warnings.map(w => w.code)).not.toContain('ASSERT-007');
+  });
+});

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

@@ -1,142 +1,142 @@
-import { describe, it, expect } from 'vitest';
-import { validateAssertion } from '../validate.js';
-import type { CanonCatalog } from '../../typed-id.js';
-
-function valid(): Record<string, unknown> {
-  return {
-    notation: 'assertion',
-    id: 'ASSERTION-MOBILE-DATA-ERASURE-1',
-    about: 'REQUIREMENT-DATA-ERASURE-1',
-    subject: 'PRODUCT-MOBILE-1',
-    realised_via: ['CAPABILITY-V2', 'PROCESS-USER-DATA-PURGE-1'],
-    status: 'compliant',
-    evidence: [{ kind: 'note', text: 'DPO review confirmed compliance.' }],
-    assessed_at: '2026-03-15',
-    next_review_at: '2026-09-15',
-    zone: 'canon',
-    admitted_at: '2026-05-28',
-    admitted_by: 'v.korobeinikov',
-    gate_checks: { uniqueness: 'pass' },
-    valid_from: '2026-03-15',
-    valid_to: null,
-  };
-}
-
-const codes = (input: unknown, opts?: Parameters<typeof validateAssertion>[1]): string[] =>
-  validateAssertion(input, opts).errors.map(e => e.code);
-const warnCodes = (input: unknown, opts?: Parameters<typeof validateAssertion>[1]): string[] =>
-  validateAssertion(input, opts).warnings.map(w => w.code);
-
-describe('validateAssertion — positive', () => {
-  it('accepts a well-formed assertion', () => {
-    const r = validateAssertion(valid());
-    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
-  });
-});
-
-describe('validateAssertion — ASSERT-001 (shape / id grammar)', () => {
-  it('flags id grammar, wrong notation, missing admission/lifecycle fields', () => {
-    expect(codes({ ...valid(), id: 'ASSERT-1' })).toContain('ASSERT-001');
-    expect(codes({ ...valid(), notation: 'claim' })).toContain('ASSERT-001');
-    const noAdmit = valid(); delete noAdmit.admitted_at;
-    expect(codes(noAdmit)).toContain('ASSERT-001');
-    const noValidTo = valid(); delete noValidTo.valid_to;
-    expect(codes(noValidTo)).toContain('ASSERT-001');
-  });
-
-  it('flags a missing status as ASSERT-001 (required field)', () => {
-    const r = valid(); delete r.status;
-    expect(codes(r)).toContain('ASSERT-001');
-  });
-
-  it('rejects a non-object', () => {
-    expect(codes(null)).toEqual(['ASSERT-001']);
-  });
-});
-
-describe('validateAssertion — ASSERT-002 (about → REQUIREMENT)', () => {
-  it('flags a missing about', () => {
-    const r = valid(); delete r.about;
-    expect(codes(r)).toContain('ASSERT-002');
-  });
-  it('flags an about that is not a REQUIREMENT typed id', () => {
-    expect(codes({ ...valid(), about: 'PRODUCT-MOBILE-1' })).toContain('ASSERT-002');
-  });
-  it('with a catalog, flags an unresolved about and a wrong-type about', () => {
-    expect(codes({ ...valid() }, { catalog: { typeOf: () => undefined } })).toContain('ASSERT-002');
-    const catalog: CanonCatalog = { typeOf: (id) => (id === 'REQUIREMENT-DATA-ERASURE-1' ? 'GOAL' : 'PRODUCT') };
-    expect(codes(valid(), { catalog })).toContain('ASSERT-002');
-  });
-});
-
-describe('validateAssertion — ASSERT-003 (subject TYPE)', () => {
-  it('flags a subject whose TYPE is not PRODUCT/PROCESS/CAPABILITY', () => {
-    expect(codes({ ...valid(), subject: 'GOAL-1' })).toContain('ASSERT-003');
-  });
-  it('accepts PRODUCT, PROCESS and CAPABILITY subjects', () => {
-    for (const s of ['PRODUCT-1', 'PROCESS-1', 'CAPABILITY-V2']) {
-      expect(codes({ ...valid(), subject: s })).not.toContain('ASSERT-003');
-    }
-  });
-  it('with a catalog, flags an unresolved subject', () => {
-    const catalog: CanonCatalog = { typeOf: (id) => (id === 'PRODUCT-MOBILE-1' ? undefined : 'REQUIREMENT') };
-    expect(codes(valid(), { catalog })).toContain('ASSERT-003');
-  });
-});
-
-describe('validateAssertion — ASSERT-004 (realised_via resolves)', () => {
-  it('flags a malformed realised_via entry', () => {
-    expect(codes({ ...valid(), realised_via: ['nope'] })).toContain('ASSERT-004');
-  });
-  it('with a catalog, flags an unresolved realised_via entry', () => {
-    const catalog: CanonCatalog = { typeOf: (id) => (id.startsWith('CAPABILITY') ? undefined : 'X') };
-    expect(codes(valid(), { catalog })).toContain('ASSERT-004');
-  });
-});
-
-describe('validateAssertion — ASSERT-005 (canonical_ref evidence resolves)', () => {
-  it('flags a malformed canonical_ref', () => {
-    expect(codes({ ...valid(), evidence: [{ kind: 'canonical_ref', ref: 'nope' }] })).toContain('ASSERT-005');
-  });
-  it('with a catalog, flags an unresolved canonical_ref', () => {
-    const catalog: CanonCatalog = { typeOf: () => undefined };
-    expect(codes({ ...valid(), evidence: [{ kind: 'canonical_ref', ref: 'PROCESS-X-1' }] }, { catalog })).toContain('ASSERT-005');
-  });
-  it('ignores external_doc and note evidence kinds for resolution', () => {
-    const ev = [{ kind: 'external_doc', title: 't', url: 'u' }, { kind: 'note', text: 'n' }];
-    expect(codes({ ...valid(), evidence: ev })).not.toContain('ASSERT-005');
-  });
-});
-
-describe('validateAssertion — ASSERT-006 (status enum)', () => {
-  it('flags an out-of-enum status', () => {
-    expect(codes({ ...valid(), status: 'maybe' })).toContain('ASSERT-006');
-  });
-  it('accepts every status value', () => {
-    for (const s of ['compliant', 'partial', 'non_compliant', 'under_review', 'n_a']) {
-      expect(codes({ ...valid(), status: s, evidence: [{ kind: 'note', text: 'x' }] })).not.toContain('ASSERT-006');
-    }
-  });
-});
-
-describe('validateAssertion — ASSERT-007 (positive status without evidence)', () => {
-  it('warns when evidence is empty and status is compliant or partial', () => {
-    expect(warnCodes({ ...valid(), evidence: [], status: 'compliant' })).toContain('ASSERT-007');
-    expect(warnCodes({ ...valid(), evidence: [], status: 'partial' })).toContain('ASSERT-007');
-  });
-  it('does not warn for under_review / non_compliant / n_a with empty evidence', () => {
-    for (const s of ['under_review', 'non_compliant', 'n_a']) {
-      expect(warnCodes({ ...valid(), evidence: [], status: s })).not.toContain('ASSERT-007');
-    }
-  });
-});
-
-describe('validateAssertion — ASSERT-008 (stale review)', () => {
-  it('warns only when today is supplied and next_review_at is in the past', () => {
-    expect(warnCodes({ ...valid(), next_review_at: '2026-01-01' }, { today: '2026-06-02' })).toContain('ASSERT-008');
-    expect(warnCodes({ ...valid(), next_review_at: '2026-12-01' }, { today: '2026-06-02' })).not.toContain('ASSERT-008');
-    // No `today` → clock-free, never warns.
-    expect(warnCodes({ ...valid(), next_review_at: '2000-01-01' })).not.toContain('ASSERT-008');
-  });
-});
+import { describe, it, expect } from 'vitest';
+import { validateAssertion } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'assertion',
+    id: 'ASSERTION-MOBILE-DATA-ERASURE-1',
+    about: 'REQUIREMENT-DATA-ERASURE-1',
+    subject: 'PRODUCT-MOBILE-1',
+    realised_via: ['CAPABILITY-V2', 'PROCESS-USER-DATA-PURGE-1'],
+    status: 'compliant',
+    evidence: [{ kind: 'note', text: 'DPO review confirmed compliance.' }],
+    assessed_at: '2026-03-15',
+    next_review_at: '2026-09-15',
+    zone: 'canon',
+    admitted_at: '2026-05-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass' },
+    valid_from: '2026-03-15',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown, opts?: Parameters<typeof validateAssertion>[1]): string[] =>
+  validateAssertion(input, opts).errors.map(e => e.code);
+const warnCodes = (input: unknown, opts?: Parameters<typeof validateAssertion>[1]): string[] =>
+  validateAssertion(input, opts).warnings.map(w => w.code);
+
+describe('validateAssertion — positive', () => {
+  it('accepts a well-formed assertion', () => {
+    const r = validateAssertion(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+});
+
+describe('validateAssertion — ASSERT-001 (shape / id grammar)', () => {
+  it('flags id grammar, wrong notation, missing admission/lifecycle fields', () => {
+    expect(codes({ ...valid(), id: 'ASSERT-1' })).toContain('ASSERT-001');
+    expect(codes({ ...valid(), notation: 'claim' })).toContain('ASSERT-001');
+    const noAdmit = valid(); delete noAdmit.admitted_at;
+    expect(codes(noAdmit)).toContain('ASSERT-001');
+    const noValidTo = valid(); delete noValidTo.valid_to;
+    expect(codes(noValidTo)).toContain('ASSERT-001');
+  });
+
+  it('flags a missing status as ASSERT-001 (required field)', () => {
+    const r = valid(); delete r.status;
+    expect(codes(r)).toContain('ASSERT-001');
+  });
+
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['ASSERT-001']);
+  });
+});
+
+describe('validateAssertion — ASSERT-002 (about → REQUIREMENT)', () => {
+  it('flags a missing about', () => {
+    const r = valid(); delete r.about;
+    expect(codes(r)).toContain('ASSERT-002');
+  });
+  it('flags an about that is not a REQUIREMENT typed id', () => {
+    expect(codes({ ...valid(), about: 'PRODUCT-MOBILE-1' })).toContain('ASSERT-002');
+  });
+  it('with a catalog, flags an unresolved about and a wrong-type about', () => {
+    expect(codes({ ...valid() }, { catalog: { typeOf: () => undefined } })).toContain('ASSERT-002');
+    const catalog: CanonCatalog = { typeOf: (id) => (id === 'REQUIREMENT-DATA-ERASURE-1' ? 'GOAL' : 'PRODUCT') };
+    expect(codes(valid(), { catalog })).toContain('ASSERT-002');
+  });
+});
+
+describe('validateAssertion — ASSERT-003 (subject TYPE)', () => {
+  it('flags a subject whose TYPE is not PRODUCT/PROCESS/CAPABILITY', () => {
+    expect(codes({ ...valid(), subject: 'GOAL-1' })).toContain('ASSERT-003');
+  });
+  it('accepts PRODUCT, PROCESS and CAPABILITY subjects', () => {
+    for (const s of ['PRODUCT-1', 'PROCESS-1', 'CAPABILITY-V2']) {
+      expect(codes({ ...valid(), subject: s })).not.toContain('ASSERT-003');
+    }
+  });
+  it('with a catalog, flags an unresolved subject', () => {
+    const catalog: CanonCatalog = { typeOf: (id) => (id === 'PRODUCT-MOBILE-1' ? undefined : 'REQUIREMENT') };
+    expect(codes(valid(), { catalog })).toContain('ASSERT-003');
+  });
+});
+
+describe('validateAssertion — ASSERT-004 (realised_via resolves)', () => {
+  it('flags a malformed realised_via entry', () => {
+    expect(codes({ ...valid(), realised_via: ['nope'] })).toContain('ASSERT-004');
+  });
+  it('with a catalog, flags an unresolved realised_via entry', () => {
+    const catalog: CanonCatalog = { typeOf: (id) => (id.startsWith('CAPABILITY') ? undefined : 'X') };
+    expect(codes(valid(), { catalog })).toContain('ASSERT-004');
+  });
+});
+
+describe('validateAssertion — ASSERT-005 (canonical_ref evidence resolves)', () => {
+  it('flags a malformed canonical_ref', () => {
+    expect(codes({ ...valid(), evidence: [{ kind: 'canonical_ref', ref: 'nope' }] })).toContain('ASSERT-005');
+  });
+  it('with a catalog, flags an unresolved canonical_ref', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes({ ...valid(), evidence: [{ kind: 'canonical_ref', ref: 'PROCESS-X-1' }] }, { catalog })).toContain('ASSERT-005');
+  });
+  it('ignores external_doc and note evidence kinds for resolution', () => {
+    const ev = [{ kind: 'external_doc', title: 't', url: 'u' }, { kind: 'note', text: 'n' }];
+    expect(codes({ ...valid(), evidence: ev })).not.toContain('ASSERT-005');
+  });
+});
+
+describe('validateAssertion — ASSERT-006 (status enum)', () => {
+  it('flags an out-of-enum status', () => {
+    expect(codes({ ...valid(), status: 'maybe' })).toContain('ASSERT-006');
+  });
+  it('accepts every status value', () => {
+    for (const s of ['compliant', 'partial', 'non_compliant', 'under_review', 'n_a']) {
+      expect(codes({ ...valid(), status: s, evidence: [{ kind: 'note', text: 'x' }] })).not.toContain('ASSERT-006');
+    }
+  });
+});
+
+describe('validateAssertion — ASSERT-007 (positive status without evidence)', () => {
+  it('warns when evidence is empty and status is compliant or partial', () => {
+    expect(warnCodes({ ...valid(), evidence: [], status: 'compliant' })).toContain('ASSERT-007');
+    expect(warnCodes({ ...valid(), evidence: [], status: 'partial' })).toContain('ASSERT-007');
+  });
+  it('does not warn for under_review / non_compliant / n_a with empty evidence', () => {
+    for (const s of ['under_review', 'non_compliant', 'n_a']) {
+      expect(warnCodes({ ...valid(), evidence: [], status: s })).not.toContain('ASSERT-007');
+    }
+  });
+});
+
+describe('validateAssertion — ASSERT-008 (stale review)', () => {
+  it('warns only when today is supplied and next_review_at is in the past', () => {
+    expect(warnCodes({ ...valid(), next_review_at: '2026-01-01' }, { today: '2026-06-02' })).toContain('ASSERT-008');
+    expect(warnCodes({ ...valid(), next_review_at: '2026-12-01' }, { today: '2026-06-02' })).not.toContain('ASSERT-008');
+    // No `today` → clock-free, never warns.
+    expect(warnCodes({ ...valid(), next_review_at: '2000-01-01' })).not.toContain('ASSERT-008');
+  });
+});