@transitrix/diagrams 1.0.0 → 1.1.0

package/dist/activity-card/types.d.ts

@@ -17,6 +17,11 @@ export interface ActivityCardBlock {
     project: string;
     description?: string;
     milestones?: RawMilestone[];
+    /**
+     * Supplementary notes shown in the card footer. Free text; stored in the
+     * view file (not in canon elements) as report-level context.
+     */
+    notes?: string;
 }
 export interface ActivityCardDoc {
     notation: string;
@@ -41,6 +46,17 @@ export interface ResolvedProject {
     /** Planned work range. */
     start_date?: string;
     end_date?: string;
+    /**
+     * Activity scale: programme | project | workstream | task (or any custom
+     * value). Shown in the card header so the reader knows what level this card
+     * represents. Optional — card shows "—" when absent.
+     */
+    activity_type?: string;
+    /**
+     * Current execution state: planned | in_progress | on_track | at_risk |
+     * blocked | completed | cancelled. Optional — card shows "—" when absent.
+     */
+    status?: string;
 }
 export interface ResolvedMilestone {
     id: string;
@@ -50,15 +66,32 @@ export interface ResolvedMilestone {
     /** CHANGE-… IDs this milestone delivers (subset of the project's). */
     deliversChanges: string[];
 }
-export interface ResolvedFactor {
+export interface ResolvedDriver {
+    id: string;
+    name: string;
+}
+/** @deprecated Use {@link ResolvedDriver}. */
+export type ResolvedFactor = ResolvedDriver;
+/**
+ * A dated finding about the current state of a Driver, answering the
+ * question "what specific problem are we solving?" (pain point).
+ * Resolved from ASSESSMENT elements whose `assesses` field points to a
+ * Driver that is in scope for this activity's motivation chain.
+ */
+export interface ResolvedAssessment {
     id: string;
     name: string;
+    /** ID of the Driver this assessment observes. */
+    driverId: string;
+    description?: string;
+    /** ISO 8601 date when the finding was observed. */
+    observed_at?: string;
 }
 export interface ResolvedGoal {
     id: string;
     name: string;
-    /** FACTOR-… IDs that motivate this goal (canonical `goal.factors`). */
-    factorIds: string[];
+    /** DRIVER-… IDs that motivate this goal (canonical `goal.factors` YAML field). */
+    driverIds: string[];
 }
 export interface ResolvedChange {
     id: string;
@@ -66,9 +99,9 @@ export interface ResolvedChange {
     /** GOAL-… IDs this change advances (canonical `change.goals`). */
     goalIds: string[];
 }
-/** Motivation chain: Factors → Goals → Changes, scoped to the project. */
+/** Motivation chain: Drivers → Goals → Changes, scoped to the project. */
 export interface ResolvedMotivation {
-    factors: ResolvedFactor[];
+    drivers: ResolvedDriver[];
     goals: ResolvedGoal[];
     changes: ResolvedChange[];
 }
@@ -80,6 +113,21 @@ export interface ResolvedChildActivity {
     end_date?: string;
     owner?: string;
 }
+/** A STAKEHOLDER element linked to the project (via `activity_stakeholder`). */
+export interface ResolvedStakeholder {
+    id: string;
+    name: string;
+    /** internal | external (STAKEHOLDER `type`). */
+    type?: string;
+    interest?: string;
+    influence?: string;
+    /**
+     * Project role from the `activity_stakeholder` relation:
+     * initiator | owner | sponsor | project_manager.
+     * Optional — card shows the name without a role badge when absent.
+     */
+    role?: string;
+}
 export interface ResolvedActivityCard {
     cardId: string;
     /** The card's own executive-summary description (distinct from the project's). */
@@ -88,8 +136,31 @@ export interface ResolvedActivityCard {
     /** Sorted ascending by `date`. */
     milestones: ResolvedMilestone[];
     motivation: ResolvedMotivation;
+    /**
+     * Assessments (pain points) for the in-scope Drivers, sorted by
+     * `observed_at` ascending. Empty when no Assessment elements are found —
+     * the gap is intentionally visible on the card.
+     */
+    assessments: ResolvedAssessment[];
     /** Activities whose `parent` = the project Activity id. */
     childActivities: ResolvedChildActivity[];
+    /**
+     * Names of the GOALs the project DIRECTLY serves (the `activity_goal`
+     * targets, not the wider motivation chain) — painted as the "Project goal"
+     * text field. Empty when the project serves no goal.
+     */
+    goalNames?: string[];
+    /**
+     * Stakeholders linked to the project via active `activity_stakeholder`
+     * relations. Empty when none are linked (the card still shows the field
+     * with a "—" placeholder).
+     */
+    stakeholders?: ResolvedStakeholder[];
+    /**
+     * Supplementary notes for the card footer (from `activity_card.notes` in
+     * the view YAML). Not a canonical element field.
+     */
+    notes?: string;
 }
 import type { LayoutBounds } from '../geometry.js';
 export type { LayoutBounds };
@@ -102,45 +173,89 @@ export interface DateField {
     width: number;
     height: number;
 }
-/** One milestone marker on the timeline. */
-export interface MilestoneMarker {
-    id: string;
+/** A small badge shown in the header (activity type or status). */
+export interface Badge {
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One stakeholder role slot in the header roles row. Always rendered; `name` is "—" when unfilled. */
+export interface StakeholderRoleSlot {
+    /** Display label: "Initiator", "Owner", "Sponsor", "PM". */
+    role: string;
+    /** Stakeholder name or "—". */
     name: string;
-    date: string;
-    /** ArchiMate class label appended by the renderer (§5.1). */
-    archimateClass: string;
     x: number;
     y: number;
     width: number;
     height: number;
 }
-/** One node in a motivation-chain column. */
+/** One node in a chain section (driver / assessment / goal / change). */
 export interface ChainNode {
     id: string;
     name: string;
+    /** Supplementary text shown below the name (e.g. observed_at date for assessments). */
+    meta?: string;
     x: number;
     y: number;
     width: number;
     height: number;
 }
-/** An edge between two chain nodes (factor→goal or goal→change). */
+/** An edge between two chain nodes (for SVG connectors). */
 export interface ChainEdge {
     sourceId: string;
     targetId: string;
 }
-export interface ChildActivityRow {
+/**
+ * One vertical section of the body chain: Drivers | Assessments | Goals | Changes.
+ * When `isEmpty` is true the section has no nodes and renders a gap indicator
+ * so the author sees the missing data.
+ */
+export interface ChainSectionLayout {
+    type: 'drivers' | 'assessments' | 'goals' | 'changes';
+    /** Section header label. */
+    label: string;
+    /** Short question answered by this section, shown in grey after the label. */
+    subtitle: string;
+    nodes: ChainNode[];
+    isEmpty: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One milestone marker. */
+export interface MilestoneMarker {
     id: string;
     name: string;
+    date: string;
     /** ArchiMate class label appended by the renderer (§5.1). */
     archimateClass: string;
-    meta: string;
     x: number;
     y: number;
     width: number;
     height: number;
 }
-export interface SectionHeader {
+/**
+ * A labeled, full-width text row with wrapped value lines.
+ * Used for the Description (body) and Notes (footer).
+ */
+export interface InfoRow {
     label: string;
+    valueLines: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ChildActivityRow {
+    id: string;
+    name: string;
+    /** ArchiMate class label appended by the renderer (§5.1). */
+    archimateClass: string;
+    meta: string;
     x: number;
     y: number;
     width: number;
@@ -149,27 +264,35 @@ export interface SectionHeader {
 export interface ActivityCardLayoutOptions {
     /** Outer card width (px). */
     cardWidth?: number;
-    /** Horizontal gap (px) between the three motivation-chain columns. */
-    columnGap?: number;
     /** Vertical gap (px) between stacked rows within a section. */
     rowGap?: number;
 }
 export interface ActivityCardLayout {
     bounds: LayoutBounds;
-    title: {
+    /** Project name, positioned in the title row. */
+    titleRow: {
         name: string;
         x: number;
         y: number;
     };
+    /** Activity-type badge (programme / project / workstream / task). Absent when field is unset. */
+    activityTypeBadge?: Badge;
+    /** Status badge (planned / in_progress / on_track / …). Absent when field is unset. */
+    statusBadge?: Badge;
+    /** Three date cells: Initiation, Planned start, Planned end. */
     dateFields: DateField[];
-    sectionHeaders: SectionHeader[];
-    milestones: MilestoneMarker[];
-    /** Three columns of the motivation chain, in F→G→C order. */
-    chainColumns: {
-        factors: ChainNode[];
-        goals: ChainNode[];
-        changes: ChainNode[];
-    };
+    /** Four role slots always rendered: Initiator, Owner, Sponsor, PM. Name is "—" when unfilled. */
+    stakeholderRoleSlots: StakeholderRoleSlot[];
+    /** Executive-summary description row. Absent when `cardDescription` is empty. */
+    descriptionRow?: InfoRow;
+    /** Vertical chain: Drivers → Assessments → Goals → Changes. */
+    chainSections: ChainSectionLayout[];
+    /** Node-level edges within the chain (driver→assessment, driver→goal, goal→change). */
     chainEdges: ChainEdge[];
+    /** Milestone markers below the chain, wrapped left→right by date. */
+    milestones: MilestoneMarker[];
+    /** Child activities below milestones. */
     childActivities: ChildActivityRow[];
+    /** Notes row from `activity_card.notes`. Absent when empty. */
+    footerRow?: InfoRow;
 }

package/dist/activity-card/validate.js

@@ -75,6 +75,9 @@ export function validateActivityCard(input) {
     if (card['description'] !== undefined && typeof card['description'] !== 'string') {
         errors.push({ code: 'AC-001', message: 'activity_card.description must be a string' });
     }
+    if (card['notes'] !== undefined && typeof card['notes'] !== 'string') {
+        errors.push({ code: 'AC-001', message: 'activity_card.notes must be a string' });
+    }
     // ── milestones[] (optional) ─────────────────────────────────────────────────
     const milestonesRaw = card['milestones'];
     if (milestonesRaw !== undefined) {

package/dist/actor/__tests__/validate.test.js

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

package/dist/actor/index.d.ts

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

package/dist/actor/index.js

@@ -1,2 +1,2 @@
-export { ACTOR_TYPES } from './types.js';
+export { ACTOR_TYPES, ACTOR_FORBIDDEN_INLINE_FIELDS } from './types.js';
 export { validateActor } from './validate.js';

package/dist/actor/types.d.ts

@@ -1,12 +1,16 @@
 import type { GateChecks } from '../requirement/types.js';
-/** Identity discriminator — what kind of actor (person, business_unit, system). */
-export type ActorType = 'person' | 'business_unit' | 'system';
 export declare const ACTOR_TYPES: readonly ["person", "business_unit", "system"];
+export type ActorType = typeof ACTOR_TYPES[number];
+/**
+ * Fields that record engagement / org-hierarchy and therefore MUST NOT appear
+ * inline on an ACTOR file (§7.10, ACTOR-003). They belong in time-aware REL
+ * records, never on the identity primitive.
+ */
+export declare const ACTOR_FORBIDDEN_INLINE_FIELDS: readonly ["employment", "candidacy", "alumni_membership", "community_membership", "contracting", "unit_parent", "roles", "owner"];
 export interface Actor {
     notation: 'actor';
     id: string;
     name: string;
-    /** Required identity discriminator. */
     type: ActorType;
     description?: string;
     contact?: string;

package/dist/actor/types.js

@@ -1,4 +1,18 @@
-// ACTOR — business-layer identity primitive (ArchiMate Business Actor).
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.10 +
-//         notations/elements/19-actors.md + envelope §3.
+// ACTOR — active-structure identity primitive (ArchiMate Business Actor).
+// Schema: methodology notations/elements/19-actors.md + ELEMENT_PRIMITIVES.md §7.10.
 export const ACTOR_TYPES = ['person', 'business_unit', 'system'];
+/**
+ * Fields that record engagement / org-hierarchy and therefore MUST NOT appear
+ * inline on an ACTOR file (§7.10, ACTOR-003). They belong in time-aware REL
+ * records, never on the identity primitive.
+ */
+export const ACTOR_FORBIDDEN_INLINE_FIELDS = [
+    'employment',
+    'candidacy',
+    'alumni_membership',
+    'community_membership',
+    'contracting',
+    'unit_parent',
+    'roles',
+    'owner',
+];

package/dist/actor/validate.js

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

package/dist/assertion/types.d.ts

@@ -1,6 +1,6 @@
 import type { GateChecks } from '../requirement/types.js';
 /** Compliance status vocabulary (16-assertion.md §3). */
-export type AssertionStatus = 'compliant' | 'partial' | 'non_compliant' | 'under_review' | 'n_a';
+export type AssertionStatus = 'compliant' | 'partial' | 'non_compliant' | 'under_review' | 'pending_owner' | 'n_a';
 export declare const ASSERTION_STATUSES: readonly AssertionStatus[];
 /** TYPEs a `subject` may resolve to (16-assertion.md §2, ASSERT-003). */
 export declare const ASSERTION_SUBJECT_TYPES: readonly ["PRODUCT", "PROCESS", "CAPABILITY"];
@@ -34,6 +34,8 @@ export interface Assertion {
     assessed_at?: string;
     assessed_by?: string;
     next_review_at?: string;
+    /** ID or name of the party who must confirm this assertion (pending-owner state). */
+    owner_to_confirm?: string;
     zone: 'canon';
     admitted_at: string;
     admitted_by: string;

package/dist/assertion/types.js

@@ -1,7 +1,7 @@
 // ASSERTION — REQUIREMENT realisation claim.
 // Schema: methodology notations/elements/16-assertion.md §2.
 export const ASSERTION_STATUSES = [
-    'compliant', 'partial', 'non_compliant', 'under_review', 'n_a',
+    'compliant', 'partial', 'non_compliant', 'under_review', 'pending_owner', 'n_a',
 ];
 /** TYPEs a `subject` may resolve to (16-assertion.md §2, ASSERT-003). */
 export const ASSERTION_SUBJECT_TYPES = ['PRODUCT', 'PROCESS', 'CAPABILITY'];