@transitrix/diagrams 1.3.0 → 1.5.0

package/src/fgca/validate.ts

@@ -35,28 +35,20 @@ export function validateFGCADoc(input: unknown): FGCAValidationResult {
     errors.push({ code: 'MISSING_NOTATION', message: 'notation field is required' });
     return { valid: false, errors, warnings };
   }
-  if (raw.notation !== 'fgca' && raw.notation !== 'dgca') {
-    errors.push({ code: 'WRONG_NOTATION', message: `notation must be "dgca" (or legacy "fgca"), got "${String(raw.notation)}"` });
+  if (raw.notation !== 'dgca') {
+    errors.push({ code: 'WRONG_NOTATION', message: `notation must be "dgca", got "${String(raw.notation)}"` });
     return { valid: false, errors, warnings };
   }
-  if (raw.notation === 'fgca') {
-    warnings.push({ code: 'DEPRECATED_NOTATION', message: 'notation "fgca" is deprecated — rename to "dgca"' });
-  }
 
   if (!Array.isArray(raw.factors)) errors.push({ code: 'SCHEMA_INVALID', message: 'factors must be an array', path: 'factors' });
   if (!Array.isArray(raw.goals)) errors.push({ code: 'SCHEMA_INVALID', message: 'goals must be an array', path: 'goals' });
   if (!Array.isArray(raw.changes)) errors.push({ code: 'SCHEMA_INVALID', message: 'changes must be an array', path: 'changes' });
-  // Accept canonical `actions:` or deprecated `activities:`; warn on the latter.
-  const hasActions = Array.isArray(raw.actions);
-  const hasActivities = Array.isArray(raw.activities);
-  if (!hasActions && !hasActivities) {
+  if (!Array.isArray(raw.actions)) {
     errors.push({ code: 'SCHEMA_INVALID', message: 'actions must be an array', path: 'actions' });
-  } else if ('activities' in raw) {
-    warnings.push({ code: 'DEPRECATED_NOTATION', message: '"activities" key is deprecated — rename to "actions"' });
   }
   if (errors.length > 0) return { valid: false, errors, warnings };
 
-  const actionsArr = (hasActions ? raw.actions : raw.activities) as unknown[];
+  const actionsArr = raw.actions as unknown[];
   const doc = raw as unknown as FGCADoc;
   const collectIds = (arr: unknown[]): Set<number | string> => {
     const out = new Set<number | string>();

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./activities/index";
 export * from "./activity-card/index";
 export * from "./actor/index";
+export * from "./business-service/index";
 export * from "./geometry";
 export * from "./applications/index";
 export * from "./assertion/index";
@@ -13,6 +14,9 @@ export * from "./confidence/index";
 export * from "./factor/index";
 export * from "./fgca/index";
 export * from "./goals/index";
+export * from "./integration/index";
+export * from "./location/index";
+export * from "./node/index";
 export * from "./process-blueprint/index";
 export * from "./process-map/index";
 export * from "./products/index";
@@ -21,6 +25,7 @@ export * from "./requirement/index";
 export * from "./scenarios/index";
 export * from "./stakeholder/index";
 export * from "./target-state/index";
+export * from "./technology-service/index";
 export { SCHEMA_VERSION } from "./schema-version";
 export * from "./theme/index";
 export * from "./typed-id";

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

@@ -0,0 +1,203 @@
+import { describe, it, expect } from 'vitest';
+import { validateIntegration } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'integration',
+    id: 'INTEGRATION-OMS-CRM-1',
+    source: 'APPLICATION-OMS-1',
+    target: 'APPLICATION-CRM-1',
+    direction: 'outbound',
+    protocol: 'REST',
+    zone: 'canon',
+    admitted_at: '2026-06-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2024-01-01',
+    valid_to: null,
+  };
+}
+
+function validWithInterface(): Record<string, unknown> {
+  return {
+    ...valid(),
+    id: 'INTEGRATION-OMS-EVENTS-1',
+    interface_semantics: true,
+    payload_class: 'domain_event',
+    sensitivity: 'internal',
+    directionality: 'producer',
+  };
+}
+
+const codes = (input: unknown): string[] =>
+  validateIntegration(input).errors.map(e => e.code);
+
+describe('validateIntegration — positive', () => {
+  it('accepts a well-formed integration without interface_semantics', () => {
+    const r = validateIntegration(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts integration with no optional fields except required ones', () => {
+    const a = valid();
+    delete a.direction;
+    delete a.protocol;
+    expect(validateIntegration(a).valid).toBe(true);
+  });
+
+  it('accepts a valid integration with interface_semantics: true and all required fields', () => {
+    const r = validateIntegration(validWithInterface());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts valid_to as a date string', () => {
+    expect(validateIntegration({ ...valid(), valid_to: '2026-12-31' }).valid).toBe(true);
+  });
+
+  it('accepts interface_semantics: false without requiring conditional fields', () => {
+    expect(validateIntegration({ ...valid(), interface_semantics: false }).valid).toBe(true);
+  });
+
+  it('accepts all four directionality values', () => {
+    for (const d of ['producer', 'consumer', 'request_reply', 'bidirectional_stream']) {
+      expect(validateIntegration({ ...validWithInterface(), directionality: d }).valid).toBe(true);
+    }
+  });
+
+  it('accepts all four sensitivity values', () => {
+    for (const s of ['public', 'internal', 'confidential', 'restricted']) {
+      expect(validateIntegration({ ...validWithInterface(), sensitivity: s }).valid).toBe(true);
+    }
+  });
+});
+
+describe('validateIntegration — INT-001 (shape / id grammar)', () => {
+  it('flags a non-object input', () => {
+    expect(codes(null)).toEqual(['INT-001']);
+    expect(codes('string')).toEqual(['INT-001']);
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'INTEGRATION-001' })).toContain('INT-001');
+    expect(codes({ ...valid(), id: 'INT-1' })).toContain('INT-001');
+    expect(codes({ ...valid(), id: 'integration-oms-1' })).toContain('INT-001');
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'integrations' })).toContain('INT-001');
+    expect(codes({ ...valid(), notation: 'application' })).toContain('INT-001');
+  });
+
+  it('flags a non-canon zone', () => {
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('INT-001');
+  });
+
+  it('flags a missing zone', () => {
+    const a = valid();
+    delete a.zone;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags a missing source', () => {
+    const a = valid();
+    delete a.source;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags a missing target', () => {
+    const a = valid();
+    delete a.target;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags a missing admitted_at', () => {
+    const a = valid();
+    delete a.admitted_at;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags a missing valid_to key', () => {
+    const a = valid();
+    delete a.valid_to;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags missing gate_checks', () => {
+    const a = valid();
+    delete a.gate_checks;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags an invalid direction value', () => {
+    expect(codes({ ...valid(), direction: 'both' })).toContain('INT-001');
+  });
+});
+
+describe('validateIntegration — INT-001 (interface_semantics conditional fields)', () => {
+  it('flags missing protocol when interface_semantics is true', () => {
+    const a = validWithInterface();
+    delete a.protocol;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags missing payload_class when interface_semantics is true', () => {
+    const a = validWithInterface();
+    delete a.payload_class;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags missing sensitivity when interface_semantics is true', () => {
+    const a = validWithInterface();
+    delete a.sensitivity;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags missing directionality when interface_semantics is true', () => {
+    const a = validWithInterface();
+    delete a.directionality;
+    expect(codes(a)).toContain('INT-001');
+  });
+
+  it('flags all four missing at once', () => {
+    const a = valid();
+    a.interface_semantics = true;
+    delete a.protocol;
+    const errs = validateIntegration(a).errors.filter(e => e.code === 'INT-001');
+    expect(errs.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('flags an invalid sensitivity value when interface_semantics is true', () => {
+    expect(codes({ ...validWithInterface(), sensitivity: 'secret' })).toContain('INT-001');
+  });
+
+  it('flags an invalid directionality value when interface_semantics is true', () => {
+    expect(codes({ ...validWithInterface(), directionality: 'both_ways' })).toContain('INT-001');
+  });
+
+  it('does not fire INT-001 conditional checks when interface_semantics is absent', () => {
+    const a = valid();
+    const errs = validateIntegration(a).errors.filter(e => e.code === 'INT-001' && e.path && ['protocol', 'payload_class', 'sensitivity', 'directionality'].includes(e.path));
+    expect(errs).toHaveLength(0);
+  });
+});
+
+describe('validateIntegration — INT-002 (endpoint APPLICATION type)', () => {
+  it('flags a source that is not an APPLICATION-… id when interface_semantics is true', () => {
+    expect(codes({ ...validWithInterface(), source: 'INTEGRATION-OTHER-1' })).toContain('INT-002');
+    expect(codes({ ...validWithInterface(), source: 'ACTOR-SALES-1' })).toContain('INT-002');
+  });
+
+  it('flags a target that is not an APPLICATION-… id when interface_semantics is true', () => {
+    expect(codes({ ...validWithInterface(), target: 'TECHNOLOGY_SERVICE-KAFKA-1' })).toContain('INT-002');
+    expect(codes({ ...validWithInterface(), target: 'NODE-HOST-1' })).toContain('INT-002');
+  });
+
+  it('does not fire INT-002 when interface_semantics is absent', () => {
+    const a = { ...valid(), source: 'ACTOR-OPS-1', target: 'NODE-HOST-1' };
+    expect(codes(a)).not.toContain('INT-002');
+  });
+
+  it('does not fire INT-002 for valid APPLICATION-… endpoints', () => {
+    expect(codes(validWithInterface())).not.toContain('INT-002');
+  });
+});

package/src/integration/index.ts

@@ -0,0 +1,2 @@
+export { validateIntegration } from './validate.js';
+export type { Integration, IntegrationDirectionType, SensitivityValue, DirectionalityValue } from './types.js';

package/src/integration/types.ts

@@ -0,0 +1,38 @@
+// INTEGRATION — application-layer point-to-point exchange (ArchiMate Application Interface).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.8
+
+import type { GateChecks } from '../requirement/types.js';
+
+export const INTEGRATION_DIRECTIONS = ['inbound', 'outbound', 'bidirectional'] as const;
+export type IntegrationDirectionType = typeof INTEGRATION_DIRECTIONS[number];
+
+export const SENSITIVITY_VALUES = ['public', 'internal', 'confidential', 'restricted'] as const;
+export type SensitivityValue = typeof SENSITIVITY_VALUES[number];
+
+export const DIRECTIONALITY_VALUES = ['producer', 'consumer', 'request_reply', 'bidirectional_stream'] as const;
+export type DirectionalityValue = typeof DIRECTIONALITY_VALUES[number];
+
+export interface Integration {
+  notation: 'integration';
+  id: string;
+  name?: string;
+  source: string;
+  target: string;
+  direction?: IntegrationDirectionType;
+  protocol?: string;
+  description?: string;
+  interface_semantics?: boolean;
+  payload_class?: string;
+  sensitivity?: SensitivityValue;
+  directionality?: DirectionalityValue;
+
+  // 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/integration/validate.ts

@@ -0,0 +1,104 @@
+// INTEGRATION validator — methodology notations/ELEMENT_PRIMITIVES.md §7.8.
+//
+// Implements INT-001 (conditional field enforcement when interface_semantics: true)
+// and INT-002 (endpoint APPLICATION type check). The shared HDR-/LIFECYCLE- rules
+// are cross-cutting concerns (CONTRACT.md §8) and out of scope for the
+// single-artefact validator.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType } from '../typed-id.js';
+
+const REQUIRED_STRING_FIELDS = [
+  'source', 'target', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const VALID_DIRECTIONS = new Set(['inbound', 'outbound', 'bidirectional']);
+const VALID_SENSITIVITY = new Set(['public', 'internal', 'confidential', 'restricted']);
+const VALID_DIRECTIONALITY = new Set(['producer', 'consumer', 'request_reply', 'bidirectional_stream']);
+
+const IFACE_CONDITIONAL = ['protocol', 'payload_class', 'sensitivity', 'directionality'] as const;
+
+export function validateIntegration(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'INT-001', message: 'Integration must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const a = input as Record<string, unknown>;
+
+  // Shape — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(a.id, 'INTEGRATION')) {
+    errors.push({ code: 'INT-001', message: `id "${String(a.id)}" must match INTEGRATION-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (a.notation !== 'integration') {
+    errors.push({ code: 'INT-001', message: 'notation must be the fixed value "integration".', path: 'notation' });
+  }
+  if (a.zone !== undefined && a.zone !== 'canon') {
+    errors.push({ code: 'INT-001', message: 'zone must be "canon" for a standalone INTEGRATION.', path: 'zone' });
+  } else if (a.zone === undefined) {
+    errors.push({ code: 'INT-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: 'INT-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (a.gate_checks === null || typeof a.gate_checks !== 'object') {
+    errors.push({ code: 'INT-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: 'INT-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+  if (a.direction !== undefined && !VALID_DIRECTIONS.has(a.direction as string)) {
+    errors.push({ code: 'INT-001', message: `direction "${a.direction}" must be one of inbound, outbound, bidirectional.`, path: 'direction' });
+  }
+
+  // INT-001 — interface_semantics: true triggers conditional field enforcement.
+  if (a.interface_semantics === true) {
+    for (const field of IFACE_CONDITIONAL) {
+      const v = a[field];
+      if (typeof v !== 'string' || v.trim() === '') {
+        errors.push({
+          code: 'INT-001',
+          message: `${field} is required when interface_semantics is true.`,
+          path: field,
+        });
+      }
+    }
+    if (typeof a.sensitivity === 'string' && !VALID_SENSITIVITY.has(a.sensitivity)) {
+      errors.push({
+        code: 'INT-001',
+        message: `sensitivity "${a.sensitivity}" must be one of public, internal, confidential, restricted.`,
+        path: 'sensitivity',
+      });
+    }
+    if (typeof a.directionality === 'string' && !VALID_DIRECTIONALITY.has(a.directionality)) {
+      errors.push({
+        code: 'INT-001',
+        message: `directionality "${a.directionality}" must be one of producer, consumer, request_reply, bidirectional_stream.`,
+        path: 'directionality',
+      });
+    }
+
+    // INT-002 — source and target must be APPLICATION-… IDs.
+    if (typeof a.source === 'string' && a.source.trim() !== '' && !isCanonicalIdOfType(a.source, 'APPLICATION')) {
+      errors.push({
+        code: 'INT-002',
+        message: `source "${a.source}" must be an APPLICATION-… canonical id when interface_semantics is true.`,
+        path: 'source',
+      });
+    }
+    if (typeof a.target === 'string' && a.target.trim() !== '' && !isCanonicalIdOfType(a.target, 'APPLICATION')) {
+      errors.push({
+        code: 'INT-002',
+        message: `target "${a.target}" must be an APPLICATION-… canonical id when interface_semantics is true.`,
+        path: 'target',
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

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

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { validateLocation } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'location',
+    id: 'LOCATION-TBILISI-1',
+    name: 'Tbilisi Office',
+    type: 'office',
+    address: '14 Rustaveli Ave, Tbilisi 0108, Georgia',
+    country_code: 'GE',
+    timezone: 'Asia/Tbilisi',
+    zone: 'canon',
+    admitted_at: '2026-06-28',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2024-01-01',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] =>
+  validateLocation(input).errors.map(e => e.code);
+
+describe('validateLocation — positive', () => {
+  it('accepts a well-formed office location', () => {
+    const r = validateLocation(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts a country with no optional fields', () => {
+    const a = valid();
+    a.id = 'LOCATION-GE-1';
+    a.name = 'Georgia';
+    a.type = 'country';
+    delete a.address;
+    delete a.country_code;
+    delete a.timezone;
+    expect(validateLocation(a).valid).toBe(true);
+  });
+
+  it('accepts a virtual location', () => {
+    const a = valid();
+    a.id = 'LOCATION-VIRTUAL-1';
+    a.name = 'Remote';
+    a.type = 'virtual';
+    expect(validateLocation(a).valid).toBe(true);
+  });
+
+  it('accepts a location with a valid parent reference', () => {
+    expect(validateLocation({ ...valid(), parent: 'LOCATION-GE-1' }).valid).toBe(true);
+  });
+
+  it('accepts valid_to as a date string', () => {
+    expect(validateLocation({ ...valid(), valid_to: '2026-12-31' }).valid).toBe(true);
+  });
+});
+
+describe('validateLocation — LOC-001 (shape / id grammar)', () => {
+  it('flags a missing required envelope field (name)', () => {
+    const a = valid();
+    delete a.name;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'LOCATION-001' })).toContain('LOC-001');
+    expect(codes({ ...valid(), id: 'LOC-1' })).toContain('LOC-001');
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'place' })).toContain('LOC-001');
+  });
+
+  it('flags a non-canon zone', () => {
+    expect(codes({ ...valid(), zone: 'sandbox' })).toContain('LOC-001');
+  });
+
+  it('flags a missing zone', () => {
+    const a = valid();
+    delete a.zone;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags a missing type', () => {
+    const a = valid();
+    delete a.type;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags a missing valid_to key', () => {
+    const a = valid();
+    delete a.valid_to;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('flags missing gate_checks', () => {
+    const a = valid();
+    delete a.gate_checks;
+    expect(codes(a)).toContain('LOC-001');
+  });
+
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['LOC-001']);
+  });
+});
+
+describe('validateLocation — LOC-002 (type enum)', () => {
+  it('flags a type outside the allowed enum', () => {
+    expect(codes({ ...valid(), type: 'building' })).toContain('LOC-002');
+    expect(codes({ ...valid(), type: 'facility' })).toContain('LOC-002');
+  });
+});
+
+describe('validateLocation — LOC-003 (parent grammar)', () => {
+  it('flags a parent that is not a LOCATION-… id', () => {
+    expect(codes({ ...valid(), parent: 'ACTOR-OPS-1' })).toContain('LOC-003');
+    expect(codes({ ...valid(), parent: 'not-an-id' })).toContain('LOC-003');
+  });
+
+  it('accepts a null or absent parent without error', () => {
+    expect(codes({ ...valid(), parent: undefined })).not.toContain('LOC-003');
+    const a = valid();
+    delete a.parent;
+    expect(codes(a)).not.toContain('LOC-003');
+  });
+});

package/src/location/index.ts

@@ -0,0 +1,3 @@
+export type { Location, LocationType } from './types.js';
+export { LOCATION_TYPES } from './types.js';
+export { validateLocation } from './validate.js';

package/src/location/types.ts

@@ -0,0 +1,29 @@
+// LOCATION — physical and virtual place primitive (ArchiMate Location/Facility).
+// Schema: methodology notations/elements/21-locations.md
+
+import type { GateChecks } from '../requirement/types.js';
+
+export const LOCATION_TYPES = ['country', 'region', 'city', 'site', 'office', 'virtual'] as const;
+export type LocationType = typeof LOCATION_TYPES[number];
+
+export interface Location {
+  notation: 'location';
+  id: string;
+  name: string;
+  type: LocationType;
+  address?: string;
+  country_code?: string;
+  timezone?: string;
+  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/location/validate.ts

@@ -0,0 +1,70 @@
+// LOCATION validator — methodology notations/elements/21-locations.md §6.
+//
+// Implements LOC-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, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType, typeOfId } from '../typed-id.js';
+import { LOCATION_TYPES } from './types.js';
+
+const REQUIRED_STRING_FIELDS = [
+  'name', 'admitted_at', 'admitted_by', 'valid_from',
+] as const;
+
+const TYPES: readonly string[] = LOCATION_TYPES;
+
+export function validateLocation(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'LOC-001', message: 'Location must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const a = input as Record<string, unknown>;
+
+  // LOC-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(a.id, 'LOCATION')) {
+    errors.push({ code: 'LOC-001', message: `id "${String(a.id)}" must match LOCATION-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (a.notation !== 'location') {
+    errors.push({ code: 'LOC-001', message: 'notation must be the fixed value "location".', path: 'notation' });
+  }
+  if (a.zone !== undefined && a.zone !== 'canon') {
+    errors.push({ code: 'LOC-001', message: 'zone must be "canon" for a LOCATION.', path: 'zone' });
+  } else if (a.zone === undefined) {
+    errors.push({ code: 'LOC-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: 'LOC-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (a.gate_checks === null || typeof a.gate_checks !== 'object') {
+    errors.push({ code: 'LOC-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: 'LOC-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: 'LOC-001', message: 'type is required.', path: 'type' });
+  } else if (!TYPES.includes(a.type)) {
+    // LOC-002 — type enum.
+    errors.push({ code: 'LOC-002', message: `type "${a.type}" must be one of ${TYPES.join(', ')}.`, path: 'type' });
+  }
+
+  // LOC-003 — parent must resolve to a LOCATION when present.
+  if ('parent' in a && a.parent !== undefined && a.parent !== null) {
+    if (typeof a.parent !== 'string' || !isCanonicalIdOfType(a.parent, 'LOCATION')) {
+      errors.push({
+        code: 'LOC-003',
+        message: `parent "${String(a.parent)}" must be a canonical LOCATION-… id.`,
+        path: 'parent',
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}