@transitrix/diagrams 1.10.0 → 1.12.0

package/src/process-blueprint/layout.ts

@@ -19,6 +19,7 @@ import type {
   StageTextCell,
 } from './types.js';
 import { wrapTextLines } from '../webview/entity-text-layout.js';
+import { columnIndexesForRealisedVia, resolveColumnDisplay } from './resolve-columns.js';
 
 const ASPECT_CATEGORIES: AspectCategory[] = ['systems', 'actors', 'equipment', 'information_entities'];
 
@@ -33,7 +34,13 @@ const ASPECT_LABEL: Record<AspectCategory, string> = {
 // (absent = feature disabled) and must stay optional in the resolved type.
 type SizingOptionKeys = Exclude<
   keyof ProcessBlueprintLayoutOptions,
-  'complianceLane' | 'complianceInput' | 'visibleAspects' | 'visibleRows' | 'visibleStages'
+  | 'complianceLane'
+  | 'complianceInput'
+  | 'visibleAspects'
+  | 'visibleRows'
+  | 'visibleStages'
+  | 'processCatalog'
+  | 'stepHomeProcess'
 >;
 
 /**
@@ -41,7 +48,16 @@ type SizingOptionKeys = Exclude<
  * the opt-in feature fields stay optional (undefined = feature disabled).
  */
 type ResolvedLayoutOptions = Required<Pick<ProcessBlueprintLayoutOptions, SizingOptionKeys>> &
-  Pick<ProcessBlueprintLayoutOptions, 'complianceLane' | 'complianceInput' | 'visibleAspects' | 'visibleRows' | 'visibleStages'>;
+  Pick<
+    ProcessBlueprintLayoutOptions,
+    | 'complianceLane'
+    | 'complianceInput'
+    | 'visibleAspects'
+    | 'visibleRows'
+    | 'visibleStages'
+    | 'processCatalog'
+    | 'stepHomeProcess'
+  >;
 
 const DEFAULTS = {
   legendColumnWidth: 140,
@@ -258,27 +274,29 @@ function deriveComplianceRow(
 
     for (const stageRef of realisedVia) {
       if (typeof stageRef !== 'string') continue;
-      const idx = stageIndexById.get(stageRef.trim());
-      if (idx === undefined) continue;
-
-      for (const lawId of lawIds) {
-        // Apply jurisdiction filter.
-        if (filterJurisdictions) {
-          const jur = input.codexJurisdictions?.[lawId];
-          if (!jur || !filterJurisdictions.has(jur)) continue;
-        }
+      const idxs = columnIndexesForRealisedVia(stageRef, stageIndexById, opts.stepHomeProcess);
+      if (idxs.length === 0) continue;
+
+      for (const idx of idxs) {
+        for (const lawId of lawIds) {
+          // Apply jurisdiction filter.
+          if (filterJurisdictions) {
+            const jur = input.codexJurisdictions?.[lawId];
+            if (!jur || !filterJurisdictions.has(jur)) continue;
+          }
 
-        if (!stageAccum.has(idx)) stageAccum.set(idx, new Map());
-        const lawMap = stageAccum.get(idx)!;
-        const existing = lawMap.get(lawId);
-        const isGap = a.status === 'non_compliant' || a.status === 'partial';
-        if (!existing) {
-          lawMap.set(lawId, { gap: isGap, deadline: req.deadline });
-        } else {
-          existing.gap = existing.gap || isGap;
-          // Keep the earlier deadline (more urgent).
-          if (req.deadline && (!existing.deadline || req.deadline < existing.deadline)) {
-            existing.deadline = req.deadline;
+          if (!stageAccum.has(idx)) stageAccum.set(idx, new Map());
+          const lawMap = stageAccum.get(idx)!;
+          const existing = lawMap.get(lawId);
+          const isGap = a.status === 'non_compliant' || a.status === 'partial';
+          if (!existing) {
+            lawMap.set(lawId, { gap: isGap, deadline: req.deadline });
+          } else {
+            existing.gap = existing.gap || isGap;
+            // Keep the earlier deadline (more urgent).
+            if (req.deadline && (!existing.deadline || req.deadline < existing.deadline)) {
+              existing.deadline = req.deadline;
+            }
           }
         }
       }
@@ -338,6 +356,7 @@ export function layoutProcessBlueprint(
     ? allStages.filter(s => s?.id != null && opts.visibleStages!.includes(s.id))
     : allStages;
   const stageIndexById = buildStageIndex(stages);
+  const display = stages.map(s => resolveColumnDisplay(s, opts.processCatalog));
 
   // Row visibility from visibleRows
   const visRows = opts.visibleRows;
@@ -354,7 +373,7 @@ export function layoutProcessBlueprint(
   const stageHeaders: StageHeaderCell[] = stages.map((s, i) => ({
     stageIndex: i,
     id: s?.id ?? '',
-    name: s?.name ?? '',
+    name: display[i].name,
     x: opts.legendColumnWidth + i * opts.stageColumnWidth,
     y: 0,
     width: opts.stageColumnWidth,
@@ -373,8 +392,8 @@ export function layoutProcessBlueprint(
     return Math.max(minHeight, maxLines * opts.textLineHeight + 2 * opts.cellTextPadY);
   };
 
-  const goalLines = stages.map(s => wrap(s?.goal ?? ''));
-  const resultLines = stages.map(s => wrap(s?.result ?? ''));
+  const goalLines = display.map(d => wrap(d.goal));
+  const resultLines = display.map(d => wrap(d.result));
 
   let cursorY = opts.stageHeaderHeight;
   let goalRowY = 0, goalRowHeight = 0;
@@ -385,8 +404,8 @@ export function layoutProcessBlueprint(
   if (showGoal) {
     goalRowY = cursorY;
     goalRowHeight = rowHeightFor(goalLines.map(l => l.length), opts.goalRowHeight);
-    goalCells.push(...stages.map((s, i) => ({
-      stageIndex: i, text: s?.goal ?? '', lines: goalLines[i],
+    goalCells.push(...display.map((d, i) => ({
+      stageIndex: i, text: d.goal, lines: goalLines[i],
       x: opts.legendColumnWidth + i * opts.stageColumnWidth, y: goalRowY,
       width: opts.stageColumnWidth, height: goalRowHeight,
     })));
@@ -395,8 +414,8 @@ export function layoutProcessBlueprint(
   if (showResult) {
     resultRowY = cursorY;
     resultRowHeight = rowHeightFor(resultLines.map(l => l.length), opts.resultRowHeight);
-    resultCells.push(...stages.map((s, i) => ({
-      stageIndex: i, text: s?.result ?? '', lines: resultLines[i],
+    resultCells.push(...display.map((d, i) => ({
+      stageIndex: i, text: d.result, lines: resultLines[i],
       x: opts.legendColumnWidth + i * opts.stageColumnWidth, y: resultRowY,
       width: opts.stageColumnWidth, height: resultRowHeight,
     })));

package/src/process-blueprint/resolve-columns.ts

@@ -0,0 +1,147 @@
+/**
+ * Render-time resolution of Process Blueprint column headers and the
+ * compliance-lane join key.
+ *
+ * A `PROCESS-…` column is the process: `name` / `goal` / `result` come from
+ * the child PROCESS element (ELEMENT_PRIMITIVES §7.5), never from restated
+ * view fields. A `STAGE-…` column keeps the authored sketch copy.
+ *
+ * Pure: no I/O. The host (VS Code preview, JCEF, CLI) already owns loading
+ * canon/elements/** — this module only knows how to pick PROCESS / STEP
+ * records out of that pool.
+ *
+ * This is a read model, never storage. Callers render an ephemeral display
+ * copy and must never serialise it back onto the view.
+ */
+
+import type { Stage } from './types.js';
+
+const PROCESS_ID_RE = /^PROCESS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const STAGE_ID_RE = /^STAGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+
+export function isProcessColumnId(id: string): boolean {
+  return PROCESS_ID_RE.test(id);
+}
+
+export function isStageColumnId(id: string): boolean {
+  return STAGE_ID_RE.test(id);
+}
+
+/** Display fields taken from a `notation: process` element. */
+export interface ProcessColumnRecord {
+  name: string;
+  goal?: string;
+  result?: string;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function optionalString(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
+}
+
+/**
+ * Collect admitted PROCESS elements from a raw canon/elements/** doc pool,
+ * keyed by id. Malformed documents are skipped.
+ */
+export function collectProcessColumnRecords(docs: readonly unknown[]): Map<string, ProcessColumnRecord> {
+  const out = new Map<string, ProcessColumnRecord>();
+  for (const doc of docs) {
+    if (!isRecord(doc)) continue;
+    if (doc['notation'] !== 'process') continue;
+    const id = optionalString(doc['id']);
+    if (!id || !isProcessColumnId(id)) continue;
+    const name = optionalString(doc['name']);
+    if (!name) continue;
+    const rec: ProcessColumnRecord = { name };
+    const goal = optionalString(doc['goal']);
+    const result = optionalString(doc['result']);
+    if (goal) rec.goal = goal;
+    if (result) rec.result = result;
+    out.set(id, rec);
+  }
+  return out;
+}
+
+/**
+ * Map each STEP id onto the PROCESS that contains it — either inline in
+ * `PROCESS.flow.steps[]` or a promoted `{ notation: step, process }` element.
+ * First writer wins; a later duplicate is ignored.
+ */
+export function collectStepHomeProcess(docs: readonly unknown[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const doc of docs) {
+    if (!isRecord(doc)) continue;
+    if (doc['notation'] === 'process') {
+      const processId = optionalString(doc['id']);
+      if (!processId || !isProcessColumnId(processId)) continue;
+      const flow = isRecord(doc['flow']) ? doc['flow'] : undefined;
+      const steps = flow && Array.isArray(flow['steps']) ? flow['steps'] : [];
+      for (const step of steps) {
+        if (!isRecord(step)) continue;
+        const stepId = optionalString(step['id']);
+        if (!stepId || out.has(stepId)) continue;
+        out.set(stepId, processId);
+      }
+      continue;
+    }
+    if (doc['notation'] === 'step') {
+      const stepId = optionalString(doc['id']);
+      const processId = optionalString(doc['process']);
+      if (!stepId || !processId || !isProcessColumnId(processId)) continue;
+      if (!out.has(stepId)) out.set(stepId, processId);
+    }
+  }
+  return out;
+}
+
+/**
+ * Display copy for one column. PROCESS- columns ignore any restated view
+ * fields; missing catalogue falls back to the id (header) and empty
+ * goal/result. STAGE- columns keep authored name/goal/result.
+ */
+export function resolveColumnDisplay(
+  stage: Stage,
+  catalog?: ReadonlyMap<string, ProcessColumnRecord>,
+): { name: string; goal: string; result: string } {
+  const id = typeof stage.id === 'string' ? stage.id.trim() : '';
+  if (isProcessColumnId(id)) {
+    const rec = catalog?.get(id);
+    return {
+      name: rec?.name ?? id,
+      goal: rec?.goal ?? '',
+      result: rec?.result ?? '',
+    };
+  }
+  return {
+    name: typeof stage.name === 'string' ? stage.name : '',
+    goal: typeof stage.goal === 'string' ? stage.goal : '',
+    result: typeof stage.result === 'string' ? stage.result : '',
+  };
+}
+
+/**
+ * Column indexes a `realised_via` token pins on this blueprint.
+ *
+ * `STAGE-…` is never a join key (ASSERT-004). A `PROCESS-…` token pins that
+ * column. A STEP whose home process is a column pins that column.
+ */
+export function columnIndexesForRealisedVia(
+  ref: string,
+  stageIndexById: ReadonlyMap<string, number>,
+  stepHomeProcess?: ReadonlyMap<string, string>,
+): number[] {
+  const token = ref.trim();
+  if (token.length === 0) return [];
+  if (isStageColumnId(token)) return [];
+  const direct = stageIndexById.get(token);
+  if (direct !== undefined && isProcessColumnId(token)) return [direct];
+  const home = stepHomeProcess?.get(token);
+  if (home && isProcessColumnId(home)) {
+    const idx = stageIndexById.get(home);
+    if (idx !== undefined) return [idx];
+  }
+  return [];
+}

package/src/process-blueprint/types.ts

@@ -33,8 +33,9 @@ export interface ComplianceLaneAssertion {
   /** Compliance realisation status. */
   status: 'compliant' | 'partial' | 'non_compliant' | 'under_review' | 'pending_owner' | 'n_a';
   /**
-   * Typed IDs of stages / process steps where the requirement is realised.
-   * When empty/absent, the assertion covers the entire subject, not a specific stage.
+   * Typed IDs of processes or steps where the requirement is realised.
+   * Sketch `STAGE-…` ids are not a join key. When empty/absent, the assertion
+   * covers the entire subject, not a specific column.
    */
   realised_via?: string[];
 }
@@ -100,9 +101,12 @@ export interface ComplianceRow {
 
 export interface Stage {
   id: string;
-  name: string;
-  goal: string;
-  result: string;
+  /** Required on `STAGE-…` sketch columns (`BP-005`); omitted on `PROCESS-…`. */
+  name?: string;
+  /** Required on `STAGE-…` sketch columns (`BP-005`); omitted on `PROCESS-…`. */
+  goal?: string;
+  /** Required on `STAGE-…` sketch columns (`BP-005`); omitted on `PROCESS-…`. */
+  result?: string;
   description?: string;
 }
 
@@ -204,6 +208,16 @@ export interface ProcessBlueprintLayoutOptions {
    * When absent, all stages are shown.
    */
   visibleStages?: string[];
+  /**
+   * Catalogue of `PROCESS-…` column records (id → name / optional goal / result).
+   * Required to header catalogued columns; ignored for `STAGE-…` sketches.
+   */
+  processCatalog?: ReadonlyMap<string, { name: string; goal?: string; result?: string }>;
+  /**
+   * STEP id → home PROCESS id (contained in `PROCESS.flow` or promoted).
+   * Used by the compliance-lane join; omit to skip STEP-level pins.
+   */
+  stepHomeProcess?: ReadonlyMap<string, string>;
 }
 
 import type { LayoutBounds } from '../geometry.js';

package/src/process-blueprint/validate.ts

@@ -1,21 +1,63 @@
 import type { AspectCategory } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import type { CanonCatalog } from '../typed-id.js';
 
 export type { ValidationError, ValidationWarning, ValidationResult };
 
 const ID_GRAMMAR_RE = /^[A-Z][A-Z_]*(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const PROCESS_BLUEPRINT_ID_RE = /^PROCESS_BLUEPRINT(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const STAGE_ID_RE = /^STAGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const PROCESS_ID_RE = /^PROCESS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const APPLICATION_ID_RE = /^APPLICATION(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const ROLE_ID_RE = /^ROLE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 
 const ASPECT_CATEGORIES: AspectCategory[] = ['systems', 'actors', 'equipment', 'information_entities'];
 
+const RESTATED_COLUMN_FIELDS = ['name', 'goal', 'result'] as const;
+
+export interface ProcessParentEdge {
+  /** Child process id (`from`). */
+  from: string;
+  /** Parent process id (`to`). */
+  to: string;
+}
+
+export interface ProcessBlueprintValidateOptions {
+  /** When provided, BP-012 resolves `PROCESS-…` column ids against admitted canon. */
+  catalog?: CanonCatalog;
+  /**
+   * In-effect `process_parent` edges (child → parent). When provided, BP-014
+   * warns if `process_blueprint.process` is set and a `PROCESS-…` column has
+   * no such edge to that parent. Omit to skip BP-014 (file-scope without the
+   * relation catalogue).
+   */
+  processParentEdges?: readonly ProcessParentEdge[];
+}
+
 function isNonEmptyString(v: unknown): v is string {
   return typeof v === 'string' && v.trim().length > 0;
 }
 
-export function validateProcessBlueprint(input: unknown): ValidationResult {
+function isProcessColumnId(id: string): boolean {
+  return PROCESS_ID_RE.test(id);
+}
+
+function isStageColumnId(id: string): boolean {
+  return STAGE_ID_RE.test(id);
+}
+
+function isColumnId(id: string): boolean {
+  return isStageColumnId(id) || isProcessColumnId(id);
+}
+
+function fieldIsPresent(record: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+export function validateProcessBlueprint(
+  input: unknown,
+  options: ProcessBlueprintValidateOptions = {},
+): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
@@ -63,6 +105,7 @@ export function validateProcessBlueprint(input: unknown): ValidationResult {
   }
 
   const stageIds = new Set<string>();
+  const processColumnIds: string[] = [];
   for (let i = 0; i < stagesRaw.length; i++) {
     const s = stagesRaw[i] as Record<string, unknown> | undefined;
     const path = `stages[${i}]`;
@@ -71,29 +114,72 @@ export function validateProcessBlueprint(input: unknown): ValidationResult {
       continue;
     }
     if (!isNonEmptyString(s['id'])) {
-      errors.push({ code: 'BP-005', message: `${path}.id is required` });
+      errors.push({ code: 'BP-006', message: `${path}.id is required` });
+      continue;
+    }
+
+    const sid = s['id'].trim();
+    if (stageIds.has(sid)) {
+      errors.push({ code: 'BP-006', message: `Duplicate stage id: "${sid}"` });
     } else {
-      const sid = s['id'].trim();
-      if (stageIds.has(sid)) {
-        errors.push({ code: 'BP-006', message: `Duplicate stage id: "${sid}"` });
-      } else {
-        stageIds.add(sid);
-      }
-      if (!STAGE_ID_RE.test(sid)) {
-        errors.push({
-          code: 'BP-006',
-          message: `${path}.id "${sid}" must match STAGE-[<middle>-]<INTEGER>`,
-        });
-      }
+      stageIds.add(sid);
     }
-    if (!isNonEmptyString(s['name'])) {
-      errors.push({ code: 'BP-005', message: `${path}.name is required` });
+    if (!isColumnId(sid)) {
+      errors.push({
+        code: 'BP-006',
+        message: `${path}.id "${sid}" must match STAGE-[<middle>-]<INTEGER> or PROCESS-[<middle>-]<INTEGER>`,
+      });
+      continue;
     }
-    if (!isNonEmptyString(s['goal'])) {
-      errors.push({ code: 'BP-005', message: `${path}.goal is required` });
+
+    if (isProcessColumnId(sid)) {
+      processColumnIds.push(sid);
+      for (const field of RESTATED_COLUMN_FIELDS) {
+        if (fieldIsPresent(s, field)) {
+          errors.push({
+            code: 'BP-013',
+            message: `${path}.${field} must not be restated on a PROCESS-… column — derive it from the process element`,
+          });
+        }
+      }
+      if (options.catalog) {
+        const resolved = options.catalog.typeOf(sid);
+        if (resolved !== 'PROCESS') {
+          errors.push({
+            code: 'BP-012',
+            message: `${path}.id "${sid}" must resolve to an admitted PROCESS element`,
+          });
+        }
+      }
+    } else {
+      if (!isNonEmptyString(s['name'])) {
+        errors.push({ code: 'BP-005', message: `${path}.name is required` });
+      }
+      if (!isNonEmptyString(s['goal'])) {
+        errors.push({ code: 'BP-005', message: `${path}.goal is required` });
+      }
+      if (!isNonEmptyString(s['result'])) {
+        errors.push({ code: 'BP-005', message: `${path}.result is required` });
+      }
     }
-    if (!isNonEmptyString(s['result'])) {
-      errors.push({ code: 'BP-005', message: `${path}.result is required` });
+  }
+
+  const parentProcess = isNonEmptyString(pb['process']) ? pb['process'].trim() : undefined;
+  if (parentProcess && options.processParentEdges && processColumnIds.length > 0) {
+    const linked = new Set(
+      options.processParentEdges
+        .filter((e) => e.to === parentProcess)
+        .map((e) => e.from),
+    );
+    for (const child of processColumnIds) {
+      if (!linked.has(child)) {
+        warnings.push({
+          code: 'BP-014',
+          message:
+            `Column "${child}" is a PROCESS-… id and process_blueprint.process is "${parentProcess}", ` +
+            `but no in-effect process_parent REL links that column to that parent`,
+        });
+      }
     }
   }
 
@@ -123,7 +209,7 @@ export function validateProcessBlueprint(input: unknown): ValidationResult {
       if (!Array.isArray(entryStages) || entryStages.length === 0) {
         errors.push({
           code: 'BP-007',
-          message: `${path}.stages must be a non-empty array of STAGE-… ids`,
+          message: `${path}.stages must be a non-empty array of declared column ids`,
         });
       } else {
         for (let j = 0; j < entryStages.length; j++) {

package/src/repo-validate/check-process-parent.ts

@@ -0,0 +1,184 @@
+// process_parent relation checks — 17-relations.md §3 / §5 (REL-007, REL-008)
+// and endpoint TYPE (PROCESS → PROCESS), plus the in-effect edge collector
+// that process-blueprint BP-014 consumes.
+//
+// REL-007 is single-file (from === to). REL-008 is cross-cutting over the
+// admitted process_parent graph and is a warning, parallel to REL-006.
+
+import { docId, endpointId } from './validate-repo.js';
+import type { ProcessParentEdge } from '../process-blueprint/validate.js';
+import type { RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+function isProcessNotation(n: unknown): boolean {
+  return n === 'process';
+}
+
+function isoDate(value: unknown): string | undefined {
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value) ? value.slice(0, 10) : undefined;
+}
+
+/** Inclusive window: in effect at `asOf` iff valid_from ≤ asOf and (valid_to is null or asOf ≤ valid_to). */
+export function relationInEffectAt(data: Record<string, unknown>, asOf: string): boolean {
+  const from = isoDate(data['valid_from']);
+  if (from && from > asOf) return false;
+  const to = data['valid_to'];
+  if (to === null || to === undefined) return true;
+  const toDate = isoDate(to);
+  if (!toDate) return true;
+  return asOf <= toDate;
+}
+
+export function todayIsoDate(now: Date = new Date()): string {
+  return now.toISOString().slice(0, 10);
+}
+
+/** In-effect `process_parent` edges (child → parent) among loaded REL files. */
+export function collectInEffectProcessParentEdges(
+  input: RepoModelInput,
+  asOf: string = todayIsoDate(),
+): ProcessParentEdge[] {
+  const edges: ProcessParentEdge[] = [];
+  for (const doc of input.relations) {
+    if (!doc.data) continue;
+    if (doc.data['type'] !== 'process_parent') continue;
+    if (!relationInEffectAt(doc.data, asOf)) continue;
+    const fromId = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+    const toId = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+    if (!fromId || !toId) continue;
+    edges.push({ from: fromId, to: toId });
+  }
+  return edges;
+}
+
+interface ParentRel {
+  relId: string;
+  fromId: string;
+  toId: string;
+}
+
+function processParentRels(input: RepoModelInput): ParentRel[] {
+  const out: ParentRel[] = [];
+  for (const doc of input.relations) {
+    if (!doc.data) continue;
+    if (doc.data['type'] !== 'process_parent') continue;
+    const fromId = endpointId(doc.data['from']) ?? endpointId(doc.data['source']);
+    const toId = endpointId(doc.data['to']) ?? endpointId(doc.data['target']);
+    if (!fromId || !toId) continue;
+    out.push({ relId: docId(doc) ?? '', fromId, toId });
+  }
+  return out;
+}
+
+/** REL-007 — process_parent self-reference. */
+function checkSelfReference(rels: ParentRel[], findings: RepoFinding[]): void {
+  for (const rel of rels) {
+    if (rel.fromId === rel.toId) {
+      findings.push({
+        scope: PScope,
+        id: rel.relId,
+        ruleId: 'REL-007',
+        message: `REL-007: process_parent relation '${rel.relId}' has from equal to to ('${rel.fromId}').`,
+      });
+    }
+  }
+}
+
+/** REL-008 — cycle in the process_parent graph (warning). */
+function checkCycle(rels: ParentRel[], findings: RepoFinding[]): void {
+  const childrenOf = new Map<string, string[]>();
+  const relByChildParent = new Map<string, string>();
+  const nodes = new Set<string>();
+  for (const rel of rels) {
+    if (rel.fromId === rel.toId) continue;
+    nodes.add(rel.fromId);
+    nodes.add(rel.toId);
+    const list = childrenOf.get(rel.fromId);
+    if (list) list.push(rel.toId);
+    else childrenOf.set(rel.fromId, [rel.toId]);
+    relByChildParent.set(`${rel.fromId}\0${rel.toId}`, rel.relId);
+  }
+
+  const UNVISITED = 0;
+  const VISITING = 1;
+  const DONE = 2;
+  const state = new Map<string, number>();
+  let hit: string | undefined;
+
+  function walk(id: string): boolean {
+    const s = state.get(id) ?? UNVISITED;
+    if (s === DONE) return false;
+    if (s === VISITING) {
+      hit = id;
+      return true;
+    }
+    state.set(id, VISITING);
+    for (const parent of childrenOf.get(id) ?? []) {
+      if (nodes.has(parent) && walk(parent)) return true;
+    }
+    state.set(id, DONE);
+    return false;
+  }
+
+  for (const id of nodes) {
+    if (walk(id)) break;
+  }
+  if (!hit) return;
+
+  const relId =
+    [...relByChildParent.entries()].find(([key]) => key.startsWith(`${hit}\0`))?.[1] ?? hit;
+  findings.push({
+    scope: PScope,
+    id: relId,
+    ruleId: 'REL-008',
+    severity: 'warning',
+    message: `REL-008: process_parent graph contains a cycle involving '${hit}'.`,
+  });
+}
+
+/**
+ * Endpoint TYPE for process_parent: both ends must be PROCESS when they
+ * resolve. Unknown endpoints stay with referential integrity; this pass only
+ * fires when the element exists and is the wrong notation.
+ */
+function checkEndpointTypes(input: RepoModelInput, rels: ParentRel[], findings: RepoFinding[]): void {
+  const elementById = new Map<string, Record<string, unknown>>();
+  for (const doc of input.elements) {
+    const id = docId(doc);
+    if (id && doc.data) elementById.set(id, doc.data);
+  }
+
+  for (const rel of rels) {
+    const from = elementById.get(rel.fromId);
+    if (from && !isProcessNotation(from['notation'])) {
+      findings.push({
+        scope: PScope,
+        id: rel.relId,
+        ruleId: 'REL-002',
+        message:
+          `Layer-semantics: '${rel.relId}' type 'process_parent' requires from to be ` +
+          `PROCESS; got notation='${from['notation']}'.`,
+      });
+    }
+    const to = elementById.get(rel.toId);
+    if (to && !isProcessNotation(to['notation'])) {
+      findings.push({
+        scope: PScope,
+        id: rel.relId,
+        ruleId: 'REL-002',
+        message:
+          `Layer-semantics: '${rel.relId}' type 'process_parent' requires to to be ` +
+          `PROCESS; got notation='${to['notation']}'.`,
+      });
+    }
+  }
+}
+
+export function checkProcessParentSemantics(input: RepoModelInput, findings: RepoFinding[]): void {
+  const rels = processParentRels(input);
+  if (rels.length === 0) return;
+  checkSelfReference(rels, findings);
+  checkCycle(rels, findings);
+  checkEndpointTypes(input, rels, findings);
+}