@transitrix/diagrams 1.2.0 → 1.4.0

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

@@ -2,11 +2,11 @@ import { describe, it, expect } from 'vitest';
 import { validateFGCADoc } from '../validate.js';
 
 const VALID_DOC = {
-  notation: 'fgca',
+  notation: 'dgca',
   factors: [{ id: 1, name: 'Market pressure' }],
   goals: [{ id: 1, name: 'Grow revenue', factor: [{ id: 1 }] }],
   changes: [{ id: 1, name: 'Launch product', goal_id: 1, activity_ids: [1] }],
-  activities: [{ id: 1, name: 'Market research', goal_id: 1 }],
+  actions: [{ id: 1, name: 'Market research', goal_id: 1 }],
 };
 
 describe('validateFGCADoc', () => {
@@ -37,28 +37,28 @@ describe('validateFGCADoc', () => {
 
   it('errors when factors array is missing', () => {
     const { factors: _, ...without } = VALID_DOC;
-    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    const result = validateFGCADoc({ ...without, notation: 'dgca' });
     expect(result.valid).toBe(false);
     expect(result.errors.some(e => e.path === 'factors')).toBe(true);
   });
 
   it('errors when goals array is missing', () => {
     const { goals: _, ...without } = VALID_DOC;
-    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    const result = validateFGCADoc({ ...without, notation: 'dgca' });
     expect(result.valid).toBe(false);
     expect(result.errors.some(e => e.path === 'goals')).toBe(true);
   });
 
   it('errors when changes array is missing', () => {
     const { changes: _, ...without } = VALID_DOC;
-    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    const result = validateFGCADoc({ ...without, notation: 'dgca' });
     expect(result.valid).toBe(false);
     expect(result.errors.some(e => e.path === 'changes')).toBe(true);
   });
 
   it('errors when actions array is missing', () => {
-    const { activities: _, ...without } = VALID_DOC;
-    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    const { actions: _, ...without } = VALID_DOC;
+    const result = validateFGCADoc({ ...without, notation: 'dgca' });
     expect(result.valid).toBe(false);
     expect(result.errors.some(e => e.path === 'actions')).toBe(true);
   });
@@ -104,11 +104,11 @@ describe('validateFGCADoc', () => {
 
   it('accepts a document with empty arrays', () => {
     const result = validateFGCADoc({
-      notation: 'fgca',
+      notation: 'dgca',
       factors: [],
       goals: [],
       changes: [],
-      activities: [],
+      actions: [],
     });
     expect(result.valid).toBe(true);
   });
@@ -134,8 +134,8 @@ describe('validateFGCADoc', () => {
     expect(r.valid).toBe(false);
     expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
   });
-  it('[blocker] tolerates a null element in activities[] without throwing', () => {
-    const r = validateFGCADoc({ ...VALID_DOC, activities: [null] });
+  it('[blocker] tolerates a null element in actions[] without throwing', () => {
+    const r = validateFGCADoc({ ...VALID_DOC, actions: [null] });
     expect(r.valid).toBe(false);
     expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
   });

package/src/fgca/parse-canonical.ts

@@ -63,10 +63,6 @@ function asObjectArray(v: unknown): Array<Record<string, unknown>> | null {
   return v.map((el) => (el && typeof el === 'object' ? (el as Record<string, unknown>) : null) as Record<string, unknown>);
 }
 
-interface InternalIdMap {
-  /** Canonical typed-string ID → internal numeric ID for layout consumption. */
-  toInternal: Map<string, number>;
-}
 
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
@@ -86,21 +82,18 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
 
   const raw = input as Record<string, unknown>;
 
-  if ('notation' in raw && raw['notation'] !== 'fgca' && raw['notation'] !== 'dgca') {
+  if ('notation' in raw && raw['notation'] !== 'dgca') {
     return {
       valid: false,
       errors: [
         {
           code: 'FGCA-001',
-          message: `notation must be "dgca" (or legacy "fgca"), got "${String(raw['notation'])}"`,
+          message: `notation must be "dgca", got "${String(raw['notation'])}"`,
         },
       ],
       warnings,
     };
   }
-  if ('notation' in raw && raw['notation'] === 'fgca') {
-    warnings.push({ code: 'FGCA-001', message: 'notation "fgca" is deprecated — rename to "dgca"' });
-  }
 
   // FGCA-002 — document id (optional in v1.4 per the canonical spec? — spec
   // says required; absence is FGCA-002).
@@ -122,10 +115,9 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   const factorsRaw = asObjectArray(raw['factors']);
   const goalsRaw = asObjectArray(raw['goals']);
   const changesRaw = asObjectArray(raw['changes']);
-  // Accept canonical `actions:` or deprecated `activities:`; warn on the latter.
-  const activitiesRaw = asObjectArray(raw['actions']) ?? asObjectArray(raw['activities']);
-  if ('activities' in raw && !('actions' in raw)) {
-    warnings.push({ code: 'FGCA-001', message: '"activities" key is deprecated — rename to "actions"' });
+  const activitiesRaw = asObjectArray(raw['actions']);
+  if (activitiesRaw === null && 'activities' in raw) {
+    errors.push({ code: 'FGCA-004', message: '"activities" key is not accepted — rename to "actions"', path: 'actions' });
   }
 
   if (factorsRaw === null) errors.push({ code: 'FGCA-004', message: 'factors must be an array', path: 'factors' });
@@ -223,32 +215,20 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     return out;
   }
 
-  // Build internal id-maps (canonical string ID → internal sequential number).
-  const idMap: InternalIdMap = { toInternal: new Map() };
-  const allCanonicalIds = [...factorIds, ...goalIds, ...changeIds, ...activityIds];
-  allCanonicalIds.forEach((id, i) => idMap.toInternal.set(id, i + 1));
-
-  function intId(canonical: string): number {
-    const n = idMap.toInternal.get(canonical);
-    if (n === undefined) {
-      // Shouldn't happen — we built the map from the same sets.
-      throw new Error(`internal: canonical id "${canonical}" not mapped`);
-    }
-    return n;
-  }
-
-  // Layer entries (internal form).
+  // Layer entries (internal form). Canonical string IDs are passed through
+  // directly — no conversion to sequential numbers. The layout and renderer
+  // treat IDs as opaque keys and also display them verbatim to the user.
   const internalFactors: DriverItem[] = factors.map((el) => ({
-    id: intId(String(el!['id'])),
+    id: String(el!['id']),
     name: String(el!['name'] ?? ''),
   }));
 
   const internalGoals: GoalItem[] = goals.map((el, i) => {
     const refIds = checkRefArray(el!, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`);
     return {
-      id: intId(String(el!['id'])),
+      id: String(el!['id']),
       name: String(el!['name'] ?? ''),
-      factor: refIds.map((r) => ({ id: intId(r) })),
+      factor: refIds.map((r) => ({ id: r })),
     };
   });
 
@@ -284,10 +264,10 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     const canonicalChangeId = String(el!['id']);
     const linkedActivityIds = activitiesForChange.get(canonicalChangeId) ?? [];
     return {
-      id: intId(canonicalChangeId),
+      id: canonicalChangeId,
       name: String(el!['name'] ?? ''),
-      goal_id: goalRefs.length > 0 ? intId(goalRefs[0]) : 0,
-      activity_ids: linkedActivityIds.map((aid) => intId(aid)),
+      goal_id: goalRefs.length > 0 ? goalRefs[0] : '',
+      activity_ids: linkedActivityIds,
     };
   });
 
@@ -295,9 +275,9 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`);
     const typeVal = typeof el!['type'] === 'string' ? el!['type'] : undefined;
     return {
-      id: intId(String(el!['id'])),
+      id: String(el!['id']),
       name: String(el!['name'] ?? ''),
-      goal_id: goalRefs.length > 0 ? intId(goalRefs[0]) : null,
+      goal_id: goalRefs.length > 0 ? goalRefs[0] : null,
       ...(typeVal !== undefined ? { type: typeVal } : {}),
     };
   });
@@ -364,10 +344,10 @@ export function parseCanonicalFGA(input: unknown): CanonicalFGAResult {
     return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
   }
   const raw = input as Record<string, unknown>;
-  if ('notation' in raw && raw['notation'] !== 'fga' && raw['notation'] !== 'dga') {
+  if ('notation' in raw && raw['notation'] !== 'dga') {
     return {
       valid: false,
-      errors: [{ code: 'FGA-001', message: `notation must be "dga" (or legacy "fga"), got "${String(raw['notation'])}"` }],
+      errors: [{ code: 'FGA-001', message: `notation must be "dga", got "${String(raw['notation'])}"` }],
       warnings: [],
     };
   }

package/src/fgca/preview-layout.ts

@@ -154,19 +154,71 @@ export function layoutFGCAPreview(
     activity: doc.activities.map(a => ({ id: `activity_${a.id}`, label: a.name })),
   };
 
+  // Build predecessor map: for each node, which node IDs in the previous column
+  // connect to it from the left. Used for barycenter crossing minimization.
+  const predecessors = new Map<string, string[]>();
+  for (const g of doc.goals) {
+    predecessors.set(`goal_${g.id}`, (g.factor ?? []).map(f => `driver_${f.id}`));
+  }
+  if (!hideChanges) {
+    for (const c of changes) {
+      predecessors.set(`change_${c.id}`, [`goal_${c.goal_id}`]);
+    }
+    const coveredActs = new Set(changes.flatMap(c => c.activity_ids.map(String)));
+    for (const a of doc.activities) {
+      const preds = changes
+        .filter(c => c.activity_ids.map(String).includes(String(a.id)))
+        .map(c => `change_${c.id}`);
+      if (a.goal_id != null && !coveredActs.has(String(a.id))) preds.push(`goal_${a.goal_id}`);
+      predecessors.set(`activity_${a.id}`, preds);
+    }
+  } else {
+    const connectedViaChange = new Set<string>();
+    for (const c of changes) {
+      for (const aid of c.activity_ids) {
+        predecessors.set(`activity_${aid}`, [`goal_${c.goal_id}`]);
+        connectedViaChange.add(String(aid));
+      }
+    }
+    for (const a of doc.activities) {
+      if (a.goal_id != null && !connectedViaChange.has(String(a.id))) {
+        predecessors.set(`activity_${a.id}`, [`goal_${a.goal_id}`]);
+      }
+    }
+  }
+
+  // Sort a column's items by the barycenter of their predecessors' y-centres.
+  // Nodes with no predecessors sort last (Infinity barycenter) so they don't
+  // displace connected nodes.
+  function barycentricSort(
+    items: Array<{ id: string; label: string }>,
+    yCenters: Map<string, number>,
+  ): Array<{ id: string; label: string }> {
+    return [...items].sort((a, b) => {
+      const pA = (predecessors.get(a.id) ?? []).map(p => yCenters.get(p) ?? 0).filter(v => v > 0);
+      const pB = (predecessors.get(b.id) ?? []).map(p => yCenters.get(p) ?? 0).filter(v => v > 0);
+      const bcA = pA.length > 0 ? pA.reduce((s, v) => s + v, 0) / pA.length : Infinity;
+      const bcB = pB.length > 0 ? pB.reduce((s, v) => s + v, 0) / pB.length : Infinity;
+      return bcA - bcB;
+    });
+  }
+
   const nodeMap = new Map<string, FGCAPreviewNode>();
   const nodes: FGCAPreviewNode[] = [];
   const columns: FGCAPreviewColumnPos[] = [];
+  const yCenters = new Map<string, number>(); // nodeId → y + FGCA_NODE_H / 2
 
   for (let ci = 0; ci < cols.length; ci++) {
     const col = cols[ci];
     const x = FGCA_PAD + ci * colStride;
     columns.push({ col, x });
+    const items = ci === 0 ? colItems[col] : barycentricSort(colItems[col], yCenters);
     let y = FGCA_PAD + FGCA_HEADER_H + rowGap;
-    for (const item of colItems[col]) {
+    for (const item of items) {
       const node: FGCAPreviewNode = { id: item.id, x, y, label: item.label, col };
       nodes.push(node);
       nodeMap.set(item.id, node);
+      yCenters.set(item.id, y + FGCA_NODE_H / 2);
       y += FGCA_NODE_H + rowGap;
     }
   }

package/src/fgca/resolver.ts

@@ -3,7 +3,7 @@
  * view_config projection and a canon element/relation store (VP-3).
  *
  * Output shape matches the flat form that `parseCanonicalFGCA` expects:
- * top-level `factors[]`, `goals[]`, `changes[]`, `activities[]` with typed
+ * top-level `factors[]`, `goals[]`, `changes[]`, `actions[]` with typed
  * string IDs.  Filesystem-free — callable from unit tests without vscode.
  */
 
@@ -69,7 +69,7 @@ export function isFGCAViewDoc(parsed: unknown): boolean {
  * to pass to `parseCanonicalFGCA`.
  *
  * Cross-reference fields (`goal.factors[]`, `change.goals[]`,
- * `activity.changes[]`) are carried from the canon elements unchanged; the
+ * `action.changes[]`) are carried from the canon elements unchanged; the
  * resolver decides which elements to include, not how they are shaped.
  */
 export function resolveFGCA(
@@ -77,7 +77,7 @@ export function resolveFGCA(
   sources: FGCACanonSources,
 ): Record<string, unknown> {
   if (!isObject(viewDoc)) {
-    return { notation: 'fgca', factors: [], goals: [], changes: [], activities: [] };
+    return { notation: 'dgca', factors: [], goals: [], changes: [], actions: [] };
   }
 
   const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
@@ -147,13 +147,13 @@ export function resolveFGCA(
   }
 
   return {
-    notation: 'fgca',
+    notation: 'dgca',
     id: viewDoc['id'],
     name: viewDoc['name'],
     spec_version: viewDoc['spec_version'],
     factors: selectedFactors,
     goals: selectedGoals,
     changes: selectedChanges,
-    activities: selectedActivities,
+    actions: selectedActivities,
   };
 }

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;
+}