@transitrix/diagrams 1.0.0 → 1.1.0

package/src/activity-card/validate.ts

@@ -1,158 +1,162 @@
-// Activity Card — document-local structural validation.
-//
-// This validator checks only what can be known from the card document ALONE:
-// the header, the `activity_card` block shape, the project-reference grammar
-// (PC-001's "missing or malformed" half), and each milestone's shape.
-//
-// The cross-document rules — PC-001 "does not resolve", PC-002
-// (activity_type), PC-003 (milestone changes ⊆ project changes), PC-004
-// (milestone date within the project lifecycle window) and the LIFECYCLE-*
-// checks — require the sibling `*.activities.*` / `*.fgca.*` documents and so
-// live in `resolver.ts`. The preview merges both result sets.
-//
-// Codes:
-//   AC-001   document structure (root object, `activity_card` block)
-//   AC-002   `activity_card.id` grammar
-//   AC-003   milestone structure (missing id / name / date)
-//   AC-004   milestone id grammar / duplicate
-//   AC-005   milestone date format
-//   AC-006   milestone `delivers_changes` shape / grammar
-//   HDR-001  missing `notation`           (CONTRACT.md §2)
-//   HDR-002  wrong `notation`             (CONTRACT.md §2)
-//   PC-001   `project` missing or malformed (the document-local half; the
-//            "does not resolve" half is emitted by the resolver)
-
-import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
-
-export type { ValidationError, ValidationWarning, ValidationResult };
-
-const ACTIVITY_CARD_ID_RE = /^ACTIVITY_CARD(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-const ACTIVITY_ID_RE = /^ACTIVITY(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-const MILESTONE_ID_RE = /^MILESTONE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-const CHANGE_ID_RE = /^CHANGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-
-function isNonEmptyString(v: unknown): v is string {
-  return typeof v === 'string' && v.trim().length > 0;
-}
-
-export function validateActivityCard(input: unknown): ValidationResult {
-  const errors: ValidationError[] = [];
-  const warnings: ValidationWarning[] = [];
-
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'AC-001', message: 'document root is not an object' }], warnings };
-  }
-
-  const raw = input as Record<string, unknown>;
-
-  // ── Header (CONTRACT.md §2) ────────────────────────────────────────────────
-  if (!('notation' in raw)) {
-    errors.push({ code: 'HDR-001', message: 'notation field is required' });
-  } else if (raw['notation'] !== 'activity-card') {
-    errors.push({
-      code: 'HDR-002',
-      message: `notation must be "activity-card", got "${String(raw['notation'])}"`,
-    });
-  }
-
-  // ── activity_card block ─────────────────────────────────────────────────────
-  const block = raw['activity_card'];
-  if (!block || typeof block !== 'object' || Array.isArray(block)) {
-    errors.push({ code: 'AC-001', message: 'Missing required root key: activity_card (object)' });
-    return { valid: false, errors, warnings };
-  }
-  const card = block as Record<string, unknown>;
-
-  if (!isNonEmptyString(card['id'])) {
-    errors.push({ code: 'AC-002', message: 'activity_card.id is required' });
-  } else if (!ACTIVITY_CARD_ID_RE.test(card['id'])) {
-    errors.push({
-      code: 'AC-002',
-      message: `activity_card.id "${card['id']}" must match ACTIVITY_CARD-[<middle>-]<INTEGER>`,
-    });
-  }
-
-  // PC-001 (document-local half): project present + well-formed.
-  if (!isNonEmptyString(card['project'])) {
-    errors.push({ code: 'PC-001', message: 'activity_card.project is required (an ACTIVITY-… id)' });
-  } else if (!ACTIVITY_ID_RE.test(card['project'])) {
-    errors.push({
-      code: 'PC-001',
-      message: `activity_card.project "${card['project']}" is malformed; must match ACTIVITY-[<middle>-]<INTEGER>`,
-    });
-  }
-
-  if (card['description'] !== undefined && typeof card['description'] !== 'string') {
-    errors.push({ code: 'AC-001', message: 'activity_card.description must be a string' });
-  }
-
-  // ── milestones[] (optional) ─────────────────────────────────────────────────
-  const milestonesRaw = card['milestones'];
-  if (milestonesRaw !== undefined) {
-    if (!Array.isArray(milestonesRaw)) {
-      errors.push({ code: 'AC-003', message: 'activity_card.milestones must be an array', path: 'milestones' });
-    } else {
-      const seenIds = new Set<string>();
-      milestonesRaw.forEach((el, i) => {
-        const p = `milestones[${i}]`;
-        if (!el || typeof el !== 'object' || Array.isArray(el)) {
-          errors.push({ code: 'AC-003', message: `${p} must be an object`, path: p });
-          return;
-        }
-        const m = el as Record<string, unknown>;
-
-        if (!isNonEmptyString(m['id'])) {
-          errors.push({ code: 'AC-003', message: `${p}.id is required`, path: p });
-        } else {
-          const mid = m['id'].trim();
-          if (!MILESTONE_ID_RE.test(mid)) {
-            errors.push({ code: 'AC-004', message: `${p}.id "${mid}" must match MILESTONE-[<middle>-]<INTEGER>`, path: p });
-          }
-          if (seenIds.has(mid)) {
-            errors.push({ code: 'AC-004', message: `Duplicate milestone id "${mid}"`, path: p });
-          } else {
-            seenIds.add(mid);
-          }
-        }
-
-        if (!isNonEmptyString(m['name'])) {
-          errors.push({ code: 'AC-003', message: `${p}.name is required`, path: p });
-        }
-
-        if (!isNonEmptyString(m['date'])) {
-          errors.push({ code: 'AC-003', message: `${p}.date is required`, path: p });
-        } else if (!DATE_RE.test(m['date'])) {
-          errors.push({
-            code: 'AC-005',
-            message: `${p}.date "${m['date']}" must be a quoted ISO 8601 date (YYYY-MM-DD)`,
-            path: p,
-          });
-        }
-
-        if (m['description'] !== undefined && typeof m['description'] !== 'string') {
-          errors.push({ code: 'AC-003', message: `${p}.description must be a string`, path: p });
-        }
-
-        const dc = m['delivers_changes'];
-        if (dc !== undefined) {
-          if (!Array.isArray(dc)) {
-            errors.push({ code: 'AC-006', message: `${p}.delivers_changes must be an array of CHANGE-… ids`, path: p });
-          } else {
-            dc.forEach((c) => {
-              if (typeof c !== 'string' || !CHANGE_ID_RE.test(c)) {
-                errors.push({
-                  code: 'AC-006',
-                  message: `${p}.delivers_changes[] entry "${String(c)}" must match CHANGE-[<middle>-]<INTEGER>`,
-                  path: p,
-                });
-              }
-            });
-          }
-        }
-      });
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
+// Activity Card — document-local structural validation.
+//
+// This validator checks only what can be known from the card document ALONE:
+// the header, the `activity_card` block shape, the project-reference grammar
+// (PC-001's "missing or malformed" half), and each milestone's shape.
+//
+// The cross-document rules — PC-001 "does not resolve", PC-002
+// (activity_type), PC-003 (milestone changes ⊆ project changes), PC-004
+// (milestone date within the project lifecycle window) and the LIFECYCLE-*
+// checks — require the sibling `*.activities.*` / `*.fgca.*` documents and so
+// live in `resolver.ts`. The preview merges both result sets.
+//
+// Codes:
+//   AC-001   document structure (root object, `activity_card` block)
+//   AC-002   `activity_card.id` grammar
+//   AC-003   milestone structure (missing id / name / date)
+//   AC-004   milestone id grammar / duplicate
+//   AC-005   milestone date format
+//   AC-006   milestone `delivers_changes` shape / grammar
+//   HDR-001  missing `notation`           (CONTRACT.md §2)
+//   HDR-002  wrong `notation`             (CONTRACT.md §2)
+//   PC-001   `project` missing or malformed (the document-local half; the
+//            "does not resolve" half is emitted by the resolver)
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const ACTIVITY_CARD_ID_RE = /^ACTIVITY_CARD(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const ACTIVITY_ID_RE = /^ACTIVITY(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const MILESTONE_ID_RE = /^MILESTONE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const CHANGE_ID_RE = /^CHANGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+export function validateActivityCard(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'AC-001', message: 'document root is not an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  // ── Header (CONTRACT.md §2) ────────────────────────────────────────────────
+  if (!('notation' in raw)) {
+    errors.push({ code: 'HDR-001', message: 'notation field is required' });
+  } else if (raw['notation'] !== 'activity-card') {
+    errors.push({
+      code: 'HDR-002',
+      message: `notation must be "activity-card", got "${String(raw['notation'])}"`,
+    });
+  }
+
+  // ── activity_card block ─────────────────────────────────────────────────────
+  const block = raw['activity_card'];
+  if (!block || typeof block !== 'object' || Array.isArray(block)) {
+    errors.push({ code: 'AC-001', message: 'Missing required root key: activity_card (object)' });
+    return { valid: false, errors, warnings };
+  }
+  const card = block as Record<string, unknown>;
+
+  if (!isNonEmptyString(card['id'])) {
+    errors.push({ code: 'AC-002', message: 'activity_card.id is required' });
+  } else if (!ACTIVITY_CARD_ID_RE.test(card['id'])) {
+    errors.push({
+      code: 'AC-002',
+      message: `activity_card.id "${card['id']}" must match ACTIVITY_CARD-[<middle>-]<INTEGER>`,
+    });
+  }
+
+  // PC-001 (document-local half): project present + well-formed.
+  if (!isNonEmptyString(card['project'])) {
+    errors.push({ code: 'PC-001', message: 'activity_card.project is required (an ACTIVITY-… id)' });
+  } else if (!ACTIVITY_ID_RE.test(card['project'])) {
+    errors.push({
+      code: 'PC-001',
+      message: `activity_card.project "${card['project']}" is malformed; must match ACTIVITY-[<middle>-]<INTEGER>`,
+    });
+  }
+
+  if (card['description'] !== undefined && typeof card['description'] !== 'string') {
+    errors.push({ code: 'AC-001', message: 'activity_card.description must be a string' });
+  }
+
+  if (card['notes'] !== undefined && typeof card['notes'] !== 'string') {
+    errors.push({ code: 'AC-001', message: 'activity_card.notes must be a string' });
+  }
+
+  // ── milestones[] (optional) ─────────────────────────────────────────────────
+  const milestonesRaw = card['milestones'];
+  if (milestonesRaw !== undefined) {
+    if (!Array.isArray(milestonesRaw)) {
+      errors.push({ code: 'AC-003', message: 'activity_card.milestones must be an array', path: 'milestones' });
+    } else {
+      const seenIds = new Set<string>();
+      milestonesRaw.forEach((el, i) => {
+        const p = `milestones[${i}]`;
+        if (!el || typeof el !== 'object' || Array.isArray(el)) {
+          errors.push({ code: 'AC-003', message: `${p} must be an object`, path: p });
+          return;
+        }
+        const m = el as Record<string, unknown>;
+
+        if (!isNonEmptyString(m['id'])) {
+          errors.push({ code: 'AC-003', message: `${p}.id is required`, path: p });
+        } else {
+          const mid = m['id'].trim();
+          if (!MILESTONE_ID_RE.test(mid)) {
+            errors.push({ code: 'AC-004', message: `${p}.id "${mid}" must match MILESTONE-[<middle>-]<INTEGER>`, path: p });
+          }
+          if (seenIds.has(mid)) {
+            errors.push({ code: 'AC-004', message: `Duplicate milestone id "${mid}"`, path: p });
+          } else {
+            seenIds.add(mid);
+          }
+        }
+
+        if (!isNonEmptyString(m['name'])) {
+          errors.push({ code: 'AC-003', message: `${p}.name is required`, path: p });
+        }
+
+        if (!isNonEmptyString(m['date'])) {
+          errors.push({ code: 'AC-003', message: `${p}.date is required`, path: p });
+        } else if (!DATE_RE.test(m['date'])) {
+          errors.push({
+            code: 'AC-005',
+            message: `${p}.date "${m['date']}" must be a quoted ISO 8601 date (YYYY-MM-DD)`,
+            path: p,
+          });
+        }
+
+        if (m['description'] !== undefined && typeof m['description'] !== 'string') {
+          errors.push({ code: 'AC-003', message: `${p}.description must be a string`, path: p });
+        }
+
+        const dc = m['delivers_changes'];
+        if (dc !== undefined) {
+          if (!Array.isArray(dc)) {
+            errors.push({ code: 'AC-006', message: `${p}.delivers_changes must be an array of CHANGE-… ids`, path: p });
+          } else {
+            dc.forEach((c) => {
+              if (typeof c !== 'string' || !CHANGE_ID_RE.test(c)) {
+                errors.push({
+                  code: 'AC-006',
+                  message: `${p}.delivers_changes[] entry "${String(c)}" must match CHANGE-[<middle>-]<INTEGER>`,
+                  path: p,
+                });
+              }
+            });
+          }
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

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

@@ -4,64 +4,103 @@ import { validateActor } from '../validate.js';
 function valid(): Record<string, unknown> {
   return {
     notation: 'actor',
-    id: 'ACTOR-PERSON-1',
-    name: 'Alex Doe (example)',
-    type: 'person',
-    description: 'Synthetic person actor demonstrating identity-vs-engagement.',
-    contact: 'alex.doe@example.test',
+    id: 'ACTOR-OPS-1',
+    name: 'Operations',
+    type: 'business_unit',
+    description: 'The operations organisation.',
+    contact: 'ops@acme.example',
     zone: 'canon',
     admitted_at: '2026-05-29',
     admitted_by: 'v.korobeinikov',
     gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
-    valid_from: '2025-03-01',
+    valid_from: '2024-01-01',
     valid_to: null,
   };
 }
 
-const codes = (input: unknown): string[] => validateActor(input).errors.map(e => e.code);
+const codes = (input: unknown): string[] =>
+  validateActor(input).errors.map(e => e.code);
 
 describe('validateActor — positive', () => {
-  it('accepts the worked-example ACTOR-PERSON-1', () => {
+  it('accepts a well-formed business_unit actor', () => {
     const r = validateActor(valid());
     expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
   });
 
-  it('accepts each permitted type', () => {
-    for (const t of ['person', 'business_unit', 'system']) {
-      expect(validateActor({ ...valid(), type: t }).valid).toBe(true);
-    }
+  it('accepts a person actor with no optional fields', () => {
+    const a = valid();
+    a.id = 'ACTOR-JANE-DOE-1';
+    a.name = 'Jane Doe';
+    a.type = 'person';
+    delete a.description;
+    delete a.contact;
+    expect(validateActor(a).valid).toBe(true);
+  });
+
+  it('accepts a system actor with external_ref', () => {
+    const a = valid();
+    a.id = 'ACTOR-ORDER-MGMT-SYS-1';
+    a.name = 'Order Management System';
+    a.type = 'system';
+    a.external_ref = 'https://oms.acme.example/api';
+    expect(validateActor(a).valid).toBe(true);
   });
 });
 
-describe('validateActor — ACTOR-001 (envelope / shape)', () => {
-  it('flags a non-object', () => {
-    expect(codes(null)).toEqual(['ACTOR-001']);
+describe('validateActor — ACTOR-001 (shape / id grammar)', () => {
+  it('flags a missing required envelope field', () => {
+    const a = valid();
+    delete a.name;
+    expect(codes(a)).toContain('ACTOR-001');
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'ACTOR-OPS-001' })).toContain('ACTOR-001');
+    expect(codes({ ...valid(), id: 'A-1' })).toContain('ACTOR-001');
+  });
+
+  it('flags a wrong notation tag and non-canon zone', () => {
+    expect(codes({ ...valid(), notation: 'business_actor' })).toContain('ACTOR-001');
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('ACTOR-001');
   });
 
-  it('flags a wrong notation tag', () => {
-    expect(codes({ ...valid(), notation: 'agent' })).toContain('ACTOR-001');
+  it('flags a missing type', () => {
+    const a = valid();
+    delete a.type;
+    expect(codes(a)).toContain('ACTOR-001');
   });
 
-  it('flags an id with the wrong TYPE prefix', () => {
-    expect(codes({ ...valid(), id: 'ROLE-CEO-1' })).toContain('ACTOR-001');
+  it('flags a missing valid_to key', () => {
+    const a = valid();
+    delete a.valid_to;
+    expect(codes(a)).toContain('ACTOR-001');
   });
 
-  it('flags missing name', () => {
-    const r = valid();
-    delete r.name;
-    expect(codes(r)).toContain('ACTOR-001');
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['ACTOR-001']);
   });
 });
 
-describe('validateActor — ACTOR-002 (identity discriminator)', () => {
-  it('flags a missing type (the identity discriminator is required)', () => {
-    const r = valid();
-    delete r.type;
-    expect(codes(r)).toContain('ACTOR-002');
+describe('validateActor — ACTOR-002 (type enum)', () => {
+  it('flags a type outside {person, business_unit, system}', () => {
+    expect(codes({ ...valid(), type: 'organisation' })).toContain('ACTOR-002');
+  });
+});
+
+describe('validateActor — ACTOR-003 (engagement fields forbidden inline)', () => {
+  it('flags inline employment', () => {
+    expect(codes({ ...valid(), employment: 'REL-EMP-1' })).toContain('ACTOR-003');
+  });
+
+  it('flags inline unit_parent', () => {
+    expect(codes({ ...valid(), unit_parent: 'ACTOR-PARENT-1' })).toContain('ACTOR-003');
+  });
+
+  it('flags inline roles', () => {
+    expect(codes({ ...valid(), roles: ['ROLE-OPS-1'] })).toContain('ACTOR-003');
   });
 
-  it('flags a type outside person/business_unit/system', () => {
-    expect(codes({ ...valid(), type: 'employee' })).toContain('ACTOR-002');
+  it('flags inline owner', () => {
+    expect(codes({ ...valid(), owner: 'ACTOR-OPS-1' })).toContain('ACTOR-003');
   });
 });

package/src/actor/index.ts

@@ -1,3 +1,3 @@
 export type { Actor, ActorType } from './types.js';
-export { ACTOR_TYPES } from './types.js';
+export { ACTOR_TYPES, ACTOR_FORBIDDEN_INLINE_FIELDS } from './types.js';
 export { validateActor } from './validate.js';

package/src/actor/types.ts

@@ -1,29 +1,43 @@
-// ACTOR — business-layer identity primitive (ArchiMate Business Actor).
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.10 +
-//         notations/elements/19-actors.md + envelope §3.
+// ACTOR — active-structure identity primitive (ArchiMate Business Actor).
+// Schema: methodology notations/elements/19-actors.md + ELEMENT_PRIMITIVES.md §7.10.
 
 import type { GateChecks } from '../requirement/types.js';
 
-/** Identity discriminator — what kind of actor (person, business_unit, system). */
-export type ActorType = 'person' | 'business_unit' | 'system';
-
 export const ACTOR_TYPES = ['person', 'business_unit', 'system'] as const;
+export type ActorType = typeof ACTOR_TYPES[number];
+
+/**
+ * Fields that record engagement / org-hierarchy and therefore MUST NOT appear
+ * inline on an ACTOR file (§7.10, ACTOR-003). They belong in time-aware REL
+ * records, never on the identity primitive.
+ */
+export const ACTOR_FORBIDDEN_INLINE_FIELDS = [
+  'employment',
+  'candidacy',
+  'alumni_membership',
+  'community_membership',
+  'contracting',
+  'unit_parent',
+  'roles',
+  'owner',
+] as const;
 
 export interface Actor {
   notation: 'actor';
   id: string;
   name: string;
-  /** Required identity discriminator. */
   type: ActorType;
   description?: string;
   contact?: string;
   external_ref?: 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/actor/validate.ts

@@ -1,37 +1,69 @@
-// ACTOR validator — methodology notations/ELEMENT_PRIMITIVES.md §7.10 +
-// notations/elements/19-actors.md.
+// ACTOR validator — methodology notations/elements/19-actors.md §5.
 //
-// Implements ACTOR-001..002. Employment / role-assignment / unit-parent
-// relations live in first-class time-aware REL files (elements/17-relations.md
-// §3) and are out of scope for this single-artefact validator.
+// Implements ACTOR-001..003. The shared HDR-/LIFECYCLE- rules are
+// cross-cutting concerns (CONTRACT.md §8) and out of scope for the
+// single-artefact validator.
 
-import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
-import { validateElementEnvelope } from '../element-envelope.js';
-import { ACTOR_TYPES } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType } from '../typed-id.js';
+import { ACTOR_TYPES, ACTOR_FORBIDDEN_INLINE_FIELDS } from './types.js';
+
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const TYPES: readonly string[] = ACTOR_TYPES;
 
 export function validateActor(input: unknown): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  const { record, errors: envErrors } = validateElementEnvelope(input, {
-    notation: 'actor',
-    idType: 'ACTOR',
-    code: 'ACTOR-001',
-  });
-  errors.push(...envErrors);
-  if (!record) return { valid: false, errors, warnings };
-
-  // ACTOR-002 — `type` is required (the identity discriminator) and must be
-  // one of person / business_unit / system. The split with the former UNIT /
-  // EMPLOYEE TYPEs (Actors decision, 2026-05-29; §7.11) hinges on this.
-  if (record.type === undefined || record.type === null) {
-    errors.push({ code: 'ACTOR-002', message: 'type is required (person | business_unit | system).', path: 'type' });
-  } else if (!ACTOR_TYPES.includes(record.type as never)) {
-    errors.push({
-      code: 'ACTOR-002',
-      message: `type "${String(record.type)}" must be one of ${ACTOR_TYPES.join(', ')}.`,
-      path: 'type',
-    });
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'ACTOR-001', message: 'Actor must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const a = input as Record<string, unknown>;
+
+  // ACTOR-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(a.id, 'ACTOR')) {
+    errors.push({ code: 'ACTOR-001', message: `id "${String(a.id)}" must match ACTOR-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (a.notation !== 'actor') {
+    errors.push({ code: 'ACTOR-001', message: 'notation must be the fixed value "actor".', path: 'notation' });
+  }
+  if (a.zone !== undefined && a.zone !== 'canon') {
+    errors.push({ code: 'ACTOR-001', message: 'zone must be "canon" for an ACTOR.', path: 'zone' });
+  } else if (a.zone === undefined) {
+    errors.push({ code: 'ACTOR-001', message: 'zone is required.', path: 'zone' });
+  }
+  for (const field of REQUIRED_STRING_FIELDS) {
+    const v = a[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'ACTOR-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (a.gate_checks === null || typeof a.gate_checks !== 'object') {
+    errors.push({ code: 'ACTOR-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in a) || !(typeof a.valid_to === 'string' || a.valid_to === null)) {
+    errors.push({ code: 'ACTOR-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+  if (typeof a.type !== 'string' || a.type.trim() === '') {
+    errors.push({ code: 'ACTOR-001', message: 'type is required.', path: 'type' });
+  } else if (!TYPES.includes(a.type)) {
+    // ACTOR-002 — type enum.
+    errors.push({ code: 'ACTOR-002', message: `type "${a.type}" must be one of ${TYPES.join(', ')}.`, path: 'type' });
+  }
+
+  // ACTOR-003 — engagement / hierarchy fields belong on REL records, not here.
+  for (const field of ACTOR_FORBIDDEN_INLINE_FIELDS) {
+    if (field in a) {
+      errors.push({
+        code: 'ACTOR-003',
+        message: `${field} is engagement/hierarchy data — it must live in a REL-… record, not inline on the actor.`,
+        path: field,
+      });
+    }
   }
 
   return { valid: errors.length === 0, errors, warnings };