@transitrix/diagrams 1.0.0

package/dist/repo-validate/validate-repo.js

@@ -0,0 +1,189 @@
+// Repo-scope validator (vkgeorgia/transitrix-studio#141).
+//
+// Pure port of the whole-repo checks owned by the methodology's
+// `.validators/lint.py`, run over the shared TypeScript model instead of Python.
+// Parity reference: the `acme_corp` worked example, which `lint.py` passes with
+// zero findings — this validator must also produce zero findings on it.
+//
+// Ported checks (mirroring lint.py's phases):
+//   1. YAML syntax        (phase 1) — unparseable canon file -> finding.
+//   2. ID uniqueness                — same `id` defined in >1 file -> finding.
+//                                     (lint.py silently last-wins; we surface it,
+//                                      but acme_corp has no duplicates, so parity
+//                                      holds on the reference fixture.)
+//   3. Atomicity          (phase 3) — element file carrying a `relations:` key.
+//   4. Referential integ. (phase 4) — relation endpoint not resolving to a known
+//                                     element id. We resolve the canonical
+//                                     `from`/`to` keys (the real relation schema)
+//                                     and also accept lint.py's `source`/`target`.
+//   5. Semantic rules     (phase 5) — ArchiMate layer-semantics. lint.py ships
+//                                     this as a no-op stub; ported faithfully as a
+//                                     no-op (see `checkLayerSemantics`). Deferred
+//                                     until the methodology defines the rules.
+//   6. Policy             (phase 6) — element marked Active/Production with no
+//                                     owner.
+//
+// Findings stay `{ scope, id, message }` — no severity, no target/category
+// taxonomy (deferred per the ADR).
+const PScope = 'repo';
+/** Statuses that, per lint.py's policy check, require an owner. */
+const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Read a string `id` from a parsed doc, or `null` if absent/non-string.
+ *  Mirrors lint.py, which only treats a doc as an element/relation when it has
+ *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
+ *  and are ignored). */
+function docId(doc) {
+    if (!doc.data)
+        return null;
+    const id = doc.data['id'];
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+/** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
+ *  mapping (lint.py accepts both). Returns the id string or `null`. */
+function endpointId(value) {
+    if (typeof value === 'string')
+        return value.length > 0 ? value : null;
+    if (isRecord(value)) {
+        const id = value['id'];
+        if (typeof id === 'string' && id.length > 0)
+            return id;
+    }
+    return null;
+}
+/** Phase 1 — unparseable canon files surface as findings. */
+function checkSyntax(docs, findings) {
+    for (const doc of docs) {
+        if (doc.parseError) {
+            findings.push({
+                scope: PScope,
+                id: '',
+                message: `YAML syntax error in ${doc.path}: ${doc.parseError}`,
+            });
+        }
+    }
+}
+/** Phase 2 (as a check) — the same id defined in more than one file. */
+function checkIdUniqueness(input, findings) {
+    const filesById = new Map();
+    for (const doc of [...input.elements, ...input.relations]) {
+        const id = docId(doc);
+        if (!id)
+            continue;
+        const list = filesById.get(id);
+        if (list)
+            list.push(doc.path);
+        else
+            filesById.set(id, [doc.path]);
+    }
+    for (const [id, files] of filesById) {
+        if (files.length > 1) {
+            findings.push({
+                scope: PScope,
+                id,
+                message: `Duplicate id '${id}' defined in ${files.length} files: ${files.join(', ')}`,
+            });
+        }
+    }
+}
+/** Phase 3 — relations must live in their own files, not inline on elements. */
+function checkAtomicity(input, findings) {
+    for (const doc of input.elements) {
+        const id = docId(doc);
+        if (id && doc.data && 'relations' in doc.data) {
+            findings.push({
+                scope: PScope,
+                id,
+                message: `Atomicity violation: element '${id}' (${doc.path}) contains a ` +
+                    `'relations' section. Move relations to separate files under canon/relations/.`,
+            });
+        }
+    }
+}
+/** Phase 4 — every relation endpoint must resolve to a known element id. */
+function checkReferentialIntegrity(input, findings) {
+    const elementIds = new Set();
+    for (const doc of input.elements) {
+        const id = docId(doc);
+        if (id)
+            elementIds.add(id);
+    }
+    for (const doc of input.relations) {
+        if (!doc.data)
+            continue;
+        const relId = docId(doc) ?? '';
+        // Canonical relation schema uses `from`/`to`; `source`/`target` accepted for
+        // lint.py compatibility.
+        const fromId = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+        const toId = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+        if (fromId && !elementIds.has(fromId)) {
+            findings.push({
+                scope: PScope,
+                id: relId,
+                message: `Referential integrity: relation '${relId || doc.path}' endpoint '${fromId}' (from) does not resolve to a known element.`,
+            });
+        }
+        if (toId && !elementIds.has(toId)) {
+            findings.push({
+                scope: PScope,
+                id: relId,
+                message: `Referential integrity: relation '${relId || doc.path}' endpoint '${toId}' (to) does not resolve to a known element.`,
+            });
+        }
+    }
+}
+/** Phase 5 — ArchiMate layer-semantics on relations.
+ *
+ * lint.py ships `_check_semantic_rules` as a no-op stub (`pass`). It is ported
+ * here faithfully as a no-op so repo-scope validation reaches parity with
+ * lint.py on the reference fixture. Real layer-semantics rules are DEFERRED
+ * until the methodology defines them; when it does, they land here (a relation
+ * whose `type` is illegal between its endpoints' ArchiMate layers). Kept as a
+ * named hook so the intent — and the gap — is explicit rather than missing. */
+function checkLayerSemantics(_input, _findings) {
+    // Intentionally empty — parity with lint.py's stubbed phase 5. Do not add
+    // rules here without coordinating the methodology semantics canon.
+}
+/** Phase 6 — an element that is Active/Production must declare an owner. */
+function checkPolicy(input, findings) {
+    for (const doc of input.elements) {
+        const id = docId(doc);
+        if (!id || !doc.data)
+            continue;
+        const metadata = doc.data['metadata'];
+        if (!isRecord(metadata))
+            continue;
+        const status = metadata['status'];
+        const owner = metadata['owner'];
+        if (typeof status === 'string' && OWNER_REQUIRED_STATUSES.has(status) && !owner) {
+            findings.push({
+                scope: PScope,
+                id,
+                message: `Policy: element '${id}' has status '${status}' but no owner assigned.`,
+            });
+        }
+    }
+}
+/**
+ * Run all repo-scope checks over a loaded canon model and return the findings.
+ * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
+ * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
+ * (zero findings on a clean tree).
+ */
+export function validateRepoModel(input) {
+    const findings = [];
+    checkSyntax([...input.elements, ...input.relations], findings);
+    // A syntax error means the model is not reliably loaded; skip the graph checks
+    // and report the syntax problems first (mirrors lint.py, which bails after
+    // phase 1 on syntax errors).
+    if (findings.length > 0)
+        return findings;
+    checkIdUniqueness(input, findings);
+    checkAtomicity(input, findings);
+    checkReferentialIntegrity(input, findings);
+    checkLayerSemantics(input, findings);
+    checkPolicy(input, findings);
+    return findings;
+}

package/dist/requirement/__tests__/example.test.d.ts

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

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

@@ -0,0 +1,21 @@
+// Conformance test for the shipped REQUIREMENT worked examples — the
+// acme_corp canon files mirrored under `tests/fixtures/notation-corpus/requirement/`. 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 { validateRequirement } from '../validate.js';
+const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../../tests/fixtures/notation-corpus/requirement');
+const load = (f) => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
+describe('requirement worked examples (acme_corp)', () => {
+    for (const f of ['REQUIREMENT-DATA-ERASURE-1.yaml', 'REQUIREMENT-AUDIT-LOG-RETENTION-1.yaml']) {
+        it(`validates ${f} without error`, () => {
+            const v = validateRequirement(load(f));
+            expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+            expect(v.errors).toHaveLength(0);
+        });
+    }
+});

package/dist/requirement/__tests__/validate.test.d.ts

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

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

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { validateRequirement } from '../validate.js';
+function valid() {
+    return {
+        notation: 'requirement',
+        id: 'REQUIREMENT-DATA-ERASURE-1',
+        name: 'Personal-data erasure within 30 days',
+        description: 'The controller must erase personal data within 30 days of a verified request.',
+        severity: 'high',
+        zone: 'canon',
+        admitted_at: '2026-05-28',
+        admitted_by: 'v.korobeinikov',
+        gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+        valid_from: '2017-05-01',
+        valid_to: null,
+    };
+}
+const codes = (input, opts) => validateRequirement(input, opts).errors.map(e => e.code);
+describe('validateRequirement — positive', () => {
+    it('accepts a well-formed requirement', () => {
+        const r = validateRequirement(valid());
+        expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    it('accepts an internal-only requirement with no derived_from', () => {
+        const r = valid();
+        delete r.derived_from;
+        r.severity = 'medium';
+        expect(validateRequirement(r).valid).toBe(true);
+    });
+});
+describe('validateRequirement — REQ-001 (shape / id grammar)', () => {
+    it('flags a missing required field', () => {
+        const r = valid();
+        delete r.name;
+        expect(codes(r)).toContain('REQ-001');
+    });
+    it('flags an id that violates the grammar', () => {
+        expect(codes({ ...valid(), id: 'REQUIREMENT-DATA-ERASURE-001' })).toContain('REQ-001'); // leading zero
+        expect(codes({ ...valid(), id: 'REQ-1' })).toContain('REQ-001'); // wrong TYPE
+        expect(codes({ ...valid(), id: 'requirement-data-1' })).toContain('REQ-001'); // lowercase TYPE
+    });
+    it('flags a wrong notation tag and a non-canon zone', () => {
+        expect(codes({ ...valid(), notation: 'req' })).toContain('REQ-001');
+        expect(codes({ ...valid(), zone: 'sandbox' })).toContain('REQ-001');
+    });
+    it('flags a missing valid_to key (distinct from a null value)', () => {
+        const r = valid();
+        delete r.valid_to;
+        expect(codes(r)).toContain('REQ-001');
+        expect(validateRequirement({ ...valid(), valid_to: null }).valid).toBe(true);
+    });
+    it('rejects a non-object', () => {
+        expect(codes(null)).toEqual(['REQ-001']);
+        expect(codes('x')).toEqual(['REQ-001']);
+        expect(codes(['a'])).toEqual(['REQ-001']);
+    });
+});
+describe('validateRequirement — REQ-002 (derived_from resolution)', () => {
+    it('flags a well-formed allowed-type ref that does not resolve in the catalog', () => {
+        const catalog = { typeOf: () => undefined };
+        expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] }, { catalog })).toContain('REQ-002');
+    });
+    it('flags a malformed derived_from entry (cannot resolve)', () => {
+        expect(codes({ ...valid(), derived_from: ['not an id'] })).toContain('REQ-002');
+    });
+    it('does not flag REQ-002 without a catalog for a well-formed allowed-type ref', () => {
+        expect(codes({ ...valid(), derived_from: ['LAW-PERSONAL-DATA-2017-1'] })).not.toContain('REQ-002');
+    });
+});
+describe('validateRequirement — REQ-003 (derived_from TYPE)', () => {
+    it('flags a derived_from TYPE outside LAW/REGULATION/POLICY/INTERNAL_STANDARD', () => {
+        expect(codes({ ...valid(), derived_from: ['PRODUCT-MOBILE-1'] })).toContain('REQ-003');
+    });
+    it('accepts each permitted derived_from TYPE', () => {
+        for (const id of ['LAW-X-1', 'REGULATION-X-1', 'POLICY-X-1', 'INTERNAL_STANDARD-X-1']) {
+            expect(codes({ ...valid(), derived_from: [id] })).not.toContain('REQ-003');
+        }
+    });
+});

package/dist/requirement/index.d.ts

@@ -0,0 +1,4 @@
+export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export { validateRequirement } from './validate.js';
+export type { RequirementValidateOptions } from './validate.js';

package/dist/requirement/index.js

@@ -0,0 +1,2 @@
+export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export { validateRequirement } from './validate.js';

package/dist/requirement/types.d.ts

@@ -0,0 +1,25 @@
+export type RequirementSeverity = 'high' | 'medium' | 'low';
+/** Standard canon admission gate checks (CONTRACT.md §6). */
+export interface GateChecks {
+    uniqueness?: string;
+    consistency?: string;
+    completeness?: string;
+}
+/** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
+export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+export interface Requirement {
+    notation: 'requirement';
+    id: string;
+    name: string;
+    description: string;
+    /** Organisation-defined priority. */
+    severity?: RequirementSeverity;
+    /** Typed IDs of the codex source documents this requirement is drawn from. */
+    derived_from?: string[];
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/requirement/types.js

@@ -0,0 +1,4 @@
+// REQUIREMENT — motivation-layer positive obligation.
+// Schema: methodology notations/elements/15-requirement.md §2.
+/** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
+export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];

package/dist/requirement/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface RequirementValidateOptions {
+    /** When provided, REQ-002 enforces that each `derived_from` id is admitted. */
+    catalog?: CanonCatalog;
+}
+export declare function validateRequirement(input: unknown, options?: RequirementValidateOptions): ValidationResult;

package/dist/requirement/validate.js

@@ -0,0 +1,81 @@
+// REQUIREMENT validator — methodology notations/elements/15-requirement.md §4.
+//
+// Implements REQ-001..003. The shared HDR-/LIFECYCLE-/REQ-COVERAGE rules are
+// cross-cutting concerns owned elsewhere (CONTRACT.md §8) and are out of scope
+// for this single-artefact validator.
+//
+// REQ-002/003 resolve `derived_from` against the codex zone. Resolution that
+// needs artefact *existence* (REQ-002) only runs when a `CanonCatalog` is
+// supplied; the TYPE check (REQ-003) is derivable from the id prefix and runs
+// either way.
+import { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
+import { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+const REQUIRED_FIELDS = [
+    'notation', 'name', 'description', 'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'valid_from',
+];
+export function validateRequirement(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        errors.push({ code: 'REQ-001', message: 'Requirement must be a YAML mapping.' });
+        return { valid: false, errors, warnings };
+    }
+    const r = input;
+    // REQ-001 — id grammar.
+    if (!isCanonicalIdOfType(r.id, 'REQUIREMENT')) {
+        errors.push({ code: 'REQ-001', message: `id "${String(r.id)}" must match REQUIREMENT-[<middle>-]<INTEGER>.`, path: 'id' });
+    }
+    // REQ-001 — fixed notation tag.
+    if (r.notation !== 'requirement') {
+        errors.push({ code: 'REQ-001', message: 'notation must be the fixed value "requirement".', path: 'notation' });
+    }
+    // REQ-001 — required fields present and non-empty (notation handled above).
+    for (const f of REQUIRED_FIELDS) {
+        if (f === 'notation')
+            continue;
+        if (f === 'gate_checks') {
+            if (r.gate_checks === null || typeof r.gate_checks !== 'object') {
+                errors.push({ code: 'REQ-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+            }
+            continue;
+        }
+        const v = r[f];
+        if (typeof v !== 'string' || v.trim() === '') {
+            errors.push({ code: 'REQ-001', message: `${f} is required.`, path: f });
+        }
+    }
+    // REQ-001 — zone fixed value.
+    if (r.zone !== undefined && r.zone !== 'canon') {
+        errors.push({ code: 'REQ-001', message: 'zone must be "canon" for a REQUIREMENT.', path: 'zone' });
+    }
+    // REQ-001 — valid_to key must exist (string or null).
+    if (!('valid_to' in r) || !(typeof r.valid_to === 'string' || r.valid_to === null)) {
+        errors.push({ code: 'REQ-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+    }
+    // REQ-002 / REQ-003 — derived_from references.
+    if (r.derived_from !== undefined) {
+        if (!Array.isArray(r.derived_from)) {
+            errors.push({ code: 'REQ-001', message: 'derived_from must be a list of typed IDs.', path: 'derived_from' });
+        }
+        else {
+            r.derived_from.forEach((ref, i) => {
+                const type = typeOfId(ref);
+                if (!type) {
+                    // A malformed ref cannot resolve — REQ-002.
+                    errors.push({ code: 'REQ-002', message: `derived_from[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `derived_from[${i}]` });
+                    return;
+                }
+                if (!REQUIREMENT_DERIVED_FROM_TYPES.includes(type)) {
+                    // REQ-003 — TYPE not a permitted codex source type (prefix-derivable).
+                    errors.push({ code: 'REQ-003', message: `derived_from[${i}] TYPE "${type}" is not one of ${REQUIREMENT_DERIVED_FROM_TYPES.join(', ')}.`, path: `derived_from[${i}]` });
+                    return;
+                }
+                if (options.catalog && options.catalog.typeOf(ref) === undefined) {
+                    // REQ-002 — well-formed but not admitted in the codex zone.
+                    errors.push({ code: 'REQ-002', message: `derived_from[${i}] "${String(ref)}" does not resolve to an admitted codex artefact.`, path: `derived_from[${i}]` });
+                }
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/scenarios/__tests__/validate.test.d.ts

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

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

@@ -0,0 +1,183 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { validateScenario } from '../validate.js';
+const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'scenarios');
+const VALID_SCENARIO = {
+    notation: 'scenarios',
+    scenario: {
+        id: 'SCN-001',
+        name: 'Optimistic Growth 2027',
+        status: 'Active',
+        created_at: '2026-01-01',
+        vision: 'Aggressive expansion scenario.',
+        factors_view: [
+            { factor_id: 'FAC-MARKET-001', relevance: 'High', impact: 'Revenue growth' },
+            { factor_id: 'FAC-TECH-001', relevance: 'Medium' },
+        ],
+        goals: [{ goal_id: 'GOAL-REV-001' }],
+        capabilities: [{ capability_id: 'CAP-ECOMM-001' }],
+        activities: [{ activity_id: 'ACT-EXPAND-001' }],
+        products: [{ product_id: 'PROD-PLATFORM-001' }],
+        processes: [{ process_id: 'PROC-DELIVERY-001' }],
+        applications: [{ app_id: 'APP-CRM-001' }, { app_id: 'APP-OMS-001' }],
+    },
+};
+describe('validateScenario', () => {
+    it('passes on valid input', () => {
+        const r = validateScenario(VALID_SCENARIO);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    it('SCN-001: rejects non-object input', () => {
+        const r = validateScenario(null);
+        expect(r.errors[0].code).toBe('SCN-001');
+    });
+    it('SCN-001: rejects missing notation', () => {
+        const { notation: _, ...rest } = VALID_SCENARIO;
+        const r = validateScenario(rest);
+        expect(r.errors.some(e => e.code === 'SCN-001')).toBe(true);
+    });
+    it('SCN-001: rejects wrong notation value', () => {
+        const r = validateScenario({ ...VALID_SCENARIO, notation: 'goals' });
+        expect(r.errors.some(e => e.code === 'SCN-001')).toBe(true);
+    });
+    it('SCN-002: rejects missing scenario', () => {
+        const r = validateScenario({ notation: 'scenarios' });
+        expect(r.errors.some(e => e.code === 'SCN-002')).toBe(true);
+    });
+    it('SCN-002: rejects missing id/name/status', () => {
+        const r = validateScenario({ notation: 'scenarios', scenario: {} });
+        expect(r.errors.filter(e => e.code === 'SCN-002').length).toBeGreaterThanOrEqual(3);
+    });
+    it('SCN-003: rejects invalid status', () => {
+        const scn = { ...VALID_SCENARIO.scenario, status: 'Retired' };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-003')).toBe(true);
+    });
+    it('SCN-003: accepts all valid statuses', () => {
+        for (const status of ['Draft', 'Active', 'Archived']) {
+            const scn = { ...VALID_SCENARIO.scenario, status };
+            const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+            expect(r.errors.some(e => e.code === 'SCN-003')).toBe(false);
+        }
+    });
+    it('SCN-004: rejects malformed created_at', () => {
+        const scn = { ...VALID_SCENARIO.scenario, created_at: '01-01-2026' };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-004')).toBe(true);
+    });
+    it('SCN-004: accepts missing created_at', () => {
+        const { created_at: _, ...scn } = VALID_SCENARIO.scenario;
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-004')).toBe(false);
+    });
+    it('SCN-005: rejects non-array factors_view', () => {
+        const scn = { ...VALID_SCENARIO.scenario, factors_view: 'oops' };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-005')).toBe(true);
+    });
+    it('SCN-005: rejects factor missing factor_id', () => {
+        const scn = { ...VALID_SCENARIO.scenario, factors_view: [{ relevance: 'High' }] };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-005')).toBe(true);
+    });
+    it('SCN-006: rejects invalid factor relevance', () => {
+        const scn = {
+            ...VALID_SCENARIO.scenario,
+            factors_view: [{ factor_id: 'F1', relevance: 'Critical' }],
+        };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-006')).toBe(true);
+    });
+    it('SCN-013: rejects duplicate factor_id', () => {
+        const scn = {
+            ...VALID_SCENARIO.scenario,
+            factors_view: [{ factor_id: 'F1' }, { factor_id: 'F1' }],
+        };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.errors.some(e => e.code === 'SCN-013')).toBe(true);
+    });
+    const refCases = [
+        { field: 'goals', idField: 'goal_id', errorCode: 'SCN-007' },
+        { field: 'capabilities', idField: 'capability_id', errorCode: 'SCN-008' },
+        { field: 'activities', idField: 'activity_id', errorCode: 'SCN-009' },
+        { field: 'products', idField: 'product_id', errorCode: 'SCN-010' },
+        { field: 'processes', idField: 'process_id', errorCode: 'SCN-011' },
+        { field: 'applications', idField: 'app_id', errorCode: 'SCN-012' },
+    ];
+    for (const c of refCases) {
+        it(`${c.errorCode}: rejects ${c.field}[*] missing ${c.idField}`, () => {
+            const scn = { ...VALID_SCENARIO.scenario, [c.field]: [{}] };
+            const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+            expect(r.errors.some(e => e.code === c.errorCode)).toBe(true);
+        });
+        it(`${c.errorCode}: rejects non-array ${c.field}`, () => {
+            const scn = { ...VALID_SCENARIO.scenario, [c.field]: 'oops' };
+            const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+            expect(r.errors.some(e => e.code === c.errorCode)).toBe(true);
+        });
+        it(`${c.errorCode}: rejects duplicate ${c.idField}`, () => {
+            const scn = {
+                ...VALID_SCENARIO.scenario,
+                [c.field]: [{ [c.idField]: 'X1' }, { [c.idField]: 'X1' }],
+            };
+            const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+            expect(r.errors.some(e => e.code === c.errorCode)).toBe(true);
+        });
+    }
+    it('accepts minimal scenario (id+name+status only)', () => {
+        const r = validateScenario({
+            notation: 'scenarios',
+            scenario: { id: 'S1', name: 'Minimal', status: 'Draft' },
+        });
+        expect(r.valid).toBe(true);
+    });
+    it('accepts scenario with all reference lists empty', () => {
+        const scn = {
+            ...VALID_SCENARIO.scenario,
+            factors_view: [],
+            goals: [],
+            capabilities: [],
+            activities: [],
+            products: [],
+            processes: [],
+            applications: [],
+        };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.valid).toBe(true);
+    });
+    // Pre-release blocker regression (orchestrator review 2026-05-21).
+    it('[blocker] tolerates a null element in factors_view[] without throwing', () => {
+        const scn = { ...VALID_SCENARIO.scenario, factors_view: [null] };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCN-005')).toBe(true);
+    });
+    it('[blocker] tolerates a null element in goals[] without throwing', () => {
+        const scn = { ...VALID_SCENARIO.scenario, goals: [null] };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCN-007')).toBe(true);
+    });
+    it('[blocker] tolerates a string element in applications[] without throwing', () => {
+        const scn = { ...VALID_SCENARIO.scenario, applications: ['x'] };
+        const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCN-012')).toBe(true);
+    });
+});
+describe('scenarios examples (regression)', () => {
+    const files = fs.readdirSync(EXAMPLES_DIR).filter(f => f.endsWith('.yaml'));
+    expect(files.length).toBeGreaterThan(0);
+    for (const file of files) {
+        it(`validates tests/fixtures/notation-corpus/scenarios/${file}`, () => {
+            const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+            const parsed = yaml.load(text);
+            const r = validateScenario(parsed);
+            expect(r.errors).toEqual([]);
+            expect(r.valid).toBe(true);
+        });
+    }
+});

package/dist/scenarios/index.d.ts

@@ -0,0 +1,2 @@
+export type { ScenarioStatus, FactorRelevance, FactorView, GoalRef, CapabilityRef, ActivityRef, ProductRef, ProcessRef, ApplicationRef, ScenarioHeader, ScenarioFile, } from './types.js';
+export { validateScenario } from './validate.js';

package/dist/scenarios/index.js

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