@transitrix/diagrams 1.0.0 → 1.0.1

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';
     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 !== 'factor') {
+        errors.push({ code: 'FACTOR-001', message: 'notation must be the fixed value "factor".', 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__/resolver.test.js

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { resolveFGCA, isFGCAViewDoc } from '../resolver.js';
+import { parseCanonicalFGCA } from '../parse-canonical.js';
+// ── Inline canon element store (mirrors strategy-2026 data split into per-element form) ─
+const ELEMENTS = [
+    { notation: 'factor', id: 'FACTOR-1', name: 'Competitive market pressure', type: 'external' },
+    { notation: 'factor', id: 'FACTOR-2', name: 'Digital adoption acceleration', type: 'external' },
+    { notation: 'goal', id: 'GOAL-1', name: 'Grow revenue by 20%', factors: ['FACTOR-1', 'FACTOR-2'] },
+    { notation: 'goal', id: 'GOAL-2', name: 'Reduce operational costs', factors: ['FACTOR-2'] },
+    { notation: 'goal', id: 'GOAL-3', name: 'Improve customer retention', factors: ['FACTOR-1'] },
+    { notation: 'change', id: 'CHANGE-1', name: 'Launch new product line', goals: ['GOAL-1'] },
+    { notation: 'change', id: 'CHANGE-2', name: 'Automate manual processes', goals: ['GOAL-2'] },
+    { notation: 'change', id: 'CHANGE-3', name: 'Enhance support platform', goals: ['GOAL-3'] },
+    { notation: 'activity', id: 'ACTIVITY-1', name: 'Market research', changes: ['CHANGE-1'] },
+    { notation: 'activity', id: 'ACTIVITY-2', name: 'MVP development', changes: ['CHANGE-1'] },
+    { notation: 'activity', id: 'ACTIVITY-3', name: 'Process audit', changes: ['CHANGE-2'] },
+    { notation: 'activity', id: 'ACTIVITY-4', name: 'RPA tooling rollout', changes: ['CHANGE-2'] },
+    { notation: 'activity', id: 'ACTIVITY-5', name: 'CRM implementation', changes: ['CHANGE-3'] },
+];
+const SOURCES = { elements: ELEMENTS, relations: [] };
+const VIEW_DOC = {
+    notation: 'fgca',
+    id: 'FGCA-STRAT-1',
+    name: 'Strategy 2026 — FGCA chain',
+    spec_version: '0.1',
+    view_config: {
+        goals: { filter: 'all' },
+        factors: { surface: 'derived' },
+        changes: { surface: 'derived' },
+        activities: { surface: 'derived' },
+    },
+};
+// ── isFGCAViewDoc ─────────────────────────────────────────────────────────────
+describe('isFGCAViewDoc', () => {
+    it('returns true for a view_config-based doc', () => {
+        expect(isFGCAViewDoc(VIEW_DOC)).toBe(true);
+    });
+    it('returns false for an inline doc with factors/goals arrays', () => {
+        expect(isFGCAViewDoc({
+            notation: 'fgca', id: 'FGCA-1', name: 'x',
+            factors: [], goals: [], changes: [], activities: [],
+        })).toBe(false);
+    });
+    it('returns false for non-objects', () => {
+        expect(isFGCAViewDoc(null)).toBe(false);
+        expect(isFGCAViewDoc('string')).toBe(false);
+        expect(isFGCAViewDoc(42)).toBe(false);
+    });
+});
+// ── resolveFGCA — goals.filter=all (default) ──────────────────────────────────
+describe('resolveFGCA — goals.filter=all', () => {
+    it('includes all goals, changes, and activities', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        expect(doc['goals'].length).toBe(3);
+        expect(doc['changes'].length).toBe(3);
+        expect(doc['activities'].length).toBe(5);
+    });
+    it('derives factors from all goal.factors[] refs', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        const factorIds = doc['factors'].map((f) => f.id);
+        expect(factorIds).toContain('FACTOR-1');
+        expect(factorIds).toContain('FACTOR-2');
+        expect(factorIds.length).toBe(2);
+    });
+    it('passes parseCanonicalFGCA and produces a fully valid internal doc', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        const r = parseCanonicalFGCA(doc);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toEqual([]);
+        expect(r.parsed?.goals).toHaveLength(3);
+        expect(r.parsed?.factors).toHaveLength(2);
+        expect(r.parsed?.changes).toHaveLength(3);
+        expect(r.parsed?.activities).toHaveLength(5);
+    });
+    it('carries view doc metadata (id, name, spec_version)', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        expect(doc['notation']).toBe('fgca');
+        expect(doc['id']).toBe('FGCA-STRAT-1');
+        expect(doc['name']).toBe('Strategy 2026 — FGCA chain');
+        expect(doc['spec_version']).toBe('0.1');
+    });
+});
+// ── resolveFGCA — goals.filter=ids ────────────────────────────────────────────
+describe('resolveFGCA — goals.filter=ids', () => {
+    it('narrows to the specified goal and its derived changes + activities', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-1'] }, factors: { surface: 'derived' }, changes: { surface: 'derived' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        const goalIds = doc['goals'].map((g) => g.id);
+        expect(goalIds).toEqual(['GOAL-1']);
+        const changeIds = doc['changes'].map((c) => c.id);
+        expect(changeIds).toEqual(['CHANGE-1']);
+        const actIds = doc['activities'].map((a) => a.id).sort();
+        expect(actIds).toEqual(['ACTIVITY-1', 'ACTIVITY-2']);
+        const r = parseCanonicalFGCA(doc);
+        expect(r.valid).toBe(true);
+    });
+    it('returns empty arrays when none of the requested ids exist in canon', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-NONEXISTENT-1'] }, factors: { surface: 'derived' }, changes: { surface: 'derived' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        expect(doc['goals'].length).toBe(0);
+        expect(doc['changes'].length).toBe(0);
+        expect(doc['factors'].length).toBe(0);
+    });
+});
+// ── resolveFGCA — surface=all ─────────────────────────────────────────────────
+describe('resolveFGCA — surface=all', () => {
+    it('factors.surface=all includes every factor even when only some are referenced', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-3'] }, factors: { surface: 'all' }, changes: { surface: 'derived' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        // GOAL-3 only references FACTOR-1, but surface=all → both factors
+        expect(doc['factors'].length).toBe(2);
+    });
+    it('changes.surface=all includes every change', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-1'] }, factors: { surface: 'derived' }, changes: { surface: 'all' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        expect(doc['changes'].length).toBe(3);
+    });
+});
+// ── resolveFGCA — empty / degenerate inputs ───────────────────────────────────
+describe('resolveFGCA — empty sources', () => {
+    it('returns empty arrays when canon has no elements', () => {
+        const doc = resolveFGCA(VIEW_DOC, { elements: [], relations: [] });
+        expect(doc['goals'].length).toBe(0);
+        expect(doc['factors'].length).toBe(0);
+        expect(doc['changes'].length).toBe(0);
+        expect(doc['activities'].length).toBe(0);
+    });
+    it('returns empty arrays for a non-object viewDoc', () => {
+        const doc = resolveFGCA(null, SOURCES);
+        expect(doc['goals'].length).toBe(0);
+    });
+});
+// ── File-based regression — resolver + canon fixture + parseCanonicalFGCA ─────
+describe('resolveFGCA — file-based regression against canon fixture', () => {
+    const CANON_ROOT = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'fgca', 'canon');
+    const VIEW_DIR = path.join(CANON_ROOT, 'views');
+    const ELEM_DIR = path.join(CANON_ROOT, 'elements');
+    function loadYamlsUnder(dir) {
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        function walk(d) {
+            for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+                const full = path.join(d, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                }
+                else if (entry.name.endsWith('.yaml')) {
+                    out.push(yaml.load(fs.readFileSync(full, 'utf8')));
+                }
+            }
+        }
+        walk(dir);
+        return out;
+    }
+    const viewFiles = fs.existsSync(VIEW_DIR)
+        ? fs.readdirSync(VIEW_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+        : [];
+    for (const file of viewFiles) {
+        it(`resolves ${file} against canon fixtures and passes parseCanonicalFGCA`, () => {
+            const viewDoc = yaml.load(fs.readFileSync(path.join(VIEW_DIR, file), 'utf8'));
+            expect(isFGCAViewDoc(viewDoc)).toBe(true);
+            const elements = loadYamlsUnder(ELEM_DIR);
+            const doc = resolveFGCA(viewDoc, { elements, relations: [] });
+            const r = parseCanonicalFGCA(doc);
+            expect(r.valid).toBe(true);
+            expect(r.errors).toEqual([]);
+        });
+    }
+});

package/dist/fgca/index.d.ts

@@ -8,6 +8,8 @@ export { validateFGCADoc } from "./validate";
 export type { FGCADoc, FGCAValidationResult, FGCAValidationError, FGCAValidationWarning } from "./validate";
 export { ALL_FGCA_COLUMNS, FGCA_COLUMN_LABELS, } from "./types";
 export type { FactorItem, GoalItem, BdnChangeWithActivities, ActivityItem, ActivityTypeItem, DiagramStyle, FGCAColumn, } from "./types";
+export { resolveFGCA, isFGCAViewDoc } from './resolver.js';
+export type { FGCAViewConfig, FGCACanonSources } from './resolver.js';
 export { default as FGCAFactorNode } from "./nodes/FGCAFactorNode";
 export { default as FGCAGoalNode } from "./nodes/FGCAGoalNode";
 export { default as FGCAChangeNode } from "./nodes/FGCAChangeNode";

package/dist/fgca/index.js

@@ -3,6 +3,7 @@ export { layoutFGCAPreview, selectScopedFGCA, FGCA_NODE_W, FGCA_NODE_H, FGCA_HEA
 export { buildChainTable } from "./chain-table";
 export { validateFGCADoc } from "./validate";
 export { ALL_FGCA_COLUMNS, FGCA_COLUMN_LABELS, } from "./types";
+export { resolveFGCA, isFGCAViewDoc } from './resolver.js';
 export { default as FGCAFactorNode } from "./nodes/FGCAFactorNode";
 export { default as FGCAGoalNode } from "./nodes/FGCAGoalNode";
 export { default as FGCAChangeNode } from "./nodes/FGCAChangeNode";

package/dist/fgca/resolver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * FGCA canon resolver — assembles a flat canonical FGCA document from a
+ * view_config projection and a canon element/relation store (VP-3).
+ *
+ * Output shape matches the flat form that `parseCanonicalFGCA` expects:
+ * top-level `factors[]`, `goals[]`, `changes[]`, `activities[]` with typed
+ * string IDs.  Filesystem-free — callable from unit tests without vscode.
+ */
+export interface FGCAViewConfig {
+    goals?: {
+        filter?: 'all' | 'ids' | 'tags';
+        ids?: string[];
+        tags?: string[];
+    };
+    factors?: {
+        surface?: 'derived' | 'all';
+    };
+    changes?: {
+        surface?: 'derived' | 'all';
+    };
+    activities?: {
+        surface?: 'derived' | 'all';
+    };
+    display?: {
+        depth?: number | null;
+        collapsed?: string[];
+    };
+}
+export interface FGCACanonSources {
+    elements: unknown[];
+    relations: unknown[];
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `factors[]` / `goals[]` arrays).
+ * Used by the preview to decide whether to run the resolver or fall back to
+ * direct `parseCanonicalFGCA` on the inline document.
+ */
+export declare function isFGCAViewDoc(parsed: unknown): boolean;
+/**
+ * Assemble a flat canonical FGCA document from the canon element store,
+ * filtered by the view document's `view_config`.  The return value is ready
+ * to pass to `parseCanonicalFGCA`.
+ *
+ * Cross-reference fields (`goal.factors[]`, `change.goals[]`,
+ * `activity.changes[]`) are carried from the canon elements unchanged; the
+ * resolver decides which elements to include, not how they are shaped.
+ */
+export declare function resolveFGCA(viewDoc: unknown, sources: FGCACanonSources): Record<string, unknown>;

package/dist/fgca/resolver.js

@@ -0,0 +1,124 @@
+/**
+ * FGCA canon resolver — assembles a flat canonical FGCA document from a
+ * view_config projection and a canon element/relation store (VP-3).
+ *
+ * Output shape matches the flat form that `parseCanonicalFGCA` expects:
+ * top-level `factors[]`, `goals[]`, `changes[]`, `activities[]` with typed
+ * string IDs.  Filesystem-free — callable from unit tests without vscode.
+ */
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === 'string' && v.trim().length > 0 ? v : undefined;
+}
+function strArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string' && x.trim().length > 0);
+}
+function collectByNotation(docs, notation) {
+    const out = new Map();
+    for (const doc of docs) {
+        if (!isObject(doc))
+            continue;
+        if (str(doc['notation']) !== notation)
+            continue;
+        const id = str(doc['id']);
+        if (!id)
+            continue;
+        if (!out.has(id))
+            out.set(id, doc);
+    }
+    return out;
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `factors[]` / `goals[]` arrays).
+ * Used by the preview to decide whether to run the resolver or fall back to
+ * direct `parseCanonicalFGCA` on the inline document.
+ */
+export function isFGCAViewDoc(parsed) {
+    if (!isObject(parsed))
+        return false;
+    return 'view_config' in parsed && !('factors' in parsed) && !('goals' in parsed);
+}
+/**
+ * Assemble a flat canonical FGCA document from the canon element store,
+ * filtered by the view document's `view_config`.  The return value is ready
+ * to pass to `parseCanonicalFGCA`.
+ *
+ * Cross-reference fields (`goal.factors[]`, `change.goals[]`,
+ * `activity.changes[]`) are carried from the canon elements unchanged; the
+ * resolver decides which elements to include, not how they are shaped.
+ */
+export function resolveFGCA(viewDoc, sources) {
+    if (!isObject(viewDoc)) {
+        return { notation: 'fgca', factors: [], goals: [], changes: [], activities: [] };
+    }
+    const vc = isObject(viewDoc['view_config']) ? viewDoc['view_config'] : {};
+    const goalsConf = isObject(vc['goals']) ? vc['goals'] : {};
+    const factorsConf = isObject(vc['factors']) ? vc['factors'] : {};
+    const changesConf = isObject(vc['changes']) ? vc['changes'] : {};
+    const activitiesConf = isObject(vc['activities']) ? vc['activities'] : {};
+    const factorElems = collectByNotation(sources.elements, 'factor');
+    const goalElems = collectByNotation(sources.elements, 'goal');
+    const changeElems = collectByNotation(sources.elements, 'change');
+    const activityElems = collectByNotation(sources.elements, 'activity');
+    // 1. Select goal set
+    const goalsFilter = str(goalsConf['filter']) ?? 'all';
+    let selectedGoals;
+    if (goalsFilter === 'ids') {
+        const ids = strArray(goalsConf['ids']);
+        selectedGoals = ids.flatMap((id) => { const g = goalElems.get(id); return g ? [g] : []; });
+    }
+    else if (goalsFilter === 'tags') {
+        const tags = strArray(goalsConf['tags']);
+        selectedGoals = [...goalElems.values()].filter((g) => strArray(g['tags']).some((t) => tags.includes(t)));
+    }
+    else {
+        // 'all' — include every goal element in the canon store
+        selectedGoals = [...goalElems.values()];
+    }
+    const selectedGoalIds = new Set(selectedGoals.map((g) => str(g['id'])).filter((x) => x !== undefined));
+    // 2. Select factors: derived follows goal.factors[]; all = every factor
+    let selectedFactors;
+    if (str(factorsConf['surface']) === 'all') {
+        selectedFactors = [...factorElems.values()];
+    }
+    else {
+        const refIds = new Set();
+        for (const g of selectedGoals)
+            for (const fid of strArray(g['factors']))
+                refIds.add(fid);
+        selectedFactors = [...refIds].flatMap((id) => { const f = factorElems.get(id); return f ? [f] : []; });
+    }
+    // 3. Select changes: derived = changes referencing ≥1 selected goal
+    let selectedChanges;
+    if (str(changesConf['surface']) === 'all') {
+        selectedChanges = [...changeElems.values()];
+    }
+    else {
+        selectedChanges = [...changeElems.values()].filter((c) => strArray(c['goals']).some((gid) => selectedGoalIds.has(gid)));
+    }
+    const selectedChangeIds = new Set(selectedChanges.map((c) => str(c['id'])).filter((x) => x !== undefined));
+    // 4. Select activities: derived = reference ≥1 selected change or goal (degenerate FGA link)
+    let selectedActivities;
+    if (str(activitiesConf['surface']) === 'all') {
+        selectedActivities = [...activityElems.values()];
+    }
+    else {
+        selectedActivities = [...activityElems.values()].filter((a) => strArray(a['changes']).some((cid) => selectedChangeIds.has(cid)) ||
+            strArray(a['goals']).some((gid) => selectedGoalIds.has(gid)));
+    }
+    return {
+        notation: 'fgca',
+        id: viewDoc['id'],
+        name: viewDoc['name'],
+        spec_version: viewDoc['spec_version'],
+        factors: selectedFactors,
+        goals: selectedGoals,
+        changes: selectedChanges,
+        activities: selectedActivities,
+    };
+}

package/dist/goals/index.d.ts

@@ -1,4 +1,4 @@
-export type { Goal, GoalType, GoalTree, Factor, ImpactType, ValidationResult, ValidationError, ValidationWarning, MutationResult, LayoutOptions, LaidOutNode, LaidOutEdge, GoalTreeLayout, } from './types.js';
+export type { Goal, GoalType, GoalTree, ImpactType, ValidationResult, ValidationError, ValidationWarning, MutationResult, LayoutOptions, LaidOutNode, LaidOutEdge, GoalTreeLayout, } from './types.js';
 export { validateGoalTree } from './validate.js';
 export { parseCanonicalGoals } from './parse-canonical.js';
 export type { CanonicalGoalsResult } from './parse-canonical.js';

package/dist/index.d.ts

@@ -1,13 +1,16 @@
 export * from "./activities/index";
 export * from "./activity-card/index";
+export * from "./actor/index";
 export * from "./geometry";
 export * from "./applications/index";
 export * from "./assertion/index";
 export * from "./blocks/index";
 export * from "./capability-map/index";
+export * from "./change/index";
 export * from "./compliance/index";
 export * from "./compliance-matrix/index";
 export * from "./confidence/index";
+export * from "./factor/index";
 export * from "./fgca/index";
 export * from "./goals/index";
 export * from "./process-blueprint/index";
@@ -16,6 +19,8 @@ export * from "./products/index";
 export * from "./repo-validate/index";
 export * from "./requirement/index";
 export * from "./scenarios/index";
+export * from "./stakeholder/index";
+export * from "./target-state/index";
 export { SCHEMA_VERSION } from "./schema-version";
 export * from "./theme/index";
 export * from "./typed-id";

package/dist/index.js

@@ -1,13 +1,16 @@
 export * from "./activities/index";
 export * from "./activity-card/index";
+export * from "./actor/index";
 export * from "./geometry";
 export * from "./applications/index";
 export * from "./assertion/index";
 export * from "./blocks/index";
 export * from "./capability-map/index";
+export * from "./change/index";
 export * from "./compliance/index";
 export * from "./compliance-matrix/index";
 export * from "./confidence/index";
+export * from "./factor/index";
 export * from "./fgca/index";
 export * from "./goals/index";
 export * from "./process-blueprint/index";
@@ -16,6 +19,8 @@ export * from "./products/index";
 export * from "./repo-validate/index";
 export * from "./requirement/index";
 export * from "./scenarios/index";
+export * from "./stakeholder/index";
+export * from "./target-state/index";
 export { SCHEMA_VERSION } from "./schema-version";
 export * from "./theme/index";
 export * from "./typed-id";