@transitrix/diagrams 1.10.0 → 1.11.0

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/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;

package/src/compliance-verification-matrix/build.ts

@@ -0,0 +1,84 @@
+// Requirement -> verification matrix builder.
+
+import type { ComplianceIndex } from '../compliance/types.js';
+import { buildGapReport } from '../compliance/gap-report.js';
+import type {
+  RequirementVerificationMatrix,
+  RequirementVerificationMatrixOptions,
+  RequirementVerificationRow,
+} from './types.js';
+
+function byId<T extends { id: string }>(a: T, b: T): number {
+  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: ComplianceIndex,
+  options: RequirementVerificationMatrixOptions = {},
+): RequirementVerificationMatrix {
+  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: RequirementVerificationRow[] = [];
+  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: Pick<RequirementVerificationRow, 'requirementId' | 'requirementLabel' | 'parentId' | 'parentLabel'> = {
+      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' as const) : 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/src/compliance-verification-matrix/csv.ts

@@ -0,0 +1,47 @@
+// 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.
+
+import type { RequirementVerificationMatrix, RequirementVerificationRow } from './types.js';
+
+const HEADER = [
+  'requirement_id',
+  'requirement_label',
+  'parent_id',
+  'parent_label',
+  'related_test_result_id',
+  'related_test_result_label',
+  'outcome',
+  'coverage_gap',
+] as const;
+
+function csvCell(value: string | undefined): string {
+  const v = value ?? '';
+  return `"${v.replace(/"/g, '""')}"`;
+}
+
+function rowCells(row: RequirementVerificationRow): string[] {
+  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: RequirementVerificationMatrix): string {
+  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/src/compliance-verification-matrix/index.ts

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

package/src/compliance-verification-matrix/types.ts

@@ -0,0 +1,85 @@
+// 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.
+
+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/src/fgca/action-change-ids.ts

@@ -0,0 +1,13 @@
+/**
+ * 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: Record<string, unknown>,
+): 'delivers_changes' | 'changes' {
+  return Object.prototype.hasOwnProperty.call(el, 'delivers_changes')
+    ? 'delivers_changes'
+    : 'changes';
+}

package/src/fgca/parse-canonical.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`
@@ -36,6 +36,7 @@ import type {
   ValidationWarning,
   ValidationResult,
 } from '../validation-types.js';
+import { actionChangeLinkField } from './action-change-ids.js';
 
 export interface CanonicalFGCAResult extends ValidationResult {
   /** On success, the internal-form FGCADoc derived from the canonical input. */
@@ -64,9 +65,10 @@ function asObjectArray(v: unknown): Array<Record<string, unknown>> | null {
   return v.map((el) => (el && typeof el === 'object' ? (el as Record<string, unknown>) : null) as Record<string, unknown>);
 }
 
-/** DGA mode (`view_config.layers.changes: off`) may omit the changes layer. */
-function isChangesLayerOff(raw: Record<string, unknown>): boolean {
-  const vc = raw['view_config'];
+/** DGA mode (`view_config.layers.changes: off`) omits the Changes column. */
+export function isDgcaChangesLayerOff(input: unknown): boolean {
+  if (!input || typeof input !== 'object') return false;
+  const vc = (input as Record<string, unknown>)['view_config'];
   if (!vc || typeof vc !== 'object') return false;
   const layers = (vc as Record<string, unknown>)['layers'];
   if (!layers || typeof layers !== 'object') return false;
@@ -125,7 +127,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   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']);
@@ -253,11 +255,12 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     };
   });
 
-  // 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<string, string[]>();
   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);
   });
 
@@ -331,6 +334,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     goals: internalGoals,
     changes: internalChanges,
     activities: internalActivities,
+    hideChanges: isDgcaChangesLayerOff(raw),
   };
 
   return { valid: true, errors, warnings, parsed };