@transitrix/diagrams 1.0.0

package/dist/applications/__tests__/validate.test.js

@@ -0,0 +1,223 @@
+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/dist/applications/index.d.ts

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

package/dist/applications/index.js

@@ -0,0 +1 @@
+export { validateApplicationsCatalogue } from './validate.js';

package/dist/applications/types.d.ts

@@ -0,0 +1,39 @@
+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/dist/applications/types.js

@@ -0,0 +1 @@
+export {};

package/dist/applications/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+export type { ValidationError, ValidationWarning, ValidationResult };
+export declare function validateApplicationsCatalogue(input: unknown): ValidationResult;

package/dist/applications/validate.js

@@ -0,0 +1,109 @@
+const VALID_TYPES = new Set(['application', 'integration', 'platform', 'data_store']);
+const VALID_STATUSES = new Set(['Draft', 'Active', 'Deprecated', 'Decommissioning']);
+const VALID_DIRECTIONS = new Set(['inbound', 'outbound', 'bidirectional']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export function validateApplicationsCatalogue(input) {
+    const errors = [];
+    const warnings = [];
+    if (!input || typeof input !== 'object') {
+        return { valid: false, errors: [{ code: 'APP-001', message: 'Input must be an object' }], warnings };
+    }
+    const raw = input;
+    // 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'];
+    if (!cat['id'] || typeof cat['id'] !== 'string' || !cat['id'].trim()) {
+        errors.push({ code: 'APP-002', message: 'applications_catalogue.id is required' });
+    }
+    if (!cat['name'] || typeof cat['name'] !== 'string' || !cat['name'].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'])) {
+        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();
+    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;
+        // APP-003: required per-application fields
+        if (!a['app_id'] || typeof a['app_id'] !== 'string' || !a['app_id'].trim()) {
+            errors.push({ code: 'APP-003', message: `${idx}: app_id is required` });
+        }
+        else {
+            const aid = a['app_id'];
+            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'].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'])) {
+            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'])) {
+            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'];
+            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;
+                if (intg['direction'] !== undefined && !VALID_DIRECTIONS.has(intg['direction'])) {
+                    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/dist/assertion/__tests__/example.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/assertion/__tests__/example.test.js

@@ -0,0 +1,32 @@
+// 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) => 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/dist/assertion/__tests__/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/assertion/__tests__/validate.test.js

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { validateAssertion } from '../validate.js';
+function valid() {
+    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, opts) => validateAssertion(input, opts).errors.map(e => e.code);
+const warnCodes = (input, opts) => 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 = { 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 = { 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 = { 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 = { 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/dist/assertion/index.d.ts

@@ -0,0 +1,4 @@
+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';

package/dist/assertion/index.js

@@ -0,0 +1,2 @@
+export { ASSERTION_STATUSES, ASSERTION_SUBJECT_TYPES } from './types.js';
+export { validateAssertion } from './validate.js';

package/dist/assertion/types.d.ts

@@ -0,0 +1,43 @@
+import type { GateChecks } from '../requirement/types.js';
+/** Compliance status vocabulary (16-assertion.md §3). */
+export type AssertionStatus = 'compliant' | 'partial' | 'non_compliant' | 'under_review' | 'n_a';
+export declare const ASSERTION_STATUSES: readonly AssertionStatus[];
+/** TYPEs a `subject` may resolve to (16-assertion.md §2, ASSERT-003). */
+export declare const ASSERTION_SUBJECT_TYPES: readonly ["PRODUCT", "PROCESS", "CAPABILITY"];
+/** Evidence entry kinds (16-assertion.md §4). */
+export type EvidenceKind = 'canonical_ref' | 'external_doc' | 'note';
+export interface CanonicalRefEvidence {
+    kind: 'canonical_ref';
+    ref: string;
+}
+export interface ExternalDocEvidence {
+    kind: 'external_doc';
+    title: string;
+    url: string;
+}
+export interface NoteEvidence {
+    kind: 'note';
+    text: string;
+}
+export type Evidence = CanonicalRefEvidence | ExternalDocEvidence | NoteEvidence;
+export interface Assertion {
+    notation: 'assertion';
+    id: string;
+    /** Typed ID of the REQUIREMENT this assertion is about. */
+    about: string;
+    /** Exactly one typed ID; TYPE ∈ {PRODUCT, PROCESS, CAPABILITY}. */
+    subject: string;
+    /** Typed IDs of elements that realise the requirement for the subject. */
+    realised_via?: string[];
+    status: AssertionStatus;
+    evidence?: Evidence[];
+    assessed_at?: string;
+    assessed_by?: string;
+    next_review_at?: string;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/assertion/types.js

@@ -0,0 +1,7 @@
+// ASSERTION — REQUIREMENT realisation claim.
+// Schema: methodology notations/elements/16-assertion.md §2.
+export const ASSERTION_STATUSES = [
+    'compliant', 'partial', 'non_compliant', 'under_review', 'n_a',
+];
+/** TYPEs a `subject` may resolve to (16-assertion.md §2, ASSERT-003). */
+export const ASSERTION_SUBJECT_TYPES = ['PRODUCT', 'PROCESS', 'CAPABILITY'];

package/dist/assertion/validate.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface AssertionValidateOptions {
+    /** When provided, the resolution rules enforce artefact existence. */
+    catalog?: CanonCatalog;
+    /** Today as an ISO `YYYY-MM-DD` string; enables the ASSERT-008 staleness check. */
+    today?: string;
+}
+export declare function validateAssertion(input: unknown, options?: AssertionValidateOptions): ValidationResult;