@transitrix/diagrams 1.0.0

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

@@ -0,0 +1,256 @@
+import { describe, it, expect } from 'vitest';
+import { validateApplicationsCatalogue } from '../validate.js';
+
+const VALID_CATALOGUE = {
+  notation: 'applications',
+  applications_catalogue: {
+    id: 'APP-CAT-001',
+    name: 'Enterprise Applications',
+    updated_at: '2026-05-14',
+    applications: [
+      { app_id: 'APP-001', name: 'Order System', type: 'application', status: 'Active', maturity: 3 },
+      { app_id: 'INT-001', name: 'Event Bus', type: 'integration', status: 'Draft' },
+    ],
+  },
+};
+
+describe('validateApplicationsCatalogue', () => {
+  it('passes on valid input', () => {
+    const r = validateApplicationsCatalogue(VALID_CATALOGUE);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('APP-001: rejects non-object input', () => {
+    expect(validateApplicationsCatalogue(null).valid).toBe(false);
+    expect(validateApplicationsCatalogue(null).errors[0].code).toBe('APP-001');
+  });
+
+  it('APP-001: rejects missing notation', () => {
+    const { notation: _, ...rest } = VALID_CATALOGUE;
+    const r = validateApplicationsCatalogue(rest);
+    expect(r.errors.some(e => e.code === 'APP-001')).toBe(true);
+  });
+
+  it('APP-001: rejects wrong notation value', () => {
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, notation: 'products' });
+    expect(r.errors.some(e => e.code === 'APP-001')).toBe(true);
+  });
+
+  it('APP-002: rejects missing applications_catalogue', () => {
+    const r = validateApplicationsCatalogue({ notation: 'applications' });
+    expect(r.errors.some(e => e.code === 'APP-002')).toBe(true);
+  });
+
+  it('APP-002: rejects missing id', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, id: '' };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-002' && e.message.includes('id'))).toBe(true);
+  });
+
+  it('APP-002: rejects missing name', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, name: '  ' };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-002' && e.message.includes('name'))).toBe(true);
+  });
+
+  it('APP-002: rejects missing updated_at', () => {
+    const { updated_at: _, ...cat } = VALID_CATALOGUE.applications_catalogue;
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-002' && e.message.includes('updated_at'))).toBe(true);
+  });
+
+  it('APP-002: rejects non-array applications', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: 'bad' };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-002')).toBe(true);
+  });
+
+  it('APP-003: rejects missing app_id', () => {
+    const apps = [{ name: 'X', type: 'application', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-003' && e.message.includes('app_id'))).toBe(true);
+  });
+
+  it('APP-003: rejects missing name', () => {
+    const apps = [{ app_id: 'A1', name: '', type: 'application', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-003' && e.message.includes('name'))).toBe(true);
+  });
+
+  it('APP-003: rejects missing type', () => {
+    const apps = [{ app_id: 'A1', name: 'X', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-003' && e.message.includes('type'))).toBe(true);
+  });
+
+  it('APP-003: rejects missing status', () => {
+    const apps = [{ app_id: 'A1', name: 'X', type: 'application' }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-003' && e.message.includes('status'))).toBe(true);
+  });
+
+  it('APP-004: rejects invalid type', () => {
+    const apps = [{ app_id: 'A1', name: 'X', type: 'hardware', status: 'Active' }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-004')).toBe(true);
+  });
+
+  it('APP-004: accepts all valid types', () => {
+    for (const type of ['application', 'integration', 'platform', 'data_store']) {
+      const apps = [{ app_id: 'A1', name: 'X', type, status: 'Active' }];
+      const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+      const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'APP-004')).toBe(false);
+    }
+  });
+
+  it('APP-005: rejects invalid status', () => {
+    const apps = [{ app_id: 'A1', name: 'X', type: 'application', status: 'Unknown' }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-005')).toBe(true);
+  });
+
+  it('APP-005: accepts all four valid statuses', () => {
+    for (const status of ['Draft', 'Active', 'Deprecated', 'Decommissioning']) {
+      const apps = [{ app_id: 'A1', name: 'X', type: 'application', status }];
+      const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+      const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'APP-005')).toBe(false);
+    }
+  });
+
+  it('APP-006: rejects maturity < 1', () => {
+    const apps = [{ app_id: 'A1', name: 'X', type: 'application', status: 'Active', maturity: 0 }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-006')).toBe(true);
+  });
+
+  it('APP-006: rejects maturity > 5', () => {
+    const apps = [{ app_id: 'A1', name: 'X', type: 'application', status: 'Active', maturity: 6 }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-006')).toBe(true);
+  });
+
+  it('APP-006: rejects non-integer maturity', () => {
+    const apps = [{ app_id: 'A1', name: 'X', type: 'application', status: 'Active', maturity: 3.5 }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-006')).toBe(true);
+  });
+
+  it('APP-006: accepts valid maturity range 1-5', () => {
+    for (const maturity of [1, 2, 3, 4, 5]) {
+      const apps = [{ app_id: 'A1', name: 'X', type: 'application', status: 'Active', maturity }];
+      const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+      const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'APP-006')).toBe(false);
+    }
+  });
+
+  it('APP-007: rejects malformed updated_at', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, updated_at: '14/05/2026' };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-007')).toBe(true);
+  });
+
+  it('APP-007: accepts YYYY-MM-DD format', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, updated_at: '2026-01-01' };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-007')).toBe(false);
+  });
+
+  it('APP-008: rejects duplicate app_id', () => {
+    const apps = [
+      { app_id: 'A1', name: 'X', type: 'application', status: 'Active' },
+      { app_id: 'A1', name: 'Y', type: 'platform', status: 'Draft' },
+    ];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-008')).toBe(true);
+  });
+
+  it('APP-009: rejects invalid integration direction', () => {
+    const apps = [{
+      app_id: 'A1', name: 'X', type: 'application', status: 'Active',
+      integrations: [{ target: 'A2', direction: 'sideways' }],
+    }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.errors.some(e => e.code === 'APP-009')).toBe(true);
+  });
+
+  it('APP-009: accepts valid integration directions', () => {
+    for (const direction of ['inbound', 'outbound', 'bidirectional']) {
+      const apps = [{
+        app_id: 'A1', name: 'X', type: 'application', status: 'Active',
+        integrations: [{ target: 'A2', direction }],
+      }];
+      const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+      const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+      expect(r.errors.some(e => e.code === 'APP-009')).toBe(false);
+    }
+  });
+
+  it('APP-009: accepts integration without direction', () => {
+    const apps = [{
+      app_id: 'A1', name: 'X', type: 'application', status: 'Active',
+      integrations: [{ target: 'A2', protocol: 'REST' }],
+    }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.valid).toBe(true);
+  });
+
+  it('accepts empty applications array', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: [] };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.valid).toBe(true);
+  });
+
+  it('accepts application with all optional fields', () => {
+    const apps = [{
+      app_id: 'A1', name: 'Full App', type: 'application', status: 'Active',
+      domain: 'Sales', owner_role: 'ROLE-001', vendor: 'Salesforce', maturity: 4,
+      description: 'CRM system', capabilities: ['CAP-001'], products: ['PROD-001'],
+      integrations: [{ target: 'A2', direction: 'outbound', protocol: 'REST', description: 'sends events' }],
+    }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.valid).toBe(true);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it('[blocker] tolerates a null element in applications[] without throwing', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: [null] };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'APP-003')).toBe(true);
+  });
+
+  it('[blocker] tolerates a string element in applications[] without throwing', () => {
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: ['x'] };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'APP-003')).toBe(true);
+  });
+
+  it('[blocker] tolerates a null integration entry without throwing', () => {
+    const apps = [{
+      app_id: 'A1', name: 'X', type: 'application', status: 'Active',
+      integrations: [null],
+    }];
+    const cat = { ...VALID_CATALOGUE.applications_catalogue, applications: apps };
+    const r = validateApplicationsCatalogue({ ...VALID_CATALOGUE, applications_catalogue: cat });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'APP-009')).toBe(true);
+  });
+});

package/src/applications/index.ts

@@ -0,0 +1,11 @@
+export type {
+  ApplicationType,
+  ApplicationStatus,
+  IntegrationDirection,
+  ApplicationIntegration,
+  Application,
+  ApplicationsCatalogueHeader,
+  ApplicationsCatalogueFile,
+} from './types.js';
+
+export { validateApplicationsCatalogue } from './validate.js';

package/src/applications/types.ts

@@ -0,0 +1,43 @@
+export type ApplicationType = 'application' | 'integration' | 'platform' | 'data_store';
+export type ApplicationStatus = 'Draft' | 'Active' | 'Deprecated' | 'Decommissioning';
+export type IntegrationDirection = 'inbound' | 'outbound' | 'bidirectional';
+
+export interface ApplicationIntegration {
+  target?: string;
+  direction?: IntegrationDirection;
+  protocol?: string;
+  description?: string;
+}
+
+export interface Application {
+  app_id: string;
+  name: string;
+  type: ApplicationType;
+  status: ApplicationStatus;
+  domain?: string;
+  owner_role?: string;
+  vendor?: string;
+  maturity?: number;
+  description?: string;
+  capabilities?: string[];
+  products?: string[];
+  integrations?: ApplicationIntegration[];
+  source?: string;
+  target?: string;
+  protocol?: string;
+}
+
+export interface ApplicationsCatalogueHeader {
+  id: string;
+  name: string;
+  description?: string;
+  version?: string;
+  updated_at: string;
+  applications: Application[];
+}
+
+export interface ApplicationsCatalogueFile {
+  notation: string;
+  spec_version?: string;
+  applications_catalogue: ApplicationsCatalogueHeader;
+}

package/src/applications/validate.ts

@@ -0,0 +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 };
+}

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

@@ -0,0 +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');
+  });
+});

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

@@ -0,0 +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');
+  });
+});

package/src/assertion/index.ts

@@ -0,0 +1,12 @@
+export type {
+  Assertion,
+  AssertionStatus,
+  Evidence,
+  EvidenceKind,
+  CanonicalRefEvidence,
+  ExternalDocEvidence,
+  NoteEvidence,
+} from './types.js';
+export { ASSERTION_STATUSES, ASSERTION_SUBJECT_TYPES } from './types.js';
+export { validateAssertion } from './validate.js';
+export type { AssertionValidateOptions } from './validate.js';