@transitrix/diagrams 1.0.0 → 1.0.1

package/src/scenarios/validate.ts

@@ -1,122 +1,122 @@
-import type { ScenarioStatus, FactorRelevance } from './types.js';
-import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
-
-export type { ValidationError, ValidationWarning, ValidationResult };
-
-const VALID_STATUSES = new Set<ScenarioStatus>(['Draft', 'Active', 'Archived']);
-const VALID_RELEVANCE = new Set<FactorRelevance>(['High', 'Medium', 'Low']);
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-
-interface RefSpec {
-  field: string;
-  idField: string;
-  errorCode: string;
-}
-
-const REF_SPECS: RefSpec[] = [
-  { field: 'goals',        idField: 'goal_id',       errorCode: 'SCN-007' },
-  { field: 'capabilities', idField: 'capability_id', errorCode: 'SCN-008' },
-  { field: 'activities',   idField: 'activity_id',   errorCode: 'SCN-009' },
-  { field: 'products',     idField: 'product_id',    errorCode: 'SCN-010' },
-  { field: 'processes',    idField: 'process_id',    errorCode: 'SCN-011' },
-  { field: 'applications', idField: 'app_id',        errorCode: 'SCN-012' },
-];
-
-export function validateScenario(input: unknown): ValidationResult {
-  const errors: ValidationError[] = [];
-  const warnings: ValidationWarning[] = [];
-
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'SCN-001', message: 'Input must be an object' }], warnings };
-  }
-  const raw = input as Record<string, unknown>;
-
-  if (!('notation' in raw)) {
-    errors.push({ code: 'SCN-001', message: 'Missing required field: notation' });
-  } else if (raw['notation'] !== 'scenarios') {
-    errors.push({ code: 'SCN-001', message: `notation must be "scenarios", got "${raw['notation']}"` });
-  }
-  if (errors.length > 0) return { valid: false, errors, warnings };
-
-  const scn = raw['scenario'];
-  if (!scn || typeof scn !== 'object') {
-    errors.push({ code: 'SCN-002', message: 'Missing required field: scenario' });
-    return { valid: false, errors, warnings };
-  }
-  const s = scn as Record<string, unknown>;
-
-  if (!s['id'] || typeof s['id'] !== 'string' || !(s['id'] as string).trim())
-    errors.push({ code: 'SCN-002', message: 'scenario.id is required' });
-  if (!s['name'] || typeof s['name'] !== 'string' || !(s['name'] as string).trim())
-    errors.push({ code: 'SCN-002', message: 'scenario.name is required' });
-  if (!s['status']) {
-    errors.push({ code: 'SCN-002', message: 'scenario.status is required' });
-  } else if (!VALID_STATUSES.has(s['status'] as ScenarioStatus)) {
-    errors.push({ code: 'SCN-003', message: `scenario.status "${s['status']}" must be one of: Draft, Active, Archived` });
-  }
-
-  if (errors.length > 0) return { valid: false, errors, warnings };
-
-  if (s['created_at'] !== undefined) {
-    if (typeof s['created_at'] !== 'string' || !DATE_RE.test(s['created_at'] as string)) {
-      errors.push({ code: 'SCN-004', message: `scenario.created_at must be YYYY-MM-DD, got "${s['created_at']}"` });
-    }
-  }
-
-  if (s['factors_view'] !== undefined) {
-    if (!Array.isArray(s['factors_view'])) {
-      errors.push({ code: 'SCN-005', message: 'scenario.factors_view must be an array' });
-    } else {
-      const seen = new Set<string>();
-      const fv = s['factors_view'] as unknown[];
-      for (let i = 0; i < fv.length; i++) {
-        const rawFactor = fv[i];
-        const idx = `factors_view[${i}]`;
-        if (!rawFactor || typeof rawFactor !== 'object') {
-          errors.push({ code: 'SCN-005', message: `${idx} must be an object` });
-          continue;
-        }
-        const f = rawFactor as Record<string, unknown>;
-        if (!f['factor_id'] || typeof f['factor_id'] !== 'string' || !(f['factor_id'] as string).trim()) {
-          errors.push({ code: 'SCN-005', message: `${idx}: factor_id is required` });
-        } else {
-          const fid = f['factor_id'] as string;
-          if (seen.has(fid)) errors.push({ code: 'SCN-013', message: `Duplicate factor_id: "${fid}"` });
-          seen.add(fid);
-        }
-        if (f['relevance'] !== undefined && !VALID_RELEVANCE.has(f['relevance'] as FactorRelevance)) {
-          errors.push({ code: 'SCN-006', message: `${idx}: relevance "${f['relevance']}" must be one of: High, Medium, Low` });
-        }
-      }
-    }
-  }
-
-  for (const spec of REF_SPECS) {
-    const list = s[spec.field];
-    if (list === undefined) continue;
-    if (!Array.isArray(list)) {
-      errors.push({ code: spec.errorCode, message: `scenario.${spec.field} must be an array` });
-      continue;
-    }
-    const seen = new Set<string>();
-    for (let i = 0; i < list.length; i++) {
-      const rawItem = list[i];
-      const idx = `${spec.field}[${i}]`;
-      if (!rawItem || typeof rawItem !== 'object') {
-        errors.push({ code: spec.errorCode, message: `${idx} must be an object` });
-        continue;
-      }
-      const item = rawItem as Record<string, unknown>;
-      const id = item[spec.idField];
-      if (!id || typeof id !== 'string' || !(id as string).trim()) {
-        errors.push({ code: spec.errorCode, message: `${idx}: ${spec.idField} is required` });
-      } else {
-        const sid = id as string;
-        if (seen.has(sid)) errors.push({ code: spec.errorCode, message: `${idx}: duplicate ${spec.idField} "${sid}"` });
-        seen.add(sid);
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
+import type { ScenarioStatus, FactorRelevance } from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+export type { ValidationError, ValidationWarning, ValidationResult };
+
+const VALID_STATUSES = new Set<ScenarioStatus>(['Draft', 'Active', 'Archived']);
+const VALID_RELEVANCE = new Set<FactorRelevance>(['High', 'Medium', 'Low']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+interface RefSpec {
+  field: string;
+  idField: string;
+  errorCode: string;
+}
+
+const REF_SPECS: RefSpec[] = [
+  { field: 'goals',        idField: 'goal_id',       errorCode: 'SCN-007' },
+  { field: 'capabilities', idField: 'capability_id', errorCode: 'SCN-008' },
+  { field: 'activities',   idField: 'activity_id',   errorCode: 'SCN-009' },
+  { field: 'products',     idField: 'product_id',    errorCode: 'SCN-010' },
+  { field: 'processes',    idField: 'process_id',    errorCode: 'SCN-011' },
+  { field: 'applications', idField: 'app_id',        errorCode: 'SCN-012' },
+];
+
+export function validateScenario(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'SCN-001', message: 'Input must be an object' }], warnings };
+  }
+  const raw = input as Record<string, unknown>;
+
+  if (!('notation' in raw)) {
+    errors.push({ code: 'SCN-001', message: 'Missing required field: notation' });
+  } else if (raw['notation'] !== 'scenarios') {
+    errors.push({ code: 'SCN-001', message: `notation must be "scenarios", got "${raw['notation']}"` });
+  }
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const scn = raw['scenario'];
+  if (!scn || typeof scn !== 'object') {
+    errors.push({ code: 'SCN-002', message: 'Missing required field: scenario' });
+    return { valid: false, errors, warnings };
+  }
+  const s = scn as Record<string, unknown>;
+
+  if (!s['id'] || typeof s['id'] !== 'string' || !(s['id'] as string).trim())
+    errors.push({ code: 'SCN-002', message: 'scenario.id is required' });
+  if (!s['name'] || typeof s['name'] !== 'string' || !(s['name'] as string).trim())
+    errors.push({ code: 'SCN-002', message: 'scenario.name is required' });
+  if (!s['status']) {
+    errors.push({ code: 'SCN-002', message: 'scenario.status is required' });
+  } else if (!VALID_STATUSES.has(s['status'] as ScenarioStatus)) {
+    errors.push({ code: 'SCN-003', message: `scenario.status "${s['status']}" must be one of: Draft, Active, Archived` });
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  if (s['created_at'] !== undefined) {
+    if (typeof s['created_at'] !== 'string' || !DATE_RE.test(s['created_at'] as string)) {
+      errors.push({ code: 'SCN-004', message: `scenario.created_at must be YYYY-MM-DD, got "${s['created_at']}"` });
+    }
+  }
+
+  if (s['factors_view'] !== undefined) {
+    if (!Array.isArray(s['factors_view'])) {
+      errors.push({ code: 'SCN-005', message: 'scenario.factors_view must be an array' });
+    } else {
+      const seen = new Set<string>();
+      const fv = s['factors_view'] as unknown[];
+      for (let i = 0; i < fv.length; i++) {
+        const rawFactor = fv[i];
+        const idx = `factors_view[${i}]`;
+        if (!rawFactor || typeof rawFactor !== 'object') {
+          errors.push({ code: 'SCN-005', message: `${idx} must be an object` });
+          continue;
+        }
+        const f = rawFactor as Record<string, unknown>;
+        if (!f['factor_id'] || typeof f['factor_id'] !== 'string' || !(f['factor_id'] as string).trim()) {
+          errors.push({ code: 'SCN-005', message: `${idx}: factor_id is required` });
+        } else {
+          const fid = f['factor_id'] as string;
+          if (seen.has(fid)) errors.push({ code: 'SCN-013', message: `Duplicate factor_id: "${fid}"` });
+          seen.add(fid);
+        }
+        if (f['relevance'] !== undefined && !VALID_RELEVANCE.has(f['relevance'] as FactorRelevance)) {
+          errors.push({ code: 'SCN-006', message: `${idx}: relevance "${f['relevance']}" must be one of: High, Medium, Low` });
+        }
+      }
+    }
+  }
+
+  for (const spec of REF_SPECS) {
+    const list = s[spec.field];
+    if (list === undefined) continue;
+    if (!Array.isArray(list)) {
+      errors.push({ code: spec.errorCode, message: `scenario.${spec.field} must be an array` });
+      continue;
+    }
+    const seen = new Set<string>();
+    for (let i = 0; i < list.length; i++) {
+      const rawItem = list[i];
+      const idx = `${spec.field}[${i}]`;
+      if (!rawItem || typeof rawItem !== 'object') {
+        errors.push({ code: spec.errorCode, message: `${idx} must be an object` });
+        continue;
+      }
+      const item = rawItem as Record<string, unknown>;
+      const id = item[spec.idField];
+      if (!id || typeof id !== 'string' || !(id as string).trim()) {
+        errors.push({ code: spec.errorCode, message: `${idx}: ${spec.idField} is required` });
+      } else {
+        const sid = id as string;
+        if (seen.has(sid)) errors.push({ code: spec.errorCode, message: `${idx}: duplicate ${spec.idField} "${sid}"` });
+        seen.add(sid);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/schema-version.ts

@@ -1,16 +1,16 @@
-/**
- * SCHEMA_VERSION — the methodology release whose notation schemas and validation
- * rules this `@transitrix/diagrams` build conforms to (SV-1).
- *
- * Source of truth: the methodology `methodology_version`, declared in an adopter
- * repository's `transitrix.yaml` per the methodology `notations/MANIFEST.md`
- * (single source of truth for a repo's conformance). The current methodology
- * release is **0.5.0**.
- *
- * This constant is kept in lockstep with the project manifest's
- * `transitrix.methodologyVersion` (`package.json`); the
- * `tests/schema-version.test.ts` unit test asserts the two are equal. A CI guard
- * that additionally asserts both equal the methodology's published SoT lands
- * separately (SV-1 PR2) — do not bundle it here.
- */
-export const SCHEMA_VERSION = '0.5.0';
+/**
+ * SCHEMA_VERSION — the methodology release whose notation schemas and validation
+ * rules this `@transitrix/diagrams` build conforms to (SV-1).
+ *
+ * Source of truth: the methodology `methodology_version`, declared in an adopter
+ * repository's `transitrix.yaml` per the methodology `notations/MANIFEST.md`
+ * (single source of truth for a repo's conformance). The current methodology
+ * release is **0.5.0**.
+ *
+ * This constant is kept in lockstep with the project manifest's
+ * `transitrix.methodologyVersion` (`package.json`); the
+ * `tests/schema-version.test.ts` unit test asserts the two are equal. A CI guard
+ * that additionally asserts both equal the methodology's published SoT lands
+ * separately (SV-1 PR2) — do not bundle it here.
+ */
+export const SCHEMA_VERSION = '0.5.0';

package/src/scope.ts

@@ -1,46 +1,46 @@
-// Scope filtering for hierarchical / relational previews (Goals, FGA, FGCA).
-//
-// A `Scope` trims what a preview renders to part of the hierarchy:
-//   - 'all'   → everything (default, today's behaviour)
-//   - 'level' → only goals at or below a level cap, plus the factors /
-//               changes / activities that touch a visible goal
-//   - 'root'  → only a chosen goal's subtree (Goals: descendants via
-//               parent_id; FGA/FGCA goals are flat, so the subtree is the
-//               single root goal), plus its connected factors / changes /
-//               activities
-//
-// This is intentionally a small, pure rendering primitive: a role's view in
-// a future access-control layer (DSM) can be expressed as a level cap or a
-// subtree root and reuse exactly this filter. No RBAC here — just the filter.
-
-import type { ValidationWarning } from './validation-types.js';
-
-export type Scope =
-  | { mode: 'all' }
-  | { mode: 'level'; maxLevel: number }
-  | { mode: 'root'; rootGoalId: string };
-
-/** Default scope — render everything. */
-export const SCOPE_ALL: Scope = { mode: 'all' };
-
-/** Warning code emitted when a root-mode scope names a goal that isn't in the document. */
-export const SCOPE_MISSING_ROOT_CODE = 'SCOPE-001';
-
-/**
- * Returns the SCOPE-001 warning when `scope` is root-mode and `rootGoalId` is
- * not among the document's goal ids; otherwise null. Goal ids are compared as
- * strings so numeric (FGCA/Goals) and string ids both work.
- *
- * Previews call this to surface the warning in their panel — the layout
- * functions independently return an empty layout in the same situation.
- */
-export function checkScopeRoot(scope: Scope, goalIds: Iterable<string | number>): ValidationWarning | null {
-  if (scope.mode !== 'root') return null;
-  for (const id of goalIds) {
-    if (String(id) === scope.rootGoalId) return null;
-  }
-  return {
-    code: SCOPE_MISSING_ROOT_CODE,
-    message: `Scope root goal "${scope.rootGoalId}" was not found in this document — nothing to show. Clear the scope or pick a goal that exists.`,
-  };
-}
+// Scope filtering for hierarchical / relational previews (Goals, FGA, FGCA).
+//
+// A `Scope` trims what a preview renders to part of the hierarchy:
+//   - 'all'   → everything (default, today's behaviour)
+//   - 'level' → only goals at or below a level cap, plus the factors /
+//               changes / activities that touch a visible goal
+//   - 'root'  → only a chosen goal's subtree (Goals: descendants via
+//               parent_id; FGA/FGCA goals are flat, so the subtree is the
+//               single root goal), plus its connected factors / changes /
+//               activities
+//
+// This is intentionally a small, pure rendering primitive: a role's view in
+// a future access-control layer (DSM) can be expressed as a level cap or a
+// subtree root and reuse exactly this filter. No RBAC here — just the filter.
+
+import type { ValidationWarning } from './validation-types.js';
+
+export type Scope =
+  | { mode: 'all' }
+  | { mode: 'level'; maxLevel: number }
+  | { mode: 'root'; rootGoalId: string };
+
+/** Default scope — render everything. */
+export const SCOPE_ALL: Scope = { mode: 'all' };
+
+/** Warning code emitted when a root-mode scope names a goal that isn't in the document. */
+export const SCOPE_MISSING_ROOT_CODE = 'SCOPE-001';
+
+/**
+ * Returns the SCOPE-001 warning when `scope` is root-mode and `rootGoalId` is
+ * not among the document's goal ids; otherwise null. Goal ids are compared as
+ * strings so numeric (FGCA/Goals) and string ids both work.
+ *
+ * Previews call this to surface the warning in their panel — the layout
+ * functions independently return an empty layout in the same situation.
+ */
+export function checkScopeRoot(scope: Scope, goalIds: Iterable<string | number>): ValidationWarning | null {
+  if (scope.mode !== 'root') return null;
+  for (const id of goalIds) {
+    if (String(id) === scope.rootGoalId) return null;
+  }
+  return {
+    code: SCOPE_MISSING_ROOT_CODE,
+    message: `Scope root goal "${scope.rootGoalId}" was not found in this document — nothing to show. Clear the scope or pick a goal that exists.`,
+  };
+}

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

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { validateStakeholder } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
 
 function valid(): Record<string, unknown> {
   return {
@@ -8,7 +9,7 @@ function valid(): Record<string, unknown> {
     name: 'Data Protection Authority',
     type: 'external',
     actor: 'ACTOR-DPA-1',
-    concern: 'Lawful processing and timely erasure of EU customer personal data.',
+    concern: 'Lawful processing and timely erasure of personal data.',
     interest: 'high',
     influence: 'high',
     description: 'External oversight stakeholder.',
@@ -21,81 +22,84 @@ function valid(): Record<string, unknown> {
   };
 }
 
-const codes = (input: unknown): string[] => validateStakeholder(input).errors.map(e => e.code);
+const codes = (input: unknown, opts?: Parameters<typeof validateStakeholder>[1]): string[] =>
+  validateStakeholder(input, opts).errors.map(e => e.code);
 
 describe('validateStakeholder — positive', () => {
-  it('accepts the worked-example STAKEHOLDER-DPA-1', () => {
+  it('accepts a well-formed external stakeholder', () => {
     const r = validateStakeholder(valid());
     expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-    expect(r.errors).toHaveLength(0);
   });
 
-  it('accepts a minimal stakeholder (no concern / interest / influence)', () => {
-    const r = valid();
-    delete r.concern;
-    delete r.interest;
-    delete r.influence;
-    expect(validateStakeholder(r).valid).toBe(true);
+  it('accepts a minimal internal stakeholder with no optional profile fields', () => {
+    const s = valid();
+    s.id = 'STAKEHOLDER-OPS-1';
+    s.name = 'Operations';
+    s.type = 'internal';
+    s.actor = 'ACTOR-OPS-1';
+    delete s.concern;
+    delete s.interest;
+    delete s.influence;
+    delete s.description;
+    expect(validateStakeholder(s).valid).toBe(true);
   });
-});
 
-describe('validateStakeholder — STAKEHOLDER-001 (envelope / shape)', () => {
-  it('flags a non-object', () => {
-    expect(codes(null)).toEqual(['STAKEHOLDER-001']);
+  it('accepts when the catalog resolves the actor', () => {
+    const catalog: CanonCatalog = { typeOf: id => (id === 'ACTOR-DPA-1' ? 'ACTOR' : undefined) };
+    expect(validateStakeholder(valid(), { catalog }).valid).toBe(true);
   });
+});
 
-  it('flags a wrong notation tag', () => {
-    expect(codes({ ...valid(), notation: 'stake' })).toContain('STAKEHOLDER-001');
+describe('validateStakeholder — STAKE-001 (shape / id grammar / levels)', () => {
+  it('flags a missing required envelope field', () => {
+    const s = valid();
+    delete s.name;
+    expect(codes(s)).toContain('STAKE-001');
   });
 
-  it('flags an id with the wrong TYPE prefix', () => {
-    expect(codes({ ...valid(), id: 'ACTOR-DPA-1' })).toContain('STAKEHOLDER-001');
+  it('flags an id that violates the grammar', () => {
+    expect(codes({ ...valid(), id: 'STAKEHOLDER-DPA-001' })).toContain('STAKE-001');
+    expect(codes({ ...valid(), id: 'STAKE-1' })).toContain('STAKE-001');
   });
-});
 
-describe('validateStakeholder — STAKEHOLDER-002 (type enum)', () => {
-  it('flags a missing type', () => {
-    const r = valid();
-    delete r.type;
-    expect(codes(r)).toContain('STAKEHOLDER-002');
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'stakeholders' })).toContain('STAKE-001');
   });
 
-  it('flags a type outside internal/external', () => {
-    expect(codes({ ...valid(), type: 'regulator' })).toContain('STAKEHOLDER-002');
+  it('flags an interest / influence value outside {high, medium, low}', () => {
+    expect(codes({ ...valid(), interest: 'critical' })).toContain('STAKE-001');
+    expect(codes({ ...valid(), influence: 'none' })).toContain('STAKE-001');
   });
 
-  it('accepts both internal and external', () => {
-    for (const t of ['internal', 'external']) {
-      expect(validateStakeholder({ ...valid(), type: t }).valid).toBe(true);
-    }
+  it('rejects a non-object', () => {
+    expect(codes(null)).toEqual(['STAKE-001']);
   });
 });
 
-describe('validateStakeholder — STAKEHOLDER-003 (actor binding)', () => {
+describe('validateStakeholder — STAKE-002 (actor binding)', () => {
   it('flags a missing actor', () => {
-    const r = valid();
-    delete r.actor;
-    expect(codes(r)).toContain('STAKEHOLDER-003');
+    const s = valid();
+    delete s.actor;
+    expect(codes(s)).toContain('STAKE-002');
   });
 
-  it('flags an actor that is not an ACTOR typed id', () => {
-    expect(codes({ ...valid(), actor: 'ROLE-CEO-1' })).toContain('STAKEHOLDER-003');
-    expect(codes({ ...valid(), actor: 'not an id' })).toContain('STAKEHOLDER-003');
+  it('flags an actor of the wrong TYPE', () => {
+    expect(codes({ ...valid(), actor: 'ROLE-OPS-1' })).toContain('STAKE-002');
   });
-});
 
-describe('validateStakeholder — STAKEHOLDER-004 (level enums)', () => {
-  it('flags an interest outside high/medium/low', () => {
-    expect(codes({ ...valid(), interest: 'extreme' })).toContain('STAKEHOLDER-004');
+  it('flags an actor that does not resolve when a catalog is supplied', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes(valid(), { catalog })).toContain('STAKE-002');
   });
 
-  it('flags an influence outside high/medium/low', () => {
-    expect(codes({ ...valid(), influence: 'extreme' })).toContain('STAKEHOLDER-004');
+  it('flags an actor whose catalog TYPE is not ACTOR', () => {
+    const catalog: CanonCatalog = { typeOf: () => 'ROLE' };
+    expect(codes(valid(), { catalog })).toContain('STAKE-002');
   });
+});
 
-  it('accepts each permitted level', () => {
-    for (const l of ['high', 'medium', 'low']) {
-      expect(validateStakeholder({ ...valid(), interest: l, influence: l }).valid).toBe(true);
-    }
+describe('validateStakeholder — STAKE-003 (type enum)', () => {
+  it('flags a type outside {internal, external}', () => {
+    expect(codes({ ...valid(), type: 'partner' })).toContain('STAKE-003');
   });
 });

package/src/stakeholder/index.ts

@@ -1,3 +1,4 @@
 export type { Stakeholder, StakeholderType, StakeholderLevel } from './types.js';
 export { STAKEHOLDER_TYPES, STAKEHOLDER_LEVELS } from './types.js';
 export { validateStakeholder } from './validate.js';
+export type { StakeholderValidateOptions } from './validate.js';

package/src/stakeholder/types.ts

@@ -1,33 +1,33 @@
-// STAKEHOLDER — motivation-layer interest primitive.
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.15 +
-//         notations/elements/20-stakeholders.md + envelope §3.
+// STAKEHOLDER — motivation-layer interest primitive (ArchiMate Stakeholder).
+// Schema: methodology notations/elements/20-stakeholders.md + ELEMENT_PRIMITIVES.md §7.16.
 
 import type { GateChecks } from '../requirement/types.js';
 
-export type StakeholderType = 'internal' | 'external';
 export const STAKEHOLDER_TYPES = ['internal', 'external'] as const;
+export type StakeholderType = typeof STAKEHOLDER_TYPES[number];
 
-export type StakeholderLevel = 'high' | 'medium' | 'low';
 export const STAKEHOLDER_LEVELS = ['high', 'medium', 'low'] as const;
+export type StakeholderLevel = typeof STAKEHOLDER_LEVELS[number];
 
 export interface Stakeholder {
   notation: 'stakeholder';
   id: string;
   name: string;
-  /** Required subtype — internal | external. */
   type: StakeholderType;
-  /** Required ACTOR-… typed id — identity binding (never inline). */
+  /** ACTOR-… whose identity this stake attaches to (STAKE-002). */
   actor: string;
   concern?: string;
   interest?: StakeholderLevel;
   influence?: StakeholderLevel;
   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;
 }