@transitrix/diagrams 1.10.0 → 1.12.0

package/dist/fgca/parse-canonical.d.ts

@@ -8,7 +8,7 @@
  * - Typed string IDs per `IDS_AND_REFERENCES.md` (`FACTOR-1`,
  *   `GOAL-RET-1`, `CHANGE-1`, `ACTION-ONBOARD-1` (legacy `ACTIVITY-*` accepted).
  * - Plural canonical-direction cross-references: `goal.factors`,
- *   `change.goals`, `activity.changes`, `activity.goals`.
+ *   `change.goals`, `action.delivers_changes`, `action.goals`.
  * - Per-notation validation codes `FGCA-001 … FGCA-015`.
  *
  * Returns the validation result plus, on success, an internal `FGCADoc`
@@ -28,15 +28,29 @@ import type { ValidationResult } from '../validation-types.js';
 export interface CanonicalFGCAResult extends ValidationResult {
     /** On success, the internal-form FGCADoc derived from the canonical input. */
     parsed?: FGCADoc;
+    /** True when a goal-scoped projection should show the scope caption. */
+    scopeCaption?: boolean;
 }
+/** DGA mode (`view_config.layers.changes: off`) omits the Changes column. */
+export declare function isDgcaChangesLayerOff(input: unknown): boolean;
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
  * `FGCADoc` ready for `buildFGCALayout`.
+ *
+ * @param input The FGCA document to parse
+ * @param outOfScopeGoalIds When a goal-scoped projection omits goals that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-011/FGCA-009 errors
+ *        for references to out-of-scope goals. When provided and non-empty, and at least
+ *        one action or change references an out-of-scope goal, `scopeCaption` is set true.
+ * @param outOfScopeFactorIds When a goal-scoped projection omits factors that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-008 errors.
  */
-export declare function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult;
+export declare function parseCanonicalFGCA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null): CanonicalFGCAResult;
 /** On success, the internal-form FGCADoc derived from canonical FGA input. */
 export interface CanonicalFGAResult extends ValidationResult {
     parsed?: FGCADoc;
+    /** True when a goal-scoped projection should show the scope caption. */
+    scopeCaption?: boolean;
 }
 /**
  * Canonical-form FGA parser + validator.
@@ -55,4 +69,4 @@ export interface CanonicalFGAResult extends ValidationResult {
  * the canonical FGA path is unit-testable and the library owns the single
  * canon shape — flat form only, no `fga:` wrapper.
  */
-export declare function parseCanonicalFGA(input: unknown): CanonicalFGAResult;
+export declare function parseCanonicalFGA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null): CanonicalFGAResult;

package/dist/fgca/parse-canonical.js

@@ -8,7 +8,7 @@
  * - Typed string IDs per `IDS_AND_REFERENCES.md` (`FACTOR-1`,
  *   `GOAL-RET-1`, `CHANGE-1`, `ACTION-ONBOARD-1` (legacy `ACTIVITY-*` accepted).
  * - Plural canonical-direction cross-references: `goal.factors`,
- *   `change.goals`, `activity.changes`, `activity.goals`.
+ *   `change.goals`, `action.delivers_changes`, `action.goals`.
  * - Per-notation validation codes `FGCA-001 … FGCA-015`.
  *
  * Returns the validation result plus, on success, an internal `FGCADoc`
@@ -23,6 +23,7 @@
  * unify the internal types with the canonical form across all sister
  * modules.
  */
+import { actionChangeLinkField } from './action-change-ids.js';
 // Canonical ID grammars per IDS_AND_REFERENCES.md §1. The TYPE prefix
 // is fixed per layer; middle segments are optional; the terminal is a
 // positive integer with no leading zeros.
@@ -43,9 +44,11 @@ function asObjectArray(v) {
         return null;
     return v.map((el) => (el && typeof el === 'object' ? el : null));
 }
-/** DGA mode (`view_config.layers.changes: off`) may omit the changes layer. */
-function isChangesLayerOff(raw) {
-    const vc = raw['view_config'];
+/** DGA mode (`view_config.layers.changes: off`) omits the Changes column. */
+export function isDgcaChangesLayerOff(input) {
+    if (!input || typeof input !== 'object')
+        return false;
+    const vc = input['view_config'];
     if (!vc || typeof vc !== 'object')
         return false;
     const layers = vc['layers'];
@@ -56,8 +59,16 @@ function isChangesLayerOff(raw) {
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
  * `FGCADoc` ready for `buildFGCALayout`.
+ *
+ * @param input The FGCA document to parse
+ * @param outOfScopeGoalIds When a goal-scoped projection omits goals that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-011/FGCA-009 errors
+ *        for references to out-of-scope goals. When provided and non-empty, and at least
+ *        one action or change references an out-of-scope goal, `scopeCaption` is set true.
+ * @param outOfScopeFactorIds When a goal-scoped projection omits factors that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-008 errors.
  */
-export function parseCanonicalFGCA(input) {
+export function parseCanonicalFGCA(input, outOfScopeGoalIds, outOfScopeFactorIds) {
     const errors = [];
     const warnings = [];
     if (!input || typeof input !== 'object') {
@@ -99,7 +110,7 @@ export function parseCanonicalFGCA(input) {
     const factorsRaw = asObjectArray(raw['factors']);
     const goalsRaw = asObjectArray(raw['goals']);
     let changesRaw = asObjectArray(raw['changes']);
-    if (changesRaw === null && raw['changes'] === undefined && isChangesLayerOff(raw)) {
+    if (changesRaw === null && raw['changes'] === undefined && isDgcaChangesLayerOff(raw)) {
         changesRaw = [];
     }
     const activitiesRaw = asObjectArray(raw['actions']);
@@ -170,8 +181,10 @@ export function parseCanonicalFGCA(input) {
     activities.forEach((el, i) => checkLayerElement(el, `activities[${i}]`, ACTION_OR_ACTIVITY_ID_RE, activityIds));
     if (errors.length > 0)
         return { valid: false, errors, warnings };
+    // Track if any out-of-scope goals/factors are referenced (for scope caption).
+    let hasOutOfScopeRef = false;
     // Cross-refs.
-    function checkRefArray(el, field, targets, refRe, code, path) {
+    function checkRefArray(el, field, targets, refRe, code, path, outOfScope) {
         const ref = el[field];
         if (ref === undefined || ref === null)
             return [];
@@ -189,6 +202,12 @@ export function parseCanonicalFGCA(input) {
                 errors.push({ code: 'FGCA-007', message: `${path}.${field}[] entry "${r}" does not match the expected grammar`, path });
                 continue;
             }
+            if (outOfScope?.has(r)) {
+                // Reference is out-of-scope: suppress error and mark that we found an out-of-scope reference (for caption).
+                hasOutOfScopeRef = true;
+                out.push(r);
+                continue;
+            }
             if (!targets.has(r)) {
                 errors.push({ code, message: `${path}.${field}[] references undeclared element "${r}"`, path });
                 continue;
@@ -205,18 +224,19 @@ export function parseCanonicalFGCA(input) {
         name: String(el['name'] ?? ''),
     }));
     const internalGoals = goals.map((el, i) => {
-        const refIds = checkRefArray(el, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`);
+        const refIds = checkRefArray(el, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`, outOfScopeFactorIds);
         return {
             id: String(el['id']),
             name: String(el['name'] ?? ''),
             factor: refIds.map((r) => ({ id: r })),
         };
     });
-    // Build a reverse mapping: which changes does each activity reference (via
-    // canonical activity.changes)? Used to populate the internal `change.activity_ids`.
+    // Build a reverse mapping: which changes does each action deliver (via
+    // canonical `delivers_changes`, or the pre-rename `changes` alias)?
     const activityChangesByCanonicalActivityId = new Map();
     activities.forEach((el, i) => {
-        const refIds = checkRefArray(el, 'changes', changeIds, CHANGE_ID_RE, 'FGCA-010', `activities[${i}]`);
+        const field = actionChangeLinkField(el);
+        const refIds = checkRefArray(el, field, changeIds, CHANGE_ID_RE, 'FGCA-010', `activities[${i}]`);
         activityChangesByCanonicalActivityId.set(String(el['id']), refIds);
     });
     // For each change, find the activities that reference it.
@@ -229,7 +249,7 @@ export function parseCanonicalFGCA(input) {
         }
     }
     const internalChanges = changes.map((el, i) => {
-        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`);
+        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`, outOfScopeGoalIds);
         // Internal `change.goal_id` is singular; canonical `change.goals` is plural.
         // First goal wins for the singular field; warn (not error) if multiple.
         if (goalRefs.length > 1) {
@@ -249,7 +269,7 @@ export function parseCanonicalFGCA(input) {
         };
     });
     const internalActivities = activities.map((el, i) => {
-        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`);
+        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`, outOfScopeGoalIds);
         const typeVal = typeof el['type'] === 'string' ? el['type'] : undefined;
         return {
             id: String(el['id']),
@@ -286,8 +306,15 @@ export function parseCanonicalFGCA(input) {
         goals: internalGoals,
         changes: internalChanges,
         activities: internalActivities,
+        hideChanges: isDgcaChangesLayerOff(raw),
+    };
+    return {
+        valid: true,
+        errors,
+        warnings,
+        parsed,
+        scopeCaption: (outOfScopeGoalIds?.size ?? 0) > 0 && hasOutOfScopeRef,
     };
-    return { valid: true, errors, warnings, parsed };
 }
 const FGA_DOC_ID_RE = /^(FGA|DGA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 /**
@@ -307,7 +334,7 @@ const FGA_DOC_ID_RE = /^(FGA|DGA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
  * the canonical FGA path is unit-testable and the library owns the single
  * canon shape — flat form only, no `fga:` wrapper.
  */
-export function parseCanonicalFGA(input) {
+export function parseCanonicalFGA(input, outOfScopeGoalIds, outOfScopeFactorIds) {
     if (!input || typeof input !== 'object') {
         return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
     }
@@ -334,7 +361,7 @@ export function parseCanonicalFGA(input) {
     // codes are remapped on the way out. FGCA-009 / 010 / 014 (changes-related)
     // are unreachable here because `changes` is empty.
     const synth = { ...raw, notation: 'dgca', id: 'DGCA-FROM-DGA-1', changes: [] };
-    const r = parseCanonicalFGCA(synth);
+    const r = parseCanonicalFGCA(synth, outOfScopeGoalIds, outOfScopeFactorIds);
     const remap = {
         'FGCA-001': 'FGA-001',
         'FGCA-002': 'FGA-002',
@@ -354,5 +381,6 @@ export function parseCanonicalFGA(input) {
         errors: r.errors.map((e) => ({ ...e, code: remapCode(e.code) })),
         warnings: r.warnings.map((w) => ({ ...w, code: remapCode(w.code) })),
         parsed: r.parsed,
+        scopeCaption: r.scopeCaption,
     };
 }

package/dist/fgca/resolver.d.ts

@@ -18,6 +18,10 @@ export interface FGCAViewConfig {
     changes?: {
         surface?: 'derived' | 'all';
     };
+    /** Canonical projection key. `activities` remains a deprecated alias. */
+    actions?: {
+        surface?: 'derived' | 'all';
+    };
     activities?: {
         surface?: 'derived' | 'all';
     };
@@ -43,7 +47,7 @@ export declare function isFGCAViewDoc(parsed: unknown): boolean;
  * to pass to `parseCanonicalFGCA`.
  *
  * Cross-reference fields (`goal.factors[]`, `change.goals[]`,
- * `action.changes[]`) are carried from the canon elements unchanged; the
- * resolver decides which elements to include, not how they are shaped.
+ * `action.delivers_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

@@ -6,6 +6,7 @@
  * top-level `factors[]`, `goals[]`, `changes[]`, `actions[]` with typed
  * string IDs.  Filesystem-free — callable from unit tests without vscode.
  */
+import { actionChangeLinkField } from './action-change-ids.js';
 function isObject(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
@@ -49,8 +50,8 @@ export function isFGCAViewDoc(parsed) {
  * to pass to `parseCanonicalFGCA`.
  *
  * Cross-reference fields (`goal.factors[]`, `change.goals[]`,
- * `action.changes[]`) are carried from the canon elements unchanged; the
- * resolver decides which elements to include, not how they are shaped.
+ * `action.delivers_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)) {
@@ -60,7 +61,11 @@ export function resolveFGCA(viewDoc, sources) {
     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 actionsConf = isObject(vc['actions'])
+        ? vc['actions']
+        : isObject(vc['activities'])
+            ? vc['activities']
+            : {};
     const factorElemsLegacy = collectByNotation(sources.elements, 'factor');
     const factorElemsNew = collectByNotation(sources.elements, 'driver');
     const factorElems = new Map([...factorElemsLegacy, ...factorElemsNew]);
@@ -108,15 +113,29 @@ export function resolveFGCA(viewDoc, sources) {
         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)
+    // 4. Select actions: derived = delivers ≥1 selected change, or (DGA) a selected goal
     let selectedActivities;
-    if (str(activitiesConf['surface']) === 'all') {
+    if (str(actionsConf['surface']) === 'all') {
         selectedActivities = [...activityElems.values()];
     }
     else {
-        selectedActivities = [...activityElems.values()].filter((a) => strArray(a['changes']).some((cid) => selectedChangeIds.has(cid)) ||
+        selectedActivities = [...activityElems.values()].filter((a) => strArray(a[actionChangeLinkField(a)]).some((cid) => selectedChangeIds.has(cid)) ||
             strArray(a['goals']).some((gid) => selectedGoalIds.has(gid)));
     }
+    // Collect out-of-scope goals (exist in catalogue but not in selected set).
+    // Used by the validator to suppress errors for references to goals that exist
+    // but are outside the scope.
+    let outOfScopeGoalIds;
+    if (goalsFilter !== 'all') {
+        // Goal scope is restricted; collect goals that exist but aren't selected.
+        outOfScopeGoalIds = new Set([...goalElems.keys()].filter((id) => !selectedGoalIds.has(id)));
+    }
+    // Collect out-of-scope factors (exist in catalogue but not in selected set).
+    const selectedFactorIds = new Set(selectedFactors.map((f) => str(f['id'])).filter((x) => x !== undefined));
+    let outOfScopeFactorIds;
+    if (goalsFilter !== 'all') {
+        outOfScopeFactorIds = new Set([...factorElems.keys()].filter((id) => !selectedFactorIds.has(id)));
+    }
     return {
         notation: 'dgca',
         id: viewDoc['id'],
@@ -126,5 +145,8 @@ export function resolveFGCA(viewDoc, sources) {
         goals: selectedGoals,
         changes: selectedChanges,
         actions: selectedActivities,
+        view_config: viewDoc['view_config'],
+        __outOfScopeGoalIds: outOfScopeGoalIds,
+        __outOfScopeFactorIds: outOfScopeFactorIds,
     };
 }

package/dist/fgca/validate.d.ts

@@ -10,5 +10,7 @@ export interface FGCADoc {
     goals: GoalItem[];
     changes: BdnChangeWithActivities[];
     activities: ActivityItem[];
+    /** DGA mode: omit the Changes column (`view_config.layers.changes: off`). */
+    hideChanges?: boolean;
 }
 export declare function validateFGCADoc(input: unknown): FGCAValidationResult;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { validateCapabilityMap, layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE
 export * from "./change/index";
 export * from "./compliance/index";
 export * from "./compliance-matrix/index";
+export * from "./compliance-verification-matrix/index";
 export * from "./confidence/index";
 export * from "./factor/index";
 export * from "./fgca/index";

package/dist/index.js

@@ -10,6 +10,7 @@ export { validateCapabilityMap, layoutCapabilityTree, TREE_NODE_WIDTH, TREE_NODE
 export * from "./change/index.js";
 export * from "./compliance/index.js";
 export * from "./compliance-matrix/index.js";
+export * from "./compliance-verification-matrix/index.js";
 export * from "./confidence/index.js";
 export * from "./factor/index.js";
 export * from "./fgca/index.js";

package/dist/process-blueprint/index.d.ts

@@ -1,4 +1,6 @@
 export type { AspectCategory, RowId, Stage, AspectEntry, LaneConfig, ProcessBlueprintHeader, ProcessBlueprintFile, ProcessBlueprintLayoutOptions, LegendCell, StageHeaderCell, StageTextCell, AspectPill, AspectRow, ProcessBlueprintLayout, ComplianceDecoration, ComplianceChip, ComplianceRow, ComplianceLaneConfig, ComplianceLaneAssertion, ComplianceLaneRequirement, ComplianceLaneInput, } from './types.js';
 export { validateProcessBlueprint } from './validate.js';
-export type { ValidationError as ProcessBlueprintValidationError, ValidationWarning as ProcessBlueprintValidationWarning, ValidationResult as ProcessBlueprintValidationResult, } from './validate.js';
+export type { ValidationError as ProcessBlueprintValidationError, ValidationWarning as ProcessBlueprintValidationWarning, ValidationResult as ProcessBlueprintValidationResult, ProcessBlueprintValidateOptions, ProcessParentEdge, } from './validate.js';
 export { layoutProcessBlueprint } from './layout.js';
+export { collectProcessColumnRecords, collectStepHomeProcess, columnIndexesForRealisedVia, isProcessColumnId, isStageColumnId, resolveColumnDisplay, } from './resolve-columns.js';
+export type { ProcessColumnRecord } from './resolve-columns.js';

package/dist/process-blueprint/index.js

@@ -1,2 +1,3 @@
 export { validateProcessBlueprint } from './validate.js';
 export { layoutProcessBlueprint } from './layout.js';
+export { collectProcessColumnRecords, collectStepHomeProcess, columnIndexesForRealisedVia, isProcessColumnId, isStageColumnId, resolveColumnDisplay, } from './resolve-columns.js';

package/dist/process-blueprint/layout.js

@@ -1,4 +1,5 @@
 import { wrapTextLines } from '../webview/entity-text-layout.js';
+import { columnIndexesForRealisedVia, resolveColumnDisplay } from './resolve-columns.js';
 const ASPECT_CATEGORIES = ['systems', 'actors', 'equipment', 'information_entities'];
 const ASPECT_LABEL = {
     systems: 'Systems',
@@ -181,29 +182,31 @@ function deriveComplianceRow(stages, stageIndexById, input, opts, yStart) {
         for (const stageRef of realisedVia) {
             if (typeof stageRef !== 'string')
                 continue;
-            const idx = stageIndexById.get(stageRef.trim());
-            if (idx === undefined)
+            const idxs = columnIndexesForRealisedVia(stageRef, stageIndexById, opts.stepHomeProcess);
+            if (idxs.length === 0)
                 continue;
-            for (const lawId of lawIds) {
-                // Apply jurisdiction filter.
-                if (filterJurisdictions) {
-                    const jur = input.codexJurisdictions?.[lawId];
-                    if (!jur || !filterJurisdictions.has(jur))
-                        continue;
-                }
-                if (!stageAccum.has(idx))
-                    stageAccum.set(idx, new Map());
-                const lawMap = stageAccum.get(idx);
-                const existing = lawMap.get(lawId);
-                const isGap = a.status === 'non_compliant' || a.status === 'partial';
-                if (!existing) {
-                    lawMap.set(lawId, { gap: isGap, deadline: req.deadline });
-                }
-                else {
-                    existing.gap = existing.gap || isGap;
-                    // Keep the earlier deadline (more urgent).
-                    if (req.deadline && (!existing.deadline || req.deadline < existing.deadline)) {
-                        existing.deadline = req.deadline;
+            for (const idx of idxs) {
+                for (const lawId of lawIds) {
+                    // Apply jurisdiction filter.
+                    if (filterJurisdictions) {
+                        const jur = input.codexJurisdictions?.[lawId];
+                        if (!jur || !filterJurisdictions.has(jur))
+                            continue;
+                    }
+                    if (!stageAccum.has(idx))
+                        stageAccum.set(idx, new Map());
+                    const lawMap = stageAccum.get(idx);
+                    const existing = lawMap.get(lawId);
+                    const isGap = a.status === 'non_compliant' || a.status === 'partial';
+                    if (!existing) {
+                        lawMap.set(lawId, { gap: isGap, deadline: req.deadline });
+                    }
+                    else {
+                        existing.gap = existing.gap || isGap;
+                        // Keep the earlier deadline (more urgent).
+                        if (req.deadline && (!existing.deadline || req.deadline < existing.deadline)) {
+                            existing.deadline = req.deadline;
+                        }
                     }
                 }
             }
@@ -253,6 +256,7 @@ export function layoutProcessBlueprint(file, options) {
         ? allStages.filter(s => s?.id != null && opts.visibleStages.includes(s.id))
         : allStages;
     const stageIndexById = buildStageIndex(stages);
+    const display = stages.map(s => resolveColumnDisplay(s, opts.processCatalog));
     // Row visibility from visibleRows
     const visRows = opts.visibleRows;
     const showGoal = !visRows || visRows.includes('goal');
@@ -266,7 +270,7 @@ export function layoutProcessBlueprint(file, options) {
     const stageHeaders = stages.map((s, i) => ({
         stageIndex: i,
         id: s?.id ?? '',
-        name: s?.name ?? '',
+        name: display[i].name,
         x: opts.legendColumnWidth + i * opts.stageColumnWidth,
         y: 0,
         width: opts.stageColumnWidth,
@@ -280,8 +284,8 @@ export function layoutProcessBlueprint(file, options) {
         const maxLines = Math.max(1, ...lineCounts);
         return Math.max(minHeight, maxLines * opts.textLineHeight + 2 * opts.cellTextPadY);
     };
-    const goalLines = stages.map(s => wrap(s?.goal ?? ''));
-    const resultLines = stages.map(s => wrap(s?.result ?? ''));
+    const goalLines = display.map(d => wrap(d.goal));
+    const resultLines = display.map(d => wrap(d.result));
     let cursorY = opts.stageHeaderHeight;
     let goalRowY = 0, goalRowHeight = 0;
     let resultRowY = 0, resultRowHeight = 0;
@@ -290,8 +294,8 @@ export function layoutProcessBlueprint(file, options) {
     if (showGoal) {
         goalRowY = cursorY;
         goalRowHeight = rowHeightFor(goalLines.map(l => l.length), opts.goalRowHeight);
-        goalCells.push(...stages.map((s, i) => ({
-            stageIndex: i, text: s?.goal ?? '', lines: goalLines[i],
+        goalCells.push(...display.map((d, i) => ({
+            stageIndex: i, text: d.goal, lines: goalLines[i],
             x: opts.legendColumnWidth + i * opts.stageColumnWidth, y: goalRowY,
             width: opts.stageColumnWidth, height: goalRowHeight,
         })));
@@ -300,8 +304,8 @@ export function layoutProcessBlueprint(file, options) {
     if (showResult) {
         resultRowY = cursorY;
         resultRowHeight = rowHeightFor(resultLines.map(l => l.length), opts.resultRowHeight);
-        resultCells.push(...stages.map((s, i) => ({
-            stageIndex: i, text: s?.result ?? '', lines: resultLines[i],
+        resultCells.push(...display.map((d, i) => ({
+            stageIndex: i, text: d.result, lines: resultLines[i],
             x: opts.legendColumnWidth + i * opts.stageColumnWidth, y: resultRowY,
             width: opts.stageColumnWidth, height: resultRowHeight,
         })));

package/dist/process-blueprint/resolve-columns.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Render-time resolution of Process Blueprint column headers and the
+ * compliance-lane join key.
+ *
+ * A `PROCESS-…` column is the process: `name` / `goal` / `result` come from
+ * the child PROCESS element (ELEMENT_PRIMITIVES §7.5), never from restated
+ * view fields. A `STAGE-…` column keeps the authored sketch copy.
+ *
+ * Pure: no I/O. The host (VS Code preview, JCEF, CLI) already owns loading
+ * canon/elements/** — this module only knows how to pick PROCESS / STEP
+ * records out of that pool.
+ *
+ * This is a read model, never storage. Callers render an ephemeral display
+ * copy and must never serialise it back onto the view.
+ */
+import type { Stage } from './types.js';
+export declare function isProcessColumnId(id: string): boolean;
+export declare function isStageColumnId(id: string): boolean;
+/** Display fields taken from a `notation: process` element. */
+export interface ProcessColumnRecord {
+    name: string;
+    goal?: string;
+    result?: string;
+}
+/**
+ * Collect admitted PROCESS elements from a raw canon/elements/** doc pool,
+ * keyed by id. Malformed documents are skipped.
+ */
+export declare function collectProcessColumnRecords(docs: readonly unknown[]): Map<string, ProcessColumnRecord>;
+/**
+ * Map each STEP id onto the PROCESS that contains it — either inline in
+ * `PROCESS.flow.steps[]` or a promoted `{ notation: step, process }` element.
+ * First writer wins; a later duplicate is ignored.
+ */
+export declare function collectStepHomeProcess(docs: readonly unknown[]): Map<string, string>;
+/**
+ * Display copy for one column. PROCESS- columns ignore any restated view
+ * fields; missing catalogue falls back to the id (header) and empty
+ * goal/result. STAGE- columns keep authored name/goal/result.
+ */
+export declare function resolveColumnDisplay(stage: Stage, catalog?: ReadonlyMap<string, ProcessColumnRecord>): {
+    name: string;
+    goal: string;
+    result: string;
+};
+/**
+ * Column indexes a `realised_via` token pins on this blueprint.
+ *
+ * `STAGE-…` is never a join key (ASSERT-004). A `PROCESS-…` token pins that
+ * column. A STEP whose home process is a column pins that column.
+ */
+export declare function columnIndexesForRealisedVia(ref: string, stageIndexById: ReadonlyMap<string, number>, stepHomeProcess?: ReadonlyMap<string, string>): number[];

package/dist/process-blueprint/resolve-columns.js

@@ -0,0 +1,138 @@
+/**
+ * Render-time resolution of Process Blueprint column headers and the
+ * compliance-lane join key.
+ *
+ * A `PROCESS-…` column is the process: `name` / `goal` / `result` come from
+ * the child PROCESS element (ELEMENT_PRIMITIVES §7.5), never from restated
+ * view fields. A `STAGE-…` column keeps the authored sketch copy.
+ *
+ * Pure: no I/O. The host (VS Code preview, JCEF, CLI) already owns loading
+ * canon/elements/** — this module only knows how to pick PROCESS / STEP
+ * records out of that pool.
+ *
+ * This is a read model, never storage. Callers render an ephemeral display
+ * copy and must never serialise it back onto the view.
+ */
+const PROCESS_ID_RE = /^PROCESS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const STAGE_ID_RE = /^STAGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+export function isProcessColumnId(id) {
+    return PROCESS_ID_RE.test(id);
+}
+export function isStageColumnId(id) {
+    return STAGE_ID_RE.test(id);
+}
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function optionalString(v) {
+    return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+}
+/**
+ * Collect admitted PROCESS elements from a raw canon/elements/** doc pool,
+ * keyed by id. Malformed documents are skipped.
+ */
+export function collectProcessColumnRecords(docs) {
+    const out = new Map();
+    for (const doc of docs) {
+        if (!isRecord(doc))
+            continue;
+        if (doc['notation'] !== 'process')
+            continue;
+        const id = optionalString(doc['id']);
+        if (!id || !isProcessColumnId(id))
+            continue;
+        const name = optionalString(doc['name']);
+        if (!name)
+            continue;
+        const rec = { name };
+        const goal = optionalString(doc['goal']);
+        const result = optionalString(doc['result']);
+        if (goal)
+            rec.goal = goal;
+        if (result)
+            rec.result = result;
+        out.set(id, rec);
+    }
+    return out;
+}
+/**
+ * Map each STEP id onto the PROCESS that contains it — either inline in
+ * `PROCESS.flow.steps[]` or a promoted `{ notation: step, process }` element.
+ * First writer wins; a later duplicate is ignored.
+ */
+export function collectStepHomeProcess(docs) {
+    const out = new Map();
+    for (const doc of docs) {
+        if (!isRecord(doc))
+            continue;
+        if (doc['notation'] === 'process') {
+            const processId = optionalString(doc['id']);
+            if (!processId || !isProcessColumnId(processId))
+                continue;
+            const flow = isRecord(doc['flow']) ? doc['flow'] : undefined;
+            const steps = flow && Array.isArray(flow['steps']) ? flow['steps'] : [];
+            for (const step of steps) {
+                if (!isRecord(step))
+                    continue;
+                const stepId = optionalString(step['id']);
+                if (!stepId || out.has(stepId))
+                    continue;
+                out.set(stepId, processId);
+            }
+            continue;
+        }
+        if (doc['notation'] === 'step') {
+            const stepId = optionalString(doc['id']);
+            const processId = optionalString(doc['process']);
+            if (!stepId || !processId || !isProcessColumnId(processId))
+                continue;
+            if (!out.has(stepId))
+                out.set(stepId, processId);
+        }
+    }
+    return out;
+}
+/**
+ * Display copy for one column. PROCESS- columns ignore any restated view
+ * fields; missing catalogue falls back to the id (header) and empty
+ * goal/result. STAGE- columns keep authored name/goal/result.
+ */
+export function resolveColumnDisplay(stage, catalog) {
+    const id = typeof stage.id === 'string' ? stage.id.trim() : '';
+    if (isProcessColumnId(id)) {
+        const rec = catalog?.get(id);
+        return {
+            name: rec?.name ?? id,
+            goal: rec?.goal ?? '',
+            result: rec?.result ?? '',
+        };
+    }
+    return {
+        name: typeof stage.name === 'string' ? stage.name : '',
+        goal: typeof stage.goal === 'string' ? stage.goal : '',
+        result: typeof stage.result === 'string' ? stage.result : '',
+    };
+}
+/**
+ * Column indexes a `realised_via` token pins on this blueprint.
+ *
+ * `STAGE-…` is never a join key (ASSERT-004). A `PROCESS-…` token pins that
+ * column. A STEP whose home process is a column pins that column.
+ */
+export function columnIndexesForRealisedVia(ref, stageIndexById, stepHomeProcess) {
+    const token = ref.trim();
+    if (token.length === 0)
+        return [];
+    if (isStageColumnId(token))
+        return [];
+    const direct = stageIndexById.get(token);
+    if (direct !== undefined && isProcessColumnId(token))
+        return [direct];
+    const home = stepHomeProcess?.get(token);
+    if (home && isProcessColumnId(home)) {
+        const idx = stageIndexById.get(home);
+        if (idx !== undefined)
+            return [idx];
+    }
+    return [];
+}