@transitrix/diagrams 1.0.0

package/src/confidence/types.ts

@@ -0,0 +1,96 @@
+// Confidence-scoring types per methodology CONTRACT §11 (Confidence and
+// freshness). Two independent signals — source trust (authored, fixed) and
+// freshness (derived, recomputed on read) — combined per element and rolled
+// up to a view composite. See packages/diagrams/src/confidence/score.ts for
+// the pure scoring functions.
+
+/** Closed source-trust scale per CONTRACT §11.2. */
+export type SourceQuality =
+  | 'authoritative'
+  | 'corroborated'
+  | 'single_source'
+  | 'unverified';
+
+/** Confidence band per CONTRACT §11.6 — derived from a numeric confidence. */
+export type ConfidenceBand = 'A' | 'B' | 'C' | 'D';
+
+/** Per-TYPE freshness-decay parameters per CONTRACT §11.3. */
+export interface DecayParams {
+  fresh_days: number;
+  stale_days: number;
+  floor: number;
+}
+
+/**
+ * Adopter-manifest `confidence_decay` block (MANIFEST.md §2). Both halves
+ * are optional: an absent `defaults` block falls back to the §11.3 implicit
+ * defaults, and an absent `by_type` entry inherits from `defaults`.
+ */
+export interface ConfidenceDecayConfig {
+  defaults?: Partial<DecayParams>;
+  by_type?: Record<string, Partial<DecayParams>>;
+}
+
+/**
+ * One canonical element fed to the scorer. The caller (Studio / DSM) has
+ * already resolved `derived_from` to the field artefacts and extracted their
+ * `source_quality` labels — this module never reads files.
+ */
+export interface ScoringElement {
+  /** Element TYPE name, used to look up per-TYPE decay (e.g. `CAPABILITY`). */
+  type: string;
+  /**
+   * ISO 8601 date the admission gate last ran for this element
+   * (`admitted_at`, CONTRACT §6). Reaffirmation bumps this date — the cure
+   * for staleness. Absent ⇒ treated as fully stale (freshness = floor).
+   */
+  admitted_at?: string;
+  /**
+   * Source qualities resolved from `derived_from` — one entry per cited
+   * field artefact. Undefined or empty ⇒ unsourced: scored as `unverified`
+   * (0.25) and counted separately per §11.5.
+   */
+  sources?: SourceQuality[];
+}
+
+/** Per-element scoring output. */
+export interface ElementScore {
+  /** Max source-trust weight over `sources`; 0.25 (`unverified`) if unsourced. */
+  source_trust: number;
+  /** Freshness in [floor, 1.0] per the §11.3 curve. */
+  freshness: number;
+  /** `source_trust × freshness`. */
+  confidence: number;
+  /**
+   * True iff at least one resolvable `derived_from` source was supplied.
+   * Drives the §11.5 "counted separately" gap signal and view coverage.
+   */
+  sourced: boolean;
+}
+
+/**
+ * View-level composite per CONTRACT §11.6. Three numbers surfaced alongside
+ * the view's formation date; the headline `band` is the band of the
+ * weakest link.
+ */
+export interface ViewComposite {
+  /** `min(confidence)` over the rendered elements. The headline figure. */
+  weakest_link: number;
+  /** Arithmetic mean of `confidence` (equal element weight in v1). */
+  mean: number;
+  /** Fraction of elements with `sourced === true`. */
+  coverage: number;
+  /** Band of the weakest link. */
+  band: ConfidenceBand;
+  element_count: number;
+  /** Elements with no resolvable `derived_from` — `unsourced_count` / `element_count` is the gap. */
+  unsourced_count: number;
+}
+
+/** Full scorer output: per-element + composite, plus the `today` used. */
+export interface ViewScore {
+  elements: ElementScore[];
+  composite: ViewComposite;
+  /** The date used as `today` (the reference for `age_days`). */
+  today: string;
+}

package/src/edge-path.ts

@@ -0,0 +1,44 @@
+// Shared edge geometry for the static notation previews (Goals, FGCA, FGA,
+// Activities). All four render dependency/relationship edges as a single cubic
+// Bézier with horizontal control handles: each control point shares its
+// endpoint's Y, so the tangent is horizontal at both ends and the marker-end
+// arrow reads as perpendicular to the node's vertical edge.
+//
+// Pulling the path math here (rather than duplicating it inline in each
+// preview) makes the configurable-curvature behaviour (vkgeorgia/strategy#76)
+// unit-testable — the extension has no test harness.
+
+/**
+ * Base handle length floor + span factors. The handle grows with both the
+ * horizontal and vertical span so the curve stays visibly horizontal long
+ * enough for the arrowhead to sit flush against the line.
+ */
+export const EDGE_MIN_HANDLE = 64;
+const DX_FACTOR = 0.5;
+const DY_FACTOR = 0.8;
+
+/** Multiplier applied to the base handle length. 1 = historical appearance. */
+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.
+ *   - 1   → the historical curve (no visual change from before #76).
+ *   - >1  → progressively stronger arc.
+ */
+export function horizontalCubicEdgePath(
+  sx: number,
+  sy: number,
+  tx: number,
+  ty: number,
+  curvature: number = DEFAULT_EDGE_CURVATURE,
+): string {
+  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}`;
+}

package/src/element-envelope.ts

@@ -0,0 +1,76 @@
+// Shared §3 envelope validator for standalone element primitives.
+//
+// Every standalone element file in the methodology canon carries the same
+// envelope: a fixed `notation` tag, a canonical `id` whose TYPE prefix matches
+// the element TYPE, `name`, an admission record (`zone`/`admitted_at`/
+// `admitted_by`/`gate_checks`), and a primitive lifecycle
+// (`valid_from`/`valid_to`). Per-TYPE fields (§7) sit between.
+//
+// Each per-TYPE validator delegates envelope checks here so the §3 rule lives
+// in one place; per-TYPE fields (subtype enums, cross-references) are checked
+// in the TYPE's own validator. The error `code` is parameterised so an
+// envelope failure surfaces under the TYPE's own code (e.g. `FACTOR-001`,
+// `CHANGE-001`), preserving per-TYPE attribution.
+
+import type { ValidationError } from './validation-types.js';
+import { isCanonicalIdOfType } from './typed-id.js';
+
+export interface EnvelopeOptions {
+  /** Fixed `notation:` tag — lowercased TYPE short name (e.g. `factor`). */
+  notation: string;
+  /** Required `id:` TYPE prefix (e.g. `FACTOR`). */
+  idType: string;
+  /** Error code used for every envelope failure (e.g. `FACTOR-001`). */
+  code: string;
+}
+
+export interface EnvelopeResult {
+  /** The input narrowed to a record on success; `null` when the input is not a mapping. */
+  record: Record<string, unknown> | null;
+  errors: ValidationError[];
+}
+
+export function validateElementEnvelope(input: unknown, opts: EnvelopeOptions): EnvelopeResult {
+  const errors: ValidationError[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: opts.code, message: `${opts.idType} must be a YAML mapping.` });
+    return { record: null, errors };
+  }
+  const r = input as Record<string, unknown>;
+
+  if (r.notation !== opts.notation) {
+    errors.push({
+      code: opts.code,
+      message: `notation must be the fixed value "${opts.notation}".`,
+      path: 'notation',
+    });
+  }
+  if (!isCanonicalIdOfType(r.id, opts.idType)) {
+    errors.push({
+      code: opts.code,
+      message: `id "${String(r.id)}" must match ${opts.idType}-[<middle>-]<INTEGER>.`,
+      path: 'id',
+    });
+  }
+  for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from'] as const) {
+    if (typeof r[f] !== 'string' || (r[f] as string).trim() === '') {
+      errors.push({ code: opts.code, message: `${f} is required.`, path: f });
+    }
+  }
+  if (r.zone !== 'canon') {
+    errors.push({ code: opts.code, message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  if (r.gate_checks === null || typeof r.gate_checks !== 'object' || Array.isArray(r.gate_checks)) {
+    errors.push({ code: opts.code, message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in r) || !(typeof r.valid_to === 'string' || r.valid_to === null)) {
+    errors.push({
+      code: opts.code,
+      message: 'valid_to is required (an ISO date string or null).',
+      path: 'valid_to',
+    });
+  }
+
+  return { record: r, errors };
+}

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

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { validateFactor } from '../validate.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'factor',
+    id: 'FACTOR-EU-REG-1',
+    name: 'EU regulatory window for market entry',
+    type: 'external',
+    category: 'legal',
+    description: 'Standing external driver — the EU regulatory regime.',
+    references_constraint: ['CONSTRAINT-GDPR-RESIDENCY-1'],
+    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: unknown): string[] => validateFactor(input).errors.map(e => e.code);
+const warns = (input: unknown): string[] => validateFactor(input).warnings.map(w => w.code);
+
+describe('validateFactor — positive', () => {
+  it('accepts the worked-example FACTOR-EU-REG-1', () => {
+    const r = validateFactor(valid());
+    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);
+  });
+});
+
+describe('validateFactor — FACTOR-001 (envelope / shape)', () => {
+  it('flags a non-object', () => {
+    expect(codes(null)).toEqual(['FACTOR-001']);
+    expect(codes(['x'])).toEqual(['FACTOR-001']);
+  });
+
+  it('flags a wrong notation tag', () => {
+    expect(codes({ ...valid(), notation: 'driver' })).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 with a leading-zero terminal', () => {
+    expect(codes({ ...valid(), id: 'FACTOR-EU-REG-01' })).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);
+  });
+
+  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');
+  });
+});
+
+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');
+    }
+  });
+});
+
+describe('validateFactor — FACTOR-003 (PESTLE category)', () => {
+  it('flags a category outside the PESTLE classes', () => {
+    expect(codes({ ...valid(), category: 'cultural' })).toContain('FACTOR-003');
+  });
+
+  it('warns when category is set on an internal factor', () => {
+    expect(warns({ ...valid(), type: 'internal', category: 'economic' })).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');
+    }
+  });
+});

package/src/factor/index.ts

@@ -0,0 +1,8 @@
+// The `Factor` type is re-exported under the alias `FactorPrimitive` at the
+// package surface to avoid a name collision with the legacy FGCA-inline
+// `Factor` shape exported from `./goals/index` (a v0.x view shape with
+// numeric ids — distinct from this element primitive). Both types remain
+// importable from their module subpaths.
+export type { Factor as FactorPrimitive, FactorType, FactorCategory } from './types.js';
+export { FACTOR_TYPES, FACTOR_CATEGORIES } from './types.js';
+export { validateFactor } from './validate.js';

package/src/factor/types.ts

@@ -0,0 +1,41 @@
+// FACTOR — motivation-layer driver primitive.
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.1 + envelope §3.
+
+import type { GateChecks } from '../requirement/types.js';
+
+/** Optional subtype — internal/external organisation force. */
+export type FactorType = 'external' | 'internal';
+
+export const FACTOR_TYPES = ['external', 'internal'] as const;
+
+/** 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 const FACTOR_CATEGORIES = [
+  'political', 'economic', 'social', 'technological', 'legal', 'environmental',
+] as const;
+
+export interface Factor {
+  notation: 'factor';
+  id: string;
+  name: string;
+  type?: FactorType;
+  category?: FactorCategory;
+  description?: string;
+  references_constraint?: string[];
+
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/factor/validate.ts

@@ -0,0 +1,74 @@
+// 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 type { ValidationError, ValidationResult, ValidationWarning } from '../validation-types.js';
+import { typeOfId } from '../typed-id.js';
+import { validateElementEnvelope } from '../element-envelope.js';
+import { FACTOR_CATEGORIES, FACTOR_TYPES } from './types.js';
+
+export function validateFactor(input: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  const { record, errors: envErrors } = validateElementEnvelope(input, {
+    notation: 'factor',
+    idType: 'FACTOR',
+    code: 'FACTOR-001',
+  });
+  errors.push(...envErrors);
+  if (!record) return { valid: false, errors, warnings };
+
+  // FACTOR-002 — type subtype enum (optional field).
+  if (record.type !== undefined && !FACTOR_TYPES.includes(record.type as never)) {
+    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 as never)) {
+      errors.push({
+        code: 'FACTOR-003',
+        message: `category "${String(record.category)}" must be a PESTLE class (${FACTOR_CATEGORIES.join(', ')}).`,
+        path: 'category',
+      });
+    } 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',
+      });
+    }
+  }
+
+  // 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',
+      });
+    } else {
+      record.references_constraint.forEach((ref, i) => {
+        const type = typeOfId(ref);
+        if (type !== 'CONSTRAINT') {
+          errors.push({
+            code: 'FACTOR-001',
+            message: `references_constraint[${i}] "${String(ref)}" must be a CONSTRAINT typed ID.`,
+            path: `references_constraint[${i}]`,
+          });
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/fgca/__tests__/chain-table.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect } from 'vitest';
+import { buildChainTable, type ChainTable, type ChainColumn } from '../chain-table.js';
+import type { FGCAPreviewDoc } from '../preview-layout.js';
+
+// Renders a ChainTable to a compact text grid for readable assertions. Each
+// cell shows "label×rowSpan" (×1 omitted); a position covered by a span above
+// shows "·".
+function asGrid(t: ChainTable): string[][] {
+  return t.rows.map(row =>
+    row.map(c => {
+      if (c === null) return '·';
+      const label = c.cell ? c.cell.label : '∅';
+      return c.rowSpan > 1 ? `${label}×${c.rowSpan}` : label;
+    }),
+  );
+}
+
+describe('buildChainTable — worked example (FGCA)', () => {
+  // F1 → G1, G2 ; G1 → C1 → A1 ; G2 → C2 → A2, A3
+  const doc: FGCAPreviewDoc = {
+    factors: [{ id: 1, name: 'F1' }],
+    goals: [
+      { id: 10, name: 'G1', factor: [{ id: 1 }] },
+      { id: 11, name: 'G2', factor: [{ id: 1 }] },
+    ],
+    changes: [
+      { id: 20, name: 'C1', goal_id: 10, activity_ids: [30] },
+      { id: 21, name: 'C2', goal_id: 11, activity_ids: [31, 32] },
+    ],
+    activities: [
+      { id: 30, name: 'A1', goal_id: 10 },
+      { id: 31, name: 'A2', goal_id: 11 },
+      { id: 32, name: 'A3', goal_id: 11 },
+    ],
+  };
+
+  it('produces the spec grid with F1 spanning 3 and G2/C2 spanning 2', () => {
+    const t = buildChainTable(doc);
+    expect(t.columns).toEqual<ChainColumn[]>(['factor', 'goal', 'change', 'activity']);
+    expect(asGrid(t)).toEqual([
+      ['F1×3', 'G1', 'C1', 'A1'],
+      ['·', 'G2×2', 'C2×2', 'A2'],
+      ['·', '·', '·', 'A3'],
+    ]);
+  });
+
+  it('orders the merged cells with correct rowSpans on the model', () => {
+    const t = buildChainTable(doc);
+    // Factor cell spans all three rows.
+    expect(t.rows[0][0]).toMatchObject({ rowSpan: 3, cell: { label: 'F1' } });
+    // Covered positions are null (no <td> emitted).
+    expect(t.rows[1][0]).toBeNull();
+    expect(t.rows[2][1]).toBeNull();
+  });
+});
+
+describe('buildChainTable — FGA (no Change column)', () => {
+  // FGA links Goal → Activity directly via activity.goal_id; no changes.
+  const doc: FGCAPreviewDoc = {
+    factors: [{ id: 1, name: 'F1' }],
+    goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
+    activities: [
+      { id: 30, name: 'A1', goal_id: 10 },
+      { id: 31, name: 'A2', goal_id: 10 },
+    ],
+  };
+
+  it('emits three columns and merges Factor/Goal across the two activities', () => {
+    const t = buildChainTable(doc, { hideChanges: true });
+    expect(t.columns).toEqual<ChainColumn[]>(['factor', 'goal', 'activity']);
+    expect(asGrid(t)).toEqual([
+      ['F1×2', 'G1×2', 'A1'],
+      ['·', '·', 'A2'],
+    ]);
+  });
+});
+
+describe('buildChainTable — missing downstream links (gaps stay visible)', () => {
+  it('shows a factor with no goal, a goal with no change, and a change with no activity', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [
+        { id: 1, name: 'F1' },
+        { id: 2, name: 'F2' }, // no goals
+      ],
+      goals: [
+        { id: 10, name: 'G1', factor: [{ id: 1 }] }, // no change, no activity
+        { id: 11, name: 'G2', factor: [{ id: 1 }] }, // has a change with no activity
+      ],
+      changes: [{ id: 20, name: 'C1', goal_id: 11, activity_ids: [] }],
+      activities: [],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([
+      ['F1×2', 'G1', '∅', '∅'],
+      ['·', 'G2', 'C1', '∅'],
+      ['F2', '∅', '∅', '∅'],
+    ]);
+  });
+
+  it('renders a change-less direct goal→activity path with an empty Change cell', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 1, name: 'F1' }],
+      goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
+      // activity bound straight to the goal, not covered by any change
+      changes: [],
+      activities: [{ id: 30, name: 'A1', goal_id: 10 }],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([['F1', 'G1', '∅', 'A1']]);
+  });
+});
+
+describe('buildChainTable — orphans (broken refs are warnings, not errors)', () => {
+  it('places a goal with a missing factor in a trailing empty-Factor row', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 1, name: 'F1' }],
+      goals: [
+        { id: 10, name: 'G1', factor: [{ id: 1 }] },
+        { id: 11, name: 'Gx', factor: [{ id: 99 }] }, // factor 99 does not exist
+        { id: 12, name: 'Gy' }, // no factor at all
+      ],
+      changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
+      activities: [{ id: 30, name: 'A1', goal_id: 10 }],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([
+      ['F1', 'G1', 'C1', 'A1'],
+      ['∅×2', 'Gx', '∅', '∅'],
+      ['·', 'Gy', '∅', '∅'],
+    ]);
+  });
+
+  it('surfaces an unlinked activity as a trailing row with empty cells to its left', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 1, name: 'F1' }],
+      goals: [{ id: 10, name: 'G1', factor: [{ id: 1 }] }],
+      changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
+      activities: [
+        { id: 30, name: 'A1', goal_id: 10 },
+        { id: 99, name: 'Aorphan' }, // no goal, no change
+      ],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([
+      ['F1', 'G1', 'C1', 'A1'],
+      ['∅', '∅', '∅', 'Aorphan'],
+    ]);
+  });
+
+  it('surfaces a change whose goal is missing as an empty Factor+Goal row', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [],
+      goals: [],
+      changes: [{ id: 20, name: 'Cx', goal_id: 999, activity_ids: [30] }],
+      activities: [{ id: 30, name: 'A1' }],
+    };
+    const t = buildChainTable(doc);
+    expect(asGrid(t)).toEqual([['∅', '∅', 'Cx', 'A1']]);
+  });
+});
+
+describe('buildChainTable — name fallback', () => {
+  it('falls back to the id when an element has an empty name', () => {
+    const doc: FGCAPreviewDoc = {
+      factors: [{ id: 7, name: '' }],
+      goals: [],
+      activities: [],
+    };
+    const t = buildChainTable(doc);
+    expect(t.rows[0][0]?.cell?.label).toBe('7');
+  });
+});