@transitrix/diagrams 1.0.0

package/src/activity-card/__tests__/validate.test.ts

@@ -0,0 +1,131 @@
+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/src/activity-card/index.ts

@@ -0,0 +1,32 @@
+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/src/activity-card/layout.ts

@@ -0,0 +1,194 @@
+// 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.
+
+import type {
+  ActivityCardLayout,
+  ActivityCardLayoutOptions,
+  ChainEdge,
+  ChainNode,
+  ChildActivityRow,
+  DateField,
+  MilestoneMarker,
+  ResolvedActivityCard,
+  SectionHeader,
+} from './types.js';
+
+const DEFAULTS = {
+  cardWidth: 780,
+  columnGap: 28,
+  rowGap: 12,
+} as const;
+
+// 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',
+} as const;
+
+export function layoutActivityCard(
+  card: ResolvedActivityCard,
+  options?: ActivityCardLayoutOptions,
+): ActivityCardLayout {
+  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: Array<{ label: string; value: string }> = [
+    { 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: DateField[] = 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: SectionHeader[] = [];
+  const pushHeader = (label: string): void => {
+    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: MilestoneMarker[] = [];
+  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: ChainEdge[] = [];
+  const factorsCol: ChainNode[] = [];
+  const goalsCol: ChainNode[] = [];
+  const changesCol: ChainNode[] = [];
+  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: { id: string; name: string }[], colIndex: number, into: ChainNode[]) => {
+      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: ChildActivityRow[] = [];
+  if (card.childActivities.length > 0) {
+    pushHeader('Child activities');
+    const rowStartY = cursorY;
+    card.childActivities.forEach((a, i) => {
+      const metaBits: string[] = [];
+      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/src/activity-card/resolver.ts

@@ -0,0 +1,337 @@
+// 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).
+
+import type {
+  ActivityCardDoc,
+  ActivityCardSources,
+  ResolvedActivityCard,
+  ResolvedChange,
+  ResolvedChildActivity,
+  ResolvedFactor,
+  ResolvedGoal,
+  ResolvedMilestone,
+  ResolvedProject,
+} from './types.js';
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export interface ActivityCardResolution extends ValidationResult {
+  /** Present only when resolution succeeded (project found + valid_from OK). */
+  resolved?: ResolvedActivityCard;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim().length > 0 ? v : undefined;
+}
+
+function strArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v.filter((x): x is string => typeof x === 'string' && x.trim().length > 0);
+}
+
+/** A parseable quoted ISO 8601 date, calendar-checked (rejects 2026-13-40). */
+function isIsoDate(v: unknown): v is string {
+  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: unknown[],
+  notation: string,
+): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>();
+  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: unknown[], fromId: string): string[] {
+  const out: string[] = [];
+  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: ActivityCardDoc,
+  sources: ActivityCardSources,
+): ActivityCardResolution {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  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 as string) < (validFrom as string)) {
+        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: ResolvedMilestone[] = [];
+  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 as string)) {
+      warnings.push({
+        code: 'PC-004',
+        message: `Milestone "${mid}" date "${mdate}" is before project valid_from "${String(validFrom)}"`,
+      });
+    }
+    if (validToOk && mdate > (validToRaw as string)) {
+      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: ResolvedChange[] = [];
+  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<string>(projectGoalIds);
+  for (const ch of changes) for (const g of ch.goalIds) goalIdSet.add(g);
+
+  const goals: ResolvedGoal[] = [];
+  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<string>();
+  for (const g of goals) for (const f of g.factorIds) factorIdSet.add(f);
+
+  const factors: ResolvedFactor[] = [];
+  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: ResolvedChildActivity[] = [];
+  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: ResolvedProject = {
+    id: projectId,
+    name: str(projectRec['name']) ?? projectId,
+    description: str(projectRec['description']),
+    valid_from: validFromOk ? (validFrom as string) : undefined,
+    valid_to: validToOk ? (validToRaw as string) : undefined,
+    start_date: str(projectRec['start_date']),
+    end_date: str(projectRec['end_date']),
+  };
+
+  const resolved: ResolvedActivityCard = {
+    cardId: str(card.id) ?? '',
+    cardDescription: str(card.description),
+    project,
+    milestones,
+    motivation: { factors, goals, changes },
+    childActivities,
+  };
+
+  return { valid: true, errors, warnings, resolved };
+}