@transitrix/diagrams 1.9.18 → 1.11.0

package/dist/requirement/types.d.ts

@@ -7,7 +7,7 @@ export interface GateChecks {
     completeness?: string;
 }
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD", "PRINCIPLE"];
 /** ISO/IEC/IEEE 29148 specification-tier ladder (15-requirement.md §2.5, REQ-005). */
 export type RequirementLevel = 'stakeholder' | 'system' | 'software';
 export declare const REQUIREMENT_LEVELS: readonly RequirementLevel[];

package/dist/requirement/types.js

@@ -1,6 +1,6 @@
 // REQUIREMENT — motivation-layer positive obligation.
 // Schema: methodology notations/elements/15-requirement.md §2.
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];
+export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
 export const REQUIREMENT_LEVELS = ['stakeholder', 'system', 'software'];
 export const REQUIREMENT_KINDS = ['functional', 'quality'];

package/dist/webview/entry.js

@@ -28,7 +28,7 @@ import yaml from 'js-yaml';
 import { validateActivities } from '../activities/index.js';
 import { validateActivityCard } from '../activity-card/index.js';
 import { validateApplicationsCatalogue } from '../applications/index.js';
-import { validateNestedBlocks } from '../blocks/index.js';
+import { validateBlocks } from '../blocks/index.js';
 import { validateCapabilityMap } from '../capability-map/validate.js';
 import { parseCanonicalFGCA, parseCanonicalFGA } from '../fgca/parse-canonical.js';
 import { parseCanonicalGoals } from '../goals/parse-canonical.js';
@@ -40,7 +40,7 @@ import { coerceDatesToIsoStrings } from '../yaml-normalize.js';
 import { renderActivitiesSvg } from './render-activities.js';
 import { renderActivityCardSvg } from './render-activity-card.js';
 import { renderApplicationsHtml } from './render-applications.js';
-import { renderBlocksSvg } from './render-blocks.js';
+import { renderBlocksSvg, renderGridSvg } from './render-blocks.js';
 import { renderCapabilityMapHtml } from './render-capability-map.js';
 import { renderFgcaSvg } from './render-fgca.js';
 import { renderGoalsSvg } from './render-goals.js';
@@ -138,8 +138,15 @@ function dispatchValidate(kind, doc) {
             return renderFromValidation('action-card', validateActivityCard(doc), () => renderActivityCardSvg(doc));
         case 'process-blueprint':
             return renderFromValidation('process-blueprint', validateProcessBlueprint(doc), () => renderProcessBlueprintSvg(doc));
-        case 'blocks':
-            return renderFromValidation('blocks', validateNestedBlocks(doc), () => renderBlocksSvg(doc));
+        case 'blocks': {
+            // Two alternative root forms (08-blocks.md §4): a `nested_blocks:`
+            // containment tree, or a `grid:` matrix subset (§4a). `validateBlocks`
+            // is the shared root-form dispatcher (BL-020 on both/neither present);
+            // mirrors the VS Code path's `hasGrid` branch in `blocks-preview.ts`.
+            const raw = (doc && typeof doc === 'object' ? doc : {});
+            const hasGrid = raw['grid'] !== undefined && raw['grid'] !== null;
+            return renderFromValidation('blocks', validateBlocks(doc), () => hasGrid ? renderGridSvg(doc) : renderBlocksSvg(doc));
+        }
         // Catalogue notations render an HTML fragment from the header nested under
         // their top-level wrapper key (`<thing>_catalogue` / `scenario` / …).
         case 'applications':

package/dist/webview/render-fgca.js

@@ -67,7 +67,7 @@ export function renderFgcaBody(columns, nodes, edges, curvature, entryCurvature,
 }
 export function renderFgcaSvg(doc, options = {}) {
     const { variant = 'dgca', title = '', curvature = DEFAULT_EDGE_CURVATURE, entryCurvature, nodeSizePreset = 'normal', layoutOptions, } = options;
-    const hideChanges = variant === 'dga';
+    const hideChanges = variant === 'dga' || doc.hideChanges === true;
     const nodeSize = resolveDgcaNodeSize(parseNodeSizePreset(nodeSizePreset));
     const { nodes, edges, columns, width, height } = layoutFGCAPreview(doc, {
         hideChanges,

package/dist/webview/render-process.d.ts

@@ -64,13 +64,31 @@ export interface ProcessDiagramLayout {
     flows: ProcessFlow[];
     associations: ProcessAssociation[];
 }
+export interface BpmnTypography {
+    taskFontPx: number;
+    headerFontPx: number;
+    labelFontPx: number;
+    taskChars: number;
+    taskLineH: number;
+    labelChars: number;
+    labelLineH: number;
+    headerCharW: number;
+}
+/** Interactive-preview / default-export type sizes. */
+export declare const DEFAULT_BPMN_TYPOGRAPHY: BpmnTypography;
+/** Presentation-export type sizes (20 px floor, wrap tuned to default node boxes). */
+export declare const PRESENTATION_BPMN_TYPOGRAPHY: BpmnTypography;
 export interface RenderProcessOptions {
     /** Raw SVG injected after `<style>` — a title line or full title block. */
     title?: string;
     /** Extra vertical space (px) reserved above the pool for a title block. */
     topInset?: number;
+    /** Label metrics. Omit for the interactive-preview defaults. */
+    typography?: BpmnTypography;
 }
-export declare const BPMN_PROCESS_CSS = "\n.bpmn-pool { fill: var(--ts-bg-surface,#f8fafc); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }\n.bpmn-pool-name { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }\n.bpmn-lane { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }\n.bpmn-lane-header { fill: var(--ts-bg-elevated,#f1f5f9); stroke: var(--ts-node-stroke,#004d67); stroke-width: 0.75; }\n.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; }\n.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; }\n.bpmn-task { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }\n.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; }\n.bpmn-event { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); }\n.bpmn-event-start { stroke-width: 1.5; }\n.bpmn-event-end { stroke-width: 4; }\n.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; }\n.bpmn-gateway { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; }\n.bpmn-gateway-marker { stroke: var(--ts-node-stroke,#004d67); stroke-width: 2.5; stroke-linecap: round; fill: none; }\n.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; }\n.bpmn-seq-flow { fill: none; stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1.5; }\n.bpmn-default-mark { stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1.5; stroke-linecap: round; }\n.bpmn-assoc { fill: none; stroke: var(--ts-edge-stroke,#004d67); stroke-width: 1; stroke-dasharray: 4 2; }\n.bpmn-data-obj { fill: var(--ts-bg,#ffffff); stroke: var(--ts-node-stroke,#004d67); stroke-width: 1; }\n.bpmn-data-obj-label { fill: var(--ts-text-secondary,#516970); font-size: 10px; text-anchor: middle; }\n.bpmn-event-intermediate { fill: none; stroke: var(--ts-node-stroke,#004d67); stroke-width: 1; }\n.bpmn-event-icon { fill: none; stroke: var(--ts-node-stroke,#004d67); stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }\n";
+export declare function bpmnProcessCss(t?: BpmnTypography): string;
+/** Default-preview CSS (11 px / 10 px). Presentation export builds its own via `bpmnProcessCss`. */
+export declare const BPMN_PROCESS_CSS: string;
 /**
  * Canonical body emitter, shared by every host (VS Code, JCEF, static export).
  *

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.9.18",
+  "version": "1.11.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

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') {

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/codex/index.ts

@@ -1,4 +1,4 @@
-export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, PRINCIPLE_CODEX_TYPES } from './types.js';
 export type { CodexArtefactType } from './types.js';
 export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';
 export type { CodexValidateOptions } from './validate.js';

package/src/codex/types.ts

@@ -1,13 +1,21 @@
-// Codex artefact — external laws/regulations and internal policies/standards.
+// Codex artefact — external laws/regulations and internal policies/standards/principles.
 // Schema: methodology notations/elements/14-codex.md §3–§4.
 
 /** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
-export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'] as const;
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'] as const;
 
 export type CodexArtefactType = (typeof CODEX_ARTEFACT_TYPES)[number];
 
 /** External codex artefacts (codex/external/<jurisdiction>/). */
 export const EXTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['LAW', 'REGULATION'];
 
-/** Internal codex artefacts (codex/internal/). */
+/** Internal codex artefacts (codex/internal/) that carry a named issuing authority (§4). */
 export const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['POLICY', 'INTERNAL_STANDARD'];
+
+/**
+ * Internal codex artefacts (codex/internal/) with the `PRINCIPLE` shape (§4.1) —
+ * `statement` + `rationale` required, `issuing_authority`/`effective_date`/`established_by`
+ * optional. Kept distinct from {@link INTERNAL_CODEX_TYPES} because the required-field set
+ * differs; both share the same file location.
+ */
+export const PRINCIPLE_CODEX_TYPES: readonly CodexArtefactType[] = ['PRINCIPLE'];

package/src/codex/validate.ts

@@ -3,9 +3,20 @@
 // CODEX-001 — shape, zone, id grammar, admission envelope.
 // CODEX-002 — `type` field matches the id TYPE prefix when present.
 // CODEX-003 — external artefact frontmatter (jurisdiction, effective_date).
-// CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date).
+// CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date for
+//             POLICY/INTERNAL_STANDARD; statement, rationale for PRINCIPLE — §4.1).
 // CODEX-005 — jurisdiction must match the parent folder under codex/external/
 //             (when `folderJurisdiction` is supplied by the repo sweep).
+// CODEX-006 — a PRINCIPLE artefact does not declare `established_by` (§4.1). The spec
+//             marks this "info" severity; this module has no info tier, so it is
+//             surfaced as a warning — the nearest existing severity that does not fail
+//             `valid`.
+//
+// Note: this file's CODEX-00x numbering predates the spec's own v0.2 renumbering
+// (14-codex.md §6, §8.2) and does not track it code-for-code — e.g. the spec's current
+// CODEX-001 is a folder/jurisdiction check this file assigns to CODEX-005. Realigning the
+// full scheme is out of scope here; this change only adds the purely-additive PRINCIPLE
+// TYPE (§4.1) under the existing local numbering.
 
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 import { isCanonicalId, typeOfId } from '../typed-id.js';
@@ -13,6 +24,7 @@ import {
   CODEX_ARTEFACT_TYPES,
   EXTERNAL_CODEX_TYPES,
   INTERNAL_CODEX_TYPES,
+  PRINCIPLE_CODEX_TYPES,
   type CodexArtefactType,
 } from './types.js';
 
@@ -48,7 +60,7 @@ export function validateCodex(input: unknown, options: CodexValidateOptions = {}
   if (!isCanonicalId(c.id) || !isCodexType(idType)) {
     errors.push({
       code: 'CODEX-001',
-      message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, or INTERNAL_STANDARD).`,
+      message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, INTERNAL_STANDARD, or PRINCIPLE).`,
       path: 'id',
     });
   }
@@ -106,6 +118,22 @@ export function validateCodex(input: unknown, options: CodexValidateOptions = {}
     }
   }
 
+  if (artefactType && (PRINCIPLE_CODEX_TYPES as readonly string[]).includes(artefactType)) {
+    if (typeof c.statement !== 'string' || c.statement.trim() === '') {
+      errors.push({ code: 'CODEX-004', message: 'statement is required for a PRINCIPLE artefact.', path: 'statement' });
+    }
+    if (typeof c.rationale !== 'string' || c.rationale.trim() === '') {
+      errors.push({ code: 'CODEX-004', message: 'rationale is required for a PRINCIPLE artefact.', path: 'rationale' });
+    }
+    if (typeof c.established_by !== 'string' || c.established_by.trim() === '') {
+      warnings.push({
+        code: 'CODEX-006',
+        message: 'established_by is not declared on this PRINCIPLE artefact — admissible, but a review finding for whoever admits it.',
+        path: 'established_by',
+      });
+    }
+  }
+
   return { valid: errors.length === 0, errors, warnings };
 }