@transitrix/diagrams 1.0.0 → 1.1.0

package/dist/compliance/markdown.js

@@ -10,6 +10,7 @@ const STATUS_LABELS = {
     partial: 'Partial',
     non_compliant: 'Non-compliant',
     under_review: 'Under review',
+    pending_owner: 'Pending owner',
     n_a: 'N/A',
 };
 /** Escapes a value for a Markdown table cell (pipes + newlines). */

package/dist/compliance/types.d.ts

@@ -44,18 +44,37 @@ export interface IndexAssertion {
      * stage-grouped matrix cells.
      */
     realised_via?: string[];
+    /** ID or name of the party who must confirm this assertion (pending-owner state). */
+    owner_to_confirm?: string;
 }
-/** One detail-level element of a business object, used as a matrix sub-column. */
+/** One stage (or task) element of a business object, used as a matrix sub-column. */
 export interface ObjectDetailDef {
     id: string;
     name: string;
+    /**
+     * Ordered task-type flow steps within this stage.
+     * Present only when `grouping.columns: product-stage-task` grain is active.
+     * Each task produces a separate matrix column: (subject, stageId, taskId).
+     * When absent or empty, the stage itself is the column grain.
+     */
+    tasks?: Array<{
+        id: string;
+        name: string;
+    }>;
 }
 /**
- * Maps a business object to its ordered detail elements.
- * Passed into `buildImpactMatrix` when `grouping.columns` is
- * `object-details`. The details can be process stages, product
- * components, capability modules, etc. — whatever sub-structure the object
- * exposes. Typically extracted from a process-blueprint via`extractObjectDetails`.
+ * Maps a business object to its ordered stages (and optionally their tasks).
+ * Passed into `buildImpactMatrix` to enable stage/task column grouping.
+ *
+ * - For `grouping.columns: product-stage`: `details` contains stages; each
+ *   stage becomes one matrix column.
+ * - For `grouping.columns: product-stage-task`: each stage in `details` carries
+ *   a `tasks` array; each task produces a `(subject, stage, task)` column.
+ *   Stages with no tasks fall back to a stage-grain column.
+ *
+ * Typically built by combining `extractObjectDetails` (blueprint stages) and
+ * `extractProcessFlowTasks` (process flow tasks), then merging via
+ * `mergeStageTaskDetails`.
  */
 export interface ObjectDetailInput {
     objectId: string;

package/dist/edge-path.d.ts

@@ -10,9 +10,13 @@ export declare const DEFAULT_EDGE_CURVATURE = 1;
  * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
  * (tx,ty).
  *
- * `curvature` scales the control-handle length:
- *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
+ * `curvature` scales the exit control-handle (departure from source).
+ * `entryCurvature` scales the entry control-handle (arrival at target);
+ * defaults to `curvature` when omitted so callers that pass one value get
+ * symmetric handles (the historical behaviour).
+ *
+ *   - 0   → handle collapses onto its endpoint ⇒ straight at that end.
  *   - 1   → the historical curve (no visual change from before #76).
- *   - >1  → progressively stronger arc.
+ *   - >1  → progressively stronger arc at that end.
  */
-export declare function horizontalCubicEdgePath(sx: number, sy: number, tx: number, ty: number, curvature?: number): string;
+export declare function horizontalCubicEdgePath(sx: number, sy: number, tx: number, ty: number, curvature?: number, entryCurvature?: number): string;

package/dist/edge-path.js

@@ -21,15 +21,20 @@ export const DEFAULT_EDGE_CURVATURE = 1;
  * Builds the SVG `d` for a horizontal-tangent cubic Bézier from (sx,sy) to
  * (tx,ty).
  *
- * `curvature` scales the control-handle length:
- *   - 0   → control points collapse onto the endpoints ⇒ a straight line.
+ * `curvature` scales the exit control-handle (departure from source).
+ * `entryCurvature` scales the entry control-handle (arrival at target);
+ * defaults to `curvature` when omitted so callers that pass one value get
+ * symmetric handles (the historical behaviour).
+ *
+ *   - 0   → handle collapses onto its endpoint ⇒ straight at that end.
  *   - 1   → the historical curve (no visual change from before #76).
- *   - >1  → progressively stronger arc.
+ *   - >1  → progressively stronger arc at that end.
  */
-export function horizontalCubicEdgePath(sx, sy, tx, ty, curvature = DEFAULT_EDGE_CURVATURE) {
+export function horizontalCubicEdgePath(sx, sy, tx, ty, curvature = DEFAULT_EDGE_CURVATURE, entryCurvature) {
     const dx = tx - sx;
     const dy = ty - sy;
     const baseHandle = Math.max(EDGE_MIN_HANDLE, Math.abs(dx) * DX_FACTOR, Math.abs(dy) * DY_FACTOR);
-    const handle = baseHandle * curvature;
-    return `M${sx},${sy} C${sx + handle},${sy} ${tx - handle},${ty} ${tx},${ty}`;
+    const exitHandle = baseHandle * curvature;
+    const entryHandle = baseHandle * (entryCurvature ?? curvature);
+    return `M${sx},${sy} C${sx + exitHandle},${sy} ${tx - entryHandle},${ty} ${tx},${ty}`;
 }

package/dist/factor/__tests__/validate.test.js

@@ -1,10 +1,10 @@
 import { describe, it, expect } from 'vitest';
 import { validateFactor } from '../validate.js';
-function valid() {
+function validExternal() {
     return {
-        notation: 'factor',
+        notation: 'driver',
         id: 'FACTOR-EU-REG-1',
-        name: 'EU regulatory window for market entry',
+        name: 'EU regulatory window',
         type: 'external',
         category: 'legal',
         description: 'Standing external driver — the EU regulatory regime.',
@@ -17,67 +17,96 @@ function valid() {
         valid_to: null,
     };
 }
-const codes = (input) => validateFactor(input).errors.map(e => e.code);
-const warns = (input) => validateFactor(input).warnings.map(w => w.code);
+function validInternal() {
+    return {
+        notation: 'driver',
+        id: 'FACTOR-COMP-1',
+        name: 'Support response time',
+        type: 'internal',
+        description: 'Standing internal driver.',
+        zone: 'canon',
+        admitted_at: '2026-05-29',
+        admitted_by: 'v.korobeinikov',
+        gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+        valid_from: '2026-05-26',
+        valid_to: null,
+    };
+}
+const codes = (input, opts) => validateFactor(input, opts).errors.map(e => e.code);
 describe('validateFactor — positive', () => {
-    it('accepts the worked-example FACTOR-EU-REG-1', () => {
-        const r = validateFactor(valid());
+    it('accepts a well-formed external PESTLE factor', () => {
+        const r = validateFactor(validExternal());
         expect(r.valid, JSON.stringify(r.errors)).toBe(true);
-        expect(r.errors).toHaveLength(0);
     });
-    it('accepts a minimal factor (no type/category/references)', () => {
-        const r = valid();
-        delete r.type;
-        delete r.category;
-        delete r.references_constraint;
-        expect(validateFactor(r).valid).toBe(true);
+    it('accepts a well-formed internal factor (no PESTLE category)', () => {
+        expect(validateFactor(validInternal()).valid).toBe(true);
     });
-});
-describe('validateFactor — FACTOR-001 (envelope / shape)', () => {
-    it('flags a non-object', () => {
-        expect(codes(null)).toEqual(['FACTOR-001']);
-        expect(codes(['x'])).toEqual(['FACTOR-001']);
+    it('accepts a minimal factor with no optional fields', () => {
+        const f = validInternal();
+        delete f.type;
+        delete f.description;
+        expect(validateFactor(f).valid).toBe(true);
     });
-    it('flags a wrong notation tag', () => {
-        expect(codes({ ...valid(), notation: 'driver' })).toContain('FACTOR-001');
+});
+describe('validateFactor — FACTOR-001 (shape / id grammar)', () => {
+    it('flags a missing required envelope field', () => {
+        const f = validExternal();
+        delete f.admitted_by;
+        expect(codes(f)).toContain('FACTOR-001');
     });
-    it('flags an id with the wrong TYPE prefix', () => {
-        expect(codes({ ...valid(), id: 'GOAL-EU-1' })).toContain('FACTOR-001');
+    it('flags an id that violates the grammar', () => {
+        expect(codes({ ...validExternal(), id: 'FACTOR-EU-REG-001' })).toContain('FACTOR-001');
+        expect(codes({ ...validExternal(), id: 'FAC-1' })).toContain('FACTOR-001');
+        expect(codes({ ...validExternal(), id: 'factor-1' })).toContain('FACTOR-001');
     });
-    it('flags an id with a leading-zero terminal', () => {
-        expect(codes({ ...valid(), id: 'FACTOR-EU-REG-01' })).toContain('FACTOR-001');
+    it('flags a wrong notation tag and a non-canon zone', () => {
+        expect(codes({ ...validExternal(), notation: 'factor' })).toContain('FACTOR-001');
+        expect(codes({ ...validExternal(), zone: 'sandbox' })).toContain('FACTOR-001');
     });
     it('flags a missing valid_to key (distinct from a null value)', () => {
-        const r = valid();
-        delete r.valid_to;
-        expect(codes(r)).toContain('FACTOR-001');
-        expect(validateFactor({ ...valid(), valid_to: null }).valid).toBe(true);
+        const f = validExternal();
+        delete f.valid_to;
+        expect(codes(f)).toContain('FACTOR-001');
     });
-    it('flags references_constraint entries that are not CONSTRAINT typed ids', () => {
-        expect(codes({ ...valid(), references_constraint: ['GOAL-EU-1'] })).toContain('FACTOR-001');
-        expect(codes({ ...valid(), references_constraint: 'CONSTRAINT-X-1' })).toContain('FACTOR-001');
+    it('rejects a non-object', () => {
+        expect(codes(null)).toEqual(['FACTOR-001']);
+        expect(codes(['a'])).toEqual(['FACTOR-001']);
     });
 });
 describe('validateFactor — FACTOR-002 (type enum)', () => {
-    it('flags a type outside external/internal', () => {
-        expect(codes({ ...valid(), type: 'driver' })).toContain('FACTOR-002');
-    });
-    it('accepts each permitted type', () => {
-        for (const t of ['external', 'internal']) {
-            expect(codes({ ...valid(), type: t, category: undefined })).not.toContain('FACTOR-002');
-        }
+    it('flags a type value outside {external, internal}', () => {
+        expect(codes({ ...validExternal(), type: 'driver' })).toContain('FACTOR-002');
     });
 });
 describe('validateFactor — FACTOR-003 (PESTLE category)', () => {
-    it('flags a category outside the PESTLE classes', () => {
-        expect(codes({ ...valid(), category: 'cultural' })).toContain('FACTOR-003');
+    it('flags a category outside PESTLE', () => {
+        expect(codes({ ...validExternal(), category: 'cosmic' })).toContain('FACTOR-003');
     });
-    it('warns when category is set on an internal factor', () => {
-        expect(warns({ ...valid(), type: 'internal', category: 'economic' })).toContain('FACTOR-003');
+    it('flags PESTLE category on an internal factor', () => {
+        const f = validInternal();
+        f.category = 'legal';
+        expect(codes(f)).toContain('FACTOR-003');
     });
-    it('accepts each permitted PESTLE class', () => {
-        for (const c of ['political', 'economic', 'social', 'technological', 'legal', 'environmental']) {
-            expect(codes({ ...valid(), category: c })).not.toContain('FACTOR-003');
+    it('accepts each permitted PESTLE category on an external factor', () => {
+        for (const cat of ['political', 'economic', 'social', 'technological', 'legal', 'environmental']) {
+            const f = validExternal();
+            f.category = cat;
+            expect(codes(f)).not.toContain('FACTOR-003');
         }
     });
 });
+describe('validateFactor — FACTOR-004 (references_constraint)', () => {
+    it('flags a malformed references_constraint entry', () => {
+        expect(codes({ ...validExternal(), references_constraint: ['not an id'] })).toContain('FACTOR-004');
+    });
+    it('flags a references_constraint entry of the wrong TYPE', () => {
+        expect(codes({ ...validExternal(), references_constraint: ['GOAL-X-1'] })).toContain('FACTOR-004');
+    });
+    it('flags an unresolved id when a catalog is supplied', () => {
+        const catalog = { typeOf: () => undefined };
+        expect(codes(validExternal(), { catalog })).toContain('FACTOR-004');
+    });
+    it('does not flag without a catalog for a well-formed CONSTRAINT id', () => {
+        expect(codes(validExternal())).not.toContain('FACTOR-004');
+    });
+});

package/dist/factor/index.d.ts

@@ -1,3 +1,4 @@
-export type { Factor as FactorPrimitive, FactorType, FactorCategory } from './types.js';
-export { FACTOR_TYPES, FACTOR_CATEGORIES } from './types.js';
+export type { Factor, FactorType, FactorPestleCategory } from './types.js';
+export { FACTOR_PESTLE_CATEGORIES } from './types.js';
 export { validateFactor } from './validate.js';
+export type { FactorValidateOptions } from './validate.js';

package/dist/factor/index.js

@@ -1,2 +1,2 @@
-export { FACTOR_TYPES, FACTOR_CATEGORIES } from './types.js';
+export { FACTOR_PESTLE_CATEGORIES } from './types.js';
 export { validateFactor } from './validate.js';

package/dist/factor/types.d.ts

@@ -1,17 +1,14 @@
 import type { GateChecks } from '../requirement/types.js';
-/** Optional subtype — internal/external organisation force. */
 export type FactorType = 'external' | 'internal';
-export declare const FACTOR_TYPES: readonly ["external", "internal"];
-/** PESTLE sub-classification — external factors only. Open-ended in practice
- *  but v1 fixes the six standard classes; an unknown category is flagged. */
-export type FactorCategory = 'political' | 'economic' | 'social' | 'technological' | 'legal' | 'environmental';
-export declare const FACTOR_CATEGORIES: readonly ["political", "economic", "social", "technological", "legal", "environmental"];
+/** PESTLE sub-classification — external factors only (§7.1). */
+export declare const FACTOR_PESTLE_CATEGORIES: readonly ["political", "economic", "social", "technological", "legal", "environmental"];
+export type FactorPestleCategory = typeof FACTOR_PESTLE_CATEGORIES[number];
 export interface Factor {
-    notation: 'factor';
+    notation: 'driver';
     id: string;
     name: string;
     type?: FactorType;
-    category?: FactorCategory;
+    category?: FactorPestleCategory;
     description?: string;
     references_constraint?: string[];
     zone: 'canon';

package/dist/factor/types.js

@@ -1,6 +1,11 @@
-// FACTOR — motivation-layer driver primitive.
-// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.1 + envelope §3.
-export const FACTOR_TYPES = ['external', 'internal'];
-export const FACTOR_CATEGORIES = [
-    'political', 'economic', 'social', 'technological', 'legal', 'environmental',
+// FACTOR — motivation-layer Driver (ArchiMate).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.1.
+/** PESTLE sub-classification — external factors only (§7.1). */
+export const FACTOR_PESTLE_CATEGORIES = [
+    'political',
+    'economic',
+    'social',
+    'technological',
+    'legal',
+    'environmental',
 ];

package/dist/factor/validate.d.ts

@@ -1,2 +1,7 @@
 import type { ValidationResult } from '../validation-types.js';
-export declare function validateFactor(input: unknown): ValidationResult;
+import { type CanonCatalog } from '../typed-id.js';
+export interface FactorValidateOptions {
+    /** When provided, enforces that each `references_constraint` id is admitted. */
+    catalog?: CanonCatalog;
+}
+export declare function validateFactor(input: unknown, options?: FactorValidateOptions): ValidationResult;

package/dist/factor/validate.js

@@ -1,66 +1,84 @@
 // FACTOR validator — methodology notations/ELEMENT_PRIMITIVES.md §7.1.
 //
-// Implements FACTOR-001..003. Cross-cutting HDR-/LIFECYCLE-/policy rules
-// (CONTRACT.md §8) are owned elsewhere and out of scope for this
-// single-artefact validator.
-import { typeOfId } from '../typed-id.js';
-import { validateElementEnvelope } from '../element-envelope.js';
-import { FACTOR_CATEGORIES, FACTOR_TYPES } from './types.js';
-export function validateFactor(input) {
+// Codes:
+//   FACTOR-001 — shape / id grammar / required envelope fields.
+//   FACTOR-002 — `type` outside {external, internal}.
+//   FACTOR-003 — `category` outside PESTLE vocabulary, or PESTLE applied to a
+//                non-external factor (PESTLE applies only to external drivers).
+//   FACTOR-004 — `references_constraint` entry malformed or wrong TYPE.
+//
+// `references_constraint` existence (resolves to an admitted artefact) runs
+// only when a `CanonCatalog` is supplied; the prefix-TYPE check runs either way.
+import { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
+import { FACTOR_PESTLE_CATEGORIES } from './types.js';
+const REQUIRED_STRING_FIELDS = [
+    'name', 'admitted_at', 'admitted_by', 'valid_from',
+];
+const PESTLE = FACTOR_PESTLE_CATEGORIES;
+export function validateFactor(input, options = {}) {
     const errors = [];
     const warnings = [];
-    const { record, errors: envErrors } = validateElementEnvelope(input, {
-        notation: 'factor',
-        idType: 'FACTOR',
-        code: 'FACTOR-001',
-    });
-    errors.push(...envErrors);
-    if (!record)
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        errors.push({ code: 'FACTOR-001', message: 'Factor must be a YAML mapping.' });
         return { valid: false, errors, warnings };
-    // FACTOR-002 — type subtype enum (optional field).
-    if (record.type !== undefined && !FACTOR_TYPES.includes(record.type)) {
-        errors.push({
-            code: 'FACTOR-002',
-            message: `type "${String(record.type)}" must be one of ${FACTOR_TYPES.join(', ')}.`,
-            path: 'type',
-        });
     }
-    // FACTOR-003 — PESTLE category enum on external factors; warn on internal.
-    if (record.category !== undefined) {
-        if (!FACTOR_CATEGORIES.includes(record.category)) {
-            errors.push({
-                code: 'FACTOR-003',
-                message: `category "${String(record.category)}" must be a PESTLE class (${FACTOR_CATEGORIES.join(', ')}).`,
-                path: 'category',
-            });
+    const f = input;
+    // FACTOR-001 — id grammar + notation tag + envelope.
+    if (!isCanonicalIdOfType(f.id, 'FACTOR')) {
+        errors.push({ code: 'FACTOR-001', message: `id "${String(f.id)}" must match FACTOR-[<middle>-]<INTEGER>.`, path: 'id' });
+    }
+    if (f.notation !== 'driver') {
+        errors.push({ code: 'FACTOR-001', message: 'notation must be the fixed value "driver".', path: 'notation' });
+    }
+    if (f.zone !== undefined && f.zone !== 'canon') {
+        errors.push({ code: 'FACTOR-001', message: 'zone must be "canon" for a FACTOR.', path: 'zone' });
+    }
+    else if (f.zone === undefined) {
+        errors.push({ code: 'FACTOR-001', message: 'zone is required.', path: 'zone' });
+    }
+    for (const field of REQUIRED_STRING_FIELDS) {
+        const v = f[field];
+        if (typeof v !== 'string' || v.trim() === '') {
+            errors.push({ code: 'FACTOR-001', message: `${field} is required.`, path: field });
         }
-        else if (record.type === 'internal') {
-            // §7.1: "Omit on internal factors — PESTLE does not apply."
-            warnings.push({
-                code: 'FACTOR-003',
-                message: 'category is set on an internal factor; PESTLE applies to external drivers only.',
-                path: 'category',
-            });
+    }
+    if (f.gate_checks === null || typeof f.gate_checks !== 'object') {
+        errors.push({ code: 'FACTOR-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+    }
+    if (!('valid_to' in f) || !(typeof f.valid_to === 'string' || f.valid_to === null)) {
+        errors.push({ code: 'FACTOR-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+    }
+    // FACTOR-002 — type enum (optional field; only check when present).
+    if (f.type !== undefined && f.type !== 'external' && f.type !== 'internal') {
+        errors.push({ code: 'FACTOR-002', message: `type "${String(f.type)}" must be one of external, internal.`, path: 'type' });
+    }
+    // FACTOR-003 — category PESTLE vocabulary + external-only constraint.
+    if (f.category !== undefined) {
+        if (typeof f.category !== 'string' || !PESTLE.includes(f.category)) {
+            errors.push({ code: 'FACTOR-003', message: `category "${String(f.category)}" must be one of ${PESTLE.join(', ')}.`, path: 'category' });
+        }
+        else if (f.type === 'internal') {
+            errors.push({ code: 'FACTOR-003', message: 'category is PESTLE — applies only to external factors; omit on internal factors.', path: 'category' });
         }
     }
-    // FACTOR-001 — references_constraint shape + TYPE on each entry.
-    if (record.references_constraint !== undefined) {
-        if (!Array.isArray(record.references_constraint)) {
-            errors.push({
-                code: 'FACTOR-001',
-                message: 'references_constraint must be a list of typed CONSTRAINT IDs.',
-                path: 'references_constraint',
-            });
+    // FACTOR-004 — references_constraint refs.
+    if (f.references_constraint !== undefined) {
+        if (!Array.isArray(f.references_constraint)) {
+            errors.push({ code: 'FACTOR-001', message: 'references_constraint must be a list of typed IDs.', path: 'references_constraint' });
         }
         else {
-            record.references_constraint.forEach((ref, i) => {
+            f.references_constraint.forEach((ref, i) => {
                 const type = typeOfId(ref);
+                if (!type) {
+                    errors.push({ code: 'FACTOR-004', message: `references_constraint[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `references_constraint[${i}]` });
+                    return;
+                }
                 if (type !== 'CONSTRAINT') {
-                    errors.push({
-                        code: 'FACTOR-001',
-                        message: `references_constraint[${i}] "${String(ref)}" must be a CONSTRAINT typed ID.`,
-                        path: `references_constraint[${i}]`,
-                    });
+                    errors.push({ code: 'FACTOR-004', message: `references_constraint[${i}] TYPE "${type}" must be CONSTRAINT.`, path: `references_constraint[${i}]` });
+                    return;
+                }
+                if (options.catalog && options.catalog.typeOf(ref) === undefined) {
+                    errors.push({ code: 'FACTOR-004', message: `references_constraint[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `references_constraint[${i}]` });
                 }
             });
         }

package/dist/fgca/__tests__/chain-table.test.js

@@ -31,7 +31,7 @@ describe('buildChainTable — worked example (FGCA)', () => {
     };
     it('produces the spec grid with F1 spanning 3 and G2/C2 spanning 2', () => {
         const t = buildChainTable(doc);
-        expect(t.columns).toEqual(['factor', 'goal', 'change', 'activity']);
+        expect(t.columns).toEqual(['driver', 'goal', 'change', 'activity']);
         expect(asGrid(t)).toEqual([
             ['F1×3', 'G1', 'C1', 'A1'],
             ['·', 'G2×2', 'C2×2', 'A2'],
@@ -59,7 +59,7 @@ describe('buildChainTable — FGA (no Change column)', () => {
     };
     it('emits three columns and merges Factor/Goal across the two activities', () => {
         const t = buildChainTable(doc, { hideChanges: true });
-        expect(t.columns).toEqual(['factor', 'goal', 'activity']);
+        expect(t.columns).toEqual(['driver', 'goal', 'activity']);
         expect(asGrid(t)).toEqual([
             ['F1×2', 'G1×2', 'A1'],
             ['·', '·', 'A2'],

package/dist/fgca/__tests__/layout.test.js

@@ -39,15 +39,15 @@ describe("buildFGCALayout — all columns visible", () => {
     });
     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 === "fgcaDriver")).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_"));
+        const fgEdges = edges.filter((e) => e.source.startsWith("driver_") && e.target.startsWith("goal_"));
         expect(fgEdges).toHaveLength(2);
-        expect(fgEdges.find((e) => e.source === "factor_1" && e.target === "goal_10")).toBeTruthy();
+        expect(fgEdges.find((e) => e.source === "driver_1" && e.target === "goal_10")).toBeTruthy();
     });
     it("creates Goal→Change edges", () => {
         const gcEdges = edges.filter((e) => e.source.startsWith("goal_") && e.target.startsWith("change_"));
@@ -66,7 +66,7 @@ describe("buildFGCALayout — all columns visible", () => {
         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");
+        const factorNode = nodes.find((n) => n.id === "driver_1");
         expect(String(factorNode?.data.id).padStart(4, "0")).toBe("0001");
     });
     it("encodes C-XXX label format via id in node data", () => {
@@ -74,14 +74,14 @@ describe("buildFGCALayout — all columns visible", () => {
         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"));
+describe("buildFGCALayout — Driver column hidden", () => {
+    const cols = new Set(ALL_FGCA_COLUMNS.filter((c) => c !== "driver"));
     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 driver nodes", () => {
+        expect(nodes.filter((n) => n.type === "fgcaDriver")).toHaveLength(0);
     });
-    it("produces no Factor→Goal edges", () => {
-        expect(edges.filter((e) => e.source.startsWith("factor_"))).toHaveLength(0);
+    it("produces no Driver→Goal edges", () => {
+        expect(edges.filter((e) => e.source.startsWith("driver_"))).toHaveLength(0);
     });
     it("still produces Goal and downstream nodes", () => {
         expect(nodes.filter((n) => n.type === "fgcaGoal")).toHaveLength(goals.length);
@@ -116,7 +116,7 @@ describe("buildFGCALayout — only one column visible", () => {
 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 f = nodes.find((n) => n.type === "fgcaDriver");
         const g = nodes.find((n) => n.type === "fgcaGoal");
         expect(f.position.x).toBeLessThan(g.position.x);
     });

package/dist/fgca/__tests__/preview-layout.test.js

@@ -18,7 +18,7 @@ const doc = {
 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']);
+        expect(layout.columns.map(c => c.col)).toEqual(['driver', 'goal', 'change', 'activity']);
         // 2 factors + 2 goals + 1 change + 2 activities
         expect(layout.nodes).toHaveLength(7);
         expect(layout.width).toBeGreaterThan(0);
@@ -31,7 +31,7 @@ describe('layoutFGCAPreview', () => {
     });
     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']);
+        expect(layout.columns.map(c => c.col)).toEqual(['driver', 'goal', 'activity']);
         // 2 factors + 2 goals + 2 activities
         expect(layout.nodes).toHaveLength(6);
         // F1→G1, F2→G2 (2), G1→A1, G2→A2 (2) = 4
@@ -57,7 +57,7 @@ describe('layoutFGCAPreview', () => {
     });
     it('larger rowGap increases the gap between stacked nodes', () => {
         const gapOf = (rowGap) => {
-            const factors = layoutFGCAPreview(doc, { rowGap }).nodes.filter(n => n.col === 'factor');
+            const factors = layoutFGCAPreview(doc, { rowGap }).nodes.filter(n => n.col === 'driver');
             return factors[1].y - factors[0].y;
         };
         expect(gapOf(120)).toBeGreaterThan(gapOf(20));
@@ -71,14 +71,14 @@ describe('layoutFGCAPreview', () => {
             // 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']));
+            expect(idsOf(layout)).toEqual(new Set(['driver_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']));
+            expect(idsOf(layout)).toEqual(new Set(['driver_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 === 'driver_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", () => {
@@ -95,7 +95,7 @@ describe('layoutFGCAPreview', () => {
                 ],
             };
             const layout = layoutFGCAPreview(leveled, { scope: { mode: 'level', maxLevel: 0 } });
-            expect(idsOf(layout)).toEqual(new Set(['factor_1', 'goal_10', 'activity_30']));
+            expect(idsOf(layout)).toEqual(new Set(['driver_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' } });