@transitrix/diagrams 1.10.0 → 1.12.0

package/dist/webview/render-process.js

@@ -14,6 +14,28 @@
  */
 import { generateSvgEmbedCss } from '../theme/index.js';
 import { escXml } from './render-util.js';
+/** Interactive-preview / default-export type sizes. */
+export const DEFAULT_BPMN_TYPOGRAPHY = {
+    taskFontPx: 11,
+    headerFontPx: 11,
+    labelFontPx: 10,
+    taskChars: 14,
+    taskLineH: 14,
+    labelChars: 18,
+    labelLineH: 13,
+    headerCharW: 6.5,
+};
+/** Presentation-export type sizes (20 px floor, wrap tuned to default node boxes). */
+export const PRESENTATION_BPMN_TYPOGRAPHY = {
+    taskFontPx: 20,
+    headerFontPx: 20,
+    labelFontPx: 20,
+    taskChars: 9,
+    taskLineH: 22,
+    labelChars: 14,
+    labelLineH: 22,
+    headerCharW: 11.5,
+};
 // ---------------------------------------------------------------------------
 // Constants — match DEFAULT_LAYOUT_DIAGRAM_OPTIONS in src/layout-options.ts
 // ---------------------------------------------------------------------------
@@ -21,43 +43,49 @@ import { escXml } from './render-util.js';
 const LANE_LABEL_BAND = 44;
 /** End margin (px) along the header height axis for rotated pool/lane captions. */
 const HEADER_LABEL_AXIS_PAD = 32;
-/** Estimated horizontal advance (px) per character at the header label font size. */
-const HEADER_LABEL_CHAR_W = 6.5;
-/** Maximum characters per wrapped line inside a task box. */
-const TASK_CHARS = 14;
-/** Line height for wrapped task-name text (px). */
-const TASK_LINE_H = 14;
-/** Maximum characters per line for below-element labels (events, gateways). */
-const LABEL_CHARS = 18;
-/** Line height for multi-line below-element labels (px). */
-const LABEL_LINE_H = 13;
+/** Active wrap/font metrics for the current render call (sync, restored after). */
+let typo = DEFAULT_BPMN_TYPOGRAPHY;
+function runWithTypography(t, fn) {
+    const prev = typo;
+    typo = t;
+    try {
+        return fn();
+    }
+    finally {
+        typo = prev;
+    }
+}
 // ---------------------------------------------------------------------------
 // BPMN-specific CSS — no font-style:italic per CLAUDE.md design rule
 // ---------------------------------------------------------------------------
-export const BPMN_PROCESS_CSS = `
+export function bpmnProcessCss(t = DEFAULT_BPMN_TYPOGRAPHY) {
+    return `
 .bpmn-pool { fill: var(--ts-bg-surface,#f8fafc); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }
 .bpmn-pool-name { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }
 .bpmn-lane { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }
 .bpmn-lane-header { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }
-.bpmn-pool-label { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 11px; font-weight: 700; }
-.bpmn-lane-label { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 11px; font-weight: 600; }
+.bpmn-pool-label { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: ${t.headerFontPx}px; font-weight: 700; }
+.bpmn-lane-label { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: ${t.headerFontPx}px; font-weight: 600; }
 .bpmn-task { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }
-.bpmn-task-name { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 11px; text-anchor: middle; }
+.bpmn-task-name { fill: var(--ts-text-primary,#0d2b35); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: ${t.taskFontPx}px; text-anchor: middle; }
 .bpmn-event { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); }
 .bpmn-event-start { stroke-width: 1.5; }
 .bpmn-event-end { stroke-width: 4; }
-.bpmn-event-label { fill: var(--ts-text-secondary,#516970); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 10px; text-anchor: middle; }
+.bpmn-event-label { fill: var(--ts-text-secondary,#516970); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: ${t.labelFontPx}px; text-anchor: middle; }
 .bpmn-gateway { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }
 .bpmn-gateway-marker { stroke: var(--ts-node-stroke,#004d67); stroke-width: 2.5; stroke-linecap: round; fill: none; }
-.bpmn-gateway-label { fill: var(--ts-text-secondary,#516970); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: 10px; text-anchor: middle; }
+.bpmn-gateway-label { fill: var(--ts-text-secondary,#516970); font-family: var(--vscode-font-family, system-ui, -apple-system, sans-serif); font-size: ${t.labelFontPx}px; text-anchor: middle; }
 .bpmn-seq-flow { fill: none; stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1.5; }
 .bpmn-default-mark { stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1.5; stroke-linecap: round; }
 .bpmn-assoc { fill: none; stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1; stroke-dasharray: 4 2; }
 .bpmn-data-obj { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1; }
-.bpmn-data-obj-label { fill: var(--ts-text-secondary,#516970); font-size: 10px; text-anchor: middle; }
+.bpmn-data-obj-label { fill: var(--ts-text-secondary,#516970); font-size: ${t.labelFontPx}px; text-anchor: middle; }
 .bpmn-event-intermediate { fill: none; stroke: var(--ts-node-stroke,#004d67); stroke-width: 1; }
 .bpmn-event-icon { fill: none; stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
 `;
+}
+/** Default-preview CSS (11 px / 10 px). Presentation export builds its own via `bpmnProcessCss`. */
+export const BPMN_PROCESS_CSS = bpmnProcessCss(DEFAULT_BPMN_TYPOGRAPHY);
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -73,28 +101,29 @@ function wordTruncate(text, maxChars) {
     return (lastSpace > maxChars / 2 ? cut.slice(0, lastSpace) : cut) + '…';
 }
 function fitRotatedHeaderText(name, spanPx) {
-    const maxChars = Math.max(4, Math.floor(spanPx / HEADER_LABEL_CHAR_W));
+    const maxChars = Math.max(4, Math.floor(spanPx / typo.headerCharW));
     return wordTruncate(name, maxChars);
 }
 function wrapTaskName(name) {
     if (!name)
         return [];
+    const limit = typo.taskChars;
     const words = name.split(/\s+/);
     const lines = [];
     let cur = '';
     for (const w of words) {
-        const token = w.length > TASK_CHARS ? w.slice(0, TASK_CHARS - 1) + '…' : w;
+        const token = w.length > limit ? w.slice(0, limit - 1) + '…' : w;
         if (!cur) {
             cur = token;
         }
-        else if (cur.length + 1 + token.length <= TASK_CHARS) {
+        else if (cur.length + 1 + token.length <= limit) {
             cur += ' ' + token;
         }
         else {
             lines.push(cur);
             if (lines.length === 3) {
-                if (lines[2].length > TASK_CHARS - 1)
-                    lines[2] = lines[2].slice(0, TASK_CHARS - 1) + '…';
+                if (lines[2].length > limit - 1)
+                    lines[2] = lines[2].slice(0, limit - 1) + '…';
                 return lines;
             }
             cur = token;
@@ -103,28 +132,29 @@ function wrapTaskName(name) {
     if (cur && lines.length < 3)
         lines.push(cur);
     if (lines.length === 0)
-        lines.push(name.slice(0, TASK_CHARS));
+        lines.push(name.slice(0, limit));
     return lines;
 }
 function taskNameSvg(name, cx, cy) {
     if (!name)
         return '';
     const lines = wrapTaskName(name);
-    const totalH = lines.length * TASK_LINE_H;
-    const startY = cy - totalH / 2 + TASK_LINE_H * 0.8;
+    const totalH = lines.length * typo.taskLineH;
+    const startY = cy - totalH / 2 + typo.taskLineH * 0.8;
     const tspans = lines
-        .map((ln, i) => `<tspan x="${r(cx)}" y="${r(startY + i * TASK_LINE_H)}">${escXml(ln)}</tspan>`)
+        .map((ln, i) => `<tspan x="${r(cx)}" y="${r(startY + i * typo.taskLineH)}">${escXml(ln)}</tspan>`)
         .join('');
     return `<text class="bpmn-task-name">${tspans}</text>`;
 }
 function wrapBelowLabel(name) {
+    const limit = typo.labelChars;
     const words = name.split(/\s+/).filter(Boolean);
     const allLines = [];
     let cur = '';
     for (const word of words) {
-        const tok = word.length > LABEL_CHARS ? word.slice(0, LABEL_CHARS - 1) + '…' : word;
+        const tok = word.length > limit ? word.slice(0, limit - 1) + '…' : word;
         const test = cur ? `${cur} ${tok}` : tok;
-        if (test.length <= LABEL_CHARS) {
+        if (test.length <= limit) {
             cur = test;
         }
         else {
@@ -136,12 +166,12 @@ function wrapBelowLabel(name) {
     if (cur)
         allLines.push(cur);
     if (allLines.length === 0)
-        return [name.slice(0, LABEL_CHARS)];
+        return [name.slice(0, limit)];
     if (allLines.length <= 3)
         return allLines;
     const lines = allLines.slice(0, 3);
     const last = lines[2];
-    lines[2] = last.length + 1 <= LABEL_CHARS ? last + '…' : last.slice(0, LABEL_CHARS - 1) + '…';
+    lines[2] = last.length + 1 <= limit ? last + '…' : last.slice(0, limit - 1) + '…';
     return lines;
 }
 function belowLabelSvg(name, cls, cx, belowY, minX = 0) {
@@ -155,7 +185,7 @@ function belowLabelSvg(name, cls, cx, belowY, minX = 0) {
         return `<text class="${cls}" x="${r(textX)}" y="${startY}">${escXml(lines[0])}</text>`;
     }
     const tspans = lines
-        .map((ln, i) => `<tspan x="${r(textX)}" dy="${i === 0 ? 0 : LABEL_LINE_H}">${escXml(ln)}</tspan>`)
+        .map((ln, i) => `<tspan x="${r(textX)}" dy="${i === 0 ? 0 : typo.labelLineH}">${escXml(ln)}</tspan>`)
         .join('');
     return `<text class="${cls}" x="${r(textX)}" y="${startY}">${tspans}</text>`;
 }
@@ -378,15 +408,18 @@ export function renderProcessBody(layout, ox, oy) {
  */
 export function renderProcessLayoutSvg(layout, options = {}) {
     const { title = '', topInset = title ? 32 : 0 } = options;
-    const pb = layout.poolBounds;
-    const PAD = 16;
-    const svgW = r(pb.x + pb.width + PAD);
-    const svgH = r(pb.y + pb.height + PAD + topInset);
-    const embedCss = generateSvgEmbedCss('transitrix') + BPMN_PROCESS_CSS;
-    const body = renderProcessBody(layout, 0, topInset);
-    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${svgW}" height="${svgH}" viewBox="0 0 ${svgW} ${svgH}">\n` +
-        `<style>${embedCss}</style>\n` +
-        (title ? `${title}\n` : '') +
-        `${body}\n` +
-        `</svg>`);
+    const t = options.typography ?? DEFAULT_BPMN_TYPOGRAPHY;
+    return runWithTypography(t, () => {
+        const pb = layout.poolBounds;
+        const PAD = 16;
+        const svgW = r(pb.x + pb.width + PAD);
+        const svgH = r(pb.y + pb.height + PAD + topInset);
+        const embedCss = generateSvgEmbedCss('transitrix') + bpmnProcessCss(t);
+        const body = renderProcessBody(layout, 0, topInset);
+        return (`<svg xmlns="http://www.w3.org/2000/svg" width="${svgW}" height="${svgH}" viewBox="0 0 ${svgW} ${svgH}">\n` +
+            `<style>${embedCss}</style>\n` +
+            (title ? `${title}\n` : '') +
+            `${body}\n` +
+            `</svg>`);
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",
@@ -55,12 +55,12 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.4",
+    "@types/react-dom": "^19.2.5",
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "reactflow": "^11.11.4",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }

package/src/activities/resolver.ts

@@ -12,7 +12,7 @@
  * §2). Filesystem-free — callable from unit tests without vscode.
  */
 
-import { isObject, str, strArray, descendantsOf, stripEnvelope } from '../canon-resolver-utils.js';
+import { isObject, str, strArray, stripEnvelope, reachesRootViaParent } from '../canon-resolver-utils.js';
 
 export interface ActionViewConfig {
   scope?: {
@@ -44,6 +44,10 @@ export interface ActionCanonSources {
   relations?: unknown[];
 }
 
+/** In-memory bag of ACTION ids dropped by `root_action` scoping. Consumed by
+ *  `validateActivities` as `ACT-021`. Not part of the notation. */
+export const ACT_021_OMITTED_KEY = '__act021_omitted';
+
 /** ACTION elements by id. `notation: action` is canonical; `notation: activity`
  *  is the deprecated pre-2026-06-25 alias (elements/24-action.md §"Deprecated
  *  alias") — accepted the same way `collectByNotation` callers elsewhere do. */
@@ -123,32 +127,26 @@ export function resolveAction(
     return relGoals.length > 0 ? relGoals : strArray(el['goals']);
   }
 
-  // 1. Scope by root_action (this action + its descendants), or the full
-  // catalogue when omitted (§5.1: "Omit to include elements from the full
-  // catalogue (or use goals/type_filter for other scoping)").
-  const rootAction = str(scope['root_action']);
-  let candidateIds: Set<string>;
-  if (rootAction) {
-    candidateIds = allActions.has(rootAction) ? descendantsOf(rootAction, allActions) : new Set();
-  } else {
-    candidateIds = new Set(allActions.keys());
-  }
+  // 1. Other scope fields first — the set the view would otherwise select
+  // (07-action.md §5.1). `root_action` then omits (and warns) rather than
+  // silently intersecting first.
+  let otherwiseIds: Set<string> = new Set(allActions.keys());
 
-  // 2. Narrow by goals — only actions linked to at least one listed GOAL
+  // Narrow by goals — only actions linked to at least one listed GOAL
   // (via an active action_goal relation, or inline goals[] when no relation
   // exists for that action).
   const goalsFilter = strArray(scope['goals']);
   if (goalsFilter.length > 0) {
-    candidateIds = new Set(
-      [...candidateIds].filter((id) => effectiveGoals(id, allActions.get(id)!).some((g) => goalsFilter.includes(g))),
+    otherwiseIds = new Set(
+      [...otherwiseIds].filter((id) => effectiveGoals(id, allActions.get(id)!).some((g) => goalsFilter.includes(g))),
     );
   }
 
-  // 3. Narrow by type_filter — only actions of a listed type.
+  // Narrow by type_filter — only actions of a listed type.
   const typeFilter = strArray(scope['type_filter']);
   if (typeFilter.length > 0) {
-    candidateIds = new Set(
-      [...candidateIds].filter((id) => {
+    otherwiseIds = new Set(
+      [...otherwiseIds].filter((id) => {
         const el = allActions.get(id);
         const t = str(el?.['type']) ?? str(el?.['activity_type']);
         return t !== undefined && typeFilter.includes(t);
@@ -156,13 +154,13 @@ export function resolveAction(
     );
   }
 
-  // 4. Narrow by valid_at — only actions in effect on that date. Actions with
+  // Narrow by valid_at — only actions in effect on that date. Actions with
   // no valid_from are not lifecycle-tracked and are kept (permissive default,
   // matching the resolver's general "missing = not excluded" stance).
   const validAt = str(scope['valid_at']);
   if (validAt) {
-    candidateIds = new Set(
-      [...candidateIds].filter((id) => {
+    otherwiseIds = new Set(
+      [...otherwiseIds].filter((id) => {
         const el = allActions.get(id);
         const from = str(el?.['valid_from']);
         const to = str(el?.['valid_to']);
@@ -173,6 +171,27 @@ export function resolveAction(
     );
   }
 
+  const rootAction = str(scope['root_action']);
+  let candidateIds: Set<string>;
+  const omittedOutsideRoot: string[] = [];
+  if (rootAction) {
+    if (!allActions.has(rootAction)) {
+      candidateIds = new Set();
+    } else {
+      candidateIds = new Set();
+      for (const id of otherwiseIds) {
+        if (reachesRootViaParent(id, rootAction, allActions)) {
+          candidateIds.add(id);
+        } else {
+          omittedOutsideRoot.push(id);
+        }
+      }
+      omittedOutsideRoot.sort();
+    }
+  } else {
+    candidateIds = otherwiseIds;
+  }
+
   // Element fields map onto Activity fields unchanged, except the canonical
   // `type` (elements/24-action.md §2) which becomes the internal `activity_type`
   // (types.ts `Activity.activity_type`), and `goals` which is resolved via
@@ -204,5 +223,6 @@ export function resolveAction(
     actions: selectedActions,
   };
   if (Object.keys(project).length > 0) out['project'] = project;
+  if (omittedOutsideRoot.length > 0) out[ACT_021_OMITTED_KEY] = { root: rootAction, ids: omittedOutsideRoot };
   return out;
 }

package/src/activities/validate.ts

@@ -5,10 +5,62 @@ import type {
   ActivityValidationError,
   ActivityValidationWarning,
 } from './types.js';
+import { isObject, str, reachesRootViaParent } from '../canon-resolver-utils.js';
+import { ACT_021_OMITTED_KEY } from './resolver.js';
 
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const VALID_WEEKDAYS = new Set(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']);
 
+function act021Message(actionId: string, rootId: string): string {
+  return `ACTION "${actionId}" is not "${rootId}" and is not reachable from it via parent`;
+}
+
+function collectAct021FromProjection(raw: Record<string, unknown>): ActivityValidationWarning[] {
+  const bag = raw[ACT_021_OMITTED_KEY];
+  delete raw[ACT_021_OMITTED_KEY];
+  if (!isObject(bag)) return [];
+  const root = str(bag['root']);
+  const ids = Array.isArray(bag['ids']) ? bag['ids'] : [];
+  if (!root) return [];
+  const out: ActivityValidationWarning[] = [];
+  for (const id of ids) {
+    if (typeof id !== 'string' || !id.trim()) continue;
+    out.push({
+      code: 'ACT-021',
+      message: act021Message(id, root),
+      path: 'view_config.scope.root_action',
+    });
+  }
+  return out;
+}
+
+function collectAct021FromAuthored(
+  raw: Record<string, unknown>,
+  actions: unknown[],
+): ActivityValidationWarning[] {
+  const vc = isObject(raw['view_config']) ? raw['view_config'] : undefined;
+  const scope = vc && isObject(vc['scope']) ? vc['scope'] : undefined;
+  const root = scope ? str(scope['root_action']) : undefined;
+  if (!root) return [];
+  const byId = new Map<string, Record<string, unknown>>();
+  for (const el of actions) {
+    if (!isObject(el)) continue;
+    const id = str(el['id']);
+    if (id) byId.set(id, el);
+  }
+  if (!byId.has(root)) return [];
+  const out: ActivityValidationWarning[] = [];
+  for (const id of byId.keys()) {
+    if (reachesRootViaParent(id, root, byId)) continue;
+    out.push({
+      code: 'ACT-021',
+      message: act021Message(id, root),
+      path: 'view_config.scope.root_action',
+    });
+  }
+  return out;
+}
+
 export function validateActivities(input: unknown): ActivityValidationResult {
   const errors: ActivityValidationError[] = [];
   const warnings: ActivityValidationWarning[] = [];
@@ -46,6 +98,12 @@ export function validateActivities(input: unknown): ActivityValidationResult {
   // Normalise onto raw.activities for the rest of this function (avoids touching downstream code)
   if (!Array.isArray(raw.activities)) raw.activities = raw.actions;
 
+  const fromProjection = collectAct021FromProjection(raw);
+  warnings.push(...fromProjection);
+  if (fromProjection.length === 0) {
+    warnings.push(...collectAct021FromAuthored(raw, rawArray));
+  }
+
   // ACT-014 / ACT-015: project.calendar validation (run before per-activity loop;
   // surfaces clearly even when activities also have issues).
   if (raw.project && typeof raw.project === 'object') {
@@ -158,8 +216,9 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
 
     // ACT-011: warn if no duration (duration_days is accepted as an alias)
+    // Network view is unaffected; this is only about CPM/Gantt rendering.
     if ((act.duration === undefined || act.duration === null) && (act.duration_days === undefined || act.duration_days === null)) {
-      warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — cannot participate in CPM analysis`, path });
+      warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — Gantt view and CPM analysis will exclude it. Network view is unaffected.`, path });
     }
   }
 
@@ -234,7 +293,9 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
   }
 
-  // ACT-013: orphan activities (warning only)
+  // ACT-013: orphan activities (warning only). An activity is structurally orphan
+  // if it has no connections to the rest of the graph. Valid connections are:
+  // predecessors, successors, parent, or goals (direct or via delivers_changes).
   const successorIds = new Set<string>();
   for (const a of doc.activities) {
     for (const pred of (a.predecessors ?? [])) successorIds.add(pred);
@@ -244,10 +305,11 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     const hasSuccessors = successorIds.has(a.id);
     const hasGoals = Array.isArray(a.goals) && a.goals.length > 0;
     const hasPredecessors = Array.isArray(a.predecessors) && a.predecessors.length > 0;
-    if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors) {
+    const hasParent = typeof a.parent === 'string' && a.parent.length > 0;
+    if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors && !hasParent) {
       warnings.push({
         code: 'ACT-013',
-        message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, or goals)`,
+        message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, parent, or goals)`,
         path: `activities[${i}]`,
       });
     }

package/src/canon-resolver-utils.ts

@@ -48,6 +48,25 @@ export function descendantsOf(
   return result;
 }
 
+/** Walk `parent` from `id` toward its ancestors until `rootId` or the chain
+ *  ends. Cycle-safe: a cycle is not a path to the root. */
+export function reachesRootViaParent(
+  id: string,
+  rootId: string,
+  all: Map<string, Record<string, unknown>>,
+): boolean {
+  const seen = new Set<string>();
+  let current: string | undefined = id;
+  while (current) {
+    if (current === rootId) return true;
+    if (seen.has(current)) return false;
+    seen.add(current);
+    const el = all.get(current);
+    current = el ? str(el['parent']) : undefined;
+  }
+  return false;
+}
+
 /** Depth of `id` in its `parent` chain within `all` (root = 0, each step up
  *  adds 1). Cycle-safe (a cycle resolves the entering node to depth 0) and
  *  memoized across calls via the shared `memo` map. */

package/src/compliance/classify.ts

@@ -166,6 +166,7 @@ export function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): strin
     if (!verifies || !method || !outcome) return null;
     const ok = pushUnique(canon, canon.verifications, {
       id, verifies, method, outcome,
+      protocol: str(d.protocol),
       performed_at: str(d.performed_at),
       evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
       admitted_at: str(d.admitted_at),

package/src/compliance/impact.ts

@@ -12,6 +12,7 @@ import type { ComplianceCanon } from './classify.js';
 import { buildComplianceIndex } from './reverse-index.js';
 import type { CanonCatalog } from '../typed-id.js';
 import type { ComplianceIndex, IndexAssertion, IndexRequirement, ObjectDetailInput, ObjectDetailDef, DeadlineStatus } from './types.js';
+import { isStageColumnId } from '../process-blueprint/resolve-columns.js';
 
 /** Filter selecting REQUIREMENTs by codex source (jurisdiction / regime keys
  *  are accepted for forward compatibility but not yet honoured — the canon
@@ -649,22 +650,48 @@ function buildTaskColumns(
  *
  * At `'product'` grain: `a.subject` must match `col.subjectId`.
  * At `'product-stage'` grain: `a.subject` must match AND either
- * `a.realised_via` is absent (claim covers the whole subject) OR
- * `col.stageId` ∈ `a.realised_via`.
- * At `'product-stage-task'` grain: as above for stage, plus `col.taskId` ∈
- * `a.realised_via` counts as a match (task-level claim covers this task column).
- * A stage-level claim (`col.stageId` ∈ `a.realised_via`) covers all task columns
- * in that stage.
+ * `a.realised_via` is absent (claim covers the whole subject) OR the token
+ * pins this column: a `PROCESS-…` id matching `col.stageId`, or a STEP whose
+ * home process is that column. Sketch `STAGE-…` ids are never a join key.
+ * At `'product-stage-task'` grain: a task-id hit covers that task column; a
+ * process-level claim covers every task column of that process.
  */
-function assertionMatchesColumn(a: IndexAssertion, col: ImpactColumn): boolean {
+function assertionMatchesColumn(
+  a: IndexAssertion,
+  col: ImpactColumn,
+  stepHomeProcess?: ReadonlyMap<string, string>,
+): boolean {
   if (a.subject !== col.subjectId) return false;
   if (!col.stageId) return true;
   if (!a.realised_via || a.realised_via.length === 0) return true;
-  if (col.taskId) {
-    // Task grain: match on taskId OR on stageId (stage claim covers all tasks).
-    return a.realised_via.includes(col.taskId) || a.realised_via.includes(col.stageId);
+
+  const stageId = col.stageId;
+  if (isStageColumnId(stageId)) {
+    // Sketch column: only a task-id hit counts — never the STAGE- key.
+    return col.taskId != null && a.realised_via.includes(col.taskId);
+  }
+
+  for (const ref of a.realised_via) {
+    if (typeof ref !== 'string') continue;
+    if (isStageColumnId(ref)) continue;
+    if (col.taskId && ref === col.taskId) return true;
+    if (ref === stageId) return true;
+    if (!col.taskId && stepHomeProcess?.get(ref) === stageId) return true;
   }
-  return a.realised_via.includes(col.stageId);
+  return false;
+}
+
+function stepHomeFromObjectDetails(objectDetails?: ObjectDetailInput[]): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!objectDetails) return out;
+  for (const od of objectDetails) {
+    for (const d of od.details ?? []) {
+      for (const t of d.tasks ?? []) {
+        if (typeof t?.id === 'string' && t.id.length > 0) out.set(t.id, d.id);
+      }
+    }
+  }
+  return out;
 }
 
 /**
@@ -691,6 +718,7 @@ export function buildImpactMatrix(
   canon: ComplianceCanon,
   config: ImpactViewConfig,
   objectDetails?: ObjectDetailInput[],
+  join?: { stepHomeProcess?: ReadonlyMap<string, string> },
 ): ImpactMatrix {
   const index = buildComplianceIndex({
     requirements: canon.requirements,
@@ -755,6 +783,7 @@ export function buildImpactMatrix(
 
   const rowIndex = new Set(obligations.map(r => r.id));
   const cells: ImpactCell[][] = obligations.map(() => columns.map(() => emptyCell()));
+  const stepHome = join?.stepHomeProcess ?? stepHomeFromObjectDetails(objectDetails);
 
   for (let c = 0; c < columns.length; c++) {
     const col = columns[c];
@@ -762,7 +791,7 @@ export function buildImpactMatrix(
     for (const a of subjectAssertions) {
       if (!rowIndex.has(a.about)) continue;
       if (!allowedStatuses.has(a.status)) continue;
-      if (!assertionMatchesColumn(a, col)) continue;
+      if (!assertionMatchesColumn(a, col, stepHome)) continue;
       const rowIdx = obligations.findIndex(r => r.id === a.about);
       if (rowIdx < 0) continue;
       cells[rowIdx][c].assertions.push(a);

package/src/compliance/types.ts

@@ -128,6 +128,12 @@ export interface IndexVerification {
   verifies: string;
   method: VerificationMethod;
   outcome: VerificationOutcome;
+  /**
+   * The verification procedure (27-verification.md §2). VERIFICATION carries
+   * no `name` field of its own; `protocol` is the closest human-readable
+   * description and is what a matrix/list view shows as the row's label.
+   */
+  protocol?: string;
   performed_at?: string;
   /** Number of evidence entries — feeds the VERIF-006 gap. */
   evidenceCount?: number;