@transitrix/diagrams 1.8.21 → 1.10.0

package/dist/fgca/preview-layout.d.ts

@@ -37,7 +37,7 @@ export interface FGCAPreviewLayoutOptions {
     colGap?: number;
     /** Vertical gap (px) between stacked nodes within a column. Default matches the historical hardcoded value. */
     rowGap?: number;
-    /** Trim to a level cap or a single root goal (vkgeorgia/strategy#77). Defaults to 'all'. */
+    /** Trim to a level cap or a single root goal. Defaults to 'all'. */
     scope?: Scope;
     /** Entity node width (px). Default {@link FGCA_NODE_W}. */
     nodeWidth?: number;

package/dist/goals/GoalNode.d.ts

@@ -15,5 +15,5 @@ export interface GoalNodeData {
 }
 declare const GoalNode: React.MemoExoticComponent<({ data }: {
     data: GoalNodeData;
-}) => import("react/jsx-runtime").JSX.Element>;
+}) => React.JSX.Element>;
 export default GoalNode;

package/dist/goals/layout.d.ts

@@ -1,7 +1,7 @@
 import type { Goal, GoalTree, LayoutOptions, GoalTreeLayout } from './types.js';
 import type { Scope } from '../scope.js';
 /**
- * Trims a flat goal list to a scope (vkgeorgia/strategy#77).
+ * Trims a flat goal list to a scope.
  *   - 'level' → goals with `level <= maxLevel`.
  *   - 'root'  → the root goal (matched by string id) plus all its descendants
  *               via `parent_id`; an empty list when the root is absent.

package/dist/goals/layout.js

@@ -4,7 +4,7 @@ const DEFAULT_NODE_HEIGHT = 80;
 const DEFAULT_RANK_SEP = 80;
 const DEFAULT_NODE_SEP = 40;
 /**
- * Trims a flat goal list to a scope (vkgeorgia/strategy#77).
+ * Trims a flat goal list to a scope.
  *   - 'level' → goals with `level <= maxLevel`.
  *   - 'root'  → the root goal (matched by string id) plus all its descendants
  *               via `parent_id`; an empty list when the root is absent.

package/dist/goals/parse-canonical.d.ts

@@ -15,7 +15,7 @@
  * mapped to internal sequential numbers, `parent: GOAL-X` becomes
  * `parent_id: <numeric>`, `parent_id: 0` denotes a root.
  *
- * Strategy hub #63: this lives at the input boundary so the library's
+ * This lives at the input boundary so the library's
  * internal types (numeric IDs) stay where they are. Convergence on
  * canonical typed-string IDs across all sister modules is a follow-up
  * task.

package/dist/goals/parse-canonical.js

@@ -15,7 +15,7 @@
  * mapped to internal sequential numbers, `parent: GOAL-X` becomes
  * `parent_id: <numeric>`, `parent_id: 0` denotes a root.
  *
- * Strategy hub #63: this lives at the input boundary so the library's
+ * This lives at the input boundary so the library's
  * internal types (numeric IDs) stay where they are. Convergence on
  * canonical typed-string IDs across all sister modules is a follow-up
  * task.

package/dist/goals/types.d.ts

@@ -44,7 +44,7 @@ export interface LayoutOptions {
     nodeSep?: number;
     hideCollapsed?: number[];
     viewDepth?: number | null;
-    /** Trim the tree to a level cap or a subtree root (vkgeorgia/strategy#77). Defaults to 'all'. */
+    /** Trim the tree to a level cap or a subtree root. Defaults to 'all'. */
     scope?: Scope;
 }
 export interface LaidOutNode {

package/dist/goals/validate.js

@@ -15,7 +15,7 @@ export function validateGoalTree(input) {
         return { valid: false, errors, warnings };
     const tree = raw;
     // GOALS-013 — goal_types[].level values must be contiguous starting from 0.
-    // Per the N+1 rule (decision in vkgeorgia/strategy#66), the level set must
+    // Per the N+1 rule, the level set must
     // be exactly {0, 1, …, N}; a gap breaks the parent→child level invariant
     // and means GOALS-012 cannot be enforced consistently.
     const levels = tree.goal_types
@@ -84,7 +84,7 @@ export function validateGoalTree(input) {
             continue;
         }
         // GOALS-012 — parent must be exactly one level above the child (N+1
-        // hierarchy, decision in vkgeorgia/strategy#66). Only enforced when the
+        // hierarchy). Only enforced when the
         // parent is resolvable; a missing parent is covered by BROKEN_PARENT_REF.
         if (g.parent_id !== 0) {
             const parentLevel = levelById.get(g.parent_id);

package/dist/link-suspicion.d.ts

@@ -0,0 +1,43 @@
+export declare const ENVELOPE_FIELDS: string[];
+/** Every non-blank, non-comment line of the file, except those belonging to
+ *  an `ENVELOPE_FIELDS` block (the key line and its more-indented
+ *  continuation lines), whitespace-normalised and sorted —
+ *  order-independent, formatting-independent, comment-independent. Not a
+ *  general YAML parser — a flat, line-oriented pass over the already-known
+ *  envelope field names, the same posture the methodology reference script
+ *  takes (its own header comment cites `baseline-manifest.mjs` /
+ *  `check-agreement.mjs` for precedent). */
+export declare function statementLines(text: string): string[];
+export interface LineEdit {
+    from: string;
+    to: string;
+}
+/** A parsed `migrations/<slug>/TRANSFORM.yaml` manifest (§16.3). */
+export interface MigrationManifest {
+    slug: string;
+    mechanical: boolean;
+    appliesTo: string[];
+    lineEdits: LineEdit[];
+}
+/** Minimal parse of the fixed `TRANSFORM.yaml` shape — `mechanical: true`,
+ *  `applies_to: [exact relative paths]`, `line_edits: [{from, to}]`. Not a
+ *  general YAML parser, same posture as {@link statementLines}. */
+export declare function parseMigrationManifest(text: string): Omit<MigrationManifest, 'slug'>;
+export interface SuspicionResult {
+    suspicious: boolean;
+    /** True when a manifest declared `mechanical: true` for this target but
+     *  its replay did not fully explain the change — the hatch does not
+     *  self-grant; suspicion stands regardless of the flag (§16.3). */
+    hatchRefused?: boolean;
+}
+/**
+ * §16.2: *Suspicious* ⟺ the target's content identity at the anchor commit
+ * differs from its content identity now, **and** §16.3's hatch does not
+ * explain the difference.
+ *
+ * `beforeText` / `afterText` are already-fetched (git IO lives in the
+ * caller); `undefined` for either (no anchor, or the target no longer
+ * exists) means nothing to compare — not suspicious, per the reference
+ * script's `target-absent-at-anchor` / `target-absent-now` cases.
+ */
+export declare function checkSuspicion(beforeText: string | undefined, afterText: string | undefined, applicableManifests?: Array<Omit<MigrationManifest, 'slug'>>): SuspicionResult;

package/dist/link-suspicion.js

@@ -0,0 +1,156 @@
+// Link suspicion — methodology CONTRACT.md §16, reference implementation
+// `scripts/check-link-suspicion.mjs`. Pure: content-identity normalisation
+// (§16.1) and the suspicion verdict (§16.2 / §16.3's mechanical hatch) over
+// already-fetched file text. Git plumbing (finding the anchor commit,
+// reading a file at a ref) and the repo walk are IO and live in the CLI
+// (`src/repo-validate.ts`), same split as the rest of this package.
+//
+// Nothing here is stored: a caller re-derives the verdict on every check;
+// no file ever carries a `suspicious: true` flag (§16.2).
+// The administrative envelope (§16.1) — field names CONTRACT.md already
+// defines by name (§6 / §6.1 / §6.2 / §6.3 when present / §7). One list,
+// defined once; a spec revision that adds an envelope field extends this
+// list in the same revision rather than inventing a second mechanism.
+export const ENVELOPE_FIELDS = [
+    'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'derived_from',
+    'admission_state', 'proposed_at', 'proposed_by', 'owner_to_confirm',
+    'rejected_at', 'rejected_by', 'rejection_reason',
+    'reviewer_authority',
+    'agreement', 'agreed_by', 'agreed_at',
+    'valid_from', 'valid_to',
+];
+function stripComment(line) {
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === '"')
+            inQuotes = !inQuotes;
+        else if (ch === '#' && !inQuotes)
+            return line.slice(0, i);
+    }
+    return line;
+}
+/** Every non-blank, non-comment line of the file, except those belonging to
+ *  an `ENVELOPE_FIELDS` block (the key line and its more-indented
+ *  continuation lines), whitespace-normalised and sorted —
+ *  order-independent, formatting-independent, comment-independent. Not a
+ *  general YAML parser — a flat, line-oriented pass over the already-known
+ *  envelope field names, the same posture the methodology reference script
+ *  takes (its own header comment cites `baseline-manifest.mjs` /
+ *  `check-agreement.mjs` for precedent). */
+export function statementLines(text) {
+    const kept = [];
+    let skipIndent = null;
+    for (const raw of text.split('\n')) {
+        const stripped = stripComment(raw).replace(/\s+$/, '');
+        if (!stripped.trim())
+            continue;
+        const indent = stripped.match(/^ */)?.[0].length ?? 0;
+        if (skipIndent !== null) {
+            if (indent > skipIndent)
+                continue;
+            skipIndent = null;
+        }
+        const keyMatch = stripped.match(/^(\s*)([A-Za-z_][A-Za-z0-9_]*):/);
+        if (keyMatch && keyMatch[1].length === 0 && ENVELOPE_FIELDS.includes(keyMatch[2])) {
+            skipIndent = indent;
+            continue;
+        }
+        kept.push(stripped.trim().replace(/\s+/g, ' '));
+    }
+    return kept.sort();
+}
+function sameLines(a, b) {
+    return a.length === b.length && a.every((line, i) => line === b[i]);
+}
+function unquote(s) {
+    const m = s.match(/^"(.*)"$/);
+    return m ? m[1] : s;
+}
+function normalizeEditLine(s) {
+    return unquote(s.trim()).trim().replace(/\s+/g, ' ');
+}
+/** Minimal parse of the fixed `TRANSFORM.yaml` shape — `mechanical: true`,
+ *  `applies_to: [exact relative paths]`, `line_edits: [{from, to}]`. Not a
+ *  general YAML parser, same posture as {@link statementLines}. */
+export function parseMigrationManifest(text) {
+    const manifest = { mechanical: false, appliesTo: [], lineEdits: [] };
+    let section = null;
+    let current = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line.trim() || line.trim().startsWith('#'))
+            continue;
+        const topMatch = line.match(/^(\w+):\s*(.*)$/);
+        if (topMatch) {
+            const [, key, val] = topMatch;
+            if (key === 'mechanical') {
+                manifest.mechanical = val.trim() === 'true';
+                section = null;
+            }
+            else if (key === 'applies_to') {
+                section = 'applies_to';
+            }
+            else if (key === 'line_edits') {
+                section = 'line_edits';
+            }
+            continue;
+        }
+        if (section === 'applies_to') {
+            const m = line.match(/^\s*-\s*(.+)$/);
+            if (m)
+                manifest.appliesTo.push(unquote(m[1].trim()));
+        }
+        else if (section === 'line_edits') {
+            const fromMatch = line.match(/^\s*-\s*from:\s*(.+)$/);
+            if (fromMatch) {
+                current = { from: normalizeEditLine(fromMatch[1]), to: '' };
+                manifest.lineEdits.push(current);
+                continue;
+            }
+            const toMatch = line.match(/^\s*to:\s*(.+)$/);
+            if (toMatch && current)
+                current.to = normalizeEditLine(toMatch[1]);
+        }
+    }
+    return manifest;
+}
+/** Replay a manifest's declared `lineEdits` against the before-state and
+ *  check the result matches the after-state exactly — the independent
+ *  verification §16.3 requires: the tool's `mechanical: true` declaration is
+ *  never trusted on its own; only a replay that reproduces the after-state
+ *  suppresses suspicion. */
+function replayExplains(beforeLines, afterLines, lineEdits) {
+    const working = [...beforeLines];
+    for (const edit of lineEdits) {
+        const idx = working.indexOf(edit.from);
+        if (idx === -1)
+            return false;
+        working.splice(idx, 1, edit.to);
+    }
+    return sameLines([...working].sort(), [...afterLines].sort());
+}
+/**
+ * §16.2: *Suspicious* ⟺ the target's content identity at the anchor commit
+ * differs from its content identity now, **and** §16.3's hatch does not
+ * explain the difference.
+ *
+ * `beforeText` / `afterText` are already-fetched (git IO lives in the
+ * caller); `undefined` for either (no anchor, or the target no longer
+ * exists) means nothing to compare — not suspicious, per the reference
+ * script's `target-absent-at-anchor` / `target-absent-now` cases.
+ */
+export function checkSuspicion(beforeText, afterText, applicableManifests = []) {
+    if (beforeText === undefined || afterText === undefined)
+        return { suspicious: false };
+    const beforeLines = statementLines(beforeText);
+    const afterLines = statementLines(afterText);
+    if (sameLines(beforeLines, afterLines))
+        return { suspicious: false };
+    for (const manifest of applicableManifests) {
+        if (replayExplains(beforeLines, afterLines, manifest.lineEdits)) {
+            return { suspicious: false };
+        }
+    }
+    return { suspicious: true, hatchRefused: applicableManifests.some((m) => m.mechanical) };
+}

package/dist/metric/index.d.ts

@@ -0,0 +1,4 @@
+export type { Metric, MetricDirectionOfGood } from './types.js';
+export { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+export { validateMetric } from './validate.js';
+export type { MetricValidateOptions } from './validate.js';

package/dist/metric/index.js

@@ -0,0 +1,2 @@
+export { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+export { validateMetric } from './validate.js';

package/dist/metric/types.d.ts

@@ -0,0 +1,24 @@
+import type { GateChecks } from '../requirement/types.js';
+/** How to read movement relative to `target` (§7.27). */
+export type MetricDirectionOfGood = 'higher_is_better' | 'lower_is_better' | 'on_target';
+export declare const METRIC_DIRECTIONS_OF_GOOD: readonly MetricDirectionOfGood[];
+export interface Metric {
+    notation: 'metric';
+    id: string;
+    name: string;
+    /** Typed IDs of what this metric tracks — GOAL, CAPABILITY, or PROCESS. Non-empty. */
+    measures: string[];
+    /** Free-form unit the value and `target` are expressed in (percent, days, …). */
+    unit: string;
+    target: number;
+    direction_of_good: MetricDirectionOfGood;
+    /** ROLE-… accountable for tracking this metric and acting on it. */
+    owner_role: string;
+    description?: string;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/metric/types.js

@@ -0,0 +1,7 @@
+// METRIC — motivation-layer managed indicator (no ArchiMate counterpart).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.27.
+export const METRIC_DIRECTIONS_OF_GOOD = [
+    'higher_is_better',
+    'lower_is_better',
+    'on_target',
+];

package/dist/metric/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface MetricValidateOptions {
+    /** When provided, METRIC-002/004 enforce artefact existence for cross-refs. */
+    catalog?: CanonCatalog;
+}
+export declare function validateMetric(input: unknown, options?: MetricValidateOptions): ValidationResult;

package/dist/metric/validate.js

@@ -0,0 +1,90 @@
+// METRIC validator — methodology ELEMENT_PRIMITIVES.md §7.27 / §9.
+//
+// Codes:
+//   METRIC-001 — shape / id grammar / required envelope + per-type fields
+//               (measures, unit, target, direction_of_good, owner_role).
+//   METRIC-002 — measures is empty, or an entry does not resolve to an
+//               admitted GOAL / CAPABILITY / PROCESS in canon.
+//   METRIC-003 — direction_of_good outside {higher_is_better, lower_is_better,
+//               on_target}.
+//   METRIC-004 — owner_role does not resolve to an admitted ROLE in canon.
+//
+// Resolution rules (METRIC-002/004) that need artefact *existence* run only
+// when a `CanonCatalog` is supplied; the TYPE checks are derivable from the
+// id prefix and run either way.
+import { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
+import { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+const MEASURES_TYPES = ['GOAL', 'CAPABILITY', 'PROCESS'];
+export function validateMetric(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        errors.push({ code: 'METRIC-001', message: 'Metric must be a YAML mapping.' });
+        return { valid: false, errors, warnings };
+    }
+    const m = input;
+    // METRIC-001 — id grammar + notation tag + envelope + plain per-type fields.
+    if (!isCanonicalIdOfType(m.id, 'METRIC')) {
+        errors.push({ code: 'METRIC-001', message: `id "${String(m.id)}" must match METRIC-[<middle>-]<INTEGER>.`, path: 'id' });
+    }
+    if (m.notation !== 'metric') {
+        errors.push({ code: 'METRIC-001', message: 'notation must be the fixed value "metric".', path: 'notation' });
+    }
+    if (m.zone !== 'canon') {
+        errors.push({ code: 'METRIC-001', message: 'zone is required and must be "canon".', path: 'zone' });
+    }
+    for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from', 'unit', 'owner_role']) {
+        if (typeof m[f] !== 'string' || m[f].trim() === '') {
+            errors.push({ code: 'METRIC-001', message: `${f} is required.`, path: f });
+        }
+    }
+    if (m.gate_checks === null || typeof m.gate_checks !== 'object') {
+        errors.push({ code: 'METRIC-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+    }
+    if (!('valid_to' in m) || !(typeof m.valid_to === 'string' || m.valid_to === null)) {
+        errors.push({ code: 'METRIC-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+    }
+    if (typeof m.target !== 'number' || Number.isNaN(m.target)) {
+        errors.push({ code: 'METRIC-001', message: 'target is required and must be a number.', path: 'target' });
+    }
+    // direction_of_good — required (METRIC-001) + enum (METRIC-003).
+    const dir = m.direction_of_good;
+    if (dir === undefined || dir === null || dir === '') {
+        errors.push({ code: 'METRIC-001', message: 'direction_of_good is required.', path: 'direction_of_good' });
+    }
+    else if (!METRIC_DIRECTIONS_OF_GOOD.includes(dir)) {
+        errors.push({
+            code: 'METRIC-003',
+            message: `direction_of_good "${String(dir)}" must be one of ${METRIC_DIRECTIONS_OF_GOOD.join(', ')}.`,
+            path: 'direction_of_good',
+        });
+    }
+    // measures — required non-empty list (METRIC-001), each resolves to GOAL/CAPABILITY/PROCESS (METRIC-002).
+    const measures = m.measures;
+    if (!Array.isArray(measures) || measures.length === 0) {
+        errors.push({ code: 'METRIC-001', message: 'measures is required and must be a non-empty list of typed IDs.', path: 'measures' });
+    }
+    else {
+        measures.forEach((ref, i) => {
+            const type = typeOfId(ref);
+            if (!type || !MEASURES_TYPES.includes(type)) {
+                errors.push({ code: 'METRIC-002', message: `measures[${i}] "${String(ref)}" must resolve to a GOAL, CAPABILITY, or PROCESS.`, path: `measures[${i}]` });
+                return;
+            }
+            if (options.catalog && options.catalog.typeOf(ref) === undefined) {
+                errors.push({ code: 'METRIC-002', message: `measures[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `measures[${i}]` });
+            }
+        });
+    }
+    // owner_role — must be a typed ROLE id (METRIC-004), and resolve when a catalog is supplied.
+    const ownerRole = m.owner_role;
+    if (typeof ownerRole === 'string' && ownerRole.trim() !== '') {
+        if (!isCanonicalIdOfType(ownerRole, 'ROLE')) {
+            errors.push({ code: 'METRIC-004', message: `owner_role "${ownerRole}" must be a typed ROLE id.`, path: 'owner_role' });
+        }
+        else if (options.catalog && options.catalog.typeOf(ownerRole) === undefined) {
+            errors.push({ code: 'METRIC-004', message: `owner_role "${ownerRole}" does not resolve to an admitted artefact.`, path: 'owner_role' });
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/need/index.d.ts

@@ -0,0 +1,3 @@
+export type { Need } from './types.js';
+export { validateNeed } from './validate.js';
+export type { NeedValidateOptions } from './validate.js';

package/dist/need/index.js

@@ -0,0 +1 @@
+export { validateNeed } from './validate.js';

package/dist/need/types.d.ts

@@ -0,0 +1,21 @@
+import type { GateChecks } from '../requirement/types.js';
+import type { AgreementValue } from '../agreement.js';
+export interface Need {
+    notation: 'need';
+    id: string;
+    name: string;
+    /** Typed ID of the STAKEHOLDER whose need this is. */
+    stakeholder: string;
+    description?: string;
+    /** `draft` \| `agreed` \| `disputed`. Absent ⇒ `agreed` (back-compat). */
+    agreement?: AgreementValue;
+    /** Required whenever `agreement` is present (AGREE-003). Written only by a human when `agreement: agreed` (AGREE-002). */
+    agreed_by?: string;
+    agreed_at?: string;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/need/types.js

@@ -0,0 +1,3 @@
+// NEED — motivation-layer stakeholder/user need (no ArchiMate counterpart).
+// Upstream of REQUIREMENT — schema: methodology notations/ELEMENT_PRIMITIVES.md §7.28.
+export {};

package/dist/need/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface NeedValidateOptions {
+    /** When provided, NEED-002 enforces artefact existence for `stakeholder`. */
+    catalog?: CanonCatalog;
+}
+export declare function validateNeed(input: unknown, options?: NeedValidateOptions): ValidationResult;

package/dist/need/validate.js

@@ -0,0 +1,60 @@
+// NEED validator — methodology ELEMENT_PRIMITIVES.md §7.28 / §9.
+//
+// Codes:
+//   NEED-001 — shape / id grammar / required envelope fields, including the
+//              required per-type `stakeholder` field.
+//   NEED-002 — stakeholder does not resolve to an admitted STAKEHOLDER in canon.
+//
+// The cross-cutting NEED-COVERAGE-001 / NEED-VALIDATION-COVERAGE-001..002
+// reverse-trace rules are owned elsewhere (CONTRACT.md §8, the compliance
+// reverse-index) and are out of scope for this single-artefact validator —
+// same posture as `validateRequirement` / `validateVerification`.
+//
+// Resolution (NEED-002 existence) runs only when a `CanonCatalog` is
+// supplied; the TYPE check is derivable from the id prefix and runs either way.
+import { isCanonicalIdOfType } from '../typed-id.js';
+import { checkAgreement } from '../agreement.js';
+export function validateNeed(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        errors.push({ code: 'NEED-001', message: 'Need must be a YAML mapping.' });
+        return { valid: false, errors, warnings };
+    }
+    const n = input;
+    // NEED-001 — id grammar + notation tag + envelope.
+    if (!isCanonicalIdOfType(n.id, 'NEED')) {
+        errors.push({ code: 'NEED-001', message: `id "${String(n.id)}" must match NEED-[<middle>-]<INTEGER>.`, path: 'id' });
+    }
+    if (n.notation !== 'need') {
+        errors.push({ code: 'NEED-001', message: 'notation must be the fixed value "need".', path: 'notation' });
+    }
+    if (n.zone !== 'canon') {
+        errors.push({ code: 'NEED-001', message: 'zone is required and must be "canon".', path: 'zone' });
+    }
+    for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from']) {
+        if (typeof n[f] !== 'string' || n[f].trim() === '') {
+            errors.push({ code: 'NEED-001', message: `${f} is required.`, path: f });
+        }
+    }
+    if (n.gate_checks === null || typeof n.gate_checks !== 'object') {
+        errors.push({ code: 'NEED-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+    }
+    if (!('valid_to' in n) || !(typeof n.valid_to === 'string' || n.valid_to === null)) {
+        errors.push({ code: 'NEED-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+    }
+    // stakeholder — required (NEED-001) + resolves to STAKEHOLDER (NEED-002).
+    const stakeholder = n.stakeholder;
+    if (typeof stakeholder !== 'string' || stakeholder.trim() === '') {
+        errors.push({ code: 'NEED-001', message: 'stakeholder is required.', path: 'stakeholder' });
+    }
+    else if (!isCanonicalIdOfType(stakeholder, 'STAKEHOLDER')) {
+        errors.push({ code: 'NEED-002', message: `stakeholder "${stakeholder}" must be a typed STAKEHOLDER id.`, path: 'stakeholder' });
+    }
+    else if (options.catalog && options.catalog.typeOf(stakeholder) === undefined) {
+        errors.push({ code: 'NEED-002', message: `stakeholder "${stakeholder}" does not resolve to an admitted artefact.`, path: 'stakeholder' });
+    }
+    // AGREE-001..003 — agreement axis (CONTRACT.md §6.3.1), optional; absent ⇒ agreed.
+    errors.push(...checkAgreement(n));
+    return { valid: errors.length === 0, errors, warnings };
+}

package/dist/repo-validate/check-candidate-fields.d.ts

@@ -0,0 +1,6 @@
+import type { RepoFinding, RepoModelInput } from './types.js';
+/**
+ * `ADMIT-009` — a candidate-only field present on an admitted (`zone: canon`)
+ * element, of any TYPE. Appends findings; pure, deterministic order.
+ */
+export declare function checkCandidateFields(input: RepoModelInput, findings: RepoFinding[]): void;

package/dist/repo-validate/check-candidate-fields.js

@@ -0,0 +1,87 @@
+// 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';
+const PScope = '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 = [
+    {
+        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) {
+    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, findings) {
+    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}.`,
+            });
+        }
+    }
+}

package/dist/repo-validate/check-versioned-attributes.d.ts

@@ -0,0 +1,4 @@
+import type { RepoFinding, RepoModelInput } from './types.js';
+/** Run the versioned-attribute sidecar checks (VERSIONED-001..005) over the
+ *  loaded element set and append findings. Pure, deterministic order. */
+export declare function checkVersionedAttributes(input: RepoModelInput, findings: RepoFinding[]): void;