@transitrix/diagrams 1.0.0

package/src/activities/validate.ts

@@ -0,0 +1,357 @@
+import type {
+  ActivityDoc,
+  Activity,
+  ActivityValidationResult,
+  ActivityValidationError,
+  ActivityValidationWarning,
+} from './types.js';
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const VALID_WEEKDAYS = new Set(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']);
+
+export function validateActivities(input: unknown): ActivityValidationResult {
+  const errors: ActivityValidationError[] = [];
+  const warnings: ActivityValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'ACT-001', message: 'Input must be an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  // ACT-001: notation must equal "activities"
+  if (raw.notation === undefined) {
+    errors.push({ code: 'ACT-001', message: 'notation field is required' });
+    return { valid: false, errors, warnings };
+  }
+  if (raw.notation !== 'activities') {
+    errors.push({ code: 'ACT-001', message: `notation must be "activities", got "${String(raw.notation)}"` });
+    return { valid: false, errors, warnings };
+  }
+
+  if (!Array.isArray(raw.activities)) {
+    errors.push({ code: 'SCHEMA_INVALID', message: 'activities must be an array', path: 'activities' });
+    return { valid: false, errors, warnings };
+  }
+
+  // ACT-014 / ACT-015: project.calendar validation (run before per-activity loop;
+  // surfaces clearly even when activities also have issues).
+  if (raw.project && typeof raw.project === 'object') {
+    const project = raw.project as Record<string, unknown>;
+    const cal = project.calendar;
+    if (cal && typeof cal === 'object') {
+      const calendar = cal as Record<string, unknown>;
+      if (calendar.working_days !== undefined) {
+        if (!Array.isArray(calendar.working_days)) {
+          errors.push({ code: 'ACT-014', message: 'project.calendar.working_days must be an array of weekday names', path: 'project.calendar.working_days' });
+        } else {
+          const seen = new Set<string>();
+          for (let i = 0; i < calendar.working_days.length; i++) {
+            const raw = calendar.working_days[i];
+            const day = typeof raw === 'string' ? raw.toLowerCase() : '';
+            if (!VALID_WEEKDAYS.has(day)) {
+              errors.push({
+                code: 'ACT-014',
+                message: `project.calendar.working_days[${i}] "${String(raw)}" must be one of: mon, tue, wed, thu, fri, sat, sun`,
+                path: `project.calendar.working_days[${i}]`,
+              });
+            } else if (seen.has(day)) {
+              errors.push({
+                code: 'ACT-014',
+                message: `project.calendar.working_days has duplicate entry "${day}"`,
+                path: `project.calendar.working_days[${i}]`,
+              });
+            } else {
+              seen.add(day);
+            }
+          }
+        }
+      }
+      if (calendar.holidays !== undefined) {
+        if (!Array.isArray(calendar.holidays)) {
+          errors.push({ code: 'ACT-015', message: 'project.calendar.holidays must be an array of ISO 8601 dates', path: 'project.calendar.holidays' });
+        } else {
+          for (let i = 0; i < calendar.holidays.length; i++) {
+            const h = calendar.holidays[i];
+            if (typeof h !== 'string' || !DATE_RE.test(h)) {
+              errors.push({
+                code: 'ACT-015',
+                message: `project.calendar.holidays[${i}] "${String(h)}" must be an ISO 8601 date (YYYY-MM-DD)`,
+                path: `project.calendar.holidays[${i}]`,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const doc = raw as unknown as ActivityDoc;
+  const idSet = new Set<string>();
+
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i] as unknown;
+    const path = `activities[${i}]`;
+
+    if (!a || typeof a !== 'object') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'activity entry must be an object', path });
+      continue;
+    }
+    const act = a as Record<string, unknown>;
+
+    // ACT-010: reject single-value forms
+    if ('goal' in act) {
+      errors.push({ code: 'ACT-010', message: `Use "goals: []" array form instead of "goal:" (activity at index ${i})`, path });
+    }
+    if ('predecessor' in act) {
+      errors.push({ code: 'ACT-010', message: `Use "predecessors: []" array form instead of "predecessor:" (activity at index ${i})`, path });
+    }
+    if ('tag' in act) {
+      errors.push({ code: 'ACT-010', message: `Use "tags: []" array form instead of "tag:" (activity at index ${i})`, path });
+    }
+
+    // ACT-002: non-empty id
+    if (!act.id || typeof act.id !== 'string' || (act.id as string).trim() === '') {
+      errors.push({ code: 'ACT-002', message: `Activity at index ${i} is missing a non-empty id`, path });
+      continue;
+    }
+    const id = act.id as string;
+
+    // ACT-003: non-empty name
+    if (!act.name || typeof act.name !== 'string' || (act.name as string).trim() === '') {
+      errors.push({ code: 'ACT-003', message: `Activity "${id}" is missing a non-empty name`, path });
+    }
+
+    // ACT-004: unique ids
+    if (idSet.has(id)) {
+      errors.push({ code: 'ACT-004', message: `Duplicate activity id: "${id}"`, path });
+    } else {
+      idSet.add(id);
+    }
+
+    // ACT-009: non-negative numeric fields
+    const numericFields = ['duration', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort'] as const;
+    for (const field of numericFields) {
+      const val = act[field];
+      if (val !== undefined && val !== null) {
+        if (typeof val !== 'number' || val < 0) {
+          errors.push({ code: 'ACT-009', message: `Activity "${id}" field "${field}" must be a non-negative number, got ${String(val)}`, path });
+        }
+      }
+    }
+
+    // ACT-011: warn if no duration
+    if (act.duration === undefined || act.duration === null) {
+      warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — cannot participate in CPM analysis`, path });
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // Second pass — checks that need the full id set
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i];
+    const path = `activities[${i}]`;
+
+    // ACT-007: self-loop
+    if (Array.isArray(a.predecessors) && a.predecessors.includes(a.id)) {
+      errors.push({ code: 'ACT-007', message: `Activity "${a.id}" lists itself as a predecessor`, path });
+    }
+
+    // ACT-005: predecessor existence (intra-document)
+    for (const predId of (a.predecessors ?? [])) {
+      if (!idSet.has(predId)) {
+        errors.push({ code: 'ACT-005', message: `Activity "${a.id}" references unknown predecessor "${predId}"`, path });
+      }
+    }
+
+    // ACT-008: date format validation + end_date >= start_date.
+    // The orchestrator's pre-release review flagged that the raw lexicographic
+    // string compare is only correct for strict YYYY-MM-DD, with no format
+    // check applied. Now we validate the format first; the order compare runs
+    // only when both dates are valid (otherwise the comparison message would
+    // be misleading).
+    let startValid = true;
+    let endValid = true;
+    if (a.start_date !== undefined) {
+      if (typeof a.start_date !== 'string' || !DATE_RE.test(a.start_date)) {
+        errors.push({ code: 'ACT-008', message: `Activity "${a.id}" start_date "${String(a.start_date)}" must be ISO 8601 YYYY-MM-DD`, path });
+        startValid = false;
+      }
+    }
+    if (a.end_date !== undefined) {
+      if (typeof a.end_date !== 'string' || !DATE_RE.test(a.end_date)) {
+        errors.push({ code: 'ACT-008', message: `Activity "${a.id}" end_date "${String(a.end_date)}" must be ISO 8601 YYYY-MM-DD`, path });
+        endValid = false;
+      }
+    }
+    if (a.start_date && a.end_date && startValid && endValid) {
+      if (a.end_date < a.start_date) {
+        errors.push({ code: 'ACT-008', message: `Activity "${a.id}" end_date "${a.end_date}" is before start_date "${a.start_date}"`, path });
+      }
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // ACT-006: no cycles
+  const cycleError = detectCycle(doc.activities);
+  if (cycleError) errors.push(cycleError);
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // ACT-012: date/duration consistency (warning only)
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i];
+    if (a.start_date && a.end_date && a.duration !== undefined) {
+      const start = new Date(a.start_date).getTime();
+      const end = new Date(a.end_date).getTime();
+      const diffDays = Math.round((end - start) / 86400000);
+      if (Math.abs(diffDays - a.duration) > 1) {
+        warnings.push({
+          code: 'ACT-012',
+          message: `Activity "${a.id}" duration ${a.duration} is inconsistent with date range of ~${diffDays} days`,
+          path: `activities[${i}]`,
+        });
+      }
+    }
+  }
+
+  // ACT-013: orphan activities (warning only)
+  const successorIds = new Set<string>();
+  for (const a of doc.activities) {
+    for (const pred of (a.predecessors ?? [])) successorIds.add(pred);
+  }
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i];
+    const hasSuccessors = successorIds.has(a.id);
+    const hasGoals = Array.isArray(a.goals) && a.goals.length > 0;
+    const hasPredecessors = Array.isArray(a.predecessors) && a.predecessors.length > 0;
+    if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors) {
+      warnings.push({
+        code: 'ACT-013',
+        message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, or goals)`,
+        path: `activities[${i}]`,
+      });
+    }
+  }
+
+  // ACT-016: milestone (duration=0) with both pinned dates MUST have start == end.
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i];
+    if (a.duration === 0 && a.start_date && a.end_date && a.start_date !== a.end_date) {
+      errors.push({
+        code: 'ACT-016',
+        message: `Milestone "${a.id}" has duration 0 but start_date "${a.start_date}" ≠ end_date "${a.end_date}"`,
+        path: `activities[${i}]`,
+      });
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // ACT-017 / ACT-018: phase warnings. A "phase" is an activity that is referenced
+  // by another activity's `parent` field. ACT-017 warns when a phase carries its
+  // own duration/dates (those roll up from children). ACT-018 warns when an
+  // activity that looks like a phase (no duration, no pinned dates) has no
+  // children — possibly an unused placeholder.
+  const childCount = new Map<string, number>();
+  for (const a of doc.activities) {
+    if (typeof a.parent === 'string' && a.parent.length > 0) {
+      childCount.set(a.parent, (childCount.get(a.parent) ?? 0) + 1);
+    }
+  }
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i];
+    const isReferencedAsParent = (childCount.get(a.id) ?? 0) > 0;
+    if (isReferencedAsParent) {
+      const carriesOwnTiming =
+        (a.duration !== undefined && a.duration !== null) ||
+        typeof a.start_date === 'string' ||
+        typeof a.end_date === 'string';
+      if (carriesOwnTiming) {
+        warnings.push({
+          code: 'ACT-017',
+          message: `Phase "${a.id}" carries its own duration/dates — those should roll up from children, not be authored directly`,
+          path: `activities[${i}]`,
+        });
+      }
+    } else {
+      // Not referenced as parent. ACT-018 only fires when the activity LOOKS
+      // like a phase: no duration declared and no pinned dates. A leaf without
+      // duration is already covered by ACT-011 — the same activity may surface
+      // both warnings, which is correct (separate concerns: CPM-unfit vs
+      // empty-phase).
+      const looksLikePhase =
+        (a.duration === undefined || a.duration === null) &&
+        !a.start_date &&
+        !a.end_date;
+      if (looksLikePhase) {
+        warnings.push({
+          code: 'ACT-018',
+          message: `Activity "${a.id}" has no duration and no children — may be an empty phase`,
+          path: `activities[${i}]`,
+        });
+      }
+    }
+  }
+
+  // ACT-019: Gantt view will not render when neither project.start_date nor
+  // any per-activity pinned date pair is present. Network view is unaffected.
+  const hasProjectStart = typeof doc.project?.start_date === 'string' && doc.project.start_date.length > 0;
+  const hasPinnedActivity = doc.activities.some(
+    (a) => typeof a.start_date === 'string' && typeof a.end_date === 'string',
+  );
+  if (!hasProjectStart && !hasPinnedActivity) {
+    warnings.push({
+      code: 'ACT-019',
+      message: 'Gantt view will not render: project.start_date is absent and no activity has both start_date and end_date pinned. Network view is unaffected.',
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function detectCycle(activities: Activity[]): ActivityValidationError | null {
+  const successors = new Map<string, string[]>();
+  for (const a of activities) {
+    successors.set(a.id, []);
+  }
+  for (const a of activities) {
+    for (const pred of (a.predecessors ?? [])) {
+      const list = successors.get(pred);
+      if (list) list.push(a.id);
+    }
+  }
+
+  // Kahn's algorithm: if we can't process all nodes, there's a cycle
+  const inDegree = new Map<string, number>();
+  for (const a of activities) inDegree.set(a.id, 0);
+  for (const a of activities) {
+    for (const pred of (a.predecessors ?? [])) {
+      inDegree.set(a.id, (inDegree.get(a.id) ?? 0) + 1);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id);
+  }
+
+  let processed = 0;
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    processed++;
+    for (const succ of (successors.get(id) ?? [])) {
+      const newDeg = (inDegree.get(succ) ?? 1) - 1;
+      inDegree.set(succ, newDeg);
+      if (newDeg === 0) queue.push(succ);
+    }
+  }
+
+  if (processed < activities.length) {
+    const cycleNodes = activities.filter(a => (inDegree.get(a.id) ?? 0) > 0).map(a => a.id);
+    return { code: 'ACT-006', message: `Cycle detected in activity dependency graph involving: ${cycleNodes.join(', ')}` };
+  }
+  return null;
+}

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

@@ -0,0 +1,66 @@
+// Conformance test for the shipped worked example. Exercises the full
+// validate → resolve → layout pipeline against the real co-located example
+// files under `tests/fixtures/notation-corpus/activity-card/`, so the success signal of #134 is
+// pinned and any drift in the example or the resolver is caught by CI.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateActivityCard } from '../validate.js';
+import { resolveActivityCard } from '../resolver.js';
+import { layoutActivityCard } from '../layout.js';
+import type { ActivityCardDoc } from '../types.js';
+
+const dir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../../tests/fixtures/notation-corpus/activity-card',
+);
+const load = (f: string): unknown => yaml.load(readFileSync(path.join(dir, f), 'utf-8'));
+
+/** Recursively load every `*.yaml` doc under a canon subtree (mirrors the
+ *  extension's element/relation walk). */
+function loadYamlTree(root: string): unknown[] {
+  const out: unknown[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) out.push(...loadYamlTree(full));
+    else if (entry.name.endsWith('.yaml')) out.push(yaml.load(readFileSync(full, 'utf-8')));
+  }
+  return out;
+}
+
+describe('activity-card worked example (eu-programme)', () => {
+  it('validates, resolves, and lays out the success-signal card', () => {
+    const card = load('eu-programme.activity-card.transitrix.yaml');
+    const elements = loadYamlTree(path.join(dir, 'canon', 'elements'));
+    const relations = loadYamlTree(path.join(dir, 'canon', 'relations'));
+
+    const v = validateActivityCard(card);
+    expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+
+    const r = resolveActivityCard(card as ActivityCardDoc, { elements, relations });
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.warnings, JSON.stringify(r.warnings)).toHaveLength(0);
+
+    const c = r.resolved!;
+    expect(c.project.name).toBe('EU MDR conformity programme');
+    expect(c.project.valid_from).toBe('2026-04-01');
+    expect(c.project.start_date).toBe('2026-04-15');
+    expect(c.project.end_date).toBe('2027-03-15');
+    expect(c.milestones.map((m) => m.id)).toEqual([
+      '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.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);
+
+    const layout = layoutActivityCard(c);
+    expect(layout.bounds.height).toBeGreaterThan(0);
+    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/src/activity-card/__tests__/layout.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { layoutActivityCard, ARCHIMATE_CLASS } from '../layout.js';
+import type { ResolvedActivityCard } from '../types.js';
+
+const RESOLVED: ResolvedActivityCard = {
+  cardId: 'ACTIVITY_CARD-EU-PROGRAMME-1',
+  cardDescription: 'Summary',
+  project: {
+    id: 'ACTIVITY-EU-PROGRAMME-1',
+    name: 'EU MDR conformity programme',
+    valid_from: '2026-04-01',
+    start_date: '2026-04-15',
+    end_date: '2027-03-15',
+  },
+  milestones: [
+    { 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'] }],
+    changes: [{ id: 'CHANGE-EU-COMPLIANCE-1', name: 'Achieve MDR compliance', goalIds: ['GOAL-EU-MARKET-1'] }],
+  },
+  childActivities: [
+    { id: 'ACTIVITY-EU-CHILD-1', name: 'Notified-body engagement', start_date: '2026-05-01', end_date: '2026-12-01', owner: 'UNIT-REGULATORY' },
+  ],
+};
+
+describe('layoutActivityCard', () => {
+  it('produces all sections with positive geometry', () => {
+    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');
+    expect(l.dateFields).toHaveLength(3);
+    expect(l.dateFields[0]).toMatchObject({ label: 'Initiation', value: '2026-04-01' });
+    expect(l.milestones).toHaveLength(1);
+    expect(l.milestones[0].archimateClass).toBe(ARCHIMATE_CLASS.MILESTONE);
+    expect(l.childActivities[0].archimateClass).toBe(ARCHIMATE_CLASS.ACTIVITY);
+  });
+
+  it('builds F→G and G→C 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('renders "—" for absent dates', () => {
+    const l = layoutActivityCard({ ...RESOLVED, project: { id: 'A', name: 'n' } });
+    expect(l.dateFields.map((d) => d.value)).toEqual(['—', '—', '—']);
+  });
+
+  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: [] },
+      childActivities: [],
+    });
+    expect(l.milestones).toHaveLength(0);
+    expect(l.bounds.height).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,161 @@
+import { describe, it, expect } from 'vitest';
+import { resolveActivityCard } from '../resolver.js';
+import type { ActivityCardDoc } from '../types.js';
+
+const CARD: ActivityCardDoc = {
+  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-CERT-1', name: 'Cert', date: '2027-01-31', delivers_changes: ['CHANGE-EU-COMPLIANCE-1'] },
+    ],
+  },
+};
+
+// ── Canon element store (one element per object) ─────────────────────────────
+const PROJECT = {
+  notation: 'activity',
+  id: 'ACTIVITY-EU-PROGRAMME-1',
+  name: 'EU MDR conformity programme',
+  valid_from: '2026-04-01',
+  valid_to: null,
+  start_date: '2026-04-15',
+  end_date: '2027-03-15',
+  delivers_changes: ['CHANGE-EU-COMPLIANCE-1'],
+};
+const CHILD = {
+  notation: 'activity',
+  id: 'ACTIVITY-EU-CHILD-1',
+  name: 'Notified-body engagement',
+  parent: 'ACTIVITY-EU-PROGRAMME-1',
+  start_date: '2026-05-01',
+  end_date: '2026-12-01',
+  owner: 'ACTOR-REGULATORY-1',
+};
+const UNRELATED = {
+  notation: 'activity',
+  id: 'ACTIVITY-UNRELATED-1',
+  name: 'Other',
+  parent: 'ACTIVITY-SOMETHING-ELSE-1',
+};
+const FACTOR = { notation: 'factor', 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',
+  id: 'CHANGE-EU-COMPLIANCE-1',
+  name: 'Achieve MDR compliance',
+  goals: ['GOAL-EU-MARKET-1'],
+};
+
+// ── Canon relation store ─────────────────────────────────────────────────────
+// The project's goal link is a first-class `activity_goal` relation, not an
+// inline `goals:` field on the activity element.
+const REL_GOAL = {
+  notation: 'relation',
+  id: 'REL-EU-PROGRAMME-GOAL-1',
+  type: 'activity_goal',
+  from: 'ACTIVITY-EU-PROGRAMME-1',
+  to: 'GOAL-EU-MARKET-1',
+  valid_from: '2026-04-01',
+  valid_to: null,
+};
+
+const elements = [PROJECT, CHILD, UNRELATED, FACTOR, GOAL, CHANGE];
+const relations = [REL_GOAL];
+const sources = { elements, relations };
+
+describe('resolveActivityCard', () => {
+  it('resolves a full card from elements + relations', () => {
+    const r = resolveActivityCard(CARD, sources);
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    const c = r.resolved!;
+    expect(c.project.name).toBe('EU MDR conformity programme');
+    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.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']);
+  });
+
+  it('falls back to the inline goals field when no activity_goal relation exists', () => {
+    const projectWithInline = { ...PROJECT, goals: ['GOAL-EU-MARKET-1'] };
+    const r = resolveActivityCard(CARD, {
+      elements: [projectWithInline, CHILD, FACTOR, GOAL, CHANGE],
+      relations: [],
+    });
+    expect(r.valid).toBe(true);
+    expect(r.resolved!.motivation.goals.map((g) => g.id)).toEqual(['GOAL-EU-MARKET-1']);
+  });
+
+  it('PC-001 when the project activity element is absent', () => {
+    const r = resolveActivityCard(CARD, { elements: [FACTOR, GOAL, CHANGE], relations });
+    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', () => {
+    const r = resolveActivityCard(CARD, {
+      elements: [{ ...PROJECT, activity_type: 'Task' }, CHILD, FACTOR, GOAL, CHANGE],
+      relations,
+    });
+    expect(r.errors.some((e) => e.code === 'PC-002')).toBe(true);
+  });
+
+  it('PC-003 when a milestone change is not in the project changes', () => {
+    const card: ActivityCardDoc = {
+      ...CARD,
+      activity_card: {
+        ...CARD.activity_card,
+        milestones: [{ id: 'MILESTONE-X-1', name: 'x', date: '2027-01-01', delivers_changes: ['CHANGE-NOT-THERE-1'] }],
+      },
+    };
+    const r = resolveActivityCard(card, sources);
+    expect(r.errors.some((e) => e.code === 'PC-003')).toBe(true);
+  });
+
+  it('PC-004 warns when a milestone falls outside the lifecycle window', () => {
+    const r = resolveActivityCard(CARD, {
+      elements: [{ ...PROJECT, valid_to: '2026-12-31' }, CHILD, FACTOR, GOAL, CHANGE],
+      relations,
+    });
+    expect(r.valid).toBe(true);
+    expect(r.warnings.some((w) => w.code === 'PC-004')).toBe(true);
+  });
+
+  it('LIFECYCLE-001 when valid_from is missing', () => {
+    const r = resolveActivityCard(CARD, {
+      elements: [{ ...PROJECT, valid_from: undefined }, CHILD, FACTOR, GOAL, CHANGE],
+      relations,
+    });
+    expect(r.errors.some((e) => e.code === 'LIFECYCLE-001')).toBe(true);
+  });
+
+  it('LIFECYCLE-003 when valid_to precedes valid_from', () => {
+    const r = resolveActivityCard(CARD, {
+      elements: [{ ...PROJECT, valid_to: '2025-01-01' }, CHILD, FACTOR, GOAL, CHANGE],
+      relations,
+    });
+    expect(r.errors.some((e) => e.code === 'LIFECYCLE-003')).toBe(true);
+  });
+
+  it('warns and omits when a change element is not found in canon', () => {
+    const r = resolveActivityCard(CARD, { elements: [PROJECT, CHILD, FACTOR, GOAL], relations });
+    expect(r.valid).toBe(true);
+    expect(r.resolved!.motivation.changes).toHaveLength(0);
+    expect(r.warnings.some((w) => w.code === 'PC-001')).toBe(true);
+  });
+
+  it('does not crash on malformed element/relation docs', () => {
+    const r = resolveActivityCard(CARD, {
+      elements: [null, 'x', PROJECT, 42, { notation: 'goal', id: null }],
+      relations: [null, 'x', { notation: 'relation' }],
+    });
+    expect(r.valid).toBe(true);
+  });
+});