@transitrix/diagrams 1.0.0

package/src/fgca/__tests__/layout.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect, vi, beforeAll } from "vitest";
+
+// reactflow uses browser APIs — stub the minimum required before importing layout
+beforeAll(() => {
+  vi.mock("reactflow", () => ({
+    Position: { Left: "left", Right: "right" },
+    MarkerType: { ArrowClosed: "arrowclosed" },
+  }));
+});
+
+import { buildFGCALayout } from "../layout";
+import type { FactorItem, GoalItem, BdnChangeWithActivities, ActivityItem } from "../types";
+import { ALL_FGCA_COLUMNS } from "../types";
+
+const ALL_COLS = new Set(ALL_FGCA_COLUMNS);
+
+const factors: FactorItem[] = [
+  { id: 1, name: "Digital growth" },
+  { id: 2, name: "Talent shortage" },
+];
+
+const goals: GoalItem[] = [
+  { id: 10, name: "Grow revenue", level: 0, factor: [{ id: 1 }] },
+  { id: 11, name: "Build talent pipeline", level: 1, factor: [{ id: 2 }] },
+];
+
+const changes: BdnChangeWithActivities[] = [
+  { id: 100, name: "Launch digital channel", goal_id: 10, activity_ids: [200] },
+  { id: 101, name: "Partner with bootcamps", goal_id: 11, activity_ids: [201] },
+];
+
+const activities: ActivityItem[] = [
+  { id: 200, name: "Build e-commerce MVP", goal_id: 10, activity_type_id: 1 },
+  { id: 201, name: "Run hiring sprint", goal_id: 11, activity_type_id: 1 },
+];
+
+describe("buildFGCALayout — all columns visible", () => {
+  const { nodes, edges } = buildFGCALayout({
+    factors,
+    goals,
+    changes,
+    activities,
+    visibleColumns: ALL_COLS,
+    activityTypeList: [{ id: 1, name: "Initiative" }],
+  });
+
+  it("produces the correct number of nodes", () => {
+    expect(nodes).toHaveLength(factors.length + goals.length + changes.length + activities.length);
+  });
+
+  it("assigns correct node types", () => {
+    const types = nodes.map((n) => n.type);
+    expect(types.filter((t) => t === "fgcaFactor")).toHaveLength(factors.length);
+    expect(types.filter((t) => t === "fgcaGoal")).toHaveLength(goals.length);
+    expect(types.filter((t) => t === "fgcaChange")).toHaveLength(changes.length);
+    expect(types.filter((t) => t === "fgcaActivity")).toHaveLength(activities.length);
+  });
+
+  it("creates Factor→Goal edges", () => {
+    const fgEdges = edges.filter((e) => e.source.startsWith("factor_") && e.target.startsWith("goal_"));
+    expect(fgEdges).toHaveLength(2);
+    expect(fgEdges.find((e) => e.source === "factor_1" && e.target === "goal_10")).toBeTruthy();
+  });
+
+  it("creates Goal→Change edges", () => {
+    const gcEdges = edges.filter((e) => e.source.startsWith("goal_") && e.target.startsWith("change_"));
+    expect(gcEdges).toHaveLength(2);
+  });
+
+  it("creates Change→Activity edges", () => {
+    const caEdges = edges.filter((e) => e.source.startsWith("change_") && e.target.startsWith("activity_"));
+    expect(caEdges).toHaveLength(2);
+  });
+
+  it("does NOT create direct Goal→Activity edges when Change column is visible and all activities are covered", () => {
+    const directEdges = edges.filter(
+      (e) => e.source.startsWith("goal_") && e.target.startsWith("activity_")
+    );
+    expect(directEdges).toHaveLength(0);
+  });
+
+  it("uses the activity type name in activity node data", () => {
+    const actNode = nodes.find((n) => n.id === "activity_200");
+    expect(actNode?.data.activityTypeName).toBe("Initiative");
+  });
+
+  it("encodes F-XXXX label format via id in node data", () => {
+    const factorNode = nodes.find((n) => n.id === "factor_1");
+    expect(String(factorNode?.data.id).padStart(4, "0")).toBe("0001");
+  });
+
+  it("encodes C-XXX label format via id in node data", () => {
+    const changeNode = nodes.find((n) => n.id === "change_100");
+    expect(String(changeNode?.data.id).padStart(3, "0")).toBe("100");
+  });
+});
+
+describe("buildFGCALayout — Factor column hidden", () => {
+  const cols = new Set(ALL_FGCA_COLUMNS.filter((c) => c !== "factor"));
+  const { nodes, edges } = buildFGCALayout({ factors, goals, changes, activities, visibleColumns: cols });
+
+  it("produces no factor nodes", () => {
+    expect(nodes.filter((n) => n.type === "fgcaFactor")).toHaveLength(0);
+  });
+
+  it("produces no Factor→Goal edges", () => {
+    expect(edges.filter((e) => e.source.startsWith("factor_"))).toHaveLength(0);
+  });
+
+  it("still produces Goal and downstream nodes", () => {
+    expect(nodes.filter((n) => n.type === "fgcaGoal")).toHaveLength(goals.length);
+  });
+});
+
+describe("buildFGCALayout — Change column hidden", () => {
+  const cols = new Set(ALL_FGCA_COLUMNS.filter((c) => c !== "change"));
+  const { nodes, edges } = buildFGCALayout({ factors, goals, changes, activities, visibleColumns: cols });
+
+  it("produces no change nodes", () => {
+    expect(nodes.filter((n) => n.type === "fgcaChange")).toHaveLength(0);
+  });
+
+  it("creates direct Goal→Activity edges when Change column is hidden", () => {
+    const directEdges = edges.filter(
+      (e) => e.source.startsWith("goal_") && e.target.startsWith("activity_")
+    );
+    expect(directEdges.length).toBeGreaterThan(0);
+  });
+});
+
+describe("buildFGCALayout — only one column visible", () => {
+  const { nodes, edges } = buildFGCALayout({
+    factors,
+    goals,
+    changes,
+    activities,
+    visibleColumns: new Set(["goal"] as const),
+  });
+
+  it("produces only goal nodes", () => {
+    expect(nodes.filter((n) => n.type !== "fgcaGoal")).toHaveLength(0);
+  });
+
+  it("produces no edges", () => {
+    expect(edges).toHaveLength(0);
+  });
+});
+
+describe("buildFGCALayout — columns are positioned left to right", () => {
+  const { nodes } = buildFGCALayout({ factors, goals, changes, activities, visibleColumns: ALL_COLS });
+
+  it("factor column x < goal column x", () => {
+    const f = nodes.find((n) => n.type === "fgcaFactor")!;
+    const g = nodes.find((n) => n.type === "fgcaGoal")!;
+    expect(f.position.x).toBeLessThan(g.position.x);
+  });
+
+  it("goal column x < change column x", () => {
+    const g = nodes.find((n) => n.type === "fgcaGoal")!;
+    const c = nodes.find((n) => n.type === "fgcaChange")!;
+    expect(g.position.x).toBeLessThan(c.position.x);
+  });
+
+  it("change column x < activity column x", () => {
+    const c = nodes.find((n) => n.type === "fgcaChange")!;
+    const a = nodes.find((n) => n.type === "fgcaActivity")!;
+    expect(c.position.x).toBeLessThan(a.position.x);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it("[blocker] tolerates a change with no activity_ids (optional per validator)", () => {
+    const changesNoIds: BdnChangeWithActivities[] = [
+      { id: 100, name: "No activities", goal_id: 10 } as BdnChangeWithActivities,
+    ];
+    expect(() =>
+      buildFGCALayout({ factors, goals, changes: changesNoIds, activities, visibleColumns: ALL_COLS }),
+    ).not.toThrow();
+  });
+});

package/src/fgca/__tests__/parse-canonical.test.ts

@@ -0,0 +1,248 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { parseCanonicalFGCA, parseCanonicalFGA } from '../parse-canonical.js';
+
+const VALID = {
+  notation: 'fgca',
+  spec_version: '0.1',
+  id: 'FGCA-SAMPLE-1',
+  name: 'Sample FGCA chain',
+  factors: [
+    { id: 'FACTOR-1', name: 'Driver one', type: 'external' },
+  ],
+  goals: [
+    { id: 'GOAL-1', name: 'Outcome one', factors: ['FACTOR-1'] },
+  ],
+  changes: [
+    { id: 'CHANGE-1', name: 'Transformation', goals: ['GOAL-1'] },
+  ],
+  activities: [
+    { id: 'ACTIVITY-1', name: 'Workstream', changes: ['CHANGE-1'] },
+  ],
+};
+
+describe('parseCanonicalFGCA', () => {
+  it('accepts a valid canonical document', () => {
+    const r = parseCanonicalFGCA(VALID);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toEqual([]);
+    expect(r.parsed).toBeDefined();
+    expect(r.parsed?.factors).toHaveLength(1);
+    expect(r.parsed?.goals).toHaveLength(1);
+    expect(r.parsed?.changes).toHaveLength(1);
+    expect(r.parsed?.activities).toHaveLength(1);
+  });
+
+  it('FGCA-001: rejects non-object input', () => {
+    expect(parseCanonicalFGCA(null).errors[0].code).toBe('FGCA-001');
+    expect(parseCanonicalFGCA('string').errors[0].code).toBe('FGCA-001');
+  });
+
+  it('FGCA-001: rejects wrong notation', () => {
+    const r = parseCanonicalFGCA({ ...VALID, notation: 'fga' });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-001')).toBe(true);
+  });
+
+  it('FGCA-002: rejects malformed doc id', () => {
+    const r = parseCanonicalFGCA({ ...VALID, id: 'fgca-lowercase-1' });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-002')).toBe(true);
+  });
+
+  it('FGCA-003: rejects missing name', () => {
+    const { name: _, ...rest } = VALID;
+    const r = parseCanonicalFGCA(rest);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-003')).toBe(true);
+  });
+
+  it('FGCA-004: rejects missing factors array', () => {
+    const { factors: _, ...rest } = VALID;
+    const r = parseCanonicalFGCA(rest);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-004')).toBe(true);
+  });
+
+  it('FGCA-006: rejects duplicate IDs within a layer', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      factors: [
+        { id: 'FACTOR-1', name: 'A' },
+        { id: 'FACTOR-1', name: 'B' },
+      ],
+    });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-006')).toBe(true);
+  });
+
+  it('FGCA-007: rejects malformed factor id', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      factors: [{ id: 'F-1', name: 'A' }],
+    });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-007')).toBe(true);
+  });
+
+  it('FGCA-008: rejects goal.factors[] referencing undefined factor', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      goals: [{ id: 'GOAL-1', name: 'A', factors: ['FACTOR-99'] }],
+    });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-008')).toBe(true);
+  });
+
+  it('FGCA-009: rejects change.goals[] referencing undefined goal', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      changes: [{ id: 'CHANGE-1', name: 'A', goals: ['GOAL-99'] }],
+    });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-009')).toBe(true);
+  });
+
+  it('FGCA-010: rejects activity.changes[] referencing undefined change', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      activities: [{ id: 'ACTIVITY-1', name: 'A', changes: ['CHANGE-99'] }],
+    });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-010')).toBe(true);
+  });
+
+  it('FGCA-015: rejects factor.references_constraint with malformed ID', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      factors: [{ id: 'FACTOR-1', name: 'A', references_constraint: ['BAD-1'] }],
+    });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGCA-015')).toBe(true);
+  });
+
+  it('accepts factor.references_constraint with valid CONSTRAINT ID', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      factors: [{ id: 'FACTOR-1', name: 'A', references_constraint: ['CONSTRAINT-GDPR-1'] }],
+    });
+    expect(r.valid).toBe(true);
+  });
+
+  it('populates internal change.activity_ids from canonical activity.changes (reversed direction)', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      changes: [{ id: 'CHANGE-1', name: 'C', goals: ['GOAL-1'] }],
+      activities: [
+        { id: 'ACTIVITY-1', name: 'A1', changes: ['CHANGE-1'] },
+        { id: 'ACTIVITY-2', name: 'A2', changes: ['CHANGE-1'] },
+      ],
+    });
+    expect(r.valid).toBe(true);
+    expect(r.parsed?.changes[0].activity_ids).toHaveLength(2);
+  });
+});
+
+// The "FGCA preview blank / FGA no edges" regression (vkgeorgia/strategy#65,
+// transitrix/methodology#65) was a data defect: the canonical flat shape was
+// not being mapped to the internal cross-ref fields the renderer turns into
+// edges. These assert the edge-driving fields are populated, so the renderer
+// has something to draw — locking the fix.
+describe('parseCanonicalFGCA — edge-driving fields populated', () => {
+  it('maps goal.factors → goal.factor[], change.goals → change.goal_id, activity.changes → change.activity_ids', () => {
+    const r = parseCanonicalFGCA(VALID);
+    expect(r.valid).toBe(true);
+    const parsed = r.parsed!;
+    // factor → goal edge source
+    expect(parsed.goals[0].factor).toHaveLength(1);
+    // goal → change edge
+    expect(parsed.changes[0].goal_id).not.toBe(0);
+    // change → activity edge
+    expect(parsed.changes[0].activity_ids).toHaveLength(1);
+  });
+});
+
+describe('parseCanonicalFGA', () => {
+  const VALID_FGA = {
+    notation: 'fga',
+    spec_version: '0.1',
+    id: 'FGA-SAMPLE-1',
+    name: 'Sample FGA chain',
+    factors: [{ id: 'FACTOR-1', name: 'Driver' }],
+    goals: [{ id: 'GOAL-1', name: 'Outcome', factors: ['FACTOR-1'] }],
+    activities: [{ id: 'ACTIVITY-1', name: 'Workstream', goals: ['GOAL-1'] }],
+  };
+
+  it('accepts a valid canonical FGA document (no changes layer)', () => {
+    const r = parseCanonicalFGA(VALID_FGA);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toEqual([]);
+    expect(r.parsed?.factors).toHaveLength(1);
+    expect(r.parsed?.goals).toHaveLength(1);
+    expect(r.parsed?.activities).toHaveLength(1);
+  });
+
+  it('populates activity.goal_id from activity.goals[] (the FGA edge-driving field)', () => {
+    // The "FGA nodes render, no edges" bug: activities had no resolvable
+    // goal_id, so the renderer drew no goal → activity edges.
+    const r = parseCanonicalFGA(VALID_FGA);
+    expect(r.valid).toBe(true);
+    expect(r.parsed?.activities[0].goal_id).not.toBeNull();
+    expect(r.parsed?.activities[0].goal_id).not.toBe(0);
+  });
+
+  it('FGA-001: rejects wrong notation', () => {
+    const r = parseCanonicalFGA({ ...VALID_FGA, notation: 'fgca' });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGA-001')).toBe(true);
+  });
+
+  it('FGA-002: rejects malformed doc id', () => {
+    const r = parseCanonicalFGA({ ...VALID_FGA, id: 'fga-lower-1' });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGA-002')).toBe(true);
+  });
+
+  it('remaps FGCA layer codes into the FGA registry (e.g. FGA-007 for a bad id)', () => {
+    const r = parseCanonicalFGA({ ...VALID_FGA, factors: [{ id: 'F-1', name: 'bad' }] });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some((e) => e.code === 'FGA-007')).toBe(true);
+    // No raw FGCA-prefixed code should leak through the remap.
+    expect(r.errors.every((e) => !e.code.startsWith('FGCA-'))).toBe(true);
+  });
+});
+
+describe('parseCanonicalFGCA — example file regression', () => {
+  const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'fgca');
+  const files = fs.existsSync(EXAMPLES_DIR)
+    ? fs.readdirSync(EXAMPLES_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+    : [];
+  for (const file of files) {
+    it(`accepts tests/fixtures/notation-corpus/fgca/${file}`, () => {
+      const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+      const parsedYaml = yaml.load(text);
+      const r = parseCanonicalFGCA(parsedYaml);
+      expect(r.errors).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+  }
+});
+
+describe('parseCanonicalFGA — example file regression', () => {
+  const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'fga');
+  const files = fs.existsSync(EXAMPLES_DIR)
+    ? fs.readdirSync(EXAMPLES_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+    : [];
+  for (const file of files) {
+    it(`accepts tests/fixtures/notation-corpus/fga/${file} and resolves every activity to a goal`, () => {
+      const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+      const r = parseCanonicalFGA(yaml.load(text));
+      expect(r.errors).toEqual([]);
+      expect(r.valid).toBe(true);
+      // Every activity must carry a goal_id, or the FGA preview draws no edges.
+      expect(r.parsed!.activities.every((a) => a.goal_id != null && a.goal_id !== 0)).toBe(true);
+    });
+  }
+});

package/src/fgca/__tests__/preview-layout.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from 'vitest';
+import {
+  layoutFGCAPreview,
+  FGCA_PAD,
+  FGCA_NODE_W,
+  type FGCAPreviewDoc,
+} from '../preview-layout.js';
+
+const doc: FGCAPreviewDoc = {
+  factors: [
+    { id: 1, name: 'F1' },
+    { id: 2, name: 'F2' },
+  ],
+  goals: [
+    { id: 10, name: 'G1', factor: [{ id: 1 }] },
+    { id: 11, name: 'G2', factor: [{ id: 2 }] },
+  ],
+  changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
+  activities: [
+    { id: 30, name: 'A1', goal_id: 10 },
+    { id: 31, name: 'A2', goal_id: 11 },
+  ],
+};
+
+describe('layoutFGCAPreview', () => {
+  it('lays out all four columns in order (FGCA)', () => {
+    const layout = layoutFGCAPreview(doc);
+    expect(layout.columns.map(c => c.col)).toEqual(['factor', 'goal', 'change', 'activity']);
+    // 2 factors + 2 goals + 1 change + 2 activities
+    expect(layout.nodes).toHaveLength(7);
+    expect(layout.width).toBeGreaterThan(0);
+    expect(layout.height).toBeGreaterThan(0);
+  });
+
+  it('produces the expected FGCA edge set', () => {
+    // F1→G1, F2→G2 (2), G1→C1 (1), C1→A1 (1), G2→A2 direct (1) = 5
+    const layout = layoutFGCAPreview(doc);
+    expect(layout.edges).toHaveLength(5);
+  });
+
+  it('hideChanges (FGA) drops the Changes column and links goals to activities', () => {
+    const layout = layoutFGCAPreview(doc, { hideChanges: true });
+    expect(layout.columns.map(c => c.col)).toEqual(['factor', 'goal', 'activity']);
+    // 2 factors + 2 goals + 2 activities
+    expect(layout.nodes).toHaveLength(6);
+    // F1→G1, F2→G2 (2), G1→A1, G2→A2 (2) = 4
+    expect(layout.edges).toHaveLength(4);
+  });
+
+  it('first column sits at the pad origin', () => {
+    const layout = layoutFGCAPreview(doc);
+    expect(layout.columns[0].x).toBe(FGCA_PAD);
+  });
+
+  it('empty options reproduce the default layout', () => {
+    const a = layoutFGCAPreview(doc);
+    const b = layoutFGCAPreview(doc, {});
+    expect(b.nodes.map(n => `${n.id}:${n.x},${n.y}`)).toEqual(a.nodes.map(n => `${n.id}:${n.x},${n.y}`));
+  });
+
+  it('larger colGap widens the column step', () => {
+    const stepOf = (colGap: number) => {
+      const cols = layoutFGCAPreview(doc, { colGap }).columns;
+      return cols[1].x - cols[0].x;
+    };
+    expect(stepOf(80)).toBe(FGCA_NODE_W + 80);
+    expect(stepOf(240)).toBe(FGCA_NODE_W + 240);
+    expect(stepOf(240)).toBeGreaterThan(stepOf(80));
+  });
+
+  it('larger rowGap increases the gap between stacked nodes', () => {
+    const gapOf = (rowGap: number) => {
+      const factors = layoutFGCAPreview(doc, { rowGap }).nodes.filter(n => n.col === 'factor');
+      return factors[1].y - factors[0].y;
+    };
+    expect(gapOf(120)).toBeGreaterThan(gapOf(20));
+  });
+
+  // vkgeorgia/strategy#77 — scope filtering. FGCA goals are flat, so 'root'
+  // selects the single matching goal plus the factors/changes/activities that
+  // touch it.
+  describe('scope', () => {
+    const idsOf = (layout: ReturnType<typeof layoutFGCAPreview>) => new Set(layout.nodes.map(n => n.id));
+
+    it("mode 'root' keeps only the root goal and what connects to it", () => {
+      // root 10 → factor 1 (referenced by G10), change 20 (goal_id 10),
+      // activity 30 (via change 20). G11/F2/A31 are dropped.
+      const layout = layoutFGCAPreview(doc, { scope: { mode: 'root', rootGoalId: '10' } });
+      expect(idsOf(layout)).toEqual(new Set(['factor_1', 'goal_10', 'change_20', 'activity_30']));
+    });
+
+    it("mode 'root' filters factors and activities to those touching the visible goal", () => {
+      // root 11 → factor 2, activity 31 (direct goal link); no change touches G11.
+      const layout = layoutFGCAPreview(doc, { scope: { mode: 'root', rootGoalId: '11' } });
+      expect(idsOf(layout)).toEqual(new Set(['factor_2', 'goal_11', 'activity_31']));
+      // F1, A30, C20 (which only touch the hidden G10) are excluded.
+      expect(layout.nodes.some(n => n.id === 'factor_1')).toBe(false);
+      expect(layout.nodes.some(n => n.id === 'activity_30')).toBe(false);
+    });
+
+    it("mode 'level' trims goals above the cap and their connections", () => {
+      const leveled: FGCAPreviewDoc = {
+        factors: [{ id: 1, name: 'F1' }, { id: 2, name: 'F2' }],
+        goals: [
+          { id: 10, name: 'G1', level: 0, factor: [{ id: 1 }] },
+          { id: 11, name: 'G2', level: 1, factor: [{ id: 2 }] },
+        ],
+        changes: [],
+        activities: [
+          { id: 30, name: 'A1', goal_id: 10 },
+          { id: 31, name: 'A2', goal_id: 11 },
+        ],
+      };
+      const layout = layoutFGCAPreview(leveled, { scope: { mode: 'level', maxLevel: 0 } });
+      expect(idsOf(layout)).toEqual(new Set(['factor_1', 'goal_10', 'activity_30']));
+    });
+
+    it("mode 'root' returns an empty layout when the root is absent", () => {
+      const layout = layoutFGCAPreview(doc, { scope: { mode: 'root', rootGoalId: '999' } });
+      expect(layout.nodes).toHaveLength(0);
+      expect(layout.edges).toHaveLength(0);
+    });
+  });
+});

package/src/fgca/__tests__/validate.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { validateFGCADoc } from '../validate.js';
+
+const VALID_DOC = {
+  notation: 'fgca',
+  factors: [{ id: 1, name: 'Market pressure' }],
+  goals: [{ id: 1, name: 'Grow revenue', factor: [{ id: 1 }] }],
+  changes: [{ id: 1, name: 'Launch product', goal_id: 1, activity_ids: [1] }],
+  activities: [{ id: 1, name: 'Market research', goal_id: 1 }],
+};
+
+describe('validateFGCADoc', () => {
+  it('accepts a valid document', () => {
+    const result = validateFGCADoc(VALID_DOC);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('rejects non-object input', () => {
+    expect(validateFGCADoc('string').valid).toBe(false);
+    expect(validateFGCADoc(null).valid).toBe(false);
+    expect(validateFGCADoc(42).valid).toBe(false);
+  });
+
+  it('errors on missing notation field', () => {
+    const { notation: _, ...without } = VALID_DOC;
+    const result = validateFGCADoc(without);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].code).toBe('MISSING_NOTATION');
+  });
+
+  it('errors on wrong notation value', () => {
+    const result = validateFGCADoc({ ...VALID_DOC, notation: 'goals' });
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].code).toBe('WRONG_NOTATION');
+  });
+
+  it('errors when factors array is missing', () => {
+    const { factors: _, ...without } = VALID_DOC;
+    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.path === 'factors')).toBe(true);
+  });
+
+  it('errors when goals array is missing', () => {
+    const { goals: _, ...without } = VALID_DOC;
+    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.path === 'goals')).toBe(true);
+  });
+
+  it('errors when changes array is missing', () => {
+    const { changes: _, ...without } = VALID_DOC;
+    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.path === 'changes')).toBe(true);
+  });
+
+  it('errors when activities array is missing', () => {
+    const { activities: _, ...without } = VALID_DOC;
+    const result = validateFGCADoc({ ...without, notation: 'fgca' });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.path === 'activities')).toBe(true);
+  });
+
+  it('errors on empty factor name', () => {
+    const result = validateFGCADoc({ ...VALID_DOC, factors: [{ id: 1, name: '' }] });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.code === 'EMPTY_NAME')).toBe(true);
+  });
+
+  it('errors on empty goal name', () => {
+    const result = validateFGCADoc({ ...VALID_DOC, goals: [{ id: 1, name: '  ', factor: [] }] });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.code === 'EMPTY_NAME')).toBe(true);
+  });
+
+  it('warns on broken factor reference in goal', () => {
+    const result = validateFGCADoc({
+      ...VALID_DOC,
+      goals: [{ id: 1, name: 'Goal', factor: [{ id: 99 }] }],
+    });
+    expect(result.valid).toBe(true);
+    expect(result.warnings.some(w => w.code === 'BROKEN_REF' && w.message.includes('factor 99'))).toBe(true);
+  });
+
+  it('warns on broken goal reference in change', () => {
+    const result = validateFGCADoc({
+      ...VALID_DOC,
+      changes: [{ id: 1, name: 'Change', goal_id: 99, activity_ids: [] }],
+    });
+    expect(result.valid).toBe(true);
+    expect(result.warnings.some(w => w.code === 'BROKEN_REF' && w.message.includes('goal 99'))).toBe(true);
+  });
+
+  it('warns on broken activity reference in change', () => {
+    const result = validateFGCADoc({
+      ...VALID_DOC,
+      changes: [{ id: 1, name: 'Change', goal_id: 1, activity_ids: [99] }],
+    });
+    expect(result.valid).toBe(true);
+    expect(result.warnings.some(w => w.code === 'BROKEN_REF' && w.message.includes('activity 99'))).toBe(true);
+  });
+
+  it('accepts a document with empty arrays', () => {
+    const result = validateFGCADoc({
+      notation: 'fgca',
+      factors: [],
+      goals: [],
+      changes: [],
+      activities: [],
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts optional spec_version field', () => {
+    const result = validateFGCADoc({ ...VALID_DOC, spec_version: '0.1' });
+    expect(result.valid).toBe(true);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it('[blocker] tolerates a null element in goals[] without throwing', () => {
+    const r = validateFGCADoc({ ...VALID_DOC, goals: [null] });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+  it('[blocker] tolerates a string element in factors[] without throwing', () => {
+    const r = validateFGCADoc({ ...VALID_DOC, factors: ['x'] });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+  it('[blocker] tolerates a null element in changes[] without throwing', () => {
+    const r = validateFGCADoc({ ...VALID_DOC, changes: [null] });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+  it('[blocker] tolerates a null element in activities[] without throwing', () => {
+    const r = validateFGCADoc({ ...VALID_DOC, activities: [null] });
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+  });
+});