@transitrix/diagrams 1.9.18 → 1.11.0

package/dist/compliance-verification-matrix/build.js

@@ -0,0 +1,65 @@
+// Requirement -> verification matrix builder.
+import { buildGapReport } from '../compliance/gap-report.js';
+function byId(a, b) {
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+ * Builds the repository-wide requirement -> verification matrix.
+ *
+ * Pure projection over an already-built `ComplianceIndex`
+ * (`compliance/reverse-index.ts`) — no I/O, no revalidation. Reuses
+ * `buildGapReport`'s `REQ-VERIF-COVERAGE-001`/`-002` verdicts verbatim rather
+ * than recomputing a competing coverage status.
+ *
+ * Ordering: requirements sorted by id; within a requirement, its verification
+ * rows sorted by verification id. Both are explicit sorts over the index's
+ * values, so the result is independent of the Map's insertion order (which —
+ * for a caller that built the index from a filesystem walk — would otherwise
+ * track directory enumeration order).
+ */
+export function buildRequirementVerificationMatrix(index, options = {}) {
+    const gapReport = buildGapReport(index, options);
+    const noVerification = new Set(gapReport.requirementsWithoutVerification.map(r => r.id));
+    const unresolvedVerification = new Set(gapReport.requirementsWithUnresolvedVerification.map(r => r.id));
+    const requirements = [...index.requirementById.values()].sort(byId);
+    const rows = [];
+    let verificationRowCount = 0;
+    let gapRequirementCount = 0;
+    for (const requirement of requirements) {
+        const parentId = requirement.parent;
+        const parentLabel = parentId ? index.requirementById.get(parentId)?.name : undefined;
+        const base = {
+            requirementId: requirement.id,
+            requirementLabel: requirement.name,
+            ...(parentId !== undefined ? { parentId } : {}),
+            ...(parentLabel !== undefined ? { parentLabel } : {}),
+        };
+        if (noVerification.has(requirement.id)) {
+            gapRequirementCount++;
+            rows.push({ ...base, coverageGap: 'REQ-VERIF-COVERAGE-001' });
+            continue;
+        }
+        const gap = unresolvedVerification.has(requirement.id) ? 'REQ-VERIF-COVERAGE-002' : undefined;
+        if (gap)
+            gapRequirementCount++;
+        const verifications = [...(index.verificationsByRequirement.get(requirement.id) ?? [])].sort(byId);
+        for (const verification of verifications) {
+            verificationRowCount++;
+            rows.push({
+                ...base,
+                verificationId: verification.id,
+                verificationLabel: verification.protocol ?? verification.id,
+                verificationOutcome: verification.outcome,
+                ...(gap ? { coverageGap: gap } : {}),
+            });
+        }
+    }
+    return {
+        rows,
+        summary: {
+            requirements: requirements.length,
+            verifications: verificationRowCount,
+            gaps: gapRequirementCount,
+        },
+    };
+}

package/dist/compliance-verification-matrix/csv.d.ts

@@ -0,0 +1,6 @@
+import type { RequirementVerificationMatrix } from './types.js';
+/**
+ * Serialise the matrix to CSV. Identical input yields byte-identical output;
+ * the row order is the builder's stable order.
+ */
+export declare function renderRequirementVerificationMatrixCsv(matrix: RequirementVerificationMatrix): string;

package/dist/compliance-verification-matrix/csv.js

@@ -0,0 +1,41 @@
+// Deterministic CSV serialiser for the requirement-verification matrix.
+// Same row order as `buildRequirementVerificationMatrix` (requirement id,
+// then verification id). CRLF line endings, RFC-4180 quoting — the same
+// convention as the Gap Dashboard export.
+const HEADER = [
+    'requirement_id',
+    'requirement_label',
+    'parent_id',
+    'parent_label',
+    'related_test_result_id',
+    'related_test_result_label',
+    'outcome',
+    'coverage_gap',
+];
+function csvCell(value) {
+    const v = value ?? '';
+    return `"${v.replace(/"/g, '""')}"`;
+}
+function rowCells(row) {
+    return [
+        row.requirementId,
+        row.requirementLabel,
+        row.parentId ?? '',
+        row.parentLabel ?? '',
+        row.verificationId ?? '',
+        row.verificationLabel ?? '',
+        row.verificationOutcome ?? '',
+        row.coverageGap ?? '',
+    ];
+}
+/**
+ * Serialise the matrix to CSV. Identical input yields byte-identical output;
+ * the row order is the builder's stable order.
+ */
+export function renderRequirementVerificationMatrixCsv(matrix) {
+    const lines = [HEADER.map(h => csvCell(h)).join(',')];
+    for (const row of matrix.rows) {
+        lines.push(rowCells(row).map(csvCell).join(','));
+    }
+    return lines.join('\r\n') + '\r\n';
+}

package/dist/compliance-verification-matrix/index.d.ts

@@ -0,0 +1,3 @@
+export { buildRequirementVerificationMatrix } from './build.js';
+export { renderRequirementVerificationMatrixCsv } from './csv.js';
+export type { RequirementVerificationMatrix, RequirementVerificationMatrixOptions, RequirementVerificationRow, } from './types.js';

package/dist/compliance-verification-matrix/index.js

@@ -0,0 +1,2 @@
+export { buildRequirementVerificationMatrix } from './build.js';
+export { renderRequirementVerificationMatrixCsv } from './csv.js';

package/dist/compliance-verification-matrix/types.d.ts

@@ -0,0 +1,75 @@
+import type { VerificationOutcome } from '../verification/types.js';
+/**
+ * One row of the requirement-verification matrix.
+ *
+ * A requirement with N admitted VERIFICATION records produces N rows, one per
+ * verification. A requirement with none still produces exactly one row,
+ * carrying the `REQ-VERIF-COVERAGE-001` gap. A requirement whose
+ * verifications exist but never closed (pass/fail) produces one row per
+ * verification — each carrying the `REQ-VERIF-COVERAGE-002` gap alongside its
+ * (still-open) outcome; the open verification is real data and is never
+ * replaced by a placeholder gap row.
+ *
+ * Coverage comes only from `VERIFICATION.verifies` (27-verification.md §2). A
+ * child requirement's verification never covers its `parent`
+ * (15-requirement.md §2.4 — `parent` records structure only, no roll-up).
+ */
+export interface RequirementVerificationRow {
+    requirementId: string;
+    requirementLabel: string;
+    /**
+     * Direct `REQUIREMENT.parent` id, verbatim, present whenever the field is
+     * set — whether or not it resolves. `parent` resolution is not currently a
+     * validator concern (15-requirement.md §2.4); a dangling parent must still
+     * be visible on the row, not silently dropped.
+     */
+    parentId?: string;
+    /**
+     * The resolved parent's `name`, present only when `parentId` names an
+     * admitted requirement in the index. Absent when `parentId` is set but
+     * unresolved (dangling), or when the requirement has no parent.
+     */
+    parentLabel?: string;
+    /** The verification filling this row, when one exists. */
+    verificationId?: string;
+    /**
+     * VERIFICATION carries no `name`/label field of its own
+     * (27-verification.md §2); `protocol` — the procedure description — is the
+     * closest human-readable text and is what this row shows as its label.
+     */
+    verificationLabel?: string;
+    verificationOutcome?: VerificationOutcome;
+    /**
+     * `REQ-VERIF-COVERAGE-001` / `-002` (`compliance/gap-report.ts`), reused
+     * verbatim — this builder never recomputes a competing coverage verdict.
+     * Absent once the requirement has at least one closed (pass/fail)
+     * verification.
+     */
+    coverageGap?: 'REQ-VERIF-COVERAGE-001' | 'REQ-VERIF-COVERAGE-002';
+}
+export interface RequirementVerificationMatrixOptions {
+    /**
+     * Forwarded to `buildGapReport`. Neither coverage gap this matrix surfaces
+     * (`REQ-VERIF-COVERAGE-001`/`-002`) depends on `today` — accepted only for
+     * call-site symmetry with the other compliance-view builders.
+     */
+    today?: string;
+}
+export interface RequirementVerificationMatrix {
+    /**
+     * One row per (requirement, verification) pair, plus one gap row per
+     * requirement with zero verifications.
+     *
+     * Ordering (stable, independent of filesystem/Map enumeration order):
+     * requirements sorted by id; within a requirement, its verification rows
+     * sorted by verification id.
+     */
+    rows: RequirementVerificationRow[];
+    summary: {
+        requirements: number;
+        /** Rows carrying a real verification (excludes -001 gap-only rows). */
+        verifications: number;
+        /** Requirements carrying a REQ-VERIF-COVERAGE-001 or -002 gap. */
+        gaps: number;
+    };
+}

package/dist/compliance-verification-matrix/types.js

@@ -0,0 +1,4 @@
+// Requirement -> verification matrix — deterministic, repository-wide
+// projection over the shared compliance reverse-index. Pure data; the
+// consumer (a VS Code table, an export) renders it.
+export {};

package/dist/fgca/action-change-ids.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Action → Change linkage on an element record.
+ *
+ * Canonical field is `delivers_changes` (Action element spec). `changes` is
+ * the pre-rename alias still present on older fixtures and inline docs.
+ */
+export declare function actionChangeLinkField(el: Record<string, unknown>): 'delivers_changes' | 'changes';

package/dist/fgca/action-change-ids.js

@@ -0,0 +1,11 @@
+/**
+ * Action → Change linkage on an element record.
+ *
+ * Canonical field is `delivers_changes` (Action element spec). `changes` is
+ * the pre-rename alias still present on older fixtures and inline docs.
+ */
+export function actionChangeLinkField(el) {
+    return Object.prototype.hasOwnProperty.call(el, 'delivers_changes')
+        ? 'delivers_changes'
+        : 'changes';
+}

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`
@@ -29,6 +29,8 @@ export interface CanonicalFGCAResult extends ValidationResult {
     /** On success, the internal-form FGCADoc derived from the canonical input. */
     parsed?: FGCADoc;
 }
+/** 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`.

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'];
@@ -99,7 +102,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']);
@@ -212,11 +215,12 @@ export function parseCanonicalFGCA(input) {
             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.
@@ -286,6 +290,7 @@ export function parseCanonicalFGCA(input) {
         goals: internalGoals,
         changes: internalChanges,
         activities: internalActivities,
+        hideChanges: isDgcaChangesLayerOff(raw),
     };
     return { valid: true, errors, warnings, parsed };
 }

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,13 +113,13 @@ 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)));
     }
     return {
@@ -126,5 +131,6 @@ export function resolveFGCA(viewDoc, sources) {
         goals: selectedGoals,
         changes: selectedChanges,
         actions: selectedActivities,
+        view_config: viewDoc['view_config'],
     };
 }

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[];