@transitrix/diagrams 1.0.0 → 1.1.0

package/src/capability-map/validate.ts

@@ -1,127 +1,127 @@
-import type { CapabilityType } from './types.js';
-import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
-
-export type { ValidationError, ValidationWarning, ValidationResult };
-
-const VALID_TYPES = new Set<CapabilityType>(['domain', 'supporting']);
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-// Canonical form per `IDS_AND_REFERENCES.md` §2: `CAPABILITY-V…` /
-// `CAPABILITY-H…` with the dotted address (`V1`, `V1.2.1`, `H1`). The bare
-// legacy form (`V1`, `H1`) is still accepted so existing maps without the
-// canonical prefix do not break — migration is tracked under
-// vkgeorgia/strategy#36.
-const CAP_ID_RE = /^(CAPABILITY-)?(V|H)\d+(\.\d+)*$/;
-
-export function validateCapabilityMap(input: unknown): ValidationResult {
-  const errors: ValidationError[] = [];
-  const warnings: ValidationWarning[] = [];
-
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'CMAP-001', message: 'Input must be an object' }], warnings };
-  }
-  const raw = input as Record<string, unknown>;
-
-  if (!('notation' in raw)) {
-    errors.push({ code: 'CMAP-001', message: 'Missing required field: notation' });
-  } else if (raw['notation'] !== 'capability-map') {
-    errors.push({ code: 'CMAP-001', message: `notation must be "capability-map", got "${raw['notation']}"` });
-  }
-  if (errors.length > 0) return { valid: false, errors, warnings };
-
-  const map = raw['capability_map'];
-  if (!map || typeof map !== 'object') {
-    errors.push({ code: 'CMAP-002', message: 'Missing required field: capability_map' });
-    return { valid: false, errors, warnings };
-  }
-  const m = map as Record<string, unknown>;
-
-  if (!m['id'] || typeof m['id'] !== 'string' || !(m['id'] as string).trim())
-    errors.push({ code: 'CMAP-002', message: 'capability_map.id is required' });
-  if (!m['name'] || typeof m['name'] !== 'string' || !(m['name'] as string).trim())
-    errors.push({ code: 'CMAP-002', message: 'capability_map.name is required' });
-  if (!m['assessment_date'] || typeof m['assessment_date'] !== 'string')
-    errors.push({ code: 'CMAP-002', message: 'capability_map.assessment_date is required' });
-
-  if (errors.length > 0) return { valid: false, errors, warnings };
-
-  if (!DATE_RE.test(m['assessment_date'] as string))
-    errors.push({ code: 'CMAP-007', message: `capability_map.assessment_date must be YYYY-MM-DD, got "${m['assessment_date']}"` });
-
-  const caps = m['capabilities'];
-  if (!Array.isArray(caps)) {
-    errors.push({ code: 'CMAP-002', message: 'capability_map.capabilities must be an array' });
-    return { valid: false, errors, warnings };
-  }
-
-  const seenIds = new Set<string>();
-  validateCapabilityTree(caps, 'capabilities', errors, seenIds);
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-function validateCapabilityTree(
-  nodes: unknown[],
-  pathPrefix: string,
-  errors: ValidationError[],
-  seenIds: Set<string>,
-): void {
-  for (let i = 0; i < nodes.length; i++) {
-    const rawNode = nodes[i];
-    const nodePath = `${pathPrefix}[${i}]`;
-
-    if (!rawNode || typeof rawNode !== 'object') {
-      errors.push({ code: 'CMAP-003', message: `${nodePath} must be an object` });
-      continue;
-    }
-    const node = rawNode as Record<string, unknown>;
-
-    if (!node['id'] || typeof node['id'] !== 'string' || !(node['id'] as string).trim()) {
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: id is required` });
-    } else {
-      const id = node['id'] as string;
-      if (seenIds.has(id)) {
-        errors.push({ code: 'CMAP-008', message: `Duplicate capability id: "${id}"` });
-      }
-      seenIds.add(id);
-      if (!CAP_ID_RE.test(id)) {
-        errors.push({ code: 'CMAP-009', message: `${nodePath}: id "${id}" must match the canonical pattern CAPABILITY-V[n] or CAPABILITY-H[n] with optional .n segments (e.g. CAPABILITY-V1, CAPABILITY-V1.2, CAPABILITY-H1.3); the bare V[n] / H[n] form is also accepted for legacy compatibility` });
-      }
-    }
-
-    if (!node['name'] || typeof node['name'] !== 'string' || !(node['name'] as string).trim())
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: name is required` });
-
-    if (node['current_maturity'] === undefined) {
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: current_maturity is required` });
-    } else {
-      const cm = node['current_maturity'];
-      if (typeof cm !== 'number' || !Number.isInteger(cm) || cm < 1 || cm > 5)
-        errors.push({ code: 'CMAP-005', message: `${nodePath}: current_maturity must be an integer 1–5, got "${cm}"` });
-    }
-
-    if (node['target_maturity'] !== undefined) {
-      const tm = node['target_maturity'];
-      if (typeof tm !== 'number' || !Number.isInteger(tm) || tm < 1 || tm > 5)
-        errors.push({ code: 'CMAP-006', message: `${nodePath}: target_maturity must be an integer 1–5, got "${tm}"` });
-    }
-
-    if (node['type'] !== undefined && !VALID_TYPES.has(node['type'] as CapabilityType))
-      errors.push({ code: 'CMAP-004', message: `${nodePath}: type "${node['type']}" must be one of: domain, supporting` });
-
-    if (node['target_date'] !== undefined) {
-      if (typeof node['target_date'] !== 'string' || !DATE_RE.test(node['target_date'] as string))
-        errors.push({ code: 'CMAP-007', message: `${nodePath}: target_date must be YYYY-MM-DD, got "${node['target_date']}"` });
-    }
-
-    if (node['applications'] !== undefined && !Array.isArray(node['applications']))
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: applications must be an array` });
-
-    if (node['children'] !== undefined) {
-      if (!Array.isArray(node['children'])) {
-        errors.push({ code: 'CMAP-003', message: `${nodePath}: children must be an array` });
-      } else {
-        validateCapabilityTree(node['children'] as unknown[], `${nodePath}.children`, errors, seenIds);
-      }
-    }
-  }
-}
+import type { CapabilityType } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const VALID_TYPES = new Set<CapabilityType>(['domain', 'supporting']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Canonical form per `IDS_AND_REFERENCES.md` §2: `CAPABILITY-V…` /
+// `CAPABILITY-H…` with the dotted address (`V1`, `V1.2.1`, `H1`). The bare
+// legacy form (`V1`, `H1`) is still accepted so existing maps without the
+// canonical prefix do not break — migration is tracked under
+// vkgeorgia/strategy#36.
+const CAP_ID_RE = /^(CAPABILITY-)?(V|H)\d+(\.\d+)*$/;
+
+export function validateCapabilityMap(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'CMAP-001', message: 'Input must be an object' }], warnings };
+  }
+  const raw = input as Record<string, unknown>;
+
+  if (!('notation' in raw)) {
+    errors.push({ code: 'CMAP-001', message: 'Missing required field: notation' });
+  } else if (raw['notation'] !== 'capability-map') {
+    errors.push({ code: 'CMAP-001', message: `notation must be "capability-map", got "${raw['notation']}"` });
+  }
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const map = raw['capability_map'];
+  if (!map || typeof map !== 'object') {
+    errors.push({ code: 'CMAP-002', message: 'Missing required field: capability_map' });
+    return { valid: false, errors, warnings };
+  }
+  const m = map as Record<string, unknown>;
+
+  if (!m['id'] || typeof m['id'] !== 'string' || !(m['id'] as string).trim())
+    errors.push({ code: 'CMAP-002', message: 'capability_map.id is required' });
+  if (!m['name'] || typeof m['name'] !== 'string' || !(m['name'] as string).trim())
+    errors.push({ code: 'CMAP-002', message: 'capability_map.name is required' });
+  if (!m['assessment_date'] || typeof m['assessment_date'] !== 'string')
+    errors.push({ code: 'CMAP-002', message: 'capability_map.assessment_date is required' });
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  if (!DATE_RE.test(m['assessment_date'] as string))
+    errors.push({ code: 'CMAP-007', message: `capability_map.assessment_date must be YYYY-MM-DD, got "${m['assessment_date']}"` });
+
+  const caps = m['capabilities'];
+  if (!Array.isArray(caps)) {
+    errors.push({ code: 'CMAP-002', message: 'capability_map.capabilities must be an array' });
+    return { valid: false, errors, warnings };
+  }
+
+  const seenIds = new Set<string>();
+  validateCapabilityTree(caps, 'capabilities', errors, seenIds);
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function validateCapabilityTree(
+  nodes: unknown[],
+  pathPrefix: string,
+  errors: ValidationError[],
+  seenIds: Set<string>,
+): void {
+  for (let i = 0; i < nodes.length; i++) {
+    const rawNode = nodes[i];
+    const nodePath = `${pathPrefix}[${i}]`;
+
+    if (!rawNode || typeof rawNode !== 'object') {
+      errors.push({ code: 'CMAP-003', message: `${nodePath} must be an object` });
+      continue;
+    }
+    const node = rawNode as Record<string, unknown>;
+
+    if (!node['id'] || typeof node['id'] !== 'string' || !(node['id'] as string).trim()) {
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: id is required` });
+    } else {
+      const id = node['id'] as string;
+      if (seenIds.has(id)) {
+        errors.push({ code: 'CMAP-008', message: `Duplicate capability id: "${id}"` });
+      }
+      seenIds.add(id);
+      if (!CAP_ID_RE.test(id)) {
+        errors.push({ code: 'CMAP-009', message: `${nodePath}: id "${id}" must match the canonical pattern CAPABILITY-V[n] or CAPABILITY-H[n] with optional .n segments (e.g. CAPABILITY-V1, CAPABILITY-V1.2, CAPABILITY-H1.3); the bare V[n] / H[n] form is also accepted for legacy compatibility` });
+      }
+    }
+
+    if (!node['name'] || typeof node['name'] !== 'string' || !(node['name'] as string).trim())
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: name is required` });
+
+    if (node['current_maturity'] === undefined) {
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: current_maturity is required` });
+    } else {
+      const cm = node['current_maturity'];
+      if (typeof cm !== 'number' || !Number.isInteger(cm) || cm < 1 || cm > 5)
+        errors.push({ code: 'CMAP-005', message: `${nodePath}: current_maturity must be an integer 1–5, got "${cm}"` });
+    }
+
+    if (node['target_maturity'] !== undefined) {
+      const tm = node['target_maturity'];
+      if (typeof tm !== 'number' || !Number.isInteger(tm) || tm < 1 || tm > 5)
+        errors.push({ code: 'CMAP-006', message: `${nodePath}: target_maturity must be an integer 1–5, got "${tm}"` });
+    }
+
+    if (node['type'] !== undefined && !VALID_TYPES.has(node['type'] as CapabilityType))
+      errors.push({ code: 'CMAP-004', message: `${nodePath}: type "${node['type']}" must be one of: domain, supporting` });
+
+    if (node['target_date'] !== undefined) {
+      if (typeof node['target_date'] !== 'string' || !DATE_RE.test(node['target_date'] as string))
+        errors.push({ code: 'CMAP-007', message: `${nodePath}: target_date must be YYYY-MM-DD, got "${node['target_date']}"` });
+    }
+
+    if (node['applications'] !== undefined && !Array.isArray(node['applications']))
+      errors.push({ code: 'CMAP-003', message: `${nodePath}: applications must be an array` });
+
+    if (node['children'] !== undefined) {
+      if (!Array.isArray(node['children'])) {
+        errors.push({ code: 'CMAP-003', message: `${nodePath}: children must be an array` });
+      } else {
+        validateCapabilityTree(node['children'] as unknown[], `${nodePath}.children`, errors, seenIds);
+      }
+    }
+  }
+}

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

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { validateChange } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
 
 function valid(): Record<string, unknown> {
   return {
@@ -17,72 +18,80 @@ function valid(): Record<string, unknown> {
   };
 }
 
-const codes = (input: unknown): string[] => validateChange(input).errors.map(e => e.code);
+const codes = (input: unknown, opts?: Parameters<typeof validateChange>[1]): string[] =>
+  validateChange(input, opts).errors.map(e => e.code);
 
 describe('validateChange — positive', () => {
-  it('accepts the worked-example CHANGE-EU-CRM-1', () => {
+  it('accepts a well-formed change', () => {
     const r = validateChange(valid());
     expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
   });
 
-  it('accepts a minimal change (no goals, no parent)', () => {
-    const r = valid();
-    delete r.goals;
-    expect(validateChange(r).valid).toBe(true);
+  it('accepts a minimal change with no optional fields', () => {
+    const c = valid();
+    delete c.goals;
+    delete c.description;
+    expect(validateChange(c).valid).toBe(true);
   });
 
   it('accepts a child change with a CHANGE parent', () => {
-    expect(validateChange({ ...valid(), id: 'CHANGE-EU-CRM-DETAIL-1', parent: 'CHANGE-EU-CRM-1' }).valid).toBe(true);
+    const c = valid();
+    c.id = 'CHANGE-EU-CRM-2';
+    c.parent = 'CHANGE-EU-CRM-1';
+    expect(validateChange(c).valid).toBe(true);
   });
 });
 
-describe('validateChange — CHANGE-001 (envelope / shape)', () => {
-  it('flags a non-object', () => {
-    expect(codes(null)).toEqual(['CHANGE-001']);
+describe('validateChange — CHANGE-001 (shape / id grammar)', () => {
+  it('flags a missing required envelope field', () => {
+    const c = valid();
+    delete c.name;
+    expect(codes(c)).toContain('CHANGE-001');
   });
 
-  it('flags wrong notation tag', () => {
-    expect(codes({ ...valid(), notation: 'gap' })).toContain('CHANGE-001');
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'CHANGE-EU-CRM-001' })).toContain('CHANGE-001');
+    expect(codes({ ...valid(), id: 'CHG-1' })).toContain('CHANGE-001');
   });
 
-  it('flags an id with the wrong TYPE prefix', () => {
-    expect(codes({ ...valid(), id: 'ACTIVITY-DESIGN-1' })).toContain('CHANGE-001');
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'gap' })).toContain('CHANGE-001');
   });
 
-  it('flags a missing admission field', () => {
-    const r = valid();
-    delete r.admitted_at;
-    expect(codes(r)).toContain('CHANGE-001');
+  it('flags a non-array goals', () => {
+    expect(codes({ ...valid(), goals: 'GOAL-EU-1' })).toContain('CHANGE-001');
   });
 
-  it('flags a missing valid_to key', () => {
-    const r = valid();
-    delete r.valid_to;
-    expect(codes(r)).toContain('CHANGE-001');
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['CHANGE-001']);
   });
 });
 
-describe('validateChange — CHANGE-002 (goals refs)', () => {
-  it('flags a non-GOAL typed id in goals', () => {
-    expect(codes({ ...valid(), goals: ['CHANGE-EU-CRM-1'] })).toContain('CHANGE-002');
+describe('validateChange — CHANGE-002 (goals references)', () => {
+  it('flags a malformed goals entry', () => {
+    expect(codes({ ...valid(), goals: ['not an id'] })).toContain('CHANGE-002');
   });
 
-  it('flags a malformed entry in goals', () => {
-    expect(codes({ ...valid(), goals: ['not an id'] })).toContain('CHANGE-002');
+  it('flags a goals entry of the wrong TYPE', () => {
+    expect(codes({ ...valid(), goals: ['FACTOR-X-1'] })).toContain('CHANGE-002');
   });
 
-  it('flags goals when it is not an array', () => {
-    expect(codes({ ...valid(), goals: 'GOAL-EU-1' })).toContain('CHANGE-002');
+  it('flags an unresolved id when a catalog is supplied', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes(valid(), { catalog })).toContain('CHANGE-002');
   });
 });
 
-describe('validateChange — CHANGE-003 (parent ref)', () => {
-  it('flags a non-CHANGE parent', () => {
-    expect(codes({ ...valid(), parent: 'GOAL-EU-1' })).toContain('CHANGE-003');
+describe('validateChange — CHANGE-003 (parent)', () => {
+  it('flags a parent of the wrong TYPE', () => {
+    expect(codes({ ...valid(), parent: 'GOAL-X-1' })).toContain('CHANGE-003');
   });
 
-  it('flags self-parenting', () => {
+  it('flags a parent equal to self', () => {
     expect(codes({ ...valid(), parent: 'CHANGE-EU-CRM-1' })).toContain('CHANGE-003');
   });
+
+  it('flags a malformed parent', () => {
+    expect(codes({ ...valid(), parent: 'not an id' })).toContain('CHANGE-003');
+  });
 });

package/src/change/index.ts

@@ -1,2 +1,3 @@
 export type { Change } from './types.js';
 export { validateChange } from './validate.js';
+export type { ChangeValidateOptions } from './validate.js';

package/src/change/types.ts

@@ -1,5 +1,5 @@
-// CHANGE — implementation-layer gap primitive (ArchiMate Gap).
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.3 + envelope §3.
+// CHANGE — implementation-layer Gap (ArchiMate). The BDN change layer.
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.3.
 
 import type { GateChecks } from '../requirement/types.js';
 
@@ -9,15 +9,17 @@ export interface Change {
   name: string;
   /** GOAL-… IDs this change delivers. */
   goals?: string[];
-  /** CHANGE-… — the higher-scale change this one decomposes from. */
+  /** Higher-scale CHANGE this one decomposes from (recursive, §6.1). */
   parent?: string;
   description?: string;
 
+  // Admission record (CONTRACT.md §6).
   zone: 'canon';
   admitted_at: string;
   admitted_by: string;
   gate_checks: GateChecks;
 
+  // Primitive lifecycle (CONTRACT.md §7).
   valid_from: string;
   valid_to: string | null;
 }

package/src/change/validate.ts

@@ -1,59 +1,91 @@
 // CHANGE validator — methodology notations/ELEMENT_PRIMITIVES.md §7.3.
 //
-// Implements CHANGE-001..003. Cross-cutting HDR-/LIFECYCLE- and the BDN
-// linkage rules across documents are owned elsewhere (CONTRACT.md §8) and
-// out of scope for this single-artefact validator.
-//
-// §7.3 defines no subtype vocabulary on `type`, so there is no enum gate here.
+// Codes:
+//   CHANGE-001 — shape / id grammar / required envelope fields.
+//   CHANGE-002 — `goals` entry malformed or wrong TYPE (must be GOAL-…).
+//   CHANGE-003 — `parent` malformed, wrong TYPE (must be CHANGE-…), or equals self.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
 
-import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
-import { typeOfId } from '../typed-id.js';
-import { validateElementEnvelope } from '../element-envelope.js';
+export interface ChangeValidateOptions {
+  /** When provided, enforces that each `goals` / `parent` id is admitted. */
+  catalog?: CanonCatalog;
+}
 
-export function validateChange(input: unknown): ValidationResult {
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+export function validateChange(input: unknown, options: ChangeValidateOptions = {}): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  const { record, errors: envErrors } = validateElementEnvelope(input, {
-    notation: 'change',
-    idType: 'CHANGE',
-    code: 'CHANGE-001',
-  });
-  errors.push(...envErrors);
-  if (!record) return { valid: false, errors, warnings };
-
-  // CHANGE-002 — goals[] must be a list of GOAL typed ids.
-  if (record.goals !== undefined) {
-    if (!Array.isArray(record.goals)) {
-      errors.push({ code: 'CHANGE-002', message: 'goals must be a list of typed GOAL IDs.', path: 'goals' });
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'CHANGE-001', message: 'Change must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const c = input as Record<string, unknown>;
+
+  // CHANGE-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(c.id, 'CHANGE')) {
+    errors.push({ code: 'CHANGE-001', message: `id "${String(c.id)}" must match CHANGE-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (c.notation !== 'change') {
+    errors.push({ code: 'CHANGE-001', message: 'notation must be the fixed value "change".', path: 'notation' });
+  }
+  if (c.zone !== undefined && c.zone !== 'canon') {
+    errors.push({ code: 'CHANGE-001', message: 'zone must be "canon" for a CHANGE.', path: 'zone' });
+  } else if (c.zone === undefined) {
+    errors.push({ code: 'CHANGE-001', message: 'zone is required.', path: 'zone' });
+  }
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const v = c[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'CHANGE-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (c.gate_checks === null || typeof c.gate_checks !== 'object') {
+    errors.push({ code: 'CHANGE-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in c) || !(typeof c.valid_to === 'string' || c.valid_to === null)) {
+    errors.push({ code: 'CHANGE-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // CHANGE-002 — `goals` references.
+  if (c.goals !== undefined) {
+    if (!Array.isArray(c.goals)) {
+      errors.push({ code: 'CHANGE-001', message: 'goals must be a list of typed IDs.', path: 'goals' });
     } else {
-      record.goals.forEach((ref, i) => {
-        if (typeOfId(ref) !== 'GOAL') {
-          errors.push({
-            code: 'CHANGE-002',
-            message: `goals[${i}] "${String(ref)}" must be a GOAL typed ID.`,
-            path: `goals[${i}]`,
-          });
+      c.goals.forEach((ref, i) => {
+        const type = typeOfId(ref);
+        if (!type) {
+          errors.push({ code: 'CHANGE-002', message: `goals[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `goals[${i}]` });
+          return;
+        }
+        if (type !== 'GOAL') {
+          errors.push({ code: 'CHANGE-002', message: `goals[${i}] TYPE "${type}" must be GOAL.`, path: `goals[${i}]` });
+          return;
+        }
+        if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+          errors.push({ code: 'CHANGE-002', message: `goals[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `goals[${i}]` });
         }
       });
     }
   }
 
-  // CHANGE-003 — parent must be a CHANGE typed id (multi-scale decomposition).
-  if (record.parent !== undefined) {
-    if (typeof record.parent !== 'string' || typeOfId(record.parent) !== 'CHANGE') {
-      errors.push({
-        code: 'CHANGE-003',
-        message: `parent "${String(record.parent)}" must be a CHANGE typed ID.`,
-        path: 'parent',
-      });
-    } else if (record.parent === record.id) {
-      // A change cannot decompose from itself.
-      errors.push({
-        code: 'CHANGE-003',
-        message: `parent "${record.parent}" must not equal id (a change cannot be its own parent).`,
-        path: 'parent',
-      });
+  // CHANGE-003 — `parent` (CHANGE-…; not self).
+  if (c.parent !== undefined) {
+    const p = c.parent;
+    const type = typeOfId(p);
+    if (typeof p !== 'string' || !type) {
+      errors.push({ code: 'CHANGE-003', message: `parent "${String(p)}" is not a resolvable typed ID.`, path: 'parent' });
+    } else if (type !== 'CHANGE') {
+      errors.push({ code: 'CHANGE-003', message: `parent TYPE "${type}" must be CHANGE.`, path: 'parent' });
+    } else if (typeof c.id === 'string' && p === c.id) {
+      errors.push({ code: 'CHANGE-003', message: `parent "${p}" must not equal the element's own id.`, path: 'parent' });
+    } else if (options.catalog && options.catalog.typeOf(p) === undefined) {
+      errors.push({ code: 'CHANGE-003', message: `parent "${p}" does not resolve to an admitted CHANGE.`, path: 'parent' });
     }
   }