@transitrix/diagrams 1.8.13 → 1.8.18

package/dist/webview/render-blocks.js

@@ -12,10 +12,10 @@
  * the shared theme CSS embedded in a `<style>` element and a simple optional
  * title `<text>`.
  */
-import { layoutNestedBlocks } from '../blocks/layout.js';
+import { layoutNestedBlocks, layoutGrid } from '../blocks/layout.js';
 import { parseNodeSizePreset, resolveBlocksLeafSize } from '../node-size-presets.js';
 import { generateSvgEmbedCss } from '../theme/index.js';
-import { emitCenteredTextSvg, layoutHeaderBlockText, layoutLeafBlockText, } from './entity-text-layout.js';
+import { CHAR_W_PRIMARY, emitCenteredTextSvg, layoutHeaderBlockText, layoutLeafBlockText, maxCharsForInnerWidth, wrapWords, } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 import { ENTITY_NODE_RX } from './notation-style.js';
 const PAD = 24;
@@ -105,3 +105,101 @@ export function renderBlocksSvg(doc, options = {}) {
         : '';
     return renderBlocksLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
 }
+/**
+ * Matrix subset (08-blocks.md §4a) — first cut: a single-layer rectangular
+ * `grid:` document (the RACI-style matrix case) rendered as a plain
+ * HTML/CSS-table-like SVG grid. Layers, arbitrary
+ * (non-rectangular) cell sets, and nested sub-grids belong to the general
+ * layered-grid superset, which is still in design upstream (methodology) and
+ * out of scope here — see 08-blocks.md §4a / §8.
+ */
+const GRID_CELL_PAD_X = 8;
+const GRID_LINE_HEIGHT = 15;
+const GRID_EMBED_CSS = `
+.blocks-grid-border { fill: none; stroke: var(--ts-border, #cbd5e1); }`;
+function centeredGridCellTextSvg(lines, cls, cx, cellTop, cellHeight) {
+    const ls = lines.length > 0 ? lines : [''];
+    const firstY = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * GRID_LINE_HEIGHT;
+    const tspans = ls
+        .map((ln, i) => `<tspan x="${cx}" y="${firstY + i * GRID_LINE_HEIGHT}">${escXml(ln)}</tspan>`)
+        .join('');
+    return `<text class="${cls}" text-anchor="middle" dominant-baseline="central">${tspans}</text>`;
+}
+/**
+ * Emit the grid body (headers, cells, grid lines) at the given origin offset.
+ * Shared by the host-neutral wrapper below; VS Code's blocks preview wraps
+ * this the same way it wraps {@link renderBlocksLayoutSvg} for the tree form.
+ */
+export function renderGridBody(layout, ox, oy) {
+    const tw = layout.bounds.width;
+    const th = layout.bounds.height;
+    const parts = [];
+    parts.push(`<rect class="diagram-node level-0" x="${ox}" y="${oy}" width="${tw}" height="${th}" stroke="none"/>`);
+    // Corner cell (above the row headers, left of the column headers).
+    parts.push(`<rect class="diagram-node level-1" x="${ox}" y="${oy}" width="${layout.rowHeaderWidth}" height="${layout.headerHeight}" stroke="none"/>`);
+    for (const col of layout.columns) {
+        const x = col.x + ox;
+        parts.push(`<rect class="diagram-node level-1" x="${x}" y="${oy}" width="${col.width}" height="${layout.headerHeight}" stroke="none"/>`);
+        const maxChars = maxCharsForInnerWidth(col.width - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+        const lines = wrapWords(col.name, maxChars, 2);
+        parts.push(centeredGridCellTextSvg(lines, 'text-header', x + col.width / 2, oy, layout.headerHeight));
+    }
+    for (const row of layout.rows) {
+        const y = row.y + oy;
+        parts.push(`<rect class="diagram-node level-2" x="${ox}" y="${y}" width="${layout.rowHeaderWidth}" height="${row.height}" stroke="none"/>`);
+        const maxChars = maxCharsForInnerWidth(layout.rowHeaderWidth - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+        const lines = wrapWords(row.name, maxChars, 2);
+        parts.push(centeredGridCellTextSvg(lines, 'text-primary', ox + layout.rowHeaderWidth / 2, y, row.height));
+    }
+    for (const cell of layout.cells) {
+        if (cell.value === undefined)
+            continue;
+        const cx = cell.x + ox + cell.width / 2;
+        const cy = cell.y + oy + cell.height / 2;
+        parts.push(`<text class="text-secondary" x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="central">${escXml(cell.value)}</text>`);
+    }
+    const gridX1 = ox;
+    const gridX2 = ox + tw;
+    const gridY1 = oy;
+    const gridY2 = oy + th;
+    const headerBottomY = oy + layout.headerHeight;
+    parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${headerBottomY}" x2="${gridX2}" y2="${headerBottomY}"/>`);
+    for (const row of layout.rows) {
+        const rowBottomY = oy + row.y + row.height;
+        parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${rowBottomY}" x2="${gridX2}" y2="${rowBottomY}"/>`);
+    }
+    const rowHeaderLineX = ox + layout.rowHeaderWidth;
+    parts.push(`<line class="diagram-edge" x1="${rowHeaderLineX}" y1="${gridY1}" x2="${rowHeaderLineX}" y2="${gridY2}"/>`);
+    for (const col of layout.columns) {
+        const colLineX = ox + col.x + col.width;
+        parts.push(`<line class="diagram-edge" x1="${colLineX}" y1="${gridY1}" x2="${colLineX}" y2="${gridY2}"/>`);
+    }
+    parts.push(`<rect class="blocks-grid-border" x="${ox}" y="${oy}" width="${tw}" height="${th}"/>`);
+    return parts.join('\n');
+}
+/** The single grid (matrix subset) SVG emitter shared by every host. */
+export function renderGridLayoutSvg(layout, options = {}) {
+    const { topInset = 0, title = '', embedCssTheme } = options;
+    const w = layout.bounds.width + PAD * 2;
+    const h = layout.bounds.height + PAD * 2 + topInset;
+    const ox = PAD;
+    const oy = PAD + topInset;
+    const body = renderGridBody(layout, ox, oy);
+    const styleLine = embedCssTheme ? `\n<style>${generateSvgEmbedCss(embedCssTheme)}${GRID_EMBED_CSS}</style>` : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${styleLine}
+${title}
+${body}
+</svg>`;
+}
+/** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
+export function renderGridSvg(doc, options = {}) {
+    const { title = '', layoutOptions } = options;
+    const layout = layoutGrid(doc, layoutOptions);
+    if (layout.columns.length === 0 || layout.rows.length === 0) {
+        return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
+    }
+    const titleSvg = title
+        ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Nested Blocks — ${title}`)}</text>`
+        : '';
+    return renderGridLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.8.13",
+  "version": "1.8.18",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/activities/validate.ts

@@ -19,7 +19,15 @@ export function validateActivities(input: unknown): ActivityValidationResult {
 
   const raw = input as Record<string, unknown>;
 
-  // ACT-001: notation must be "action"
+  // ACT-001: notation must be "action". ACT-020 is deliberately NOT ported
+  // here (DSM's api02/internal/importer/activities.go ValidateActivities
+  // still accepts the pre-2026-06-25 "activities" notation/root-key alias
+  // with a warning) — PR #320 ("drop deprecated notation aliases
+  // fgca/fga/activities/activity-card") already removed that leniency from
+  // this validator on purpose, with tests asserting it is "no longer
+  // accepted". Re-introducing it would reverse a deliberate, shipped
+  // decision, not fill a gap; flagged in the PR for a call rather than
+  // silently reversed either way.
   if (raw.notation === undefined) {
     errors.push({ code: 'ACT-001', message: 'notation field is required' });
     return { valid: false, errors, warnings };

package/src/blocks/index.ts

@@ -5,13 +5,27 @@ export type {
   BlocksLayoutOptions,
   LaidOutBlock,
   BlocksLayout,
+  GridColumn,
+  GridRow,
+  GridHeader,
+  GridFile,
+  GridLayoutOptions,
+  LaidOutGridColumn,
+  LaidOutGridRow,
+  LaidOutGridCell,
+  GridLayout,
 } from './types.js';
 
-export { validateNestedBlocks, isWellFormedBlock } from './validate.js';
+export { validateNestedBlocks, validateGrid, validateBlocks, isWellFormedBlock } from './validate.js';
 export type {
   ValidationError as BlocksValidationError,
   ValidationWarning as BlocksValidationWarning,
   ValidationResult as BlocksValidationResult,
+  GridRule,
+  ValidateGridOptions,
+  ValidateBlocksOptions,
 } from './validate.js';
 
-export { layoutNestedBlocks, iterateBlocks } from './layout.js';
+export { layoutNestedBlocks, layoutGrid, iterateBlocks } from './layout.js';
+
+export { GRID_TEMPLATE_RULES } from './templates/index.js';

package/src/blocks/layout.ts

@@ -3,7 +3,13 @@ import type {
   BlocksFile,
   BlocksLayout,
   BlocksLayoutOptions,
+  GridFile,
+  GridLayout,
+  GridLayoutOptions,
   LaidOutBlock,
+  LaidOutGridCell,
+  LaidOutGridColumn,
+  LaidOutGridRow,
 } from './types.js';
 import { ENTITY_NODE_SIZE } from '../node-size-presets.js';
 
@@ -16,6 +22,13 @@ const DEFAULTS: Required<BlocksLayoutOptions> = {
   topLevelGap: 24,
 };
 
+const GRID_DEFAULTS: Required<GridLayoutOptions> = {
+  columnWidth: 130,
+  rowHeight: 44,
+  rowHeaderWidth: 200,
+  headerHeight: 56,
+};
+
 interface MeasuredBlock {
   width: number;
   height: number;
@@ -185,3 +198,60 @@ export function* iterateBlocks(layout: BlocksLayout): Iterable<LaidOutBlock> {
   }
   for (const b of layout.blocks) yield* walk(b);
 }
+
+/**
+ * Matrix subset (08-blocks.md §4a): lay out a `grid:` root document as a
+ * single-layer rectangular table — a row-header column, a column-header row,
+ * and one cell per `(row, column)` pair. Assumes the document is already
+ * well-formed ({@link validateGrid}); callers validate first.
+ */
+export function layoutGrid(file: GridFile, options?: GridLayoutOptions): GridLayout {
+  const opts = { ...GRID_DEFAULTS, ...(options ?? {}) };
+  const grid = file?.grid;
+  const rawColumns = Array.isArray(grid?.columns) ? grid.columns : [];
+  const rawRows = Array.isArray(grid?.rows) ? grid.rows : [];
+
+  const columns: LaidOutGridColumn[] = rawColumns.map((c, i) => ({
+    id: c.id,
+    name: c.name,
+    x: opts.rowHeaderWidth + i * opts.columnWidth,
+    width: opts.columnWidth,
+  }));
+
+  const rows: LaidOutGridRow[] = rawRows.map((r, i) => ({
+    id: r.id,
+    name: r.name,
+    y: opts.headerHeight + i * opts.rowHeight,
+    height: opts.rowHeight,
+  }));
+
+  const cells: LaidOutGridCell[] = [];
+  for (let ri = 0; ri < rawRows.length; ri++) {
+    const row = rawRows[ri];
+    for (let ci = 0; ci < rawColumns.length; ci++) {
+      const col = rawColumns[ci];
+      const raw = row.assign?.[col.id];
+      cells.push({
+        rowId: row.id,
+        colId: col.id,
+        x: columns[ci].x,
+        y: rows[ri].y,
+        width: opts.columnWidth,
+        height: opts.rowHeight,
+        value: raw === undefined ? undefined : String(raw),
+      });
+    }
+  }
+
+  const width = opts.rowHeaderWidth + rawColumns.length * opts.columnWidth;
+  const height = opts.headerHeight + rawRows.length * opts.rowHeight;
+
+  return {
+    bounds: { x: 0, y: 0, width, height },
+    rowHeaderWidth: opts.rowHeaderWidth,
+    headerHeight: opts.headerHeight,
+    columns,
+    rows,
+    cells,
+  };
+}

package/src/blocks/templates/index.ts

@@ -0,0 +1,13 @@
+import type { GridRule } from '../validate.js';
+import { RACI_GRID_RULES } from './raci.js';
+
+/**
+ * Closed registry of built-in grid templates (§6a): each entry is a template
+ * name (as passed to `--template <name>`) mapped to its `GridRule`s. Adding a
+ * new template means adding one rule module + one entry here — the same
+ * shape as adding a new notation validator, not a plugin/config-loading
+ * mechanism (deliberately out of scope — see the design note on `RACI-001`).
+ */
+export const GRID_TEMPLATE_RULES: Record<string, GridRule[]> = {
+  raci: RACI_GRID_RULES,
+};

package/src/blocks/templates/raci.ts

@@ -0,0 +1,28 @@
+import type { GridRule } from '../validate.js';
+
+/**
+ * RACI-as-matrix template (methodology `templates/raci/`), built on the
+ * `blocks` matrix subset (08-blocks.md §4a). The base grid validator does not
+ * fix a cell-value vocabulary, so this invariant — exactly one Accountable
+ * owner per row — lives here, not in `validateGrid` (see §6a).
+ */
+export const raciExactlyOneAccountableRule: GridRule = {
+  ruleId: 'RACI-001',
+  severity: 'error',
+  check(grid) {
+    const findings: Array<{ message: string; path?: string }> = [];
+    grid.rows.forEach((row, i) => {
+      const accountableCount = Object.values(row.assign ?? {}).filter((v) => v === 'A').length;
+      if (accountableCount !== 1) {
+        findings.push({
+          message:
+            `Row "${row.name}" (${row.id}) must have exactly one column assigned "A" (Accountable); found ${accountableCount}`,
+          path: `grid.rows[${i}]`,
+        });
+      }
+    });
+    return findings;
+  },
+};
+
+export const RACI_GRID_RULES: GridRule[] = [raciExactlyOneAccountableRule];

package/src/blocks/types.ts

@@ -21,6 +21,73 @@ export interface BlocksFile {
   nested_blocks: NestedBlocksHeader;
 }
 
+export interface GridColumn {
+  id: string;
+  name: string;
+}
+
+export interface GridRow {
+  id: string;
+  name: string;
+  assign?: Record<string, unknown>;
+}
+
+export interface GridHeader {
+  columns: GridColumn[];
+  rows: GridRow[];
+}
+
+export interface GridFile {
+  notation: string;
+  spec_version?: string;
+  grid: GridHeader;
+}
+
+export interface GridLayoutOptions {
+  /** Width of each data column (px). */
+  columnWidth?: number;
+  /** Height of each data row (px). */
+  rowHeight?: number;
+  /** Width of the row-header column carrying each row's name (px). */
+  rowHeaderWidth?: number;
+  /** Height of the column-header row carrying each column's name (px). */
+  headerHeight?: number;
+}
+
+export interface LaidOutGridColumn {
+  id: string;
+  name: string;
+  x: number;
+  width: number;
+}
+
+export interface LaidOutGridRow {
+  id: string;
+  name: string;
+  y: number;
+  height: number;
+}
+
+export interface LaidOutGridCell {
+  rowId: string;
+  colId: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** The cell's `assign` value, stringified; omitted (blank) when unassigned. */
+  value?: string;
+}
+
+export interface GridLayout {
+  bounds: LayoutBounds;
+  rowHeaderWidth: number;
+  headerHeight: number;
+  columns: LaidOutGridColumn[];
+  rows: LaidOutGridRow[];
+  cells: LaidOutGridCell[];
+}
+
 export interface BlocksLayoutOptions {
   /** Width of a leaf block (a block with no children). */
   leafWidth?: number;

package/src/blocks/validate.ts

@@ -1,8 +1,27 @@
-import type { Block } from './types.js';
+import type { Block, GridColumn, GridHeader, GridRow } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 
 export type { ValidationError, ValidationWarning, ValidationResult };
 
+/**
+ * A template-level check over an already well-formed grid document (matrix
+ * subset, §4a). Templates built on the `grid:` root (e.g. RACI) supply their
+ * own `GridRule`s for vocabulary-specific invariants — the base validator
+ * intentionally does not fix what `assign` values mean (08-blocks.md §6a), so
+ * those invariants never live inside `validateGrid` itself.
+ */
+export interface GridRule {
+  /** Template-namespaced rule code, e.g. "RACI-001" — never a BL-0xx code. */
+  ruleId: string;
+  severity: 'error' | 'warning';
+  check(grid: GridHeader): Array<{ message: string; path?: string }>;
+}
+
+export interface ValidateGridOptions {
+  /** Extra template-level rules to run once the base grid is well-formed. */
+  rules?: GridRule[];
+}
+
 /** Document-level ID grammar: BLOCKS-[<middle>-]<INTEGER>. */
 const BLOCKS_DOC_ID_RE = /^BLOCKS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 
@@ -188,6 +207,143 @@ export function validateNestedBlocks(input: unknown): ValidationResult {
   return { valid: errors.length === 0, errors, warnings };
 }
 
+/** Matrix subset (§4a): validate a `grid:` root document — BL-021..BL-025. */
+export function validateGrid(input: unknown, options: ValidateGridOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'BL-001', message: 'Input must be an object' }], warnings };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  if ('notation' in raw && raw['notation'] !== 'blocks') {
+    errors.push({
+      code: 'BL-001',
+      message: `notation must be "blocks", got "${String(raw['notation'])}"`,
+    });
+  }
+
+  if (!('grid' in raw) || !raw['grid'] || typeof raw['grid'] !== 'object') {
+    errors.push({ code: 'BL-020', message: 'Missing required root key: grid' });
+    return { valid: false, errors, warnings };
+  }
+
+  const grid = raw['grid'] as Record<string, unknown>;
+  const rawColumns = grid['columns'];
+  const rawRows = grid['rows'];
+
+  if (!Array.isArray(rawColumns) || rawColumns.length === 0) {
+    errors.push({ code: 'BL-021', message: 'grid.columns must be a non-empty array' });
+  }
+  if (!Array.isArray(rawRows) || rawRows.length === 0) {
+    errors.push({ code: 'BL-022', message: 'grid.rows must be a non-empty array' });
+  }
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const columnIds = new Set<string>();
+  const columns: GridColumn[] = [];
+  (rawColumns as unknown[]).forEach((entry, i) => {
+    const path = `grid.columns[${i}]`;
+    const c = entry as Record<string, unknown>;
+    if (!entry || typeof entry !== 'object' || !isNonEmptyString(c['id']) || !isNonEmptyString(c['name'])) {
+      errors.push({ code: 'BL-023', message: `${path} must have non-empty id and name`, path });
+      return;
+    }
+    const id = c['id'].trim();
+    if (columnIds.has(id)) {
+      errors.push({ code: 'BL-024', message: `Duplicate column id: "${id}"`, path });
+    } else {
+      columnIds.add(id);
+    }
+    columns.push({ id, name: c['name'] });
+  });
+
+  const rowIds = new Set<string>();
+  const rows: GridRow[] = [];
+  (rawRows as unknown[]).forEach((entry, i) => {
+    const path = `grid.rows[${i}]`;
+    const r = entry as Record<string, unknown>;
+    if (!entry || typeof entry !== 'object' || !isNonEmptyString(r['id']) || !isNonEmptyString(r['name'])) {
+      errors.push({ code: 'BL-023', message: `${path} must have non-empty id and name`, path });
+      return;
+    }
+    const id = r['id'].trim();
+    if (rowIds.has(id)) {
+      errors.push({ code: 'BL-024', message: `Duplicate row id: "${id}"`, path });
+    } else {
+      rowIds.add(id);
+    }
+
+    const rawAssign = r['assign'];
+    let assign: Record<string, unknown> | undefined;
+    if (rawAssign !== undefined) {
+      if (!rawAssign || typeof rawAssign !== 'object' || Array.isArray(rawAssign)) {
+        errors.push({ code: 'BL-023', message: `${path}.assign must be a map when present`, path });
+      } else {
+        assign = rawAssign as Record<string, unknown>;
+        for (const colId of Object.keys(assign)) {
+          if (!columnIds.has(colId)) {
+            errors.push({
+              code: 'BL-025',
+              message: `${path}.assign references unknown column id "${colId}"`,
+              path,
+            });
+          }
+        }
+      }
+    }
+    rows.push({ id, name: r['name'], assign });
+  });
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const grid_: GridHeader = { columns, rows };
+  for (const rule of options.rules ?? []) {
+    for (const finding of rule.check(grid_)) {
+      const entry = { code: rule.ruleId, message: finding.message, path: finding.path };
+      if (rule.severity === 'error') errors.push(entry);
+      else warnings.push(entry);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export interface ValidateBlocksOptions extends ValidateGridOptions {}
+
+/**
+ * Root-form dispatcher (§4/§4a): a document declares exactly one of
+ * `nested_blocks` (tree form) or `grid` (matrix subset) — never both, never
+ * neither (BL-020). Delegates to whichever form is present.
+ */
+export function validateBlocks(input: unknown, options: ValidateBlocksOptions = {}): ValidationResult {
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'BL-001', message: 'Input must be an object' }], warnings: [] };
+  }
+
+  const raw = input as Record<string, unknown>;
+  const hasNested = raw['nested_blocks'] !== undefined && raw['nested_blocks'] !== null;
+  const hasGrid = raw['grid'] !== undefined && raw['grid'] !== null;
+
+  if (hasNested && hasGrid) {
+    return {
+      valid: false,
+      errors: [{ code: 'BL-020', message: 'Document root must declare exactly one of nested_blocks or grid, not both' }],
+      warnings: [],
+    };
+  }
+  if (hasGrid) return validateGrid(input, options);
+  if (hasNested) return validateNestedBlocks(input);
+
+  return {
+    valid: false,
+    errors: [{ code: 'BL-020', message: 'Document root must declare exactly one of nested_blocks or grid' }],
+    warnings: [],
+  };
+}
+
 /**
  * Convenience: validate a single `Block` subtree. Used by tests and by
  * downstream consumers that need to check a sub-document.

package/src/capability-map/validate.ts

@@ -21,10 +21,17 @@ export function validateCapabilityMap(input: unknown): ValidationResult {
   }
   const raw = input as Record<string, unknown>;
 
+  // HDR-001/002 — DSM's own rule codes for the same header check CMAP-001
+  // already makes (api02/internal/importer/capabilities.go ValidateCapMap),
+  // added alongside it (not instead of it) so DSM can map a finding straight
+  // back onto its own import-log taxonomy while CMAP-001 stays the richer,
+  // pre-existing Studio-native code for this notation's own validator.
   if (!('notation' in raw)) {
     errors.push({ code: 'CMAP-001', message: 'Missing required field: notation' });
+    errors.push({ code: 'HDR-001', message: 'notation field is missing' });
   } else if (raw['notation'] !== 'capability-map') {
     errors.push({ code: 'CMAP-001', message: `notation must be "capability-map", got "${raw['notation']}"` });
+    errors.push({ code: 'HDR-002', message: `notation must be "capability-map", got "${raw['notation']}"` });
   }
   if (errors.length > 0) return { valid: false, errors, warnings };
 
@@ -116,6 +123,39 @@ function validateCapabilityTree(
     if (node['applications'] !== undefined && !Array.isArray(node['applications']))
       errors.push({ code: 'CMAP-003', message: `${nodePath}: applications must be an array` });
 
+    // LIFECYCLE-001/004 — DSM's own rule codes (capabilities.go
+    // ValidateCapMap/validateCapMapNodes) for `valid_from`/`valid_to`, the
+    // CONTRACT.md §7 primitive-lifecycle fields. Net new: this notation's own
+    // validator has no equivalent check today — `CapabilityNode` (types.ts)
+    // does not even declare these fields, since Studio's own schema tracks
+    // lifecycle via `target_date` instead. The fields are still read directly
+    // off the raw untyped node here because real capability-map documents
+    // (e.g. organizations/acme_corp) author them inline per §7 regardless.
+    {
+      const id = typeof node['id'] === 'string' ? (node['id'] as string) : nodePath;
+      const validFrom = node['valid_from'];
+      const validTo = node['valid_to'];
+      let fromDate: string | undefined;
+      let toDate: string | undefined;
+      if (validFrom !== undefined && validFrom !== null) {
+        if (typeof validFrom !== 'string' || !DATE_RE.test(validFrom)) {
+          errors.push({ code: 'LIFECYCLE-001', message: `capability ${id} valid_from "${String(validFrom)}" is not a valid YYYY-MM-DD date (must be quoted)` });
+        } else {
+          fromDate = validFrom;
+        }
+      }
+      if (validTo !== undefined && validTo !== null) {
+        if (typeof validTo !== 'string' || !DATE_RE.test(validTo)) {
+          errors.push({ code: 'LIFECYCLE-001', message: `capability ${id} valid_to "${String(validTo)}" is not a valid YYYY-MM-DD date (must be quoted)` });
+        } else {
+          toDate = validTo;
+        }
+      }
+      if (fromDate && toDate && toDate < fromDate) {
+        errors.push({ code: 'LIFECYCLE-004', message: `capability ${id} valid_to ${toDate} is before valid_from ${fromDate}` });
+      }
+    }
+
     if (node['children'] !== undefined) {
       if (!Array.isArray(node['children'])) {
         errors.push({ code: 'CMAP-003', message: `${nodePath}: children must be an array` });

package/src/fgca/parse-canonical.ts

@@ -130,6 +130,14 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   }
   const activitiesRaw = asObjectArray(raw['actions']);
   if (activitiesRaw === null && 'activities' in raw) {
+    // DSM's Go ValidateFGCA (fgca.go) still accepts this as the deprecated
+    // "activities" key and promotes it with a DGCA-DEPR warning, not an
+    // error. Deliberately NOT matched here — PR #320 ("drop deprecated
+    // notation aliases fgca/fga/activities/activity-card") already removed
+    // that leniency from this validator on purpose. Re-introducing
+    // DGCA-DEPR would reverse a deliberate, shipped decision, not fill a
+    // gap; see docs/validation.md's "Standalone-element envelope rules"
+    // section for the full note.
     errors.push({ code: 'FGCA-004', message: '"activities" key is not accepted — rename to "actions"', path: 'actions' });
   }