@transitrix/diagrams 1.0.0 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023-2026 Valerii Korobeinikov
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023-2026 Valerii Korobeinikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,47 +1,47 @@
-# @transitrix/diagrams
-
-Shared rendering, validation, and pure mutations for Transitrix custom diagram
-formats (BPMN, Goals, FGCA, Capability Map, Process Blueprint, and the rest of
-the Transitrix notation family).
-
-This package is the runtime library used by the **Transitrix Studio** VS Code
-extension, the `@transitrix/cli`, and downstream tools that need to read,
-validate, or render Transitrix diagrams.
-
-## Install
-
-```bash
-npm install @transitrix/diagrams
-```
-
-`react` and `reactflow` are declared as peer dependencies — install them in the
-host application if you use the React renderers; pure validation / mutation
-APIs do not require them.
-
-## What's inside
-
-The package re-exports the per-notation modules under one entry point:
-
-- Activities, Activity Card, Applications, Assertion, Blocks, Capability Map,
-  Compliance + Compliance Matrix, Confidence, FGCA, Goals, Process Blueprint,
-  Process Map, Products, Requirement, Scenarios.
-- Shared primitives: `geometry`, `typed-id`, `validation-types`,
-  `yaml-normalize`, `SCHEMA_VERSION`, theme tokens, repository-level validators.
-
-See the source layout under [`src/`](./src) and the per-module `index.ts`
-exports for the public surface.
-
-## Versioning
-
-`@transitrix/diagrams` ships on its own version line, independent of the
-Transitrix Studio extension version. The first published release is `1.0.0`.
-
-## License
-
-MIT — see [`LICENSE`](./LICENSE).
-
-## Links
-
-- Monorepo: <https://github.com/transitrix/transitrix-studio>
-- Issues: <https://github.com/transitrix/transitrix-studio/issues>
-- Methodology spec: <https://github.com/transitrix/methodology>
+# @transitrix/diagrams
+
+Shared rendering, validation, and pure mutations for Transitrix custom diagram
+formats (BPMN, Goals, FGCA, Capability Map, Process Blueprint, and the rest of
+the Transitrix notation family).
+
+This package is the runtime library used by the **Transitrix Studio** VS Code
+extension, the `@transitrix/cli`, and downstream tools that need to read,
+validate, or render Transitrix diagrams.
+
+## Install
+
+```bash
+npm install @transitrix/diagrams
+```
+
+`react` and `reactflow` are declared as peer dependencies — install them in the
+host application if you use the React renderers; pure validation / mutation
+APIs do not require them.
+
+## What's inside
+
+The package re-exports the per-notation modules under one entry point:
+
+- Activities, Activity Card, Applications, Assertion, Blocks, Capability Map,
+  Compliance + Compliance Matrix, Confidence, FGCA, Goals, Process Blueprint,
+  Process Map, Products, Requirement, Scenarios.
+- Shared primitives: `geometry`, `typed-id`, `validation-types`,
+  `yaml-normalize`, `SCHEMA_VERSION`, theme tokens, repository-level validators.
+
+See the source layout under [`src/`](./src) and the per-module `index.ts`
+exports for the public surface.
+
+## Versioning
+
+`@transitrix/diagrams` ships on its own version line, independent of the
+Transitrix Studio extension version. The first published release is `1.0.0`.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).
+
+## Links
+
+- Monorepo: <https://github.com/transitrix/transitrix-studio>
+- Issues: <https://github.com/transitrix/transitrix-studio/issues>
+- Methodology spec: <https://github.com/transitrix/methodology>

package/dist/__tests__/edge-path.test.js

@@ -36,4 +36,12 @@ describe('horizontalCubicEdgePath', () => {
         const d = horizontalCubicEdgePath(0, 0, 0, 200, 1);
         expect(d).toBe('M0,0 C160,0 -160,200 0,200');
     });
+    it('entryCurvature independently scales the arrival handle', () => {
+        // exit handle = max(64,20,0)*1 = 64; entry handle = max(64,20,0)*2 = 128.
+        const d = horizontalCubicEdgePath(0, 0, 40, 0, 1, 2);
+        expect(d).toBe(`M0,0 C${EDGE_MIN_HANDLE},0 ${40 - EDGE_MIN_HANDLE * 2},0 40,0`);
+    });
+    it('omitting entryCurvature gives symmetric handles (historical behaviour)', () => {
+        expect(horizontalCubicEdgePath(0, 0, 40, 0, 0.5)).toBe(horizontalCubicEdgePath(0, 0, 40, 0, 0.5, 0.5));
+    });
 });

package/dist/activities/cpm.js

@@ -2,6 +2,15 @@ export function computeCpm(activities) {
     const result = new Map();
     if (activities.length === 0)
         return result;
+    // When no activity carries any duration data, critical path is indeterminate —
+    // return all non-critical so the diagram renders in default grey.
+    const hasDuration = activities.some((a) => (a.duration !== undefined && a.duration !== null) || (a.duration_days !== undefined && a.duration_days !== null));
+    if (!hasDuration) {
+        for (const a of activities) {
+            result.set(a.id, { es: 0, ef: 0, ls: 0, lf: 0, slack: 0, isCritical: false });
+        }
+        return result;
+    }
     // Build successor map and in-degree for topological sort
     const successors = new Map();
     const predecessors = new Map();
@@ -41,7 +50,7 @@ export function computeCpm(activities) {
     const ef = new Map();
     for (const id of topoOrder) {
         const a = actById.get(id);
-        const dur = a.duration ?? 0;
+        const dur = a.duration ?? a.duration_days ?? 0;
         const maxPredEf = Math.max(0, ...(predecessors.get(id) ?? []).map(p => ef.get(p) ?? 0));
         es.set(id, maxPredEf);
         ef.set(id, maxPredEf + dur);
@@ -53,7 +62,7 @@ export function computeCpm(activities) {
     const lf = new Map();
     for (const id of [...topoOrder].reverse()) {
         const a = actById.get(id);
-        const dur = a.duration ?? 0;
+        const dur = a.duration ?? a.duration_days ?? 0;
         const succs = successors.get(id) ?? [];
         const minSuccLs = succs.length === 0 ? projectFinish : Math.min(...succs.map(s => ls.get(s) ?? projectFinish));
         lf.set(id, minSuccLs);

package/dist/activities/gantt.js

@@ -86,7 +86,10 @@ function detectMode(doc, leaves) {
     if (allPinned)
         return 'pinned';
     const hasProjectStart = typeof doc.project?.start_date === 'string' && doc.project.start_date.length > 0;
-    const allHaveDuration = leaves.every((a) => typeof a.duration === 'number' && Number.isFinite(a.duration) && a.duration >= 0);
+    const allHaveDuration = leaves.every((a) => {
+        const d = a.duration ?? a.duration_days;
+        return typeof d === 'number' && Number.isFinite(d) && d >= 0;
+    });
     if (hasProjectStart && allHaveDuration)
         return 'computed';
     return null;
@@ -111,7 +114,7 @@ export function computeGanttLayout(doc) {
         for (const a of leaves) {
             const startDate = a.start_date;
             const endDate = a.end_date;
-            const isMilestone = a.duration === 0 || startDate === endDate;
+            const isMilestone = (a.duration ?? a.duration_days) === 0 || startDate === endDate;
             const bar = {
                 id: a.id,
                 name: a.name,
@@ -134,7 +137,7 @@ export function computeGanttLayout(doc) {
         for (const a of leaves) {
             const c = cpm.get(a.id);
             const es = c?.es ?? 0;
-            const dur = a.duration ?? 0;
+            const dur = a.duration ?? a.duration_days ?? 0;
             const startDate = nthWorkingDay(projectStart, es, calendar);
             const endDate = dur === 0
                 ? startDate

package/dist/activities/types.d.ts

@@ -6,6 +6,7 @@ export interface Activity {
     id: string;
     name: string;
     duration?: number;
+    duration_days?: number;
     activity_type?: string;
     goals?: string[];
     scenario?: string;

package/dist/activities/validate.js

@@ -113,7 +113,7 @@ export function validateActivities(input) {
             idSet.add(id);
         }
         // ACT-009: non-negative numeric fields
-        const numericFields = ['duration', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort'];
+        const numericFields = ['duration', 'duration_days', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort'];
         for (const field of numericFields) {
             const val = act[field];
             if (val !== undefined && val !== null) {
@@ -122,8 +122,8 @@ export function validateActivities(input) {
                 }
             }
         }
-        // ACT-011: warn if no duration
-        if (act.duration === undefined || act.duration === null) {
+        // ACT-011: warn if no duration (duration_days is accepted as an alias)
+        if ((act.duration === undefined || act.duration === null) && (act.duration_days === undefined || act.duration_days === null)) {
             warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — cannot participate in CPM analysis`, path });
         }
     }

package/dist/activity-card/__tests__/example.test.js

@@ -44,12 +44,31 @@ describe('activity-card worked example (eu-programme)', () => {
             'MILESTONE-EU-CONFORMITY-CERT-1',
             'MILESTONE-EU-MARKET-LAUNCH-1',
         ]);
-        expect(c.motivation.factors.map((f) => f.id)).toEqual(['FACTOR-EU-MDR-1']);
+        expect(c.motivation.drivers.map((d) => d.id)).toEqual(['FACTOR-EU-MDR-1']);
         expect(c.motivation.goals.map((g) => g.id)).toEqual(['GOAL-EU-MARKET-1']);
         expect(c.motivation.changes.map((x) => x.id)).toEqual(['CHANGE-EU-COMPLIANCE-1']);
         expect(c.childActivities).toHaveLength(4);
+        // Project goal text field resolves to the directly-served goal name; the
+        // example links no stakeholders, so the card shows the field empty.
+        expect(c.goalNames).toEqual(['Maintain EU market access under MDR']);
+        expect(c.stakeholders).toEqual([]);
         const layout = layoutActivityCard(c);
         expect(layout.bounds.height).toBeGreaterThan(0);
+        // Header
+        expect(layout.titleRow.name).toBe('EU MDR conformity programme');
+        expect(layout.dateFields[0]).toMatchObject({ label: 'Initiation', value: '2026-04-01' });
+        expect(layout.stakeholderRoleSlots).toHaveLength(4);
+        // Description row
+        expect(layout.descriptionRow?.label).toBe('Description');
+        // Chain sections
+        expect(layout.chainSections.map((s) => s.type)).toEqual(['drivers', 'assessments', 'goals', 'changes']);
+        const driversSection = layout.chainSections.find((s) => s.type === 'drivers');
+        const goalsSection = layout.chainSections.find((s) => s.type === 'goals');
+        const assessmentsSection = layout.chainSections.find((s) => s.type === 'assessments');
+        expect(driversSection.nodes.map((n) => n.id)).toContain('FACTOR-EU-MDR-1');
+        expect(goalsSection.nodes.map((n) => n.id)).toContain('GOAL-EU-MARKET-1');
+        expect(assessmentsSection.isEmpty).toBe(true); // no assessment in this fixture
+        // Chain edges
         expect(layout.chainEdges).toContainEqual({ sourceId: 'FACTOR-EU-MDR-1', targetId: 'GOAL-EU-MARKET-1' });
         expect(layout.chainEdges).toContainEqual({ sourceId: 'GOAL-EU-MARKET-1', targetId: 'CHANGE-EU-COMPLIANCE-1' });
     });

package/dist/activity-card/__tests__/layout.test.js

@@ -6,6 +6,8 @@ const RESOLVED = {
     project: {
         id: 'ACTIVITY-EU-PROGRAMME-1',
         name: 'EU MDR conformity programme',
+        activity_type: 'programme',
+        status: 'in_progress',
         valid_from: '2026-04-01',
         start_date: '2026-04-15',
         end_date: '2027-03-15',
@@ -14,41 +16,130 @@ const RESOLVED = {
         { id: 'MILESTONE-CERT-1', name: 'Cert', date: '2027-01-31', deliversChanges: ['CHANGE-EU-COMPLIANCE-1'] },
     ],
     motivation: {
-        factors: [{ id: 'FACTOR-EU-MDR-1', name: 'EU MDR regulation' }],
-        goals: [{ id: 'GOAL-EU-MARKET-1', name: 'Access EU market', factorIds: ['FACTOR-EU-MDR-1'] }],
+        drivers: [{ id: 'FACTOR-EU-MDR-1', name: 'EU MDR regulation' }],
+        goals: [{ id: 'GOAL-EU-MARKET-1', name: 'Access EU market', driverIds: ['FACTOR-EU-MDR-1'] }],
         changes: [{ id: 'CHANGE-EU-COMPLIANCE-1', name: 'Achieve MDR compliance', goalIds: ['GOAL-EU-MARKET-1'] }],
     },
+    assessments: [
+        { id: 'ASSESSMENT-MDR-1', name: 'NB capacity constrained', driverId: 'FACTOR-EU-MDR-1', observed_at: '2026-03-01' },
+    ],
     childActivities: [
         { id: 'ACTIVITY-EU-CHILD-1', name: 'Notified-body engagement', start_date: '2026-05-01', end_date: '2026-12-01', owner: 'UNIT-REGULATORY' },
     ],
+    goalNames: ['Access EU market'],
+    stakeholders: [
+        { id: 'STAKEHOLDER-OPS-1', name: 'Operations', role: 'owner' },
+        { id: 'STAKEHOLDER-CEO-1', name: 'CEO', role: 'sponsor' },
+    ],
+    notes: 'Pre-audit scheduled for October 2026.',
 };
 describe('layoutActivityCard', () => {
-    it('produces all sections with positive geometry', () => {
+    it('produces positive bounds', () => {
         const l = layoutActivityCard(RESOLVED);
         expect(l.bounds.width).toBeGreaterThan(0);
         expect(l.bounds.height).toBeGreaterThan(0);
-        expect(l.title.name).toBe('EU MDR conformity programme');
+    });
+    it('title row carries the project name', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.titleRow.name).toBe('EU MDR conformity programme');
+    });
+    it('renders activity type and status badges when present', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.activityTypeBadge?.label).toBe('programme');
+        expect(l.statusBadge?.label).toBe('in progress');
+    });
+    it('badges are absent when project fields are unset', () => {
+        const l = layoutActivityCard({ ...RESOLVED, project: { id: 'A', name: 'n' } });
+        expect(l.activityTypeBadge).toBeUndefined();
+        expect(l.statusBadge).toBeUndefined();
+    });
+    it('three date fields with correct labels and values', () => {
+        const l = layoutActivityCard(RESOLVED);
         expect(l.dateFields).toHaveLength(3);
         expect(l.dateFields[0]).toMatchObject({ label: 'Initiation', value: '2026-04-01' });
+        expect(l.dateFields[1]).toMatchObject({ label: 'Planned start', value: '2026-04-15' });
+        expect(l.dateFields[2]).toMatchObject({ label: 'Planned end', value: '2027-03-15' });
+    });
+    it('renders "—" for absent dates', () => {
+        const l = layoutActivityCard({ ...RESOLVED, project: { id: 'A', name: 'n' } });
+        expect(l.dateFields.map((d) => d.value)).toEqual(['—', '—', '—']);
+    });
+    it('four stakeholder role slots always rendered', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.stakeholderRoleSlots).toHaveLength(4);
+        expect(l.stakeholderRoleSlots.map((s) => s.role)).toEqual(['Initiator', 'Owner', 'Sponsor', 'PM']);
+        expect(l.stakeholderRoleSlots[0].name).toBe('—'); // no initiator
+        expect(l.stakeholderRoleSlots[1].name).toBe('Operations'); // owner
+        expect(l.stakeholderRoleSlots[2].name).toBe('CEO'); // sponsor
+        expect(l.stakeholderRoleSlots[3].name).toBe('—'); // no PM
+    });
+    it('description row present when cardDescription is set', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.descriptionRow?.label).toBe('Description');
+        expect(l.descriptionRow?.valueLines.join(' ')).toContain('Summary');
+    });
+    it('description row absent when cardDescription is empty', () => {
+        const l = layoutActivityCard({ ...RESOLVED, cardDescription: undefined });
+        expect(l.descriptionRow).toBeUndefined();
+    });
+    it('four chain sections in order: drivers, assessments, goals, changes', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.chainSections.map((s) => s.type)).toEqual(['drivers', 'assessments', 'goals', 'changes']);
+    });
+    it('chain sections carry the resolved nodes', () => {
+        const l = layoutActivityCard(RESOLVED);
+        const drivers = l.chainSections.find((s) => s.type === 'drivers');
+        const assessments = l.chainSections.find((s) => s.type === 'assessments');
+        const goals = l.chainSections.find((s) => s.type === 'goals');
+        const changes = l.chainSections.find((s) => s.type === 'changes');
+        expect(drivers.nodes.map((n) => n.id)).toEqual(['FACTOR-EU-MDR-1']);
+        expect(assessments.nodes.map((n) => n.id)).toEqual(['ASSESSMENT-MDR-1']);
+        expect(assessments.nodes[0].meta).toBe('2026-03-01');
+        expect(goals.nodes.map((n) => n.id)).toEqual(['GOAL-EU-MARKET-1']);
+        expect(changes.nodes.map((n) => n.id)).toEqual(['CHANGE-EU-COMPLIANCE-1']);
+    });
+    it('empty chain sections have isEmpty=true', () => {
+        const l = layoutActivityCard({
+            ...RESOLVED,
+            motivation: { drivers: [], goals: [], changes: [] },
+            assessments: [],
+        });
+        expect(l.chainSections.every((s) => s.isEmpty)).toBe(true);
+    });
+    it('builds driver→goal and goal→change edges', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.chainEdges).toContainEqual({ sourceId: 'FACTOR-EU-MDR-1', targetId: 'GOAL-EU-MARKET-1' });
+        expect(l.chainEdges).toContainEqual({ sourceId: 'GOAL-EU-MARKET-1', targetId: 'CHANGE-EU-COMPLIANCE-1' });
+    });
+    it('builds driver→assessment edge when assessment is linked', () => {
+        const l = layoutActivityCard(RESOLVED);
+        expect(l.chainEdges).toContainEqual({ sourceId: 'FACTOR-EU-MDR-1', targetId: 'ASSESSMENT-MDR-1' });
+    });
+    it('milestone ArchiMate class is set', () => {
+        const l = layoutActivityCard(RESOLVED);
         expect(l.milestones).toHaveLength(1);
         expect(l.milestones[0].archimateClass).toBe(ARCHIMATE_CLASS.MILESTONE);
+    });
+    it('child activity ArchiMate class is set', () => {
+        const l = layoutActivityCard(RESOLVED);
         expect(l.childActivities[0].archimateClass).toBe(ARCHIMATE_CLASS.ACTIVITY);
     });
-    it('builds F→G and G→C edges', () => {
+    it('footer row present when notes is set', () => {
         const l = layoutActivityCard(RESOLVED);
-        expect(l.chainEdges).toContainEqual({ sourceId: 'FACTOR-EU-MDR-1', targetId: 'GOAL-EU-MARKET-1' });
-        expect(l.chainEdges).toContainEqual({ sourceId: 'GOAL-EU-MARKET-1', targetId: 'CHANGE-EU-COMPLIANCE-1' });
+        expect(l.footerRow?.label).toBe('Notes');
+        expect(l.footerRow?.valueLines.join(' ')).toContain('Pre-audit');
     });
-    it('renders "—" for absent dates', () => {
-        const l = layoutActivityCard({ ...RESOLVED, project: { id: 'A', name: 'n' } });
-        expect(l.dateFields.map((d) => d.value)).toEqual(['—', '—', '—']);
+    it('footer row absent when notes is empty', () => {
+        const l = layoutActivityCard({ ...RESOLVED, notes: undefined });
+        expect(l.footerRow).toBeUndefined();
     });
     it('handles an empty card without throwing', () => {
         const l = layoutActivityCard({
             cardId: 'ACTIVITY_CARD-X-1',
             project: { id: 'ACTIVITY-X-1', name: 'Empty' },
             milestones: [],
-            motivation: { factors: [], goals: [], changes: [] },
+            motivation: { drivers: [], goals: [], changes: [] },
+            assessments: [],
             childActivities: [],
         });
         expect(l.milestones).toHaveLength(0);

package/dist/activity-card/__tests__/resolver.test.js

@@ -38,7 +38,7 @@ const UNRELATED = {
     name: 'Other',
     parent: 'ACTIVITY-SOMETHING-ELSE-1',
 };
-const FACTOR = { notation: 'factor', id: 'FACTOR-EU-MDR-1', name: 'EU MDR regulation' };
+const FACTOR = { notation: 'driver', id: 'FACTOR-EU-MDR-1', name: 'EU MDR regulation' };
 const GOAL = { notation: 'goal', id: 'GOAL-EU-MARKET-1', name: 'Access EU market', factors: ['FACTOR-EU-MDR-1'] };
 const CHANGE = {
     notation: 'change',
@@ -46,6 +46,22 @@ const CHANGE = {
     name: 'Achieve MDR compliance',
     goals: ['GOAL-EU-MARKET-1'],
 };
+const ASSESSMENT = {
+    notation: 'assessment',
+    id: 'ASSESSMENT-EU-MDR-WINDOW-1',
+    name: 'Notified-body capacity constrained through 2026',
+    assesses: 'FACTOR-EU-MDR-1',
+    description: 'Bottleneck in notified-body capacity narrows the available certification window.',
+    observed_at: '2026-03-01',
+};
+const STAKEHOLDER = {
+    notation: 'stakeholder',
+    id: 'STAKEHOLDER-OPS-1',
+    name: 'Operations',
+    type: 'internal',
+    interest: 'high',
+    influence: 'medium',
+};
 // ── Canon relation store ─────────────────────────────────────────────────────
 // The project's goal link is a first-class `activity_goal` relation, not an
 // inline `goals:` field on the activity element.
@@ -58,8 +74,18 @@ const REL_GOAL = {
     valid_from: '2026-04-01',
     valid_to: null,
 };
-const elements = [PROJECT, CHILD, UNRELATED, FACTOR, GOAL, CHANGE];
-const relations = [REL_GOAL];
+const REL_STAKEHOLDER = {
+    notation: 'relation',
+    id: 'REL-EU-PROGRAMME-STAKE-OPS-1',
+    type: 'activity_stakeholder',
+    from: 'ACTIVITY-EU-PROGRAMME-1',
+    to: 'STAKEHOLDER-OPS-1',
+    role: 'sponsor',
+    valid_from: '2026-04-01',
+    valid_to: null,
+};
+const elements = [PROJECT, CHILD, UNRELATED, FACTOR, GOAL, CHANGE, STAKEHOLDER, ASSESSMENT];
+const relations = [REL_GOAL, REL_STAKEHOLDER];
 const sources = { elements, relations };
 describe('resolveActivityCard', () => {
     it('resolves a full card from elements + relations', () => {
@@ -70,11 +96,107 @@ describe('resolveActivityCard', () => {
         expect(c.project.valid_from).toBe('2026-04-01');
         expect(c.project.start_date).toBe('2026-04-15');
         expect(c.milestones).toHaveLength(1);
-        expect(c.motivation.factors.map((f) => f.id)).toEqual(['FACTOR-EU-MDR-1']);
+        expect(c.motivation.drivers.map((d) => d.id)).toEqual(['FACTOR-EU-MDR-1']);
         expect(c.motivation.goals.map((g) => g.id)).toEqual(['GOAL-EU-MARKET-1']);
         expect(c.motivation.changes.map((ch) => ch.id)).toEqual(['CHANGE-EU-COMPLIANCE-1']);
         // only the activity whose parent = the project
         expect(c.childActivities.map((a) => a.id)).toEqual(['ACTIVITY-EU-CHILD-1']);
+        // project goal text field = the directly-served goal name
+        expect(c.goalNames).toEqual(['Access EU market']);
+        // assessments resolved for in-scope drivers
+        expect(c.assessments).toEqual([
+            {
+                id: 'ASSESSMENT-EU-MDR-WINDOW-1',
+                name: 'Notified-body capacity constrained through 2026',
+                driverId: 'FACTOR-EU-MDR-1',
+                description: 'Bottleneck in notified-body capacity narrows the available certification window.',
+                observed_at: '2026-03-01',
+            },
+        ]);
+        // stakeholders resolved from the activity_stakeholder relation (with role)
+        expect(c.stakeholders).toEqual([
+            { id: 'STAKEHOLDER-OPS-1', name: 'Operations', type: 'internal', interest: 'high', influence: 'medium', role: 'sponsor' },
+        ]);
+    });
+    it('returns empty assessments when no assessment elements are in canon', () => {
+        const r = resolveActivityCard(CARD, {
+            elements: [PROJECT, CHILD, FACTOR, GOAL, CHANGE],
+            relations,
+        });
+        expect(r.valid).toBe(true);
+        expect(r.resolved.assessments).toEqual([]);
+    });
+    it('omits assessments whose assesses driver is not in the motivation chain', () => {
+        const unrelatedAssessment = {
+            notation: 'assessment',
+            id: 'ASSESSMENT-UNRELATED-1',
+            name: 'Something unrelated',
+            assesses: 'FACTOR-UNRELATED-99',
+            observed_at: '2026-01-01',
+        };
+        const r = resolveActivityCard(CARD, {
+            elements: [PROJECT, CHILD, FACTOR, GOAL, CHANGE, unrelatedAssessment],
+            relations,
+        });
+        expect(r.valid).toBe(true);
+        expect(r.resolved.assessments).toEqual([]);
+    });
+    it('sorts assessments by observed_at ascending', () => {
+        const a1 = { notation: 'assessment', id: 'ASSESSMENT-A-1', name: 'Later', assesses: 'FACTOR-EU-MDR-1', observed_at: '2026-06-01' };
+        const a2 = { notation: 'assessment', id: 'ASSESSMENT-A-2', name: 'Earlier', assesses: 'FACTOR-EU-MDR-1', observed_at: '2026-01-01' };
+        const r = resolveActivityCard(CARD, {
+            elements: [PROJECT, CHILD, FACTOR, GOAL, CHANGE, a1, a2],
+            relations,
+        });
+        expect(r.resolved.assessments.map((a) => a.id)).toEqual(['ASSESSMENT-A-2', 'ASSESSMENT-A-1']);
+    });
+    it('resolves stakeholder role from the activity_stakeholder relation', () => {
+        const relWithRole = { ...REL_STAKEHOLDER, role: 'project_manager' };
+        const r = resolveActivityCard(CARD, { elements, relations: [REL_GOAL, relWithRole] });
+        expect(r.valid).toBe(true);
+        const sh = r.resolved?.stakeholders?.at(0);
+        expect(sh?.role).toBe('project_manager');
+    });
+    it('resolves stakeholder without role when relation has no role field', () => {
+        const relNoRole = { ...REL_STAKEHOLDER, role: undefined };
+        const r = resolveActivityCard(CARD, { elements, relations: [REL_GOAL, relNoRole] });
+        expect(r.valid).toBe(true);
+        const sh = r.resolved?.stakeholders?.at(0);
+        expect(sh).toBeDefined();
+        expect(sh?.role).toBeUndefined();
+    });
+    it('passes notes from card YAML through to the resolved card', () => {
+        const cardWithNotes = {
+            ...CARD,
+            activity_card: { ...CARD.activity_card, notes: 'Pre-audit scheduled for Q4.' },
+        };
+        const r = resolveActivityCard(cardWithNotes, sources);
+        expect(r.valid).toBe(true);
+        expect(r.resolved.notes).toBe('Pre-audit scheduled for Q4.');
+    });
+    it('notes is undefined when not set in card YAML', () => {
+        const r = resolveActivityCard(CARD, sources);
+        expect(r.resolved.notes).toBeUndefined();
+    });
+    it('resolves no stakeholders (empty list) when none are linked', () => {
+        const r = resolveActivityCard(CARD, { elements, relations: [REL_GOAL] });
+        expect(r.valid).toBe(true);
+        expect(r.resolved.stakeholders).toEqual([]);
+        expect(r.warnings.some((w) => w.code === 'PC-001')).toBe(false);
+    });
+    it('ignores an ended (valid_to set) activity_stakeholder relation', () => {
+        const ended = { ...REL_STAKEHOLDER, valid_to: '2026-12-31' };
+        const r = resolveActivityCard(CARD, { elements, relations: [REL_GOAL, ended] });
+        expect(r.resolved.stakeholders).toEqual([]);
+    });
+    it('warns but still lists a stakeholder whose element is missing from canon', () => {
+        const r = resolveActivityCard(CARD, {
+            elements: [PROJECT, CHILD, FACTOR, GOAL, CHANGE],
+            relations: [REL_GOAL, REL_STAKEHOLDER],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.resolved.stakeholders).toEqual([{ id: 'STAKEHOLDER-OPS-1', name: 'STAKEHOLDER-OPS-1', role: 'sponsor' }]);
+        expect(r.warnings.some((w) => w.code === 'PC-001')).toBe(true);
     });
     it('falls back to the inline goals field when no activity_goal relation exists', () => {
         const projectWithInline = { ...PROJECT, goals: ['GOAL-EU-MARKET-1'] };
@@ -90,12 +212,44 @@ describe('resolveActivityCard', () => {
         expect(r.valid).toBe(false);
         expect(r.errors.some((e) => e.code === 'PC-001')).toBe(true);
     });
-    it('PC-002 when the activity carries an explicit non-project type', () => {
+    it('PC-001 diagnostic discloses paths searched and actionable hint (#344)', () => {
+        const r = resolveActivityCard(CARD, { elements: [FACTOR, GOAL, CHANGE], relations });
+        const pc001 = r.errors.find((e) => e.code === 'PC-001');
+        expect(pc001).toBeDefined();
+        // Must disclose both searched paths (§7 PC-001)
+        expect(pc001.message).toContain('canon/elements/**');
+        expect(pc001.message).toContain('canon/views/activities/**');
+        // Must include actionable hint with expected file pattern (§7 PC-001)
+        expect(pc001.message).toContain('notation: activity');
+        expect(pc001.message).toContain(`id: "${CARD.activity_card.project}"`);
+    });
+    it('resolves without PC-001 when project activity lives in a deep canon/elements subfolder (#344)', () => {
+        // Regression: the resolver must accept elements regardless of which subfolder
+        // they were loaded from (e.g. canon/elements/05_implementation/activities/).
+        // The resolver is filesystem-free, so we simulate the deep-path scenario by
+        // including the PROJECT element in the elements pool — just as loadCanon does
+        // after walking canon/elements/** recursively.
+        const r = resolveActivityCard(CARD, sources);
+        expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+        expect(r.errors.some((e) => e.code === 'PC-001')).toBe(false);
+    });
+    it('resolves activity_type and status from the Activity element', () => {
         const r = resolveActivityCard(CARD, {
-            elements: [{ ...PROJECT, activity_type: 'Task' }, CHILD, FACTOR, GOAL, CHANGE],
+            elements: [{ ...PROJECT, activity_type: 'programme', status: 'on_track' }, CHILD, FACTOR, GOAL, CHANGE],
             relations,
         });
-        expect(r.errors.some((e) => e.code === 'PC-002')).toBe(true);
+        expect(r.valid).toBe(true);
+        expect(r.resolved.project.activity_type).toBe('programme');
+        expect(r.resolved.project.status).toBe('on_track');
+    });
+    it('accepts any activity_type value without error (card works at all levels)', () => {
+        for (const t of ['programme', 'project', 'workstream', 'task', 'initiative']) {
+            const r = resolveActivityCard(CARD, {
+                elements: [{ ...PROJECT, activity_type: t }, CHILD, FACTOR, GOAL, CHANGE],
+                relations,
+            });
+            expect(r.errors.some((e) => e.code === 'PC-002'), `should not error for type "${t}"`).toBe(false);
+        }
     });
     it('PC-003 when a milestone change is not in the project changes', () => {
         const card = {

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

@@ -1,4 +1,4 @@
-export type { RawMilestone, ActivityCardBlock, ActivityCardDoc, ActivityCardSources, ResolvedProject, ResolvedMilestone, ResolvedFactor, ResolvedGoal, ResolvedChange, ResolvedMotivation, ResolvedChildActivity, ResolvedActivityCard, DateField, MilestoneMarker, ChainNode, ChainEdge, ChildActivityRow, SectionHeader, ActivityCardLayoutOptions, ActivityCardLayout, ActivityCardValidationError, ActivityCardValidationWarning, ActivityCardValidationResult, } from './types.js';
+export type { RawMilestone, ActivityCardBlock, ActivityCardDoc, ActivityCardSources, ResolvedProject, ResolvedMilestone, ResolvedDriver, ResolvedFactor, ResolvedAssessment, ResolvedGoal, ResolvedChange, ResolvedMotivation, ResolvedChildActivity, ResolvedStakeholder, ResolvedActivityCard, DateField, Badge, StakeholderRoleSlot, ChainNode, ChainEdge, ChainSectionLayout, MilestoneMarker, InfoRow, ChildActivityRow, ActivityCardLayoutOptions, ActivityCardLayout, ActivityCardValidationError, ActivityCardValidationWarning, ActivityCardValidationResult, } from './types.js';
 export { validateActivityCard } from './validate.js';
 export { resolveActivityCard } from './resolver.js';
 export type { ActivityCardResolution } from './resolver.js';