@transitrix/diagrams 1.0.0

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

@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { validateScenario } from '../validate.js';
+
+const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'scenarios');
+
+const VALID_SCENARIO = {
+  notation: 'scenarios',
+  scenario: {
+    id: 'SCN-001',
+    name: 'Optimistic Growth 2027',
+    status: 'Active',
+    created_at: '2026-01-01',
+    vision: 'Aggressive expansion scenario.',
+    factors_view: [
+      { factor_id: 'FAC-MARKET-001', relevance: 'High', impact: 'Revenue growth' },
+      { factor_id: 'FAC-TECH-001', relevance: 'Medium' },
+    ],
+    goals: [{ goal_id: 'GOAL-REV-001' }],
+    capabilities: [{ capability_id: 'CAP-ECOMM-001' }],
+    activities: [{ activity_id: 'ACT-EXPAND-001' }],
+    products: [{ product_id: 'PROD-PLATFORM-001' }],
+    processes: [{ process_id: 'PROC-DELIVERY-001' }],
+    applications: [{ app_id: 'APP-CRM-001' }, { app_id: 'APP-OMS-001' }],
+  },
+};
+
+describe('validateScenario', () => {
+  it('passes on valid input', () => {
+    const r = validateScenario(VALID_SCENARIO);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('SCN-001: rejects non-object input', () => {
+    const r = validateScenario(null);
+    expect(r.errors[0].code).toBe('SCN-001');
+  });
+
+  it('SCN-001: rejects missing notation', () => {
+    const { notation: _, ...rest } = VALID_SCENARIO;
+    const r = validateScenario(rest);
+    expect(r.errors.some(e => e.code === 'SCN-001')).toBe(true);
+  });
+
+  it('SCN-001: rejects wrong notation value', () => {
+    const r = validateScenario({ ...VALID_SCENARIO, notation: 'goals' });
+    expect(r.errors.some(e => e.code === 'SCN-001')).toBe(true);
+  });
+
+  it('SCN-002: rejects missing scenario', () => {
+    const r = validateScenario({ notation: 'scenarios' });
+    expect(r.errors.some(e => e.code === 'SCN-002')).toBe(true);
+  });
+
+  it('SCN-002: rejects missing id/name/status', () => {
+    const r = validateScenario({ notation: 'scenarios', scenario: {} });
+    expect(r.errors.filter(e => e.code === 'SCN-002').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('SCN-003: rejects invalid status', () => {
+    const scn = { ...VALID_SCENARIO.scenario, status: 'Retired' };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-003')).toBe(true);
+  });
+
+  it('SCN-003: accepts all valid statuses', () => {
+    for (const status of ['Draft', 'Active', 'Archived']) {
+      const scn = { ...VALID_SCENARIO.scenario, status };
+      const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+      expect(r.errors.some(e => e.code === 'SCN-003')).toBe(false);
+    }
+  });
+
+  it('SCN-004: rejects malformed created_at', () => {
+    const scn = { ...VALID_SCENARIO.scenario, created_at: '01-01-2026' };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-004')).toBe(true);
+  });
+
+  it('SCN-004: accepts missing created_at', () => {
+    const { created_at: _, ...scn } = VALID_SCENARIO.scenario;
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-004')).toBe(false);
+  });
+
+  it('SCN-005: rejects non-array factors_view', () => {
+    const scn = { ...VALID_SCENARIO.scenario, factors_view: 'oops' };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-005')).toBe(true);
+  });
+
+  it('SCN-005: rejects factor missing factor_id', () => {
+    const scn = { ...VALID_SCENARIO.scenario, factors_view: [{ relevance: 'High' }] };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-005')).toBe(true);
+  });
+
+  it('SCN-006: rejects invalid factor relevance', () => {
+    const scn = {
+      ...VALID_SCENARIO.scenario,
+      factors_view: [{ factor_id: 'F1', relevance: 'Critical' }],
+    };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-006')).toBe(true);
+  });
+
+  it('SCN-013: rejects duplicate factor_id', () => {
+    const scn = {
+      ...VALID_SCENARIO.scenario,
+      factors_view: [{ factor_id: 'F1' }, { factor_id: 'F1' }],
+    };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.errors.some(e => e.code === 'SCN-013')).toBe(true);
+  });
+
+  const refCases = [
+    { 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' },
+  ];
+
+  for (const c of refCases) {
+    it(`${c.errorCode}: rejects ${c.field}[*] missing ${c.idField}`, () => {
+      const scn = { ...VALID_SCENARIO.scenario, [c.field]: [{}] };
+      const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+      expect(r.errors.some(e => e.code === c.errorCode)).toBe(true);
+    });
+
+    it(`${c.errorCode}: rejects non-array ${c.field}`, () => {
+      const scn = { ...VALID_SCENARIO.scenario, [c.field]: 'oops' };
+      const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+      expect(r.errors.some(e => e.code === c.errorCode)).toBe(true);
+    });
+
+    it(`${c.errorCode}: rejects duplicate ${c.idField}`, () => {
+      const scn = {
+        ...VALID_SCENARIO.scenario,
+        [c.field]: [{ [c.idField]: 'X1' }, { [c.idField]: 'X1' }],
+      };
+      const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+      expect(r.errors.some(e => e.code === c.errorCode)).toBe(true);
+    });
+  }
+
+  it('accepts minimal scenario (id+name+status only)', () => {
+    const r = validateScenario({
+      notation: 'scenarios',
+      scenario: { id: 'S1', name: 'Minimal', status: 'Draft' },
+    });
+    expect(r.valid).toBe(true);
+  });
+
+  it('accepts scenario with all reference lists empty', () => {
+    const scn = {
+      ...VALID_SCENARIO.scenario,
+      factors_view: [],
+      goals: [],
+      capabilities: [],
+      activities: [],
+      products: [],
+      processes: [],
+      applications: [],
+    };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.valid).toBe(true);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it('[blocker] tolerates a null element in factors_view[] without throwing', () => {
+    const scn = { ...VALID_SCENARIO.scenario, factors_view: [null] };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCN-005')).toBe(true);
+  });
+
+  it('[blocker] tolerates a null element in goals[] without throwing', () => {
+    const scn = { ...VALID_SCENARIO.scenario, goals: [null] };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCN-007')).toBe(true);
+  });
+
+  it('[blocker] tolerates a string element in applications[] without throwing', () => {
+    const scn = { ...VALID_SCENARIO.scenario, applications: ['x'] };
+    const r = validateScenario({ ...VALID_SCENARIO, scenario: scn });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCN-012')).toBe(true);
+  });
+});
+
+describe('scenarios examples (regression)', () => {
+  const files = fs.readdirSync(EXAMPLES_DIR).filter(f => f.endsWith('.yaml'));
+  expect(files.length).toBeGreaterThan(0);
+  for (const file of files) {
+    it(`validates tests/fixtures/notation-corpus/scenarios/${file}`, () => {
+      const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+      const parsed = yaml.load(text);
+      const r = validateScenario(parsed);
+      expect(r.errors).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+  }
+});

package/src/scenarios/index.ts

@@ -0,0 +1,15 @@
+export type {
+  ScenarioStatus,
+  FactorRelevance,
+  FactorView,
+  GoalRef,
+  CapabilityRef,
+  ActivityRef,
+  ProductRef,
+  ProcessRef,
+  ApplicationRef,
+  ScenarioHeader,
+  ScenarioFile,
+} from './types.js';
+
+export { validateScenario } from './validate.js';

package/src/scenarios/types.ts

@@ -0,0 +1,37 @@
+export type ScenarioStatus = 'Draft' | 'Active' | 'Archived';
+export type FactorRelevance = 'High' | 'Medium' | 'Low';
+
+export interface FactorView {
+  factor_id: string;
+  relevance?: FactorRelevance;
+  impact?: string;
+}
+
+export interface GoalRef        { goal_id: string }
+export interface CapabilityRef  { capability_id: string }
+export interface ActivityRef    { activity_id: string }
+export interface ProductRef     { product_id: string }
+export interface ProcessRef     { process_id: string }
+export interface ApplicationRef { app_id: string }
+
+export interface ScenarioHeader {
+  id: string;
+  name: string;
+  description?: string;
+  status: ScenarioStatus;
+  created_at?: string;
+  vision?: string;
+  factors_view?: FactorView[];
+  goals?: GoalRef[];
+  capabilities?: CapabilityRef[];
+  activities?: ActivityRef[];
+  products?: ProductRef[];
+  processes?: ProcessRef[];
+  applications?: ApplicationRef[];
+}
+
+export interface ScenarioFile {
+  notation: string;
+  spec_version?: string;
+  scenario: ScenarioHeader;
+}

package/src/scenarios/validate.ts

@@ -0,0 +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 };
+}

package/src/schema-version.ts

@@ -0,0 +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';

package/src/scope.ts

@@ -0,0 +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.`,
+  };
+}

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

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { validateStakeholder } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'stakeholder',
+    id: 'STAKEHOLDER-DPA-1',
+    name: 'Data Protection Authority',
+    type: 'external',
+    actor: 'ACTOR-DPA-1',
+    concern: 'Lawful processing and timely erasure of EU customer personal data.',
+    interest: 'high',
+    influence: 'high',
+    description: 'External oversight stakeholder.',
+    zone: 'canon',
+    admitted_at: '2026-05-29',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2018-05-25',
+    valid_to: null,
+  };
+}
+
+const codes = (input: unknown): string[] => validateStakeholder(input).errors.map(e => e.code);
+
+describe('validateStakeholder — positive', () => {
+  it('accepts the worked-example STAKEHOLDER-DPA-1', () => {
+    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);
+  });
+});
+
+describe('validateStakeholder — STAKEHOLDER-001 (envelope / shape)', () => {
+  it('flags a non-object', () => {
+    expect(codes(null)).toEqual(['STAKEHOLDER-001']);
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'stake' })).toContain('STAKEHOLDER-001');
+  });
+
+  it('flags an id with the wrong TYPE prefix', () => {
+    expect(codes({ ...valid(), id: 'ACTOR-DPA-1' })).toContain('STAKEHOLDER-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 type outside internal/external', () => {
+    expect(codes({ ...valid(), type: 'regulator' })).toContain('STAKEHOLDER-002');
+  });
+
+  it('accepts both internal and external', () => {
+    for (const t of ['internal', 'external']) {
+      expect(validateStakeholder({ ...valid(), type: t }).valid).toBe(true);
+    }
+  });
+});
+
+describe('validateStakeholder — STAKEHOLDER-003 (actor binding)', () => {
+  it('flags a missing actor', () => {
+    const r = valid();
+    delete r.actor;
+    expect(codes(r)).toContain('STAKEHOLDER-003');
+  });
+
+  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');
+  });
+});
+
+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 influence outside high/medium/low', () => {
+    expect(codes({ ...valid(), influence: 'extreme' })).toContain('STAKEHOLDER-004');
+  });
+
+  it('accepts each permitted level', () => {
+    for (const l of ['high', 'medium', 'low']) {
+      expect(validateStakeholder({ ...valid(), interest: l, influence: l }).valid).toBe(true);
+    }
+  });
+});

package/src/stakeholder/index.ts

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

package/src/stakeholder/types.ts

@@ -0,0 +1,33 @@
+// STAKEHOLDER — motivation-layer interest primitive.
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.15 +
+//         notations/elements/20-stakeholders.md + envelope §3.
+
+import type { GateChecks } from '../requirement/types.js';
+
+export type StakeholderType = 'internal' | 'external';
+export const STAKEHOLDER_TYPES = ['internal', 'external'] as const;
+
+export type StakeholderLevel = 'high' | 'medium' | 'low';
+export const STAKEHOLDER_LEVELS = ['high', 'medium', 'low'] as const;
+
+export interface Stakeholder {
+  notation: 'stakeholder';
+  id: string;
+  name: string;
+  /** Required subtype — internal | external. */
+  type: StakeholderType;
+  /** Required ACTOR-… typed id — identity binding (never inline). */
+  actor: string;
+  concern?: string;
+  interest?: StakeholderLevel;
+  influence?: StakeholderLevel;
+  description?: string;
+
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/stakeholder/validate.ts

@@ -0,0 +1,63 @@
+// STAKEHOLDER validator — methodology notations/ELEMENT_PRIMITIVES.md §7.15
+// + notations/elements/20-stakeholders.md.
+//
+// Implements STAKEHOLDER-001..004. Stake-in-a-specific-object lives on
+// `stakeholding` REL records (elements/17-relations.md §3) and is out of
+// scope for this single-artefact validator.
+
+import type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
+import { typeOfId } from '../typed-id.js';
+import { validateElementEnvelope } from '../element-envelope.js';
+import { STAKEHOLDER_LEVELS, STAKEHOLDER_TYPES } from './types.js';
+
+export function validateStakeholder(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  const { record, errors: envErrors } = validateElementEnvelope(input, {
+    notation: 'stakeholder',
+    idType: 'STAKEHOLDER',
+    code: 'STAKEHOLDER-001',
+  });
+  errors.push(...envErrors);
+  if (!record) return { valid: false, errors, warnings };
+
+  // STAKEHOLDER-002 — type subtype required.
+  if (record.type === undefined || record.type === null) {
+    errors.push({ code: 'STAKEHOLDER-002', message: 'type is required (internal | external).', path: 'type' });
+  } else if (!STAKEHOLDER_TYPES.includes(record.type as never)) {
+    errors.push({
+      code: 'STAKEHOLDER-002',
+      message: `type "${String(record.type)}" must be one of ${STAKEHOLDER_TYPES.join(', ')}.`,
+      path: 'type',
+    });
+  }
+
+  // STAKEHOLDER-003 — actor identity binding (REQUIRED, must be ACTOR-…).
+  if (record.actor === undefined || record.actor === null || record.actor === '') {
+    errors.push({
+      code: 'STAKEHOLDER-003',
+      message: 'actor is required — identity lives in an ACTOR-… record, never inline.',
+      path: 'actor',
+    });
+  } else if (typeOfId(record.actor) !== 'ACTOR') {
+    errors.push({
+      code: 'STAKEHOLDER-003',
+      message: `actor "${String(record.actor)}" must be an ACTOR typed ID.`,
+      path: 'actor',
+    });
+  }
+
+  // STAKEHOLDER-004 — interest / influence level enums (optional fields).
+  for (const f of ['interest', 'influence'] as const) {
+    if (record[f] !== undefined && !STAKEHOLDER_LEVELS.includes(record[f] as never)) {
+      errors.push({
+        code: 'STAKEHOLDER-004',
+        message: `${f} "${String(record[f])}" must be one of ${STAKEHOLDER_LEVELS.join(', ')}.`,
+        path: f,
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}