@transitrix/diagrams 1.9.18 → 1.11.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-candidate-fields.ts

@@ -0,0 +1,93 @@
+// Candidate-only fields on admitted canon — `ADMIT-009`.
+//
+// `ELEMENT_PRIMITIVES.md` §7.29 (methodology v3.6.0) states it normatively for
+// `RELEASE` and then generalises it to every TYPE:
+//
+//   > `RELEASE` has no `extraction_confidence` field — and neither does any
+//   > other canon element, of any TYPE. `extraction_confidence` is a review
+//   > flag on an ingest candidate (`candidate.extraction_confidence`,
+//   > vocabulary.yaml); it is surfaced in the review queue, drives
+//   > reviewer-authority routing (CONTRACT.md §6.2), and is never persisted
+//   > into canon. An admitted element carrying it is a defect in whatever
+//   > wrote it, not a precedent to follow.
+//
+// Nothing enforced that mechanically. The ingest pipeline that produces the
+// field lives in `methodology`'s `packages/ingest-cli` and only ever writes
+// *candidates*; admission into `canon/elements/**` happens in an adopter's own
+// tooling, which is `@transitrix/cli validate`'s side of the fence — so this is
+// where the rule has to bite.
+//
+// **Why the check keys on `zone`, not on the folder.** `extraction_confidence`
+// is legitimate on a candidate and meaningless — but not a defect — elsewhere;
+// only the *admitted* form is wrong. `zone: canon` is the admission marker
+// every standalone element carries (`ELEMENT_PRIMITIVES.md` §3, required
+// envelope field, `ELEM-001`), and it is the discriminator against the two
+// zones that may legitimately carry harvest metadata: `zone: field`, whose
+// provenance contract owns `source_quality` (CONTRACT.md §5/§11.2), and
+// `zone: codex`. Sidecars (`*.history.yaml`, `*.runstate.yaml`) carry no
+// `zone` and no `id`, so they fall out for free — the same "no id -> not an
+// element" split `docId` already makes for every sibling check in this folder.
+//
+// **Rule code.** Studio-authored as `ELEM-CANDIDATE-FIELD-001` (in the shape
+// methodology already uses for a named element-envelope rule outside the
+// numbered run — `ELEM-ALIAS-001`, `ELEM-FORMER-ID-001` — deliberately not
+// `ELEM-006`, since the numbered `ELEM-*` run is methodology's to extend and
+// squatting the next free number would collide with whatever it registers
+// there next). Renamed to `ADMIT-009` (transitrix/methodology#505, merged
+// 2026-08-19) now that methodology has registered a code of its own for
+// §7.29 — no functional change, this is that alias.
+
+import { docId } from './validate-repo.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+/**
+ * Fields that belong to an ingest candidate and are never persisted into
+ * canon. Each entry names the field and the provenance pattern that replaces
+ * it, so the finding points at the correct shape rather than only failing
+ * closed. One entry today; the list is the extension point if methodology
+ * closes another candidate-side field out of canon the same way.
+ */
+const CANDIDATE_ONLY_FIELDS: readonly { field: string; instead: string }[] = [
+  {
+    field: 'extraction_confidence',
+    instead:
+      "cite the evidence through 'derived_from' (ELEMENT_PRIMITIVES.md §3) — " +
+      'an OBSERVATION or another Field/Codex artefact; the review flag stays on the ' +
+      'ingest candidate and is not carried across admission',
+  },
+];
+
+/** True when the doc is an admitted canon element — `zone: canon` per
+ *  `ELEMENT_PRIMITIVES.md` §3. Deliberately narrow: a doc with no `zone`
+ *  (a sidecar) or a non-canon zone (`field`, `codex`) is not admitted canon
+ *  and this rule says nothing about it. */
+function isAdmittedCanonElement(doc: RepoDoc): boolean {
+  return doc.data?.['zone'] === 'canon';
+}
+
+/**
+ * `ADMIT-009` — a candidate-only field present on an admitted (`zone: canon`)
+ * element, of any TYPE. Appends findings; pure, deterministic order.
+ */
+export function checkCandidateFields(input: RepoModelInput, findings: RepoFinding[]): void {
+  for (const doc of input.elements) {
+    if (!doc.data) continue;
+    if (!isAdmittedCanonElement(doc)) continue;
+
+    const id = docId(doc) ?? '';
+    for (const { field, instead } of CANDIDATE_ONLY_FIELDS) {
+      if (doc.data[field] === undefined) continue;
+      findings.push({
+        scope: PScope,
+        id,
+        ruleId: 'ADMIT-009',
+        message:
+          `ADMIT-009: admitted element '${id || doc.path}' carries '${field}', ` +
+          `which is an ingest-candidate review flag and is never persisted into canon ` +
+          `(ELEMENT_PRIMITIVES.md §7.29). Remove it and ${instead}.`,
+      });
+    }
+  }
+}