@transitrix/diagrams 1.0.0

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

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { validateActivityCard } from '../validate.js';
+const VALID = {
+    notation: 'activity-card',
+    spec_version: '0.1',
+    activity_card: {
+        id: 'ACTIVITY_CARD-EU-PROGRAMME-1',
+        project: 'ACTIVITY-EU-PROGRAMME-1',
+        description: 'Executive summary.',
+        milestones: [
+            {
+                id: 'MILESTONE-EU-CONFORMITY-CERT-1',
+                name: 'Certification obtained',
+                date: '2027-01-31',
+                delivers_changes: ['CHANGE-EU-COMPLIANCE-1'],
+            },
+        ],
+    },
+};
+describe('validateActivityCard', () => {
+    it('accepts a well-formed card', () => {
+        const r = validateActivityCard(VALID);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toHaveLength(0);
+    });
+    it('rejects non-object input', () => {
+        expect(validateActivityCard('x').valid).toBe(false);
+        expect(validateActivityCard(null).valid).toBe(false);
+    });
+    it('HDR-001 on missing notation', () => {
+        const { notation: _drop, ...rest } = VALID;
+        const r = validateActivityCard(rest);
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'HDR-001')).toBe(true);
+    });
+    it('HDR-002 on wrong notation', () => {
+        const r = validateActivityCard({ ...VALID, notation: 'activities' });
+        expect(r.errors.some((e) => e.code === 'HDR-002')).toBe(true);
+    });
+    it('AC-001 on missing activity_card block', () => {
+        const r = validateActivityCard({ notation: 'activity-card' });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'AC-001')).toBe(true);
+    });
+    it('AC-002 on malformed card id', () => {
+        const r = validateActivityCard({ ...VALID, activity_card: { ...VALID.activity_card, id: 'CARD-1' } });
+        expect(r.errors.some((e) => e.code === 'AC-002')).toBe(true);
+    });
+    it('PC-001 on missing project', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: { ...VALID.activity_card, project: undefined },
+        });
+        expect(r.errors.some((e) => e.code === 'PC-001')).toBe(true);
+    });
+    it('PC-001 on malformed project id', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: { ...VALID.activity_card, project: 'GOAL-1' },
+        });
+        expect(r.errors.some((e) => e.code === 'PC-001')).toBe(true);
+    });
+    it('AC-003 on milestone missing required fields', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: { ...VALID.activity_card, milestones: [{ id: 'MILESTONE-X-1' }] },
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'AC-003')).toBe(true);
+    });
+    it('AC-004 on malformed milestone id', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: {
+                ...VALID.activity_card,
+                milestones: [{ id: 'MS-1', name: 'x', date: '2027-01-01' }],
+            },
+        });
+        expect(r.errors.some((e) => e.code === 'AC-004')).toBe(true);
+    });
+    it('AC-004 on duplicate milestone id', () => {
+        const m = { id: 'MILESTONE-X-1', name: 'x', date: '2027-01-01' };
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: { ...VALID.activity_card, milestones: [m, { ...m }] },
+        });
+        expect(r.errors.some((e) => e.code === 'AC-004' && /Duplicate/.test(e.message))).toBe(true);
+    });
+    it('AC-005 on bad milestone date format', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: {
+                ...VALID.activity_card,
+                milestones: [{ id: 'MILESTONE-X-1', name: 'x', date: '31/01/2027' }],
+            },
+        });
+        expect(r.errors.some((e) => e.code === 'AC-005')).toBe(true);
+    });
+    it('AC-006 on malformed delivers_changes entry', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: {
+                ...VALID.activity_card,
+                milestones: [{ id: 'MILESTONE-X-1', name: 'x', date: '2027-01-01', delivers_changes: ['GOAL-1'] }],
+            },
+        });
+        expect(r.errors.some((e) => e.code === 'AC-006')).toBe(true);
+    });
+    it('accepts a card with no milestones', () => {
+        const r = validateActivityCard({
+            ...VALID,
+            activity_card: { id: 'ACTIVITY_CARD-X-1', project: 'ACTIVITY-X-1' },
+        });
+        expect(r.valid).toBe(true);
+    });
+});

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

@@ -0,0 +1,5 @@
+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 { validateActivityCard } from './validate.js';
+export { resolveActivityCard } from './resolver.js';
+export type { ActivityCardResolution } from './resolver.js';
+export { layoutActivityCard, ARCHIMATE_CLASS } from './layout.js';

package/dist/activity-card/index.js

@@ -0,0 +1,3 @@
+export { validateActivityCard } from './validate.js';
+export { resolveActivityCard } from './resolver.js';
+export { layoutActivityCard, ARCHIMATE_CLASS } from './layout.js';

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

@@ -0,0 +1,7 @@
+import type { ActivityCardLayout, ActivityCardLayoutOptions, ResolvedActivityCard } from './types.js';
+/** ArchiMate class per §5.1 — derived from element TYPE, never stored. */
+export declare const ARCHIMATE_CLASS: {
+    readonly ACTIVITY: "Work Package";
+    readonly MILESTONE: "Implementation Event";
+};
+export declare function layoutActivityCard(card: ResolvedActivityCard, options?: ActivityCardLayoutOptions): ActivityCardLayout;

package/dist/activity-card/layout.js

@@ -0,0 +1,167 @@
+// Activity Card — single-page layout (pure geometry; the preview paints SVG).
+//
+// Top-to-bottom card sections (spec §4 / §5):
+//   1. Title         — project name
+//   2. Dates band    — Initiation (valid_from) · Planned start · Planned end
+//   3. Milestones    — narrative timeline, markers left→right by date
+//   4. Motivation    — Factors → Goals → Changes columns with F→G→C edges
+//   5. Child activities — activities whose parent = the project
+//
+// The §5.1 ArchiMate-class convention ("(Work Package)", "(Implementation
+// Event)") is applied HERE, derived from element TYPE — there is no
+// archimate_class data field.
+const DEFAULTS = {
+    cardWidth: 780,
+    columnGap: 28,
+    rowGap: 12,
+};
+// Fixed metrics (px). Kept local — the card has no user-tunable spacing yet.
+const PAD = 20;
+const TITLE_H = 38;
+const DATES_H = 56;
+const SECTION_HEADER_H = 26;
+const SECTION_GAP = 16;
+const MILESTONE_W = 168;
+const MILESTONE_H = 64;
+const MILESTONE_GAP = 16;
+const CHAIN_NODE_H = 46;
+const CHILD_ROW_H = 42;
+/** ArchiMate class per §5.1 — derived from element TYPE, never stored. */
+export const ARCHIMATE_CLASS = {
+    ACTIVITY: 'Work Package',
+    MILESTONE: 'Implementation Event',
+};
+export function layoutActivityCard(card, options) {
+    const opts = { ...DEFAULTS, ...(options ?? {}) };
+    const contentX = PAD;
+    const contentW = opts.cardWidth - PAD * 2;
+    let cursorY = PAD;
+    // 1. Title
+    const title = { name: card.project.name, x: contentX, y: cursorY + TITLE_H / 2 };
+    cursorY += TITLE_H;
+    // 2. Dates band — three equal cells.
+    const dateDefs = [
+        { label: 'Initiation', value: card.project.valid_from ?? '—' },
+        { label: 'Planned start', value: card.project.start_date ?? '—' },
+        { label: 'Planned end', value: card.project.end_date ?? '—' },
+    ];
+    const dateGap = 12;
+    const dateCellW = (contentW - dateGap * (dateDefs.length - 1)) / dateDefs.length;
+    const dateFields = dateDefs.map((d, i) => ({
+        label: d.label,
+        value: d.value,
+        x: contentX + i * (dateCellW + dateGap),
+        y: cursorY,
+        width: dateCellW,
+        height: DATES_H,
+    }));
+    cursorY += DATES_H + SECTION_GAP;
+    const sectionHeaders = [];
+    const pushHeader = (label) => {
+        sectionHeaders.push({ label, x: contentX, y: cursorY, width: contentW, height: SECTION_HEADER_H });
+        cursorY += SECTION_HEADER_H + 8;
+    };
+    // 3. Milestones — timeline markers, wrapped left→right.
+    const milestones = [];
+    if (card.milestones.length > 0) {
+        pushHeader('Milestones');
+        const perRow = Math.max(1, Math.floor((contentW + MILESTONE_GAP) / (MILESTONE_W + MILESTONE_GAP)));
+        const rowStartY = cursorY;
+        card.milestones.forEach((m, i) => {
+            const col = i % perRow;
+            const row = Math.floor(i / perRow);
+            milestones.push({
+                id: m.id,
+                name: m.name,
+                date: m.date,
+                archimateClass: ARCHIMATE_CLASS.MILESTONE,
+                x: contentX + col * (MILESTONE_W + MILESTONE_GAP),
+                y: rowStartY + row * (MILESTONE_H + opts.rowGap),
+                width: MILESTONE_W,
+                height: MILESTONE_H,
+            });
+        });
+        const rows = Math.ceil(card.milestones.length / perRow);
+        cursorY = rowStartY + rows * (MILESTONE_H + opts.rowGap) - opts.rowGap + SECTION_GAP;
+    }
+    // 4. Motivation chain — Factors | Goals | Changes columns.
+    const chainEdges = [];
+    const factorsCol = [];
+    const goalsCol = [];
+    const changesCol = [];
+    const { factors, goals, changes } = card.motivation;
+    if (factors.length + goals.length + changes.length > 0) {
+        pushHeader('Motivation — Factors → Goals → Changes');
+        const colW = (contentW - opts.columnGap * 2) / 3;
+        const colX = [contentX, contentX + colW + opts.columnGap, contentX + (colW + opts.columnGap) * 2];
+        const colStartY = cursorY;
+        const stack = (items, colIndex, into) => {
+            items.forEach((it, i) => {
+                into.push({
+                    id: it.id,
+                    name: it.name,
+                    x: colX[colIndex],
+                    y: colStartY + i * (CHAIN_NODE_H + opts.rowGap),
+                    width: colW,
+                    height: CHAIN_NODE_H,
+                });
+            });
+        };
+        stack(factors, 0, factorsCol);
+        stack(goals, 1, goalsCol);
+        stack(changes, 2, changesCol);
+        // Edges: factor→goal (goal.factorIds), goal→change (change.goalIds).
+        const factorIds = new Set(factorsCol.map((n) => n.id));
+        const goalIds = new Set(goalsCol.map((n) => n.id));
+        for (const g of goals) {
+            for (const fid of g.factorIds) {
+                if (factorIds.has(fid))
+                    chainEdges.push({ sourceId: fid, targetId: g.id });
+            }
+        }
+        for (const c of changes) {
+            for (const gid of c.goalIds) {
+                if (goalIds.has(gid))
+                    chainEdges.push({ sourceId: gid, targetId: c.id });
+            }
+        }
+        const tallest = Math.max(factorsCol.length, goalsCol.length, changesCol.length);
+        cursorY = colStartY + tallest * (CHAIN_NODE_H + opts.rowGap) - opts.rowGap + SECTION_GAP;
+    }
+    // 5. Child activities — full-width rows.
+    const childActivities = [];
+    if (card.childActivities.length > 0) {
+        pushHeader('Child activities');
+        const rowStartY = cursorY;
+        card.childActivities.forEach((a, i) => {
+            const metaBits = [];
+            if (a.start_date || a.end_date)
+                metaBits.push(`${a.start_date ?? '?'} → ${a.end_date ?? '?'}`);
+            if (a.owner)
+                metaBits.push(a.owner);
+            childActivities.push({
+                id: a.id,
+                name: a.name,
+                archimateClass: ARCHIMATE_CLASS.ACTIVITY,
+                meta: metaBits.join(' · '),
+                x: contentX,
+                y: rowStartY + i * (CHILD_ROW_H + opts.rowGap),
+                width: contentW,
+                height: CHILD_ROW_H,
+            });
+        });
+        cursorY =
+            rowStartY + card.childActivities.length * (CHILD_ROW_H + opts.rowGap) - opts.rowGap + SECTION_GAP;
+    }
+    const totalHeight = cursorY - SECTION_GAP + PAD;
+    return {
+        bounds: { x: 0, y: 0, width: opts.cardWidth, height: Math.max(totalHeight, PAD * 2 + TITLE_H) },
+        title,
+        dateFields,
+        sectionHeaders,
+        milestones,
+        chainColumns: { factors: factorsCol, goals: goalsCol, changes: changesCol },
+        chainEdges,
+        childActivities,
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { ActivityCardDoc, ActivityCardSources, ResolvedActivityCard } from './types.js';
+import type { ValidationResult } from '../validation-types.js';
+export interface ActivityCardResolution extends ValidationResult {
+    /** Present only when resolution succeeded (project found + valid_from OK). */
+    resolved?: ResolvedActivityCard;
+}
+export declare function resolveActivityCard(doc: ActivityCardDoc, sources: ActivityCardSources): ActivityCardResolution;

package/dist/activity-card/resolver.js

@@ -0,0 +1,310 @@
+// Activity Card — cross-document resolver (the novel piece of this notation).
+//
+// Unlike every other Studio preview, the Activity Card is assembled from
+// MULTIPLE documents. The card YAML names a project Activity; the resolver
+// pulls the rest of the card's content BY REFERENCE from the canonical
+// ELEMENT and RELATION store — never from other view documents (view-purity:
+// a view is a projection over elements + relations, methodology
+// ELEMENT_PRIMITIVES.md §1):
+//
+//   canon/elements/**  → one element per file. The project ACTIVITY (name,
+//                        lifecycle + schedule dates, delivers_changes[],
+//                        parent) and its child ACTIVITY elements (parent =
+//                        project id); the FACTOR / GOAL / CHANGE elements that
+//                        the motivation chain expands (goal.factors,
+//                        change.goals carried inline on the elements).
+//   canon/relations/** → `notation: relation` files. The project's goals come
+//                        from the first-class `activity_goal` REL (from =
+//                        project id), preferred over the activity element's
+//                        transitional inline `goals[]` when present
+//                        (07-activities.md §"Time-aware relations").
+//
+// The extension reads + parses the element and relation files (walking the
+// org's `canon/elements` and `canon/relations` trees) and hands the parsed
+// docs in. This resolver is filesystem-free and pure so it stays unit-testable.
+//
+// Cross-document validation lives here (the rules that need the sibling docs):
+//   PC-001   project does not resolve to an admitted Activity
+//   PC-002   resolved Activity has activity_type other than "Project"
+//   PC-003   milestone.delivers_changes[] entry not in the project's own
+//            delivers_changes[]
+//   PC-004   (warning) milestone.date outside [valid_from, valid_to]
+//   LIFECYCLE-001  project valid_from missing / not a parseable ISO date
+//   LIFECYCLE-002  project valid_to present, not null, not a parseable date
+//   LIFECYCLE-003  project valid_to earlier than valid_from
+//
+// LIFECYCLE-* are scoped to the RESOLVED PROJECT Activity only — the card is
+// built around the project's initiation date, so a missing valid_from there is
+// a hard error. Child activities and FGCA elements are not lifecycle-checked
+// here (out of this notation's scope; today's Studio activities docs may
+// legitimately omit lifecycle fields).
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === 'string' && v.trim().length > 0 ? v : undefined;
+}
+function strArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string' && x.trim().length > 0);
+}
+/** A parseable quoted ISO 8601 date, calendar-checked (rejects 2026-13-40). */
+function isIsoDate(v) {
+    if (typeof v !== 'string' || !DATE_RE.test(v))
+        return false;
+    const t = Date.parse(`${v}T00:00:00Z`);
+    if (Number.isNaN(t))
+        return false;
+    // Round-trip guard so 2026-02-30 (which Date.parse may roll forward) is rejected.
+    return new Date(t).toISOString().slice(0, 10) === v;
+}
+/**
+ * Index canon element documents of one `notation` by their `id`. Each element
+ * is its own single-element file (`notation: activity|factor|goal|change|…`
+ * with a top-level `id`); first definition wins.
+ */
+function collectByNotation(docs, notation) {
+    const out = new Map();
+    for (const doc of docs) {
+        if (!isObject(doc))
+            continue;
+        if (str(doc['notation']) !== notation)
+            continue;
+        const id = str(doc['id']);
+        if (!id)
+            continue;
+        if (!out.has(id))
+            out.set(id, doc); // first definition wins
+    }
+    return out;
+}
+/**
+ * GOAL ids reached by an *active* `activity_goal` relation originating at
+ * `fromId`. A relation with a non-null `valid_to` has ended (the activity was
+ * re-aimed) and is excluded — the card shows the currently-served goals.
+ */
+function activeActivityGoals(relations, fromId) {
+    const out = [];
+    for (const doc of relations) {
+        if (!isObject(doc))
+            continue;
+        if (str(doc['notation']) !== 'relation')
+            continue;
+        if (str(doc['type']) !== 'activity_goal')
+            continue;
+        if (str(doc['from']) !== fromId)
+            continue;
+        const to = str(doc['to']);
+        if (!to)
+            continue;
+        const validTo = doc['valid_to'];
+        if (validTo !== undefined && validTo !== null)
+            continue; // ended relation
+        if (!out.includes(to))
+            out.push(to);
+    }
+    return out;
+}
+export function resolveActivityCard(doc, sources) {
+    const errors = [];
+    const warnings = [];
+    const card = doc?.activity_card;
+    const projectId = str(card?.project);
+    if (!projectId) {
+        // Structural validator already flags this; nothing to resolve.
+        errors.push({ code: 'PC-001', message: 'activity_card.project is missing' });
+        return { valid: false, errors, warnings };
+    }
+    const activities = collectByNotation(sources.elements, 'activity');
+    const projectRec = activities.get(projectId);
+    // PC-001 — project must resolve to an admitted ACTIVITY element in canon.
+    if (!projectRec) {
+        errors.push({
+            code: 'PC-001',
+            message: `activity_card.project "${projectId}" does not resolve to an ACTIVITY element in the canon element store`,
+        });
+        return { valid: false, errors, warnings };
+    }
+    // PC-002 — the resolved Activity should be the project scale. In the element
+    // model all activity scales (initiative / programme / project / task) share
+    // one ACTIVITY TYPE and `activity_type` references an ActivityType element,
+    // so a missing/non-literal value is acceptable; only an explicit, clearly
+    // non-project marker is flagged. (Canonical project-identification semantics
+    // are tracked as a follow-up internally.)
+    const activityType = str(projectRec['activity_type']);
+    if (activityType !== undefined && activityType !== 'Project' && activityType !== 'project') {
+        errors.push({
+            code: 'PC-002',
+            message: `Activity "${projectId}" has activity_type "${activityType}", expected the project scale`,
+        });
+    }
+    // LIFECYCLE-001..003 on the project Activity.
+    const validFrom = projectRec['valid_from'];
+    const validToRaw = projectRec['valid_to'];
+    let validFromOk = false;
+    if (validFrom === undefined || validFrom === null) {
+        errors.push({ code: 'LIFECYCLE-001', message: `Activity "${projectId}" valid_from is required` });
+    }
+    else if (!isIsoDate(validFrom)) {
+        errors.push({
+            code: 'LIFECYCLE-001',
+            message: `Activity "${projectId}" valid_from "${String(validFrom)}" is not a parseable ISO 8601 date`,
+        });
+    }
+    else {
+        validFromOk = true;
+    }
+    let validToOk = false;
+    const validToPresent = validToRaw !== undefined && validToRaw !== null;
+    if (validToPresent) {
+        if (!isIsoDate(validToRaw)) {
+            errors.push({
+                code: 'LIFECYCLE-002',
+                message: `Activity "${projectId}" valid_to "${String(validToRaw)}" is not a parseable ISO 8601 date`,
+            });
+        }
+        else {
+            validToOk = true;
+            if (validFromOk && validToRaw < validFrom) {
+                errors.push({
+                    code: 'LIFECYCLE-003',
+                    message: `Activity "${projectId}" valid_to "${String(validToRaw)}" is earlier than valid_from "${String(validFrom)}"`,
+                });
+            }
+        }
+    }
+    // A failed lifecycle/PC-001 stops us producing a card view-model, but we still
+    // return every error collected so the panel lists them all at once.
+    const projectChanges = new Set(strArray(projectRec['delivers_changes']));
+    // Project goals: prefer the first-class `activity_goal` relations (the
+    // canonical, time-aware home for an Activity→Goal link); fall back to the
+    // activity element's transitional inline `goals[]` when no relation exists
+    // (07-activities.md §"Time-aware relations").
+    const relGoalIds = activeActivityGoals(sources.relations, projectId);
+    const projectGoalIds = relGoalIds.length > 0 ? relGoalIds : strArray(projectRec['goals']);
+    // PC-003 — each milestone change must be a subset of the project's changes.
+    const rawMilestones = Array.isArray(card.milestones) ? card.milestones : [];
+    const milestones = [];
+    for (const m of rawMilestones) {
+        if (!isObject(m))
+            continue;
+        const mid = str(m['id']);
+        const mname = str(m['name']);
+        const mdate = str(m['date']);
+        if (!mid || !mname || !mdate)
+            continue; // structural validator already flagged
+        const deliversChanges = strArray(m['delivers_changes']);
+        for (const c of deliversChanges) {
+            if (!projectChanges.has(c)) {
+                errors.push({
+                    code: 'PC-003',
+                    message: `Milestone "${mid}" delivers_changes "${c}" is not in project "${projectId}" delivers_changes`,
+                });
+            }
+        }
+        // PC-004 — milestone date should fall within the project lifecycle window.
+        if (validFromOk && mdate < validFrom) {
+            warnings.push({
+                code: 'PC-004',
+                message: `Milestone "${mid}" date "${mdate}" is before project valid_from "${String(validFrom)}"`,
+            });
+        }
+        if (validToOk && mdate > validToRaw) {
+            warnings.push({
+                code: 'PC-004',
+                message: `Milestone "${mid}" date "${mdate}" is after project valid_to "${String(validToRaw)}"`,
+            });
+        }
+        milestones.push({
+            id: mid,
+            name: mname,
+            date: mdate,
+            description: str(m['description']),
+            deliversChanges,
+        });
+    }
+    milestones.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+    // If we have hard errors, surface them without an assembled card.
+    if (errors.length > 0) {
+        return { valid: false, errors, warnings };
+    }
+    // ── Motivation chain — expand against canon FACTOR / GOAL / CHANGE elements ──
+    const factorElems = collectByNotation(sources.elements, 'factor');
+    const goalElems = collectByNotation(sources.elements, 'goal');
+    const changeElems = collectByNotation(sources.elements, 'change');
+    const changes = [];
+    for (const cid of projectChanges) {
+        const rec = changeElems.get(cid);
+        if (!rec) {
+            warnings.push({
+                code: 'PC-001',
+                message: `Project change "${cid}" not found as a CHANGE element in canon; omitted from the motivation chain`,
+            });
+            continue;
+        }
+        changes.push({ id: cid, name: str(rec['name']) ?? cid, goalIds: strArray(rec['goals']) });
+    }
+    // Goals shown = the project's declared goals ∪ goals referenced by in-scope
+    // changes (so the F→G→C chain stays connected).
+    const goalIdSet = new Set(projectGoalIds);
+    for (const ch of changes)
+        for (const g of ch.goalIds)
+            goalIdSet.add(g);
+    const goals = [];
+    for (const gid of goalIdSet) {
+        const rec = goalElems.get(gid);
+        if (!rec) {
+            warnings.push({
+                code: 'PC-001',
+                message: `Goal "${gid}" not found as a GOAL element in canon; omitted from the motivation chain`,
+            });
+            continue;
+        }
+        goals.push({ id: gid, name: str(rec['name']) ?? gid, factorIds: strArray(rec['factors']) });
+    }
+    // Factors shown = those referenced by the in-scope goals.
+    const factorIdSet = new Set();
+    for (const g of goals)
+        for (const f of g.factorIds)
+            factorIdSet.add(f);
+    const factors = [];
+    for (const fid of factorIdSet) {
+        const rec = factorElems.get(fid);
+        factors.push({ id: fid, name: rec ? str(rec['name']) ?? fid : fid });
+    }
+    // ── Child activities — parent = project id ──────────────────────────────────
+    const childActivities = [];
+    for (const [id, rec] of activities) {
+        if (str(rec['parent']) !== projectId)
+            continue;
+        childActivities.push({
+            id,
+            name: str(rec['name']) ?? id,
+            activity_type: str(rec['activity_type']),
+            start_date: str(rec['start_date']),
+            end_date: str(rec['end_date']),
+            owner: str(rec['owner']),
+        });
+    }
+    childActivities.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const project = {
+        id: projectId,
+        name: str(projectRec['name']) ?? projectId,
+        description: str(projectRec['description']),
+        valid_from: validFromOk ? validFrom : undefined,
+        valid_to: validToOk ? validToRaw : undefined,
+        start_date: str(projectRec['start_date']),
+        end_date: str(projectRec['end_date']),
+    };
+    const resolved = {
+        cardId: str(card.id) ?? '',
+        cardDescription: str(card.description),
+        project,
+        milestones,
+        motivation: { factors, goals, changes },
+        childActivities,
+    };
+    return { valid: true, errors, warnings, resolved };
+}