@sensigo/realm 0.40.0 → 0.42.0

package/dist/workflow/yaml-loader.js

@@ -4,7 +4,7 @@ import { dirname, resolve, join, isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
 import { load } from 'js-yaml';
 import { Ajv } from 'ajv';
-import { KNOWN_STEP_KEYS, KNOWN_WORKFLOW_KEYS, KNOWN_RETRY_KEYS, KNOWN_GATE_KEYS, } from '../types/workflow-definition.js';
+import { KNOWN_STEP_KEYS, KNOWN_WORKFLOW_KEYS, KNOWN_RETRY_KEYS, KNOWN_GATE_KEYS, SERVICE_TRUST_LEVELS, isGateTrust, classifyStepTrust, buildTrustRefusal, renderTrustValue, } from '../types/workflow-definition.js';
 import { WorkflowError } from '../types/workflow-error.js';
 import { findUnknownKeys, renderLoaderWarning, resolveSeverity, closestKey, } from './diagnostics.js';
 import { createSourcePositionCollector } from './source-positions.js';
@@ -14,12 +14,39 @@ import { splitComparison, isPathShaped } from '../engine/comparison-expr.js';
 import { DEFAULT_EXECUTION_TIMEOUT_SECONDS } from '../engine/claim-liveness.js';
 import { validateOutputSchema } from '../validation/input-schema.js';
 import { assessStructuredOutputEligibility, renderIneligibleMessage, } from './structured-output-eligibility.js';
+import { STEP_KEY_REGISTRY, CONSUMED_HOME, prohibitedKeysFor, consumedKindsFor, homeText, } from './step-key-registry.js';
+/** #517 (the drive-flip): render ONE minted kind-prohibition from registry data. message_data
+ *  cells render their recorded bespoke text verbatim (byte-identical to the pre-flip checks —
+ *  golden-proven at the flip). Generic cells render the per-cell FRONT clause (the two-shape
+ *  truth: 'not_valid' keeps the old loop grammar against THIS kind; 'only_valid' keeps the old
+ *  twin grammar against the DERIVED consumed-kind set) and append the rung-2 consequence clause
+ *  from CONSUMED_HOME — witness-backed message truth (its claims are conformance-tested data). */
+function renderRegistryProhibition(key, kind, cell) {
+    if (cell.message_data !== undefined)
+        return cell.message_data;
+    const home = CONSUMED_HOME[key];
+    /* istanbul ignore next -- conformance guarantees totality over generic minted keys */
+    if (home === undefined)
+        return `'${key}' is not valid on execution: ${kind} steps`;
+    const front = cell.front === 'only_valid'
+        ? `'${key}' is only valid on execution: ${consumedKindsFor(key).join('/')} steps`
+        : `'${key}' is not valid on execution: ${kind} steps`;
+    return `${front} — ${homeText(home.mechanism, kind)} ${homeText(home.remedy, kind)}`;
+}
 /**
  * Validate one condition leaf at load time using the shared quote-aware splitter (the SAME split
  * used at runtime). Rejects compound `and`/`or`, multiple operators, and non-path LHS. For `when`,
  * also enforces the direct-`depends_on` reference check (Change 2). Pushes actionable errors.
  */
-function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors, 
+function validateConditionLeaf(surface, leaf, stepName, dependsOn, 
+/**
+ * The step's declared `execution` kind (undefined when missing/malformed — those steps are
+ * already refused by the invalid-execution error, and the remedy below keeps its generic
+ * form). Threaded through so `validateWhenReference` can fork its remedy tail on the
+ * registry's own `depends_on` cell — a kind where `depends_on` is prohibited must never be
+ * told to add one (the wrong-remedy composition class this correction fixes).
+ */
+kind, errors, 
 /**
  * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
  * the compiler names every call site if this ever gains another one — an omitted resolver
@@ -68,7 +95,7 @@ withLine) {
             return;
         }
         if (surface === 'when')
-            validateWhenReference(split.path, stepName, dependsOn, errors, withLine);
+            validateWhenReference(split.path, stepName, dependsOn, kind, errors, withLine);
         return;
     }
     // comparison
@@ -81,7 +108,7 @@ withLine) {
         return;
     }
     if (surface === 'when')
-        validateWhenReference(split.lhsPath, stepName, dependsOn, errors, withLine);
+        validateWhenReference(split.lhsPath, stepName, dependsOn, kind, errors, withLine);
 }
 /**
  * issue #220 §4c (PR-3): validates a `$settlement.<dep>.<field>` reference reached from ANY of
@@ -133,7 +160,9 @@ withLine) {
  * step in this step's DIRECT `depends_on` (one-hop membership — no graph traversal). Field names are
  * not checked (agent-step outputs aren't statically declared).
  */
-function validateWhenReference(path, stepName, dependsOn, errors, 
+function validateWhenReference(path, stepName, dependsOn, 
+/** @see validateConditionLeaf — forks the remedy tail on the registry's `depends_on` cell. */
+kind, errors, 
 /**
  * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
  * the compiler names every call site if this ever gains another one — an omitted resolver
@@ -149,7 +178,16 @@ withLine) {
         return;
     }
     if (!dependsOn.includes(first)) {
-        errors.push(withLine(stepName, `Step '${stepName}': 'when' references step '${first}' which is not in its depends_on [${dependsOn.join(', ')}]. Add it to depends_on or use 'run.params.*'.`));
+        // The remedy's first arm is forked on the registry's own depends_on cell: on a kind where
+        // depends_on is prohibited (today exactly finalizer), 'Add it to depends_on' is a dead
+        // pointer — following it mints a second refusal (probe-executed; the wrong-remedy
+        // composition class this correction fixes). Derived from the cell so the fork can never
+        // drift from the mint.
+        const dependsOnLegal = kind === undefined || STEP_KEY_REGISTRY.depends_on[kind].c === 'consumed';
+        const remedyTail = dependsOnLegal
+            ? `Add it to depends_on or use 'run.params.*'.`
+            : `Use 'run.params.*' — 'depends_on' is not valid on this step's kind.`;
+        errors.push(withLine(stepName, `Step '${stepName}': 'when' references step '${first}' which is not in its depends_on [${dependsOn.join(', ')}]. ${remedyTail}`));
     }
 }
 /** Bumped on every breaking change to WorkflowDefinition's serialized format. */
@@ -166,11 +204,20 @@ const SERVICE_ENTRY_JSON_SCHEMA = {
     required: ['adapter'],
     properties: {
         adapter: { type: 'string', minLength: 1 },
-        trust: { enum: ['engine_delivered', 'engine_managed', 'agent_provided'] },
+        trust: { enum: [...SERVICE_TRUST_LEVELS] },
         rate_limit: { type: 'object' },
     },
 };
 const VALID_EXECUTIONS = new Set(['auto', 'agent', 'guard', 'finalizer']);
+// issue #517 (the drive-flip): the two kind-prohibition sets are DERIVED from the consumption
+// registry — every key whose cell on the kind is prohibited WITHOUT an except arm. Their meaning
+// upgraded with #517 from "the loop's array" to "the prohibited set": they now also carry the
+// keys whose refusals used to live in per-key only-valid-on checks (guard 12→20 members,
+// finalizer 13→19), and their declared type widened from a literal tuple to a computed readonly
+// array — both disclosed in the changelog. The prohibition loops that consumed the old literal
+// arrays are deleted; the registry-driven mint below is the single enforcement mechanism.
+export const FINALIZER_PROHIBITED_STEP_KEYS = prohibitedKeysFor('finalizer');
+export const GUARD_PROHIBITED_STEP_KEYS = prohibitedKeysFor('guard');
 const VALID_FINALIZER_TRIGGERS = new Set([
     'complete',
     'fail',
@@ -248,33 +295,41 @@ export function findTrustRoot(dir) {
     }
 }
 /**
- * Pure core of loadWorkflowFromFile (issue #169): parses + resolves everything a file-based load
- * needs, but never prints and never chooses between the two public presentations — it always
- * returns the definition alongside every collected LoaderWarning. `loadWorkflowFromFile` (prints
- * via renderLoaderWarning, returns just the definition — byte-identical default behavior, the
- * non-breaking invariant) and `loadWorkflowFromFileWithDiagnostics` (prints nothing, returns both)
- * are both thin wrappers over this.
- * @throws WorkflowError on read failure or structural validation errors.
+ * issue #424 — attaches the live loader warnings to an error on its way out.
+ *
+ * Two chokepoints call this (one in `parseWorkflowString`, one in `loadWorkflowFromFileCore`),
+ * which is why it exists rather than each throw site building its own error with a `warnings`
+ * option: there are eleven throw sites across this file plus four more in template-resolver.ts,
+ * the warnings array is out of scope at most of them, and a chokepoint covers every future one
+ * for free. The non-empty guard makes the classification automatic — a throw that happens before
+ * any warning could exist attaches nothing, by construction rather than by a rule someone has to
+ * remember.
+ *
+ * Attach-once: an inner chokepoint's attachment survives the outer one re-catching the same
+ * error, so a file-based load reports the warnings from the parse that produced it rather than
+ * an emptier outer set.
  */
-function loadWorkflowFromFileCore(filePath, registry) {
-    let content;
-    try {
-        content = readFileSync(filePath, 'utf8');
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new WorkflowError(`Failed to read workflow file: ${message}`, {
-            code: 'RESOURCE_FETCH_FAILED',
-            category: 'RESOURCE',
-            agentAction: 'report_to_user',
-            retryable: false,
-        });
-    }
-    const { definition, warnings } = parseWorkflowString(content, registry, {
-        allowExtensions: true,
-    });
-    // Resolve agent profiles — only possible when we have a file path.
-    const workflowDir = dirname(resolve(filePath));
+export function attachLoaderWarnings(err, warnings) {
+    if (warnings.length === 0)
+        return;
+    if (err.warnings !== undefined)
+        return;
+    err.warnings = warnings;
+}
+/**
+ * Resolves every `agent_profile` a definition declares against `<workflowDir>/<profiles_dir>`
+ * (default `profiles/`), stamping `resolved_profiles` on the definition and refusing — one
+ * `Invalid workflow:` error, one entry per missing profile (issue #425) — when any is absent.
+ *
+ * Exported (issue #553) because this is the ONE check a workflow's text cannot answer: it needs
+ * the source tree. `loadWorkflowFromFileCore` calls it with the file's directory; `validate
+ * --registered` calls it with the `source_dir` the registrar recorded, so the stored copy is
+ * audited by the same rule instead of by a synthesized file path (#493's snapshot doctrine: a
+ * synthesized path would audit the FILE, not the stored copy). Semantics are those of the
+ * former inline loop, byte for byte — the `Searched: <path>` sentence included.
+ * @throws WorkflowError (`VALIDATION_WORKFLOW_SCHEMA`) naming every missing profile.
+ */
+export function resolveAgentProfiles(definition, workflowDir) {
     const profilesDir = definition.profiles_dir !== undefined
         ? resolve(workflowDir, definition.profiles_dir)
         : join(workflowDir, 'profiles');
@@ -300,6 +355,9 @@ function loadWorkflowFromFileCore(filePath, registry) {
     }
     if (profileErrors.length > 0) {
         throw new WorkflowError(`Invalid workflow: ${profileErrors.join('; ')}`, {
+            // issue #425: the pre-join strings, so a render can list them one per line. Two missing
+            // profiles are two problems, not one long sentence.
+            errors: [...profileErrors],
             code: 'VALIDATION_WORKFLOW_SCHEMA',
             category: 'VALIDATION',
             agentAction: 'report_to_user',
@@ -309,71 +367,89 @@ function loadWorkflowFromFileCore(filePath, registry) {
     if (Object.keys(resolvedProfiles).length > 0) {
         definition.resolved_profiles = resolvedProfiles;
     }
-    // Validate context_wrapper if present.
-    if (definition.context_wrapper !== undefined) {
-        const VALID_WRAPPER_FORMATS = new Set(['xml', 'brackets', 'none']);
-        if (!VALID_WRAPPER_FORMATS.has(definition.context_wrapper)) {
-            throw new WorkflowError(`Invalid context_wrapper '${String(definition.context_wrapper)}'; must be 'xml', 'brackets', or 'none'`, {
-                code: 'VALIDATION_WORKFLOW_SCHEMA',
-                category: 'VALIDATION',
-                agentAction: 'report_to_user',
-                retryable: false,
-            });
-        }
+}
+/**
+ * Pure core of loadWorkflowFromFile (issue #169): parses + resolves everything a file-based load
+ * needs, but never prints and never chooses between the two public presentations — it always
+ * returns the definition alongside every collected LoaderWarning. `loadWorkflowFromFile` (prints
+ * via renderLoaderWarning, returns just the definition) and `loadWorkflowFromFileWithDiagnostics`
+ * (prints nothing, returns both) are both thin wrappers over this.
+ *
+ * The #169-era "byte-identical default behavior" claim was retired in issue #444 (2026-08-31):
+ * renderLoaderWarning now prefixes `⚠ ` for every code, so this printer's advisory lines gained
+ * the prefix they lacked. The SHAPE of the contract is unchanged — one printing wrapper, one
+ * silent one — and the text after the prefix is untouched.
+ * @throws WorkflowError on read failure or structural validation errors.
+ */
+function loadWorkflowFromFileCore(filePath, registry) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf8');
     }
-    // Validate and resolve workflow_context entry paths.
-    if (definition.workflow_context !== undefined) {
-        for (const [name, entry] of Object.entries(definition.workflow_context)) {
-            if (name.endsWith('.raw')) {
-                throw new WorkflowError(`workflow_context entry names must not end with '.raw' (found: '${name}')`, {
-                    code: 'VALIDATION_WORKFLOW_SCHEMA',
-                    category: 'VALIDATION',
-                    agentAction: 'report_to_user',
-                    retryable: false,
-                });
-            }
-            if (!/^[\w.]+$/.test(name)) {
-                throw new WorkflowError(`workflow_context entry name '${name}' is invalid; names must match [\\w.]+ (underscores and dots only — no hyphens)`, {
-                    code: 'VALIDATION_WORKFLOW_SCHEMA',
-                    category: 'VALIDATION',
-                    agentAction: 'report_to_user',
-                    retryable: false,
-                });
-            }
-            const rawEntry = entry;
-            const rawSource = rawEntry['source'];
-            if (rawSource === undefined || typeof rawSource['path'] !== 'string') {
-                throw new WorkflowError(`workflow_context.${name}.source.path is required`, {
-                    code: 'VALIDATION_WORKFLOW_SCHEMA',
-                    category: 'VALIDATION',
-                    agentAction: 'report_to_user',
-                    retryable: false,
-                });
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new WorkflowError(`Failed to read workflow file: ${message}`, {
+            code: 'RESOURCE_FETCH_FAILED',
+            category: 'RESOURCE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        });
+    }
+    const { definition, warnings } = parseWorkflowString(content, registry, {
+        allowExtensions: true,
+    });
+    // issue #424 — CHOKEPOINT 2. Everything past the parse can throw with `warnings` already
+    // populated (a missing agent_profile, a bad workflow_context source), and those warnings used
+    // to unwind with the stack: `register` on a file with a typo AND a missing profile printed the
+    // profile error alone, so the author fixed it, re-ran, and only then learned about the typo.
+    // The parse call itself is deliberately OUTSIDE this try — chokepoint 1 inside
+    // `parseWorkflowString` owns those throws and has already attached, and attach-once means its
+    // richer set survives.
+    try {
+        // Resolve agent profiles — only possible when we have a source tree. Every check in this
+        // file-only block is DELEGATED to a named exported resolver (issue #553): `validate
+        // --registered` supplies the recorded source tree to the same function, so the stored copy
+        // is audited by the rule register applied, not by a paraphrase. An inline `throw` here is
+        // exactly what admission-context.test.ts (cli) refuses.
+        const workflowDir = dirname(resolve(filePath));
+        resolveAgentProfiles(definition, workflowDir);
+        // Resolve workflow_context entry paths. The four context-free rules (context_wrapper enum,
+        // `.raw` names, the name charset, `source.path` required) live in `parseWorkflowString`
+        // Step 3c since issue #553 — every surface, file or string, refuses them identically. Only
+        // the TRANSFORM needs `workflowDir`, so only the transform is here.
+        if (definition.workflow_context !== undefined) {
+            for (const entry of Object.values(definition.workflow_context)) {
+                entry.source.path = resolve(workflowDir, entry.source.path);
             }
-            // Resolve relative path to absolute.
-            entry.source.path = resolve(workflowDir, rawSource['path']);
         }
+        // Auto-register schema.json if present and not explicitly declared.
+        const schemaPath = join(workflowDir, 'schema.json');
+        if (existsSync(schemaPath) && definition.workflow_context?.['schema'] === undefined) {
+            definition.workflow_context ??= {};
+            definition.workflow_context['schema'] = {
+                source: { path: schemaPath },
+                description: 'Auto-registered schema.json from workflow directory',
+            };
+        }
+        // Resolution metadata: stamped for EVERY file-loaded definition (v0.14) — trust_root is
+        // the deployment-manifest anchor (`<trust_root>/realm.yaml`), needed by extension-free
+        // workflows that consume manifest-constructed adapters by name. Core resolves/stores
+        // PATHS only — it never imports modules or reads the manifest; that is the CLI's job.
+        // `validate --registered` reads these two back to supply the source tree the stored copy's
+        // context-dependent checks need (issue #553).
+        definition.source_dir = workflowDir;
+        definition.trust_root = findTrustRoot(workflowDir);
+        if (definition.extensions !== undefined) {
+            definition.extensions =
+                typeof definition.extensions === 'string' ? [definition.extensions] : definition.extensions;
+        }
+        definition.origin = 'human';
     }
-    // Auto-register schema.json if present and not explicitly declared.
-    const schemaPath = join(workflowDir, 'schema.json');
-    if (existsSync(schemaPath) && definition.workflow_context?.['schema'] === undefined) {
-        definition.workflow_context ??= {};
-        definition.workflow_context['schema'] = {
-            source: { path: schemaPath },
-            description: 'Auto-registered schema.json from workflow directory',
-        };
-    }
-    // Resolution metadata: stamped for EVERY file-loaded definition (v0.14) — trust_root is
-    // the deployment-manifest anchor (`<trust_root>/realm.yaml`), needed by extension-free
-    // workflows that consume manifest-constructed adapters by name. Core resolves/stores
-    // PATHS only — it never imports modules or reads the manifest; that is the CLI's job.
-    definition.source_dir = workflowDir;
-    definition.trust_root = findTrustRoot(workflowDir);
-    if (definition.extensions !== undefined) {
-        definition.extensions =
-            typeof definition.extensions === 'string' ? [definition.extensions] : definition.extensions;
+    catch (err) {
+        if (err instanceof WorkflowError)
+            attachLoaderWarnings(err, warnings);
+        throw err;
     }
-    definition.origin = 'human';
     return { definition, warnings };
 }
 /**
@@ -519,1282 +595,1449 @@ function parseWorkflowString(content, registry, opts) {
     }
     const errors = [];
     const warnings = [];
-    // Finalised after the parse succeeded; resolves a semantic path to its place in the source.
-    const sourceMap = positions.finish();
-    /**
-     * Appends ` (line N)` when the step's own key can be placed, and nothing when it cannot
-     * (issue #392). Used at PUSH time, never at join time — once messages are joined into one
-     * string the step each came from is no longer recoverable.
-     */
-    const withStepLine = (stepName, message) => {
-        const line = sourceMap.posOf(['steps', stepName])?.line;
-        return line === undefined ? message : `${message} (line ${line})`;
-    };
-    /**
-     * Like `withStepLine`, but names the OFFENDING KEY's own line (issue #417).
-     *
-     * For a key-scoped refusal the step's line is the wrong place to send someone: a long step has
-     * the key twenty lines below its own name, and the author reading `(line 40)` looks at the
-     * declaration rather than at the field being refused. The position map records every pairable
-     * mapping key, so the key's own line is available wherever the step's is.
-     *
-     * Falls back to the step's line, and then to no position at all — and the two real shapes land
-     * on DIFFERENT rungs, which is why both are pinned. A step body assembled through a merge key
-     * (`<<: *anchor`) leaves the KEY unpairable while the step's own name is still placeable, so it
-     * falls back to the step's line. A `use_template` step, whose keys are synthesized, exists at no
-     * line in the file at all and carries no position. Neither guesses — a wrong line number sends
-     * an author confidently to the wrong place, which is worse than sending them nowhere.
-     */
-    const withKeyLine = (stepName, key, message) => {
-        const line = sourceMap.posOf(['steps', stepName, key])?.line ?? sourceMap.posOf(['steps', stepName])?.line;
-        return line === undefined ? message : `${message} (line ${line})`;
-    };
-    // Step 2: Top-level validation
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        throw new WorkflowError('Invalid workflow: Workflow must be a non-null object', {
-            code: 'VALIDATION_WORKFLOW_SCHEMA',
-            category: 'VALIDATION',
-            agentAction: 'report_to_user',
-            retryable: false,
-        });
-    }
-    const doc = raw;
-    // WARN (do not reject) on a key that isn't authorable — checked against KNOWN_WORKFLOW_KEYS
-    // ONLY (not RUNTIME_ONLY_WORKFLOW_KEYS), and BEFORE any loader-stamped field is added below.
-    // Deliberately excluding runtime-only keys from "known" here means hand-authoring one (e.g.
-    // `schema_version:` or `model:` in YAML) warns too — those fields are stamped by the loader
-    // and any authored value is silently overwritten/ignored, which is exactly the kind of mistake
-    // this check exists to surface (issue #144). Non-breaking by design: siblings #170
-    // (hard-reject) and #169 (structured warnings channel) are deliberately out of scope here.
-    {
-        const workflowId = typeof doc['id'] === 'string' ? doc['id'] : '<unknown>';
-        warnings.push(...findUnknownKeys(doc, KNOWN_WORKFLOW_KEYS, {
-            scope: 'workflow',
-            code: 'UNKNOWN_WORKFLOW_KEY',
-            id: workflowId,
-            positionOf: (key) => sourceMap.posOf([key]),
-        }));
-    }
-    // Project extensions: hard error for string-based loading (fires before any other
-    // processing); shape validation (string | string[], relative-only) for file-based loading.
-    if ('extensions' in doc && doc['extensions'] !== undefined) {
-        if (!opts.allowExtensions) {
-            throw new WorkflowError(`Invalid workflow: 'extensions' requires file-based loading — no directory context is ` +
-                `available to resolve extension module paths. Register this workflow from its YAML ` +
-                `file (realm workflow register <path>).`, {
+    // issue #424 — CHOKEPOINT 1. Every throw from here down unwinds past a populated `warnings`
+    // array, and used to drop it: a workflow with a prohibited key AND a `dependson` typo reported
+    // the prohibition alone. This also covers the template-resolver's own throws, which cross this
+    // frame and are unreachable from any sweep of this file.
+    try {
+        // Finalised after the parse succeeded; resolves a semantic path to its place in the source.
+        const sourceMap = positions.finish();
+        /**
+         * Appends ` (step at line N)` when the step's own key can be placed, and nothing when it cannot
+         * (issue #392). Used at PUSH time, never at join time — once messages are joined into one
+         * string the step each came from is no longer recoverable.
+         *
+         * The suffix names the STEP because that is the only position this helper ever has, and saying
+         * so is the point (issue #420). Across the loader the two forms are univocal:
+         *
+         *   `(line N)`         — the OFFENDING KEY's own line. Minted by `withKeyLine`'s first rung
+         *                        below, and by the unknown-key warnings (`renderUnknownKeyMessage`),
+         *                        which is key-exact-or-absent by construction: every `findUnknownKeys`
+         *                        call site passes a `positionOf` that resolves the offending key's own
+         *                        path, with no step fallback anywhere.
+         *   `(step at line N)` — the STEP's line. This helper, and `withKeyLine`'s fallback rung.
+         *
+         * Before that split both rungs rendered `(line N)`, so an author could not tell a cite that
+         * pointed AT the refused field from one that pointed at the declaration above it. The
+         * structured channel (`line`/`column`/`endLine`/`endColumn`) is unaffected — it always carried
+         * the distinction; only the prose was ambiguous.
+         */
+        const withStepLine = (stepName, message) => {
+            const line = sourceMap.posOf(['steps', stepName])?.line;
+            return line === undefined ? message : `${message} (step at line ${line})`;
+        };
+        /**
+         * Like `withStepLine`, but names the OFFENDING KEY's own line (issue #417).
+         *
+         * For a key-scoped refusal the step's line is the wrong place to send someone: a long step has
+         * the key twenty lines below its own name, and the author reading `(line 40)` looks at the
+         * declaration rather than at the field being refused. The position map records every pairable
+         * mapping key, so the key's own line is available wherever the step's is.
+         *
+         * Falls back to the step's line, and then to no position at all — and the two real shapes land
+         * on DIFFERENT rungs, which is why both are pinned. A step body assembled through a merge key
+         * (`<<: *anchor`) leaves the KEY unpairable while the step's own name is still placeable, so it
+         * falls back to the step's line. A `use_template` step, whose keys are synthesized, exists at no
+         * line in the file at all and carries no position. Neither guesses — a wrong line number sends
+         * an author confidently to the wrong place, which is worse than sending them nowhere.
+         *
+         * The two rungs render DIFFERENTLY (issue #420): rung 1 is ` (line N)`, the key's own line;
+         * rung 2 is ` (step at line N)`, the step's — the same vocabulary `withStepLine` above
+         * documents in full. They were previously indistinguishable, which made the fallback silently
+         * claim to be a key-exact cite. The two lookups are separate rather than one `??` chain for
+         * exactly that reason: a single chain cannot report WHICH rung answered.
+         */
+        const withKeyLine = (stepName, key, message) => {
+            const keyLine = sourceMap.posOf(['steps', stepName, key])?.line;
+            if (keyLine !== undefined)
+                return `${message} (line ${keyLine})`;
+            const stepLine = sourceMap.posOf(['steps', stepName])?.line;
+            if (stepLine !== undefined)
+                return `${message} (step at line ${stepLine})`;
+            return message;
+        };
+        /**
+         * The TOP-LEVEL sibling of `withStepLine`/`withKeyLine` (issue #553): names the line of a
+         * workflow-level key such as `context_wrapper` or `workflow_context.<name>`. No step
+         * fallback — there is no step — and no position at all when the key cannot be placed:
+         * absent-never-wrong, the loader's standing cite doctrine.
+         */
+        const withTopLevelLine = (path, message) => {
+            const line = sourceMap.posOf(path)?.line;
+            return line !== undefined ? `${message} (line ${line})` : message;
+        };
+        // Step 2: Top-level validation
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            throw new WorkflowError('Invalid workflow: Workflow must be a non-null object', {
                 code: 'VALIDATION_WORKFLOW_SCHEMA',
                 category: 'VALIDATION',
                 agentAction: 'report_to_user',
                 retryable: false,
             });
         }
-        errors.push(...validateExtensionsDeclaration(doc['extensions']));
-    }
-    const REQUIRED_TOP_LEVEL = ['id', 'name', 'version', 'steps'];
-    for (const field of REQUIRED_TOP_LEVEL) {
-        if (!(field in doc)) {
-            errors.push(`Missing required field: '${field}'`);
-        }
-    }
-    if ('version' in doc && typeof doc['version'] !== 'number') {
-        errors.push(`'version' must be a number`);
-    }
-    if ('steps' in doc &&
-        (typeof doc['steps'] !== 'object' || doc['steps'] === null || Array.isArray(doc['steps']))) {
-        errors.push(`'steps' must be a non-null object`);
-    }
-    if (errors.length > 0) {
-        throw new WorkflowError(`Invalid workflow: ${errors.join('; ')}`, {
-            code: 'VALIDATION_WORKFLOW_SCHEMA',
-            category: 'VALIDATION',
-            agentAction: 'report_to_user',
-            retryable: false,
-        });
-    }
-    // Step 1b: Resolve template instantiations before validation.
-    const rawTemplates = (doc['templates'] ?? {});
-    if (Object.keys(rawTemplates).length > 0 || hasUseTemplateInSteps(doc['steps'])) {
-        doc['steps'] = resolveTemplates(doc['steps'], rawTemplates);
-    }
-    const stepsRaw = doc['steps'];
-    // Finalizer-bearing workflows write every claim `deadline: null` (issue #101), so a per-step
-    // `idempotent` hint is INERT there (never cron-reclaimable). Used only to WARN below.
-    const hasFinalizerStep = Object.values(stepsRaw).some((s) => typeof s === 'object' &&
-        s !== null &&
-        s['execution'] === 'finalizer');
-    // Step 3: Per-step validation
-    for (const [stepName, stepRaw] of Object.entries(stepsRaw)) {
-        if (typeof stepRaw !== 'object' || stepRaw === null || Array.isArray(stepRaw)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}' must be an object`));
-            continue;
-        }
-        const step = stepRaw;
-        // issue #220 §4c (PR-3): HOISTED out of the `when`-only block below (was block-local there) so
-        // ALL THREE condition surfaces (when/abort_unless/preconditions) can thread the real
-        // depends_on list into validateConditionLeaf's `$settlement` one-hop check. Previously
-        // abort_unless/preconditions passed a literal `[]` (no reference validation existed for them
-        // at all); the legacy when-only depends_on/run.params check (validateWhenReference) is
-        // UNCHANGED — it still fires ONLY for `surface === 'when'`. This is a LIFT, not a new
-        // computation — byte-identical to the previous block-local `dependsOn` for `when`'s own use.
-        const dependsOn = Array.isArray(step['depends_on'])
-            ? step['depends_on'].filter((d) => typeof d === 'string')
-            : [];
-        // WARN (do not reject) on an unknown step key — runs after template resolution above, so a
-        // template-expanded step's keys are checked too. Same non-breaking posture as the
-        // workflow-level check (issue #144).
-        warnings.push(...findUnknownKeys(step, KNOWN_STEP_KEYS, {
-            scope: 'step',
-            code: 'UNKNOWN_STEP_KEY',
-            step: stepName,
-            positionOf: (key) => sourceMap.posOf(['steps', stepName, key]),
-        }));
-        // issue #220 §4c PR ordering interlock: `$settlement` is reserved NOW (PR-1) even though the
-        // namespace it names is not minted until a later PR — else the inter-PR gap could register a
-        // `$settlement`-named step that becomes a load-refused fossil the instant the mint ships.
-        if (stepName === 'run' || stepName === 'context' || stepName === '$settlement') {
-            errors.push(`Step name '${stepName}' is reserved and cannot be used as a step identifier`);
-        }
-        // Reject integer-like step names: JS object iteration reorders integer-like keys ahead
-        // of insertion order, which would silently break the declaration-order guarantees the
-        // eligibility loops and finalizer drain rely on (both iterate via Object.entries).
-        if (/^\d+$/.test(stepName)) {
-            errors.push(`Step name '${stepName}' is invalid: integer-like names reorder under JS object ` +
-                `iteration and would break declaration-order execution. Use a non-numeric name.`);
-        }
-        const REQUIRED_STEP = ['description', 'execution'];
-        for (const field of REQUIRED_STEP) {
-            if (!(field in step)) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': missing required field '${field}'`));
+        const doc = raw;
+        // WARN (do not reject) on a key that isn't authorable — checked against KNOWN_WORKFLOW_KEYS
+        // ONLY (not RUNTIME_ONLY_WORKFLOW_KEYS), and BEFORE any loader-stamped field is added below.
+        // Deliberately excluding runtime-only keys from "known" here means hand-authoring one (e.g.
+        // `schema_version:` or `model:` in YAML) warns too — those fields are stamped by the loader
+        // and any authored value is silently overwritten/ignored, which is exactly the kind of mistake
+        // this check exists to surface (issue #144). Non-breaking by design: siblings #170
+        // (hard-reject) and #169 (structured warnings channel) are deliberately out of scope here.
+        {
+            const workflowId = typeof doc['id'] === 'string' ? doc['id'] : '<unknown>';
+            warnings.push(...findUnknownKeys(doc, KNOWN_WORKFLOW_KEYS, {
+                scope: 'workflow',
+                code: 'UNKNOWN_WORKFLOW_KEY',
+                id: workflowId,
+                positionOf: (key) => sourceMap.posOf([key]),
+            }));
+        }
+        // Project extensions: hard error for string-based loading (fires before any other
+        // processing); shape validation (string | string[], relative-only) for file-based loading.
+        if ('extensions' in doc && doc['extensions'] !== undefined) {
+            if (!opts.allowExtensions) {
+                throw new WorkflowError(`Invalid workflow: 'extensions' requires file-based loading — no directory context is ` +
+                    `available to resolve extension module paths. Register this workflow from its YAML ` +
+                    `file (realm workflow register <path>).`, {
+                    code: 'VALIDATION_WORKFLOW_SCHEMA',
+                    category: 'VALIDATION',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
             }
+            errors.push(...validateExtensionsDeclaration(doc['extensions']));
         }
-        if ('execution' in step && !VALID_EXECUTIONS.has(step['execution'])) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': invalid execution value '${String(step['execution'])}'; must be 'auto', 'agent', 'guard', or 'finalizer'`));
-        }
-        // Finalizer step constraints (a workflow-level try/catch/finally). handler-only in v1.
-        if (step['execution'] === 'finalizer') {
-            const prohibited = [
-                'depends_on',
-                'trigger_rule',
-                'abort_unless',
-                'abort_message',
-                'output_schema',
-                'agent_profile',
-                'tools',
-                'uses_service',
-                'service_method',
-                'operation',
-                'input_map',
-                'when',
-                'retry',
-            ];
-            for (const field of prohibited) {
-                if (step[field] !== undefined) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': '${field}' is not valid on execution: finalizer steps`));
-                }
-            }
-            // A finalizer must not gate — reject any human-gate trust level.
-            if (step['trust'] !== undefined && step['trust'] !== 'auto') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'trust: ${String(step['trust'])}' is not valid on execution: finalizer steps (a finalizer must not gate)`));
-            }
-            // v1 is handler-only.
-            if (step['handler'] === undefined) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': execution: finalizer requires 'handler' (handler-only in v1)`));
-            }
-            // on_outcome is required, non-empty, every value in the FinalizerTrigger enum.
-            const rawOutcome = step['on_outcome'];
-            if (rawOutcome === undefined) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': execution: finalizer requires 'on_outcome'`));
-            }
-            else {
-                const outcomes = Array.isArray(rawOutcome) ? rawOutcome : [rawOutcome];
-                if (outcomes.length === 0) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'on_outcome' must not be empty`));
-                }
-                for (const o of outcomes) {
-                    if (typeof o !== 'string' || !VALID_FINALIZER_TRIGGERS.has(o)) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': invalid on_outcome value '${String(o)}'; must be one of ${[...VALID_FINALIZER_TRIGGERS].join(', ')}`));
-                    }
-                }
+        const REQUIRED_TOP_LEVEL = ['id', 'name', 'version', 'steps'];
+        for (const field of REQUIRED_TOP_LEVEL) {
+            if (!(field in doc)) {
+                errors.push(`Missing required field: '${field}'`);
             }
         }
-        // on_outcome is only valid on execution: finalizer steps.
-        if (step['on_outcome'] !== undefined && step['execution'] !== 'finalizer') {
-            errors.push(
-            // Consumer: settlement.ts:145 (`finalizerTriggers`) — it is read only when selecting
-            // which finalizers a run's outcome should fire.
-            withKeyLine(stepName, 'on_outcome', `Step '${stepName}': 'on_outcome' is only valid on execution: finalizer steps — it ` +
-                'selects which finalizers run for a given outcome, and only finalizers are selected ' +
-                'that way, so here it would decide nothing. Move it to the finalizer that should ' +
-                'react to the outcome, or remove it.'));
+        if ('version' in doc && typeof doc['version'] !== 'number') {
+            errors.push(`'version' must be a number`);
         }
-        // Guard step constraints.
-        if (step['execution'] === 'guard') {
-            const prohibited = [
-                'uses_service',
-                'handler',
-                'input_schema',
-                'output_schema',
-                'trust',
-                'agent_profile',
-                'trigger_rule',
-                'timeout_seconds',
-                'service_method',
-                'operation',
-                'input_map',
-                'tools',
-            ];
-            for (const field of prohibited) {
-                if (step[field] !== undefined) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': '${field}' is not valid on execution: guard steps`));
-                }
-            }
-            if (step['abort_unless'] === undefined) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': execution: guard requires 'abort_unless'`));
-            }
-            // issue #369: `preconditions` gets its OWN error rather than joining `prohibited` above,
-            // because the generic message ("'x' is not valid on execution: guard steps") would not say
-            // the thing that matters — this field was ACCEPTED and INERT before this check existed, so
-            // an author who wrote one has a workflow that looks guarded and never was. The generic
-            // list's own message style is issue #366's territory; the other twelve are left alone.
-            //
-            // The claim "never evaluates it there" rests on `checkPreconditions` having exactly one
-            // engine call site (execution-loop.ts:1380, inside `executeStep`), which `executeGuardStep`
-            // never reaches. A test pins that count so a second call site reds this message.
-            if (step['preconditions'] !== undefined) {
-                errors.push(withKeyLine(stepName, 'preconditions', `Step '${stepName}': 'preconditions' is not valid on execution: guard steps — the ` +
-                    `engine never evaluates it there (a guard's execution evaluates only 'abort_unless'), ` +
-                    `so the run would LOOK guarded while the declared check never ran. Move the condition ` +
-                    `into 'abort_unless'. Whether guards gain a live condition surface is an open design ` +
-                    `question (issue #366) — if admitted later, existing workflows are unaffected.`));
-            }
-        }
-        // abort_unless and abort_message are only valid on execution: guard steps.
-        if (step['abort_unless'] !== undefined && step['execution'] !== 'guard') {
-            errors.push(
-            // Consumer: execution-loop.ts:4828 — the condition list a guard evaluates before the
-            // run is allowed to continue.
-            withKeyLine(stepName, 'abort_unless', `Step '${stepName}': 'abort_unless' is only valid on execution: guard steps — it is ` +
-                'the condition list a guard evaluates before letting the run continue, and only ' +
-                'guard steps are evaluated that way, so here it would gate nothing. Put the check ' +
-                'on a guard step, or remove it.'));
-        }
-        if (step['abort_message'] !== undefined && step['execution'] !== 'guard') {
-            errors.push(
-            // Consumer: execution-loop.ts:4943 — the text reported when a guard aborts the run.
-            // The clause is about READERSHIP, not about who aborts: `handler_abort` and
-            // `gate_expiry_abort` are seal arms too (types/run-record.ts:603-617), so "only a guard
-            // aborts" would be false. What is true is that every reader of this key is a guard path.
-            withKeyLine(stepName, 'abort_message', `Step '${stepName}': 'abort_message' is only valid on execution: guard steps — it is ` +
-                'the text reported when a guard aborts the run, and nothing but a guard reads it, ' +
-                'so here it would never be read. Move it to the guard that performs the abort, or ' +
-                'remove it.'));
-        }
-        // agent_profile is only valid on agent steps.
-        if ('agent_profile' in step && step['execution'] !== 'agent') {
-            errors.push(
-            // Consumer: run-agent.ts:584 — resolved into the model prompt for the step.
-            withKeyLine(stepName, 'agent_profile', `Step '${stepName}': 'agent_profile' is only valid on execution: agent steps — its ` +
-                'content is resolved into the model prompt, and only an agent step makes a model ' +
-                'request, so here it would reach no model. Move it to the agent step whose prompt ' +
-                'it should shape, or remove it.'));
+        if ('steps' in doc &&
+            (typeof doc['steps'] !== 'object' || doc['steps'] === null || Array.isArray(doc['steps']))) {
+            errors.push(`'steps' must be a non-null object`);
         }
-        // llm_timeout_seconds (issue #401) is only valid on agent steps — no other execution kind
-        // makes a model request, so the key would be silently inert anywhere else. One `!== 'agent'`
-        // check covers auto/guard/finalizer.
-        if (step['llm_timeout_seconds'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(
-            // Consumer: run-agent.ts:501-507 — the per-step clock resolution, which is the
-            // per-attempt bound on the step's model request. The range names the resolution rather
-            // than each read: :501 and :507 read the KEY, :503 reads the CLI flag it overrides.
-            withKeyLine(stepName, 'llm_timeout_seconds', `Step '${stepName}': 'llm_timeout_seconds' is only valid on execution: agent steps — ` +
-                'it bounds one model request, and no other kind makes one, so here it would bound ' +
-                'nothing. Move it to the agent step whose request it should bound, or remove it. ' +
-                "An auto step's dispatch is bounded by 'timeout_seconds', and a " +
-                "finalizer's handler by its own 'timeout_seconds'."));
-        }
-        // ...and when present it must be a positive integer (the same convention as
-        // retry.total_timeout_seconds and gate.timeout_seconds).
-        if (step['llm_timeout_seconds'] !== undefined &&
-            (!Number.isInteger(step['llm_timeout_seconds']) ||
-                step['llm_timeout_seconds'] <= 0)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'llm_timeout_seconds' must be a positive integer`));
-        }
-        // timeout_seconds is NOT valid on an agent step (issue #402). Nothing enforces it there:
-        // `shouldEnforceTimeout` is `execution === 'auto'`, and agent dispatch is never wrapped in
-        // `withTimeout` at all. The key is now inert as well as unenforced — issue #412 deleted the
-        // `expected_timeout` display that used to render it into the NextAction, which is what made
-        // it actively misleading rather than merely useless. The error stays: an author who writes a
-        // bound should be told it does nothing, not left to find out. The message names both bounds
-        // that DO exist, scoped to realm's own drive (an externally driven step gets neither), on
-        // the RETRY_INERT_NON_AUTO precedent below.
-        //
-        // `=== 'agent'` EXACTLY, never `!== 'auto'`: finalizers consume this key twice — the drain
-        // lease (execution-loop.ts:5226) and the handler's own bound (:5030) — and guards already
-        // reject it in the prohibited-fields list above.
-        if (step['timeout_seconds'] !== undefined && step['execution'] === 'agent') {
-            errors.push(withKeyLine(stepName, 'timeout_seconds', `Step '${stepName}': 'timeout_seconds' is not valid on execution: agent steps — ` +
-                'the engine never enforces it there (agent dispatch is never wrapped in a timeout), ' +
-                'so the step would LOOK time-bounded while nothing enforced the bound. ' +
-                "In realm's own drive the model request is bounded by 'llm_timeout_seconds' " +
-                "(or --llm-timeout) and tool calls by 'tool_timeout'."));
-        }
-        // idempotent (issue #101 Phase 2) is only valid on execution: auto steps — the reliably
-        // time-boundable, deadline-carrying class. It is inert (no concrete deadline is ever written)
-        // on agent/guard/finalizer, so it is rejected there rather than silently ignored.
-        if (step['idempotent'] !== undefined && step['execution'] !== 'auto') {
-            errors.push(
-            // Consumers: execution-loop.ts:2526 (the `willRetry` conjunct gating `retry.on_timeout`;
-            // the :2115 advisory mirrors the rule for loader-bypassing definitions and, by its own
-            // header, never gates) and reclaim.ts:73 (reclaim eligibility) — both act on auto
-            // dispatch.
-            withKeyLine(stepName, 'idempotent', `Step '${stepName}': 'idempotent' is only valid on execution: auto steps — it gates ` +
-                "'retry.on_timeout' and reclaim eligibility, and both act on auto dispatch, so here " +
-                'it would gate nothing. Remove it, or move the work to an auto step if you need ' +
-                'either.'));
+        if (errors.length > 0) {
+            throw new WorkflowError(`Invalid workflow: ${errors.join('; ')}`, {
+                // issue #425: the pre-join strings — see the profile collector above.
+                errors: [...errors],
+                code: 'VALIDATION_WORKFLOW_SCHEMA',
+                category: 'VALIDATION',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
         }
-        // WARN (do not reject): an idempotent auto step in a finalizer-bearing workflow gets
-        // `deadline: null` (issue #101), so the RECLAIM function is inert — `realm run reclaim --all`
-        // can never select it. The author should know it stays per-step-manual-reclaim-only.
-        //
-        // Issue #140 C5 (variant-aware reword): `idempotent` now has a SECOND function — gating
-        // `retry.on_timeout` — and that GATE function is live in every workflow, finalizer-bearing or
-        // not (shouldEnforceTimeout has no finalizer conjunct). A single unconditional message would
-        // either keep a falsehood (claiming idempotent is wholly inert when on_timeout is ALSO
-        // declared) or gratuitously mention a gate the author never declared (idempotent-alone case)
-        // — so the message is keyed on `step.retry?.on_timeout`, pinned by both-variant loader tests.
-        if (step['idempotent'] === true && step['execution'] === 'auto' && hasFinalizerStep) {
-            const stepRetry = typeof step['retry'] === 'object' && step['retry'] !== null
-                ? step['retry']
+        // Step 1b: Resolve template instantiations before validation.
+        const rawTemplates = (doc['templates'] ?? {});
+        if (Object.keys(rawTemplates).length > 0 || hasUseTemplateInSteps(doc['steps'])) {
+            doc['steps'] = resolveTemplates(doc['steps'], rawTemplates);
+        }
+        const stepsRaw = doc['steps'];
+        // Finalizer-bearing workflows write every claim `deadline: null` (issue #101), so a per-step
+        // `idempotent` hint is INERT there (never cron-reclaimable). Used only to WARN below.
+        const hasFinalizerStep = Object.values(stepsRaw).some((s) => typeof s === 'object' &&
+            s !== null &&
+            s['execution'] === 'finalizer');
+        // Step 3: Per-step validation
+        for (const [stepName, stepRaw] of Object.entries(stepsRaw)) {
+            if (typeof stepRaw !== 'object' || stepRaw === null || Array.isArray(stepRaw)) {
+                errors.push(withStepLine(stepName, `Step '${stepName}' must be an object`));
+                continue;
+            }
+            const step = stepRaw;
+            // issue #220 §4c (PR-3): HOISTED out of the `when`-only block below (was block-local there) so
+            // ALL THREE condition surfaces (when/abort_unless/preconditions) can thread the real
+            // depends_on list into validateConditionLeaf's `$settlement` one-hop check. Previously
+            // abort_unless/preconditions passed a literal `[]` (no reference validation existed for them
+            // at all); the legacy when-only depends_on/run.params check (validateWhenReference) is
+            // UNCHANGED — it still fires ONLY for `surface === 'when'`. This is a LIFT, not a new
+            // computation — byte-identical to the previous block-local `dependsOn` for `when`'s own use.
+            // The step's kind, once, for every kind-forked check below (undefined = malformed or
+            // missing execution — already refused by the invalid-execution/required error).
+            const stepKind = VALID_EXECUTIONS.has(step['execution'])
+                ? step['execution']
                 : undefined;
-            const onTimeoutDeclared = stepRetry?.['on_timeout'] === true;
-            warnings.push({
-                code: 'IDEMPOTENT_INERT_IN_FINALIZER',
-                severity: resolveSeverity('IDEMPOTENT_INERT_IN_FINALIZER'),
+            const dependsOn = Array.isArray(step['depends_on'])
+                ? step['depends_on'].filter((d) => typeof d === 'string')
+                : [];
+            // WARN (do not reject) on an unknown step key — runs after template resolution above, so a
+            // template-expanded step's keys are checked too. Same non-breaking posture as the
+            // workflow-level check (issue #144).
+            warnings.push(...findUnknownKeys(step, KNOWN_STEP_KEYS, {
                 scope: 'step',
+                code: 'UNKNOWN_STEP_KEY',
                 step: stepName,
-                message: `Step '${stepName}': 'idempotent: true' cannot enable auto-reclaim in a finalizer-bearing ` +
-                    `workflow (its claim carries no deadline, so 'realm run reclaim --all' can never select ` +
-                    `it). Recover it with 'realm run reclaim <run-id> --step ${stepName} --force'.` +
-                    (onTimeoutDeclared
-                        ? ` Its 'retry.on_timeout' gate role is unaffected — timeout retries remain active.`
-                        : ''),
-            });
-        }
-        // output_schema is only valid on execution: agent steps.
-        if (step['output_schema'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'output_schema' is only valid on execution: agent steps`));
-        }
-        // issue #236 (L0 prevention layer): structured_output is only valid on execution: agent
-        // steps (mirrors output_schema's rule above), and its only legal value is the literal
-        // 'strict'. On an opted-in step, Phase A REJECTS an ineligible verdict at load time — the
-        // API provably rejects some legal schemas and silently weakens others, so authoring never
-        // ships a schema the gate already knows is unsafe. Caveats are NOT rejected (informational
-        // only, surfaced by validate's nudge — Deliverable 7); this loader block only ever REJECTS.
-        if (step['structured_output'] !== undefined) {
-            if (step['execution'] !== 'agent') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' is only valid on execution: agent steps`));
+                positionOf: (key) => sourceMap.posOf(['steps', stepName, key]),
+            }));
+            // issue #220 §4c PR ordering interlock: `$settlement` is reserved NOW (PR-1) even though the
+            // namespace it names is not minted until a later PR — else the inter-PR gap could register a
+            // `$settlement`-named step that becomes a load-refused fossil the instant the mint ships.
+            if (stepName === 'run' || stepName === 'context' || stepName === '$settlement') {
+                errors.push(`Step name '${stepName}' is reserved and cannot be used as a step identifier`);
             }
-            else if (step['structured_output'] !== 'strict') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' must be the literal string 'strict' (got ${JSON.stringify(step['structured_output'])})`));
+            // Reject integer-like step names: JS object iteration reorders integer-like keys ahead
+            // of insertion order, which would silently break the declaration-order guarantees the
+            // eligibility loops and finalizer drain rely on (both iterate via Object.entries).
+            if (/^\d+$/.test(stepName)) {
+                errors.push(`Step name '${stepName}' is invalid: integer-like names reorder under JS object ` +
+                    `iteration and would break declaration-order execution. Use a non-numeric name.`);
             }
-            else {
-                const verdict = assessStructuredOutputEligibility({
-                    ...(step['output_schema'] !== undefined
-                        ? { output_schema: step['output_schema'] }
-                        : {}),
-                    ...(step['input_schema'] !== undefined
-                        ? { input_schema: step['input_schema'] }
-                        : {}),
-                    ...(step['tools'] !== undefined ? { tools: step['tools'] } : {}),
-                });
-                if (verdict.verdict === 'ineligible') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output: strict' is not eligible for this step's ` +
-                        `schema — ${renderIneligibleMessage(verdict.reasons)}`));
+            const REQUIRED_STEP = ['description', 'execution'];
+            for (const field of REQUIRED_STEP) {
+                if (!(field in step)) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': missing required field '${field}'`));
                 }
             }
-        }
-        // issue #220 (PR-2): validation_exhaustion is only valid on execution: agent steps — the
-        // countable rejection set (VALIDATION_INPUT_SCHEMA/VALIDATION_OUTPUT_SCHEMA) is agent-only by
-        // construction (execution-loop.ts's countRejection). Full rule table: `mode` value validated
-        // (REFUSE on an unrecognized value — unvalidatable posture, fail-closed); `mode: 'default'`
-        // requires `default_output` (REFUSE — nothing to substitute) which in turn requires the step's
-        // own `output_schema` (REFUSE — B5, an unvalidatable default) against which `default_output` is
-        // then AJV-proven AT LOAD TIME (REFUSE — B10, reusing the runtime validator so load-time and
-        // runtime verdicts can never diverge); `default_output` present without `mode: 'default'` WARNS
-        // as dead config (never rejects — it's simply inert); an unknown sub-key WARNS.
-        if (step['validation_exhaustion'] !== undefined) {
-            if (step['execution'] !== 'agent') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' is only valid on execution: agent steps`));
+            if ('execution' in step && !VALID_EXECUTIONS.has(step['execution'])) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': invalid execution value '${String(step['execution'])}'; must be 'auto', 'agent', 'guard', or 'finalizer'`));
             }
-            else if (typeof step['validation_exhaustion'] !== 'object' ||
-                step['validation_exhaustion'] === null) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' must be an object`));
+            // issue #517 (the drive-flip): ONE registry-driven walk mints every kind-prohibition —
+            // for each declared key × the step's kind, a `prohibited` cell WITHOUT an except arm
+            // mints exactly one refusal, message text per-cell data (renderRegistryProhibition).
+            // Sits at the sequence position of the EARLIEST check it replaced (the old finalizer
+            // prohibited-field loop), so minted refusals still precede the structural finalizer/guard
+            // requirements below. Multi-fire is dead by construction (one lookup, one refusal per
+            // key×kind), and a multi-bad-key step now errors in YAML declaration order.
+            //
+            // Except-bearing cells are SKIPPED — their value-conditional checks stay hand-written
+            // (today exactly trust×finalizer, below). Companion/value/sub-key rules are not minted at
+            // all (the clang line): toolsMissing, the tools agent+handler clause, the gate block,
+            // retry E1-E3, structured_output literal+eligibility, trace_schema compile, pos-int
+            // checks all stay hand-written further down.
+            //
+            // The kind gate is deliberate: on a step whose `execution` is missing or not one of the
+            // four kinds, the registry has no row to consult, so NO per-key kind refusal is minted —
+            // the invalid-execution/missing-required error above is the whole verdict. (Pre-#517 the
+            // per-key `!== '<kind>'` twins ALSO fired on malformed kinds; that was per-key advice
+            // keyed to a kind nobody declared. The workflow is refused either way — the refusal
+            // POPULATION is unchanged; disclosed in the changelog.)
+            if (VALID_EXECUTIONS.has(step['execution'])) {
+                const kind = step['execution'];
+                for (const key of Object.keys(step)) {
+                    // Unknown keys are UNKNOWN_STEP_KEY's business (warned above), never a registry row.
+                    const row = STEP_KEY_REGISTRY[key];
+                    if (row === undefined || step[key] === undefined)
+                        continue;
+                    const cell = row[kind];
+                    if (cell.c !== 'prohibited' || cell.except !== undefined)
+                        continue;
+                    errors.push(withKeyLine(stepName, key, `Step '${stepName}': ${renderRegistryProhibition(key, kind, cell)}`));
+                }
             }
-            else {
-                const exhaustionBlock = step['validation_exhaustion'];
-                // WARN (do not reject) on an unknown validation_exhaustion sub-key — the retry-block-style
-                // pattern (issue #140's UNKNOWN_RETRY_KEY), its OWN code (issue #220 PR-2 mints
-                // UNKNOWN_VALIDATION_EXHAUSTION_KEY, replacing PR-1's UNKNOWN_STEP_KEY noun-override —
-                // closes the #170-flip incoherence against the structurally identical retry-key family).
-                warnings.push(...findUnknownKeys(exhaustionBlock, KNOWN_VALIDATION_EXHAUSTION_KEYS, {
-                    scope: 'step',
-                    code: 'UNKNOWN_VALIDATION_EXHAUSTION_KEY',
-                    step: stepName,
-                    noun: 'validation_exhaustion',
-                    positionOf: (key) => sourceMap.posOf(['steps', stepName, 'validation_exhaustion', key]),
-                }));
-                if ('threshold' in exhaustionBlock &&
-                    (!Number.isInteger(exhaustionBlock['threshold']) ||
-                        exhaustionBlock['threshold'] < 1)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.threshold' must be a positive integer ` +
-                        `(1 is legal — it disables in-drive schema-repair, since the first rejection ` +
-                        `already meets it)`));
+            // Finalizer step constraints (a workflow-level try/catch/finally). handler-only in v1.
+            if (step['execution'] === 'finalizer') {
+                // A finalizer must not gate — reject any human-gate trust level. Value-conditional
+                // (`trust: 'auto'` is lawful), which is why this is the registry's except-bearing cell
+                // and stays hand-written rather than minted (#517).
+                if (step['trust'] !== undefined && step['trust'] !== 'auto') {
+                    // issue #508: the reason forks on whether the declared value is actually a GATE
+                    // literal — "a finalizer must not gate" is only true THEN. Any other value (an
+                    // unrecognized trust, a service-trust literal, the retired human_notified) was never
+                    // an attempt to gate at all, so that reason would be false for it — the #523 class,
+                    // caught before shipping rather than after. `isGateTrust` is the pure-value question
+                    // (no kind involved, since this branch already knows the kind and has already
+                    // excluded 'auto'); the leading `'trust:` is kept exactly as before so the registry
+                    // conformance runner's `namesKey` (`error.includes("'trust")`) still matches this arm
+                    // — `namesKey` needs the quote BEFORE `trust`, not around the value, so switching the
+                    // value's own rendering below does not touch it.
+                    //
+                    // issue #508 (final correction): the gate-literal arm stays a hand-written KIND
+                    // prohibition (the key is the offense, not the value — #517's own boundary), but now
+                    // shares `renderTrustValue` with every other arm — a previous ruling to "keep
+                    // `String()` here to satisfy `namesKey`" was wrong (verified above) and there was
+                    // never a real reason for two renderers, even though `isGateTrust` only ever admits
+                    // the two known-string gate literals here in practice. The non-gate branch (an
+                    // unrecognized trust, a service-trust literal, the retired human_notified) routes
+                    // through the SAME composer every other refusal surface uses — no second hand-built
+                    // arm-selector, no second value renderer. The conformance fixture (`buildFixture`)
+                    // exercises only the gate-literal branch (`human_confirmed`), so the composer's three
+                    // sub-arms are unreached by it — verified by grepping the fixture builder for this key.
+                    const rawFinalizerTrust = step['trust'];
+                    const finalizerMessage = isGateTrust(rawFinalizerTrust)
+                        ? `Step '${stepName}': 'trust: ${renderTrustValue(rawFinalizerTrust)}' is not valid on execution: finalizer steps (a finalizer must not gate)`
+                        : buildTrustRefusal({
+                            kind: 'finalizer',
+                            value: rawFinalizerTrust,
+                            step: stepName,
+                            surface: 'load',
+                        });
+                    errors.push(withStepLine(stepName, finalizerMessage));
                 }
-                const modeValue = exhaustionBlock['mode'];
-                if (modeValue !== undefined && modeValue !== 'fail' && modeValue !== 'default') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.mode' must be 'fail' or 'default' ` +
-                        `(got: ${JSON.stringify(modeValue)})`));
+                // v1 is handler-only.
+                if (step['handler'] === undefined) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': execution: finalizer requires 'handler' (handler-only in v1)`));
                 }
-                const hasDefaultOutput = 'default_output' in exhaustionBlock;
-                if (modeValue === 'default') {
-                    if (!hasDefaultOutput) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.mode: default' requires ` +
-                            `'default_output' (nothing to substitute on exhaustion)`));
-                    }
-                    else if (step['output_schema'] === undefined) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.default_output' requires the step to ` +
-                            `declare 'output_schema' (an undeclared schema makes the default unvalidatable)`));
+                // on_outcome is required, non-empty, every value in the FinalizerTrigger enum.
+                const rawOutcome = step['on_outcome'];
+                if (rawOutcome === undefined) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': execution: finalizer requires 'on_outcome'`));
+                }
+                else {
+                    const outcomes = Array.isArray(rawOutcome) ? rawOutcome : [rawOutcome];
+                    if (outcomes.length === 0) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'on_outcome' must not be empty`));
                     }
-                    else {
-                        // B10 — load-time AJV proof: REUSE the runtime validator so the load-time verdict can
-                        // never diverge from the runtime verdict for the exact same (default_output,
-                        // output_schema) pair. This is the loader's first load-time Ajv compile of an
-                        // output_schema (today output_schema is only compiled at runtime), so the catch below
-                        // legitimately sees TWO different populations: a VALIDATION_OUTPUT_SCHEMA
-                        // WorkflowError (default_output fails the schema) and a raw Ajv schema-compilation
-                        // Error (a structurally malformed output_schema) — both fail-closed to a load refusal,
-                        // but they carry their detail DIFFERENTLY: a WorkflowError has `.details.errors`; a raw
-                        // Error has NO `.details` at all (reading `.details.errors` on it throws a TypeError
-                        // that would escape the loader mid-walk — verified empirically). Discriminate.
-                        try {
-                            validateOutputSchema(exhaustionBlock['default_output'], step['output_schema'], stepName);
-                        }
-                        catch (err) {
-                            const detail = err instanceof WorkflowError
-                                ? JSON.stringify(err.details['errors'])
-                                : err instanceof Error
-                                    ? err.message
-                                    : String(err);
-                            errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.default_output' does not validate ` +
-                                `against the step's own 'output_schema': ${detail}`));
+                    for (const o of outcomes) {
+                        if (typeof o !== 'string' || !VALID_FINALIZER_TRIGGERS.has(o)) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': invalid on_outcome value '${String(o)}'; must be one of ${[...VALID_FINALIZER_TRIGGERS].join(', ')}`));
                         }
                     }
                 }
-                else if (hasDefaultOutput) {
-                    // default_output present without mode: 'default' (mode: 'fail' or absent) — inert, not
-                    // an error: WARN as dead config rather than silently ignoring it.
-                    warnings.push({
-                        code: 'DEAD_VALIDATION_EXHAUSTION_CONFIG',
-                        severity: resolveSeverity('DEAD_VALIDATION_EXHAUSTION_CONFIG'),
-                        scope: 'step',
-                        step: stepName,
-                        message: `Step '${stepName}': 'validation_exhaustion.default_output' is ignored without ` +
-                            `'mode: default' — set 'validation_exhaustion.mode: default' to enable it, or ` +
-                            `remove 'default_output'.`,
-                    });
+            }
+            // issue #508 (L1) — trust VALUE validation, auto/agent only. Before this check, an
+            // unrecognized or kind-inert `trust` (a typo, a service-trust literal, the retired
+            // `human_notified`) loaded clean, warned nothing, and ran with NO gate — the step's own
+            // declared human-approval control was silently disabled. Presence-keyed (`'trust' in
+            // step`, the same convention `trigger_rule` and `retry.backoff` already use below) so
+            // `trust:`/`trust: ~` (a null value, which loads clean today) is caught too — a blank
+            // declaration of a safety control is itself a false statement, not a no-op. `trust:`
+            // absent entirely is lawful (nothing was declared) and never reaches this block.
+            //
+            // Guard's OWN trust prohibition is minted by the #517 walk above (every value refused,
+            // no except arm); finalizer's is the hand-written except-cell just above (only 'auto' is
+            // lawful there). This block is what closes the remaining two kinds — the ones where a
+            // RECOGNIZED gate literal is meaningful, so an unrecognized one needs a VALUE verdict,
+            // not a kind verdict.
+            //
+            // issue #508 (final correction) — this whole value-refusal composition, for every kind and
+            // every surface, is now `buildTrustRefusal` (types/workflow-definition.ts, beside
+            // `classifyStepTrust`). Three prior rounds each hand-composed this text independently on
+            // this surface, execution-loop.ts's dispatch refusal, run-health.ts's finding, and the
+            // protocol generator's briefing — and every defect those rounds found (arm divergence, a
+            // String()-rendered array printing as its own first element, a grammar seam) fell out of
+            // that duplication. No site chooses an arm or renders a value on its own again; see the
+            // composer's own doc for the arm/mood/rendering contract in full.
+            if ((stepKind === 'auto' || stepKind === 'agent') &&
+                'trust' in step &&
+                classifyStepTrust(stepKind, step['trust']) === 'refuse') {
+                errors.push(withKeyLine(stepName, 'trust', buildTrustRefusal({
+                    kind: stepKind,
+                    value: step['trust'],
+                    step: stepName,
+                    surface: 'load',
+                })));
+            }
+            // Guard step constraints (the guard kind-prohibitions, including `preconditions` — issue
+            // #369's own bespoke message, message_data-preserved — are minted by the #517 walk above).
+            if (step['execution'] === 'guard') {
+                if (step['abort_unless'] === undefined) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': execution: guard requires 'abort_unless'`));
                 }
             }
-        }
-        // WARN (do not reject): an agent step declaring BOTH input_schema and output_schema has its
-        // submitted output validated against BOTH (execution-loop.ts validateInputSchema AND
-        // validateOutputSchema) — a divergence between the two degrades to a confusing recoverable
-        // VALIDATION_*_SCHEMA error rather than a clean failure. Detection/warn only; no schema change.
-        if (step['execution'] === 'agent' &&
-            step['input_schema'] !== undefined &&
-            step['output_schema'] !== undefined) {
-            warnings.push({
-                code: 'DUAL_SCHEMA_DECLARED',
-                severity: resolveSeverity('DUAL_SCHEMA_DECLARED'),
-                scope: 'step',
-                step: stepName,
-                message: `Step '${stepName}': declares both input_schema and output_schema; the agent's submitted ` +
-                    `output is validated against both — prefer one to avoid divergence.`,
-            });
-        }
-        // trace_schema is only valid on execution: agent steps.
-        if (step['trace_schema'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'trace_schema' is only valid on execution: agent steps`));
-        }
-        // trace_validation_mode is only valid on execution: agent steps.
-        if (step['trace_validation_mode'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'trace_validation_mode' is only valid on execution: agent steps`));
-        }
-        // trace_validation_mode must be 'warn' or 'enforce' when provided.
-        if (step['trace_validation_mode'] !== undefined &&
-            step['trace_validation_mode'] !== 'warn' &&
-            step['trace_validation_mode'] !== 'enforce') {
-            errors.push(withStepLine(stepName, `Step '${stepName}': invalid trace_validation_mode '${String(step['trace_validation_mode'])}'; must be 'warn' or 'enforce'`));
-        }
-        // issue #291 (authorable gate timeout — the FIRST validation the `gate:` block has ever had):
-        // the E2 positive-integer checks on timeout_seconds/reminder_seconds/reminder_max, the
-        // on_expiry enum, default_choice's required-iff + choice-set validation, and the dead-config
-        // warn cells. Runs regardless of `trust` (a `gate:` block with no gate trust is already inert
-        // — no separate rejection needed; the existing render/mint paths never read it without a
-        // trust value).
-        if (step['gate'] !== undefined) {
-            if (typeof step['gate'] !== 'object' || step['gate'] === null) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'gate' must be an object`));
+            // llm_timeout_seconds must be a positive integer when present (the same convention as
+            // retry.total_timeout_seconds and gate.timeout_seconds). Deliberately kind-BLIND, which
+            // makes it the pinned DOUBLE-fire control for #517: on a wrong-kind step BOTH the minted
+            // prohibition and this shape error fire — this check was never else-if-suppressed, unlike
+            // structured_output/validation_exhaustion/input_map's value checks below.
+            if (step['llm_timeout_seconds'] !== undefined &&
+                (!Number.isInteger(step['llm_timeout_seconds']) ||
+                    step['llm_timeout_seconds'] <= 0)) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'llm_timeout_seconds' must be a positive integer`));
             }
-            else {
-                const gate = step['gate'];
-                // WARN (do not reject) on an unknown gate-block key — same non-breaking posture as
-                // retry/validation_exhaustion (issues #140/#220).
-                warnings.push(...findUnknownKeys(gate, KNOWN_GATE_KEYS, {
+            // WARN (do not reject): an idempotent auto step in a finalizer-bearing workflow gets
+            // `deadline: null` (issue #101), so the RECLAIM function is inert — `realm run reclaim --all`
+            // can never select it. The author should know it stays per-step-manual-reclaim-only.
+            //
+            // Issue #140 C5 (variant-aware reword): `idempotent` now has a SECOND function — gating
+            // `retry.on_timeout` — and that GATE function is live in every workflow, finalizer-bearing or
+            // not (shouldEnforceTimeout has no finalizer conjunct). A single unconditional message would
+            // either keep a falsehood (claiming idempotent is wholly inert when on_timeout is ALSO
+            // declared) or gratuitously mention a gate the author never declared (idempotent-alone case)
+            // — so the message is keyed on `step.retry?.on_timeout`, pinned by both-variant loader tests.
+            if (step['idempotent'] === true && step['execution'] === 'auto' && hasFinalizerStep) {
+                const stepRetry = typeof step['retry'] === 'object' && step['retry'] !== null
+                    ? step['retry']
+                    : undefined;
+                const onTimeoutDeclared = stepRetry?.['on_timeout'] === true;
+                warnings.push({
+                    code: 'IDEMPOTENT_INERT_IN_FINALIZER',
+                    severity: resolveSeverity('IDEMPOTENT_INERT_IN_FINALIZER'),
                     scope: 'step',
-                    code: 'UNKNOWN_GATE_KEY',
                     step: stepName,
-                    noun: 'gate',
-                    positionOf: (key) => sourceMap.posOf(['steps', stepName, 'gate', key]),
-                }));
-                // E2: timeout_seconds/reminder_seconds/reminder_max must each be a positive integer
-                // (yaml-loader :1164-1174 precedent — the SAME convention as retry.total_timeout_seconds).
-                if ('timeout_seconds' in gate &&
-                    (!Number.isInteger(gate['timeout_seconds']) || gate['timeout_seconds'] <= 0)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.timeout_seconds' must be a positive integer`));
-                }
-                if ('reminder_seconds' in gate &&
-                    (!Number.isInteger(gate['reminder_seconds']) || gate['reminder_seconds'] <= 0)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.reminder_seconds' must be a positive integer`));
-                }
-                if ('reminder_max' in gate &&
-                    (!Number.isInteger(gate['reminder_max']) || gate['reminder_max'] <= 0)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.reminder_max' must be a positive integer`));
-                }
-                // on_expiry must be 'settle_default' or 'abort' when provided.
-                const onExpiry = gate['on_expiry'];
-                if (onExpiry !== undefined && onExpiry !== 'settle_default' && onExpiry !== 'abort') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry' must be 'settle_default' or 'abort' (got: ${JSON.stringify(onExpiry)})`));
-                }
-                // default_choice: REQUIRED iff on_expiry === 'settle_default' (E2-style hard error,
-                // mirroring validation_exhaustion.mode:'default' requiring default_output); validated
-                // against the step's own EFFECTIVE STATIC choice set — the EXACT same three-source
-                // derivation the engine mints PendingGate.choices from (execution-loop.ts's gate-open
-                // site: gate.choices ?? input_schema.properties.choice.enum ?? ['approve','reject']) —
-                // so a load-time-legal default_choice can NEVER fail at enactment time.
-                const hasDefaultChoice = 'default_choice' in gate;
-                if (onExpiry === 'settle_default') {
-                    if (!hasDefaultChoice) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry: settle_default' requires 'gate.default_choice' ` +
-                            `(nothing to resolve the gate with on expiry)`));
-                    }
-                    else {
-                        const choicesRaw = gate['choices'] ??
-                            step['input_schema']?.properties?.['choice']?.enum;
-                        const effectiveChoices = Array.isArray(choicesRaw)
-                            ? choicesRaw
-                            : ['approve', 'reject'];
-                        if (!effectiveChoices.includes(gate['default_choice'])) {
-                            errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.default_choice' (${JSON.stringify(gate['default_choice'])}) ` +
-                                `is not one of the step's effective choices: ${effectiveChoices.join(', ')}`));
-                        }
-                    }
+                    message: `Step '${stepName}': 'idempotent: true' cannot enable auto-reclaim in a finalizer-bearing ` +
+                        `workflow (its claim carries no deadline, so 'realm run reclaim --all' can never select ` +
+                        `it). Recover it with 'realm run reclaim <run-id> --step ${stepName} --force'.` +
+                        (onTimeoutDeclared
+                            ? ` Its 'retry.on_timeout' gate role is unaffected — timeout retries remain active.`
+                            : ''),
+                });
+            }
+            // issue #236 (L0 prevention layer): structured_output's only legal value is the literal
+            // 'strict'. On an opted-in step, Phase A REJECTS an ineligible verdict at load time — the
+            // API provably rejects some legal schemas and silently weakens others, so authoring never
+            // ships a schema the gate already knows is unsafe. Caveats are NOT rejected (informational
+            // only, surfaced by validate's nudge — Deliverable 7); this loader block only ever REJECTS.
+            // #517 re-gate: the kind half is minted by the registry walk above; the value checks
+            // below keep their old else-branch semantics via an explicit valid-kind conjunct — a
+            // wrong-kind step gets ONLY the minted refusal, never the value noise.
+            if (step['structured_output'] !== undefined && step['execution'] === 'agent') {
+                if (step['structured_output'] !== 'strict') {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' must be the literal string 'strict' (got ${JSON.stringify(step['structured_output'])})`));
                 }
-                else if (hasDefaultChoice) {
-                    // default_choice with on_expiry:'abort' or with no on_expiry at all — inert, not an
-                    // error: WARN as dead config (the #220 DEAD_VALIDATION_EXHAUSTION_CONFIG precedent).
-                    warnings.push({
-                        code: 'DEAD_GATE_CONFIG',
-                        severity: resolveSeverity('DEAD_GATE_CONFIG'),
-                        scope: 'step',
-                        step: stepName,
-                        message: `Step '${stepName}': 'gate.default_choice' is ignored without ` +
-                            `'gate.on_expiry: settle_default' — set it, or remove 'gate.default_choice'.`,
+                else {
+                    const verdict = assessStructuredOutputEligibility({
+                        ...(step['output_schema'] !== undefined
+                            ? { output_schema: step['output_schema'] }
+                            : {}),
+                        ...(step['input_schema'] !== undefined
+                            ? { input_schema: step['input_schema'] }
+                            : {}),
+                        ...(step['tools'] !== undefined ? { tools: step['tools'] } : {}),
                     });
+                    if (verdict.verdict === 'ineligible') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output: strict' is not eligible for this step's ` +
+                            `schema — ${renderIneligibleMessage(verdict.reasons)}`));
+                    }
                 }
-                // Dead config: on_expiry declared but no timeout_seconds — nothing will ever trigger the
-                // enforce clock, so the declared disposition can never enact.
-                if (onExpiry !== undefined && gate['timeout_seconds'] === undefined) {
-                    warnings.push({
-                        code: 'DEAD_GATE_CONFIG',
-                        severity: resolveSeverity('DEAD_GATE_CONFIG'),
-                        scope: 'step',
-                        step: stepName,
-                        message: `Step '${stepName}': 'gate.on_expiry' is ignored without 'gate.timeout_seconds' — ` +
-                            `set a timeout, or remove 'gate.on_expiry'.`,
-                    });
+            }
+            // issue #220 (PR-2): validation_exhaustion is only valid on execution: agent steps — the
+            // countable rejection set (VALIDATION_INPUT_SCHEMA/VALIDATION_OUTPUT_SCHEMA) is agent-only by
+            // construction (execution-loop.ts's countRejection). Full rule table: `mode` value validated
+            // (REFUSE on an unrecognized value — unvalidatable posture, fail-closed); `mode: 'default'`
+            // requires `default_output` (REFUSE — nothing to substitute) which in turn requires the step's
+            // own `output_schema` (REFUSE — B5, an unvalidatable default) against which `default_output` is
+            // then AJV-proven AT LOAD TIME (REFUSE — B10, reusing the runtime validator so load-time and
+            // runtime verdicts can never diverge); `default_output` present without `mode: 'default'` WARNS
+            // as dead config (never rejects — it's simply inert); an unknown sub-key WARNS.
+            // #517 re-gate: kind half minted above; else-semantics preserved by the explicit conjunct.
+            if (step['validation_exhaustion'] !== undefined && step['execution'] === 'agent') {
+                if (typeof step['validation_exhaustion'] !== 'object' ||
+                    step['validation_exhaustion'] === null) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' must be an object`));
                 }
-                // Dead notification ([F-A2-5]): reminder_seconds >= timeout_seconds means the FIRST
-                // reminder occurrence would never fire before the enforce clock expires.
-                if (typeof gate['reminder_seconds'] === 'number' &&
-                    typeof gate['timeout_seconds'] === 'number' &&
-                    gate['reminder_seconds'] >= gate['timeout_seconds']) {
-                    warnings.push({
-                        code: 'DEAD_GATE_CONFIG',
-                        severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                else {
+                    const exhaustionBlock = step['validation_exhaustion'];
+                    // WARN (do not reject) on an unknown validation_exhaustion sub-key — the retry-block-style
+                    // pattern (issue #140's UNKNOWN_RETRY_KEY), its OWN code (issue #220 PR-2 mints
+                    // UNKNOWN_VALIDATION_EXHAUSTION_KEY, replacing PR-1's UNKNOWN_STEP_KEY noun-override —
+                    // closes the #170-flip incoherence against the structurally identical retry-key family).
+                    warnings.push(...findUnknownKeys(exhaustionBlock, KNOWN_VALIDATION_EXHAUSTION_KEYS, {
                         scope: 'step',
+                        code: 'UNKNOWN_VALIDATION_EXHAUSTION_KEY',
                         step: stepName,
-                        message: `Step '${stepName}': 'gate.reminder_seconds' (${String(gate['reminder_seconds'])}) ` +
-                            `>= 'gate.timeout_seconds' (${String(gate['timeout_seconds'])}) — the first reminder ` +
-                            `would never fire before the gate expires.`,
-                    });
+                        noun: 'validation_exhaustion',
+                        positionOf: (key) => sourceMap.posOf(['steps', stepName, 'validation_exhaustion', key]),
+                    }));
+                    if ('threshold' in exhaustionBlock &&
+                        (!Number.isInteger(exhaustionBlock['threshold']) ||
+                            exhaustionBlock['threshold'] < 1)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.threshold' must be a positive integer ` +
+                            `(1 is legal — it disables in-drive schema-repair, since the first rejection ` +
+                            `already meets it)`));
+                    }
+                    const modeValue = exhaustionBlock['mode'];
+                    if (modeValue !== undefined && modeValue !== 'fail' && modeValue !== 'default') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.mode' must be 'fail' or 'default' ` +
+                            `(got: ${JSON.stringify(modeValue)})`));
+                    }
+                    const hasDefaultOutput = 'default_output' in exhaustionBlock;
+                    if (modeValue === 'default') {
+                        if (!hasDefaultOutput) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.mode: default' requires ` +
+                                `'default_output' (nothing to substitute on exhaustion)`));
+                        }
+                        else if (step['output_schema'] === undefined) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.default_output' requires the step to ` +
+                                `declare 'output_schema' (an undeclared schema makes the default unvalidatable)`));
+                        }
+                        else {
+                            // B10 — load-time AJV proof: REUSE the runtime validator so the load-time verdict can
+                            // never diverge from the runtime verdict for the exact same (default_output,
+                            // output_schema) pair. This is the loader's first load-time Ajv compile of an
+                            // output_schema (today output_schema is only compiled at runtime), so the catch below
+                            // legitimately sees TWO different populations: a VALIDATION_OUTPUT_SCHEMA
+                            // WorkflowError (default_output fails the schema) and a raw Ajv schema-compilation
+                            // Error (a structurally malformed output_schema) — both fail-closed to a load refusal,
+                            // but they carry their detail DIFFERENTLY: a WorkflowError has `.details.errors`; a raw
+                            // Error has NO `.details` at all (reading `.details.errors` on it throws a TypeError
+                            // that would escape the loader mid-walk — verified empirically). Discriminate.
+                            try {
+                                validateOutputSchema(exhaustionBlock['default_output'], step['output_schema'], stepName);
+                            }
+                            catch (err) {
+                                const detail = err instanceof WorkflowError
+                                    ? JSON.stringify(err.details['errors'])
+                                    : err instanceof Error
+                                        ? err.message
+                                        : String(err);
+                                errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.default_output' does not validate ` +
+                                    `against the step's own 'output_schema': ${detail}`));
+                            }
+                        }
+                    }
+                    else if (hasDefaultOutput) {
+                        // default_output present without mode: 'default' (mode: 'fail' or absent) — inert, not
+                        // an error: WARN as dead config rather than silently ignoring it.
+                        warnings.push({
+                            code: 'DEAD_VALIDATION_EXHAUSTION_CONFIG',
+                            severity: resolveSeverity('DEAD_VALIDATION_EXHAUSTION_CONFIG'),
+                            scope: 'step',
+                            step: stepName,
+                            message: `Step '${stepName}': 'validation_exhaustion.default_output' is ignored without ` +
+                                `'mode: default' — set 'validation_exhaustion.mode: default' to enable it, or ` +
+                                `remove 'default_output'.`,
+                        });
+                    }
                 }
             }
-        }
-        if ('uses_service' in step && typeof step['uses_service'] === 'string') {
-            const services = doc['services'];
-            if (typeof services !== 'object' ||
-                services === null ||
-                !(step['uses_service'] in services)) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': uses_service '${step['uses_service']}' is not defined in 'services'`));
-            }
-        }
-        // Validate retry: backoff must be a recognised value when present.
-        if (step['retry'] !== undefined) {
-            if (typeof step['retry'] !== 'object' || step['retry'] === null) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'retry' must be an object`));
-            }
-            else {
-                const retry = step['retry'];
-                // WARN (do not reject) on an unknown retry-block key — same non-breaking posture as the
-                // step/workflow-level checks (issue #140). Noun overridden to 'retry' (not 'step') since
-                // this is a nested block, not the step itself.
-                warnings.push(...findUnknownKeys(retry, KNOWN_RETRY_KEYS, {
+            // WARN (do not reject): an agent step declaring BOTH input_schema and output_schema has its
+            // submitted output validated against BOTH (execution-loop.ts validateInputSchema AND
+            // validateOutputSchema) — a divergence between the two degrades to a confusing recoverable
+            // VALIDATION_*_SCHEMA error rather than a clean failure. Detection/warn only; no schema change.
+            if (step['execution'] === 'agent' &&
+                step['input_schema'] !== undefined &&
+                step['output_schema'] !== undefined) {
+                warnings.push({
+                    code: 'DUAL_SCHEMA_DECLARED',
+                    severity: resolveSeverity('DUAL_SCHEMA_DECLARED'),
                     scope: 'step',
-                    code: 'UNKNOWN_RETRY_KEY',
                     step: stepName,
-                    noun: 'retry',
-                    positionOf: (key) => sourceMap.posOf(['steps', stepName, 'retry', key]),
-                }));
-                if ('backoff' in retry &&
-                    retry['backoff'] !== 'fixed' &&
-                    retry['backoff'] !== 'linear' &&
-                    retry['backoff'] !== 'exponential') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.backoff' must be 'fixed', 'linear', or 'exponential'`));
-                }
-                if ('max_attempts' in retry &&
-                    (!Number.isInteger(retry['max_attempts']) || retry['max_attempts'] < 1)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.max_attempts' must be a positive integer`));
-                }
-                if ('base_delay_ms' in retry &&
-                    (typeof retry['base_delay_ms'] !== 'number' || retry['base_delay_ms'] < 0)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.base_delay_ms' must be a non-negative number`));
-                }
-                if ('max_delay_ms' in retry &&
-                    (typeof retry['max_delay_ms'] !== 'number' || retry['max_delay_ms'] < 0)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.max_delay_ms' must be a non-negative number`));
-                }
-                // --- issue #140: on_timeout / total_timeout_seconds --------------------------------
-                // E3: on_timeout must be a boolean (kills the 'on_timeout: "true"' silent-inert case).
-                if ('on_timeout' in retry && typeof retry['on_timeout'] !== 'boolean') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.on_timeout' must be a boolean`));
-                }
-                // E2: total_timeout_seconds must be a positive integer — same convention as
-                // timeout_seconds (0 is rejected here at load; a hand-built definition bypassing the
-                // loader may still set 0 and have the engine's resolveCapMs honor it as a present cap).
-                if ('total_timeout_seconds' in retry &&
-                    (!Number.isInteger(retry['total_timeout_seconds']) ||
-                        retry['total_timeout_seconds'] <= 0)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.total_timeout_seconds' must be a positive integer`));
-                }
-                // E1: on_timeout: true requires idempotent: true — declared, never inferred. Strict
-                // `=== true` on both loci, provably matching the engine's own conjunct.
-                if (retry['on_timeout'] === true && step['idempotent'] !== true) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.on_timeout: true' requires 'idempotent: true' declared ` +
-                        `on the step — a timeout-retry can run concurrently with the still-in-flight ` +
-                        `original attempt, so the step must explicitly attest that any partial prior ` +
-                        `application is harmless to re-apply. Declare 'idempotent: true' or remove ` +
-                        `'on_timeout'.`));
+                    message: `Step '${stepName}': declares both input_schema and output_schema; the agent's submitted ` +
+                        `output is validated against both — prefer one to avoid divergence.`,
+                });
+            }
+            // trace_validation_mode must be 'warn' or 'enforce' when provided.
+            if (step['trace_validation_mode'] !== undefined &&
+                step['trace_validation_mode'] !== 'warn' &&
+                step['trace_validation_mode'] !== 'enforce') {
+                errors.push(withStepLine(stepName, `Step '${stepName}': invalid trace_validation_mode '${String(step['trace_validation_mode'])}'; must be 'warn' or 'enforce'`));
+            }
+            // issue #433: the effective STATIC gate choice source, hoisted per-step BEFORE the
+            // `gate:`-block-only region below. Member (b) below must fire even when there is NO `gate:`
+            // key at all (the executed g433b shape: a gate-trusted step with no gate block but an
+            // empty `input_schema.properties.choice.enum`), and the entire #291 region beneath this one
+            // is gated on `step['gate'] !== undefined` — it cannot host a check that must fire without
+            // one. Pure reads; the existing E2/membership cells (below) pin messages, not evaluation
+            // order, so hoisting these three declarations ahead of them is safe.
+            const gateObj = typeof step['gate'] === 'object' && step['gate'] !== null
+                ? step['gate']
+                : undefined;
+            const declaredGateChoices = gateObj?.['choices'];
+            const declaredChoiceEnum = step['input_schema']?.properties?.['choice']?.enum;
+            // Renders the OFFENDING KEY's own line via its full nested path, falling back to the
+            // step's line and then to no position — the same two-rung univocal vocabulary
+            // `withKeyLine` documents above (issue #420: `(line N)` for the key, `(step at line N)`
+            // for the step; never conflated). `withKeyLine` itself is single-segment
+            // (`['steps', stepName, key]`) and cannot express a nested path like
+            // `['steps', stepName, 'gate', 'choices']`, so this is a local sibling rather than a call
+            // to it — no existing `withKeyLine` call site is touched.
+            const withPathLine = (path, message) => {
+                const keyLine = sourceMap.posOf(path)?.line;
+                if (keyLine !== undefined)
+                    return `${message} (line ${keyLine})`;
+                const stepLine = sourceMap.posOf(['steps', stepName])?.line;
+                if (stepLine !== undefined)
+                    return `${message} (step at line ${stepLine})`;
+                return message;
+            };
+            // Member (a) (issue #433): a DECLARED `gate.choices` list that is empty is never right, on
+            // ANY step — gate-trusted or not (the #291 block's own posture just below: a `gate:` key
+            // is validated "regardless of trust"; the #417 strict-on-known-key policy agrees). An empty
+            // list on a gate-trusted step mints an unanswerable gate (every response is refused against
+            // an empty expected set) with no disposal path short of an authored expiry — on an ungated
+            // step it is dead weight either way, so the message is deliberately population-invariant
+            // rather than false for the ungated population.
+            if (Array.isArray(declaredGateChoices) && declaredGateChoices.length === 0) {
+                errors.push(withPathLine(['steps', stepName, 'gate', 'choices'], `Step '${stepName}': 'gate.choices', when declared, must be non-empty — an empty ` +
+                    'list is never right: on a gate-trusted step (trust: human_confirmed/human_reviewed) ' +
+                    'it mints a gate NO response can ever resolve (every submission is refused against ' +
+                    'an empty expected list, and the live run wedges with no disposal path: abandon ' +
+                    'refuses a pending gate; purge and drain refuse a live run; only an authored ' +
+                    "'gate.timeout_seconds' + 'on_expiry' expiry could ever clear it). Declare at least " +
+                    "one choice, or remove the key to fall back to 'input_schema.properties.choice.enum' " +
+                    'or the default pair (approve/reject).'));
+            }
+            // Member (b) (issue #433): for a GATE-TRUSTED step with no `gate.choices` list declared
+            // (NULLISH — the mint's own `??` semantics; `gate: {choices:}` with a YAML-null value is
+            // the third executed wedge shape, and presence-keying would let it escape this check), a
+            // DECLARED-and-empty `input_schema.properties.choice.enum` is the effective choice source
+            // and the same class of error, under its own key. `choices: null` with no `enum` at all
+            // stays legal — the mint defaults to ['approve', 'reject'].
+            if (isGateTrust(step['trust']) &&
+                declaredGateChoices == null &&
+                Array.isArray(declaredChoiceEnum) &&
+                declaredChoiceEnum.length === 0) {
+                errors.push(withPathLine(['steps', stepName, 'input_schema', 'properties', 'choice', 'enum'], `Step '${stepName}': 'input_schema.properties.choice.enum' is this gate's effective ` +
+                    "choice source (no 'gate.choices' list declared) and, when declared, must be " +
+                    'non-empty — an empty list mints a gate NO response can ever resolve (every ' +
+                    'submission is refused against an empty expected list, and the live run wedges ' +
+                    'with no disposal path: abandon refuses a pending gate; purge and drain refuse a ' +
+                    "live run; only an authored 'gate.timeout_seconds' + 'on_expiry' expiry could ever " +
+                    "clear it). Declare at least one enum value, or remove 'enum' to get the default " +
+                    'pair (approve/reject).'));
+            }
+            // issue #291 (authorable gate timeout — the FIRST validation the `gate:` block has ever had):
+            // the E2 positive-integer checks on timeout_seconds/reminder_seconds/reminder_max, the
+            // on_expiry enum, default_choice's required-iff + choice-set validation, and the dead-config
+            // warn cells. The hard-error checks run regardless of `trust` (a shape/enum mistake is a
+            // mistake whether or not this step can ever gate). The dead-config ADVISORIES fork on
+            // `isGateTrust` (issue #524): the engine mints a gate only where trust requires human
+            // confirmation (Step 5b, `execution-loop.ts`) — on any other step the WHOLE block is inert,
+            // so a per-member remedy ("set a timeout") would be false: following it never makes the key
+            // live, it only silences the one diagnostic that said so.
+            if (step['gate'] !== undefined) {
+                if (typeof step['gate'] !== 'object' || step['gate'] === null) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate' must be an object`));
                 }
-                // W5 (CAP-ONLY advisory — the on_timeout half of this is already an E1 hard error, so
-                // it never reaches here as a warning): the total-time cap only bounds `execution: 'auto'`
-                // dispatch — inert on any other step type that legally declares `retry:` today.
-                if (step['execution'] !== 'auto' && retry['total_timeout_seconds'] !== undefined) {
-                    warnings.push({
-                        code: 'TOTAL_TIMEOUT_NON_AUTO',
-                        severity: resolveSeverity('TOTAL_TIMEOUT_NON_AUTO'),
+                else {
+                    const gate = step['gate'];
+                    // WARN (do not reject) on an unknown gate-block key — same non-breaking posture as
+                    // retry/validation_exhaustion (issues #140/#220).
+                    warnings.push(...findUnknownKeys(gate, KNOWN_GATE_KEYS, {
                         scope: 'step',
+                        code: 'UNKNOWN_GATE_KEY',
                         step: stepName,
-                        message: `Step '${stepName}': 'retry.total_timeout_seconds' is inert on execution: ` +
-                            `'${String(step['execution'])}' steps — the cap only bounds 'execution: auto' ` +
-                            `dispatch, which is the only dispatch ever wrapped in a timeout.`,
-                    });
+                        noun: 'gate',
+                        positionOf: (key) => sourceMap.posOf(['steps', stepName, 'gate', key]),
+                    }));
+                    // E2: timeout_seconds/reminder_seconds/reminder_max must each be a positive integer
+                    // (yaml-loader :1164-1174 precedent — the SAME convention as retry.total_timeout_seconds).
+                    if ('timeout_seconds' in gate &&
+                        (!Number.isInteger(gate['timeout_seconds']) || gate['timeout_seconds'] <= 0)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.timeout_seconds' must be a positive integer`));
+                    }
+                    if ('reminder_seconds' in gate &&
+                        (!Number.isInteger(gate['reminder_seconds']) ||
+                            gate['reminder_seconds'] <= 0)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.reminder_seconds' must be a positive integer`));
+                    }
+                    if ('reminder_max' in gate &&
+                        (!Number.isInteger(gate['reminder_max']) || gate['reminder_max'] <= 0)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.reminder_max' must be a positive integer`));
+                    }
+                    // on_expiry must be 'settle_default' or 'abort' when provided.
+                    const onExpiry = gate['on_expiry'];
+                    if (onExpiry !== undefined && onExpiry !== 'settle_default' && onExpiry !== 'abort') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry' must be 'settle_default' or 'abort' (got: ${JSON.stringify(onExpiry)})`));
+                    }
+                    // default_choice: REQUIRED iff on_expiry === 'settle_default' (E2-style hard error,
+                    // mirroring validation_exhaustion.mode:'default' requiring default_output); validated
+                    // against the step's own EFFECTIVE STATIC choice set — the EXACT same three-source
+                    // derivation the engine mints PendingGate.choices from (execution-loop.ts's gate-open
+                    // site: gate.choices ?? input_schema.properties.choice.enum ?? ['approve','reject']),
+                    // sourced from the issue #433 hoist above (`declaredGateChoices ?? declaredChoiceEnum`
+                    // — one chain, so this can never drift from the mint's) — so a load-time-legal
+                    // default_choice can NEVER fail at enactment time.
+                    const hasDefaultChoice = 'default_choice' in gate;
+                    // issue #524: the one place this block's dead-config ADVISORIES fork. The mint only
+                    // ever reads `gate.*` where `isGateTrust(trust)` holds (execution-loop.ts:3302,
+                    // `W_GATE_MINT_TRUST`) — computed once so the three sites below can never disagree.
+                    const gateTrusted = isGateTrust(step['trust']);
+                    if (onExpiry === 'settle_default') {
+                        if (!hasDefaultChoice) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry: settle_default' requires 'gate.default_choice' ` +
+                                `(nothing to resolve the gate with on expiry)`));
+                        }
+                        else {
+                            const choicesRaw = declaredGateChoices ?? declaredChoiceEnum;
+                            const effectiveChoices = Array.isArray(choicesRaw)
+                                ? choicesRaw
+                                : ['approve', 'reject'];
+                            if (!effectiveChoices.includes(gate['default_choice'])) {
+                                errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.default_choice' (${JSON.stringify(gate['default_choice'])}) ` +
+                                    `is not one of the step's effective choices: ${effectiveChoices.join(', ')}`));
+                            }
+                        }
+                    }
+                    else if (hasDefaultChoice && gateTrusted) {
+                        // default_choice with on_expiry:'abort' or with no on_expiry at all — inert, not an
+                        // error: WARN as dead config (the #220 DEAD_VALIDATION_EXHAUSTION_CONFIG precedent).
+                        // Gate-trusted only (issue #524) — off gate trust the block advisory below covers it.
+                        warnings.push({
+                            code: 'DEAD_GATE_CONFIG',
+                            severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                            scope: 'step',
+                            step: stepName,
+                            message: `Step '${stepName}': 'gate.default_choice' is ignored without ` +
+                                `'gate.on_expiry: settle_default' — set it, or remove 'gate.default_choice'.`,
+                        });
+                    }
+                    if (gateTrusted) {
+                        // Dead config: on_expiry declared but no timeout_seconds — nothing will ever trigger
+                        // the enforce clock, so the declared disposition can never enact. Gate-trusted only
+                        // (issue #524): off gate trust the block advisory below covers it.
+                        if (onExpiry !== undefined && gate['timeout_seconds'] === undefined) {
+                            warnings.push({
+                                code: 'DEAD_GATE_CONFIG',
+                                severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                                scope: 'step',
+                                step: stepName,
+                                message: `Step '${stepName}': 'gate.on_expiry' is ignored without 'gate.timeout_seconds' ` +
+                                    `— set a timeout, or remove 'gate.on_expiry'.`,
+                            });
+                        }
+                        // Dead notification ([F-A2-5]): reminder_seconds >= timeout_seconds means the FIRST
+                        // reminder occurrence would never fire before the enforce clock expires. Gate-trusted
+                        // only (issue #524): off gate trust the block advisory below covers it.
+                        if (typeof gate['reminder_seconds'] === 'number' &&
+                            typeof gate['timeout_seconds'] === 'number' &&
+                            gate['reminder_seconds'] >= gate['timeout_seconds']) {
+                            warnings.push({
+                                code: 'DEAD_GATE_CONFIG',
+                                severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                                scope: 'step',
+                                step: stepName,
+                                message: `Step '${stepName}': 'gate.reminder_seconds' (${String(gate['reminder_seconds'])}) ` +
+                                    `>= 'gate.timeout_seconds' (${String(gate['timeout_seconds'])}) — the first ` +
+                                    `reminder would never fire before the gate expires.`,
+                            });
+                        }
+                    }
+                    else {
+                        // issue #524 (the gate-remedy silence): without gate trust the mint never reads ANY
+                        // key in this block, so a per-member remedy ("set a timeout") is false — following it
+                        // would silence the diagnostic while the whole block stays exactly as dead. ONE
+                        // advisory naming the true cause, unconditional on which keys are set (the block is
+                        // equally inert whichever ones are). Position on the STRUCTURED channel only
+                        // (`withKeyLine`/`withPathLine` are the ERROR-string helpers, consumed only by
+                        // `errors.push` — no loader advisory carries a position today, and this one follows
+                        // that convention: `renderLoaderWarning` prints `⚠ ${message}` alone). The kind list
+                        // is DERIVED from the registry (`consumedKindsFor('trust')`, the #517
+                        // `consumed_home.kinds` pattern) so the remedy can never drift from the vocabulary
+                        // that actually gates it.
+                        const gatePos = sourceMap.posOf(['steps', stepName, 'gate']);
+                        const trustKinds = consumedKindsFor('trust');
+                        warnings.push({
+                            code: 'DEAD_GATE_CONFIG',
+                            severity: resolveSeverity('DEAD_GATE_CONFIG'),
+                            scope: 'step',
+                            step: stepName,
+                            key: 'gate',
+                            ...(gatePos !== undefined
+                                ? {
+                                    line: gatePos.line,
+                                    column: gatePos.column,
+                                    endLine: gatePos.endLine,
+                                    endColumn: gatePos.endColumn,
+                                }
+                                : {}),
+                            message: `Step '${stepName}': the 'gate:' block is inert — this step declares no gate ` +
+                                `trust ('trust: human_confirmed' or 'trust: human_reviewed'), so no gate is ever ` +
+                                `minted and none of its keys are read. Remove the block, or (on an ` +
+                                `${trustKinds.join(' or ')} step) declare that trust.`,
+                        });
+                    }
                 }
-                // issue #218 (extends the W5 family): the BARE-KEYS advisory — no explicit
-                // total_timeout_seconds (that shape is W5's, above), but retry: is present on a step the
-                // built-in dispatch path never wraps in a throwing retry loop at all. Complementary to
-                // W5's own `!== undefined` conjunct on the SAME `execution !== 'auto'` gate, so for any
-                // non-auto retry block that reaches this point (finalizer+retry and invalid-cap shapes
-                // already hard-errored above; on_timeout: true already hard-errored via E1 unless
-                // idempotent is also declared, which is itself rejected by the pre-existing
-                // idempotent-non-auto check) exactly ONE of {W5, RETRY_INERT_NON_AUTO} ever fires — never
-                // both, never neither.
-                if (step['execution'] !== 'auto' && retry['total_timeout_seconds'] === undefined) {
-                    const isAgent = step['execution'] === 'agent';
-                    const message = isAgent
-                        ? `Step '${stepName}': 'retry' is inert on execution: 'agent' steps — the built-in ` +
-                            `dispatch path never throws for agent steps, so this block can never mint a second ` +
-                            `attempt here (for schema-repair budgets, use the CLI drive's '--schema-retries' ` +
-                            `flag instead). An embedder-supplied throwing dispatcher may still consume this ` +
-                            `config — a deliberate public-API capability, not an invalid one.`
-                        : `Step '${stepName}': 'retry' is inert on execution: '${String(step['execution'])}' ` +
-                            `steps — the built-in dispatch path never throws for these steps, so this block can ` +
-                            `never mint a second attempt here. An embedder-supplied throwing dispatcher may ` +
-                            `still consume this config — a deliberate public-API capability, not an invalid one.`;
-                    warnings.push({
-                        code: 'RETRY_INERT_NON_AUTO',
-                        severity: resolveSeverity('RETRY_INERT_NON_AUTO'),
-                        scope: 'step',
-                        step: stepName,
-                        message,
-                    });
+            }
+            if ('uses_service' in step && typeof step['uses_service'] === 'string') {
+                const services = doc['services'];
+                if (typeof services !== 'object' ||
+                    services === null ||
+                    !(step['uses_service'] in services)) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': uses_service '${step['uses_service']}' is not defined in 'services'`));
+                }
+            }
+            // Validate retry: backoff must be a recognised value when present.
+            if (step['retry'] !== undefined) {
+                if (typeof step['retry'] !== 'object' || step['retry'] === null) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry' must be an object`));
                 }
-                // W1: on_timeout with an effective max_attempts of 1 (explicit OR absent, since the
-                // loader admits an absent max_attempts and the engine then defaults it to 1) — there is
-                // no second attempt for the opt-in to retry into.
-                const effectiveMaxAttempts = typeof retry['max_attempts'] === 'number' ? retry['max_attempts'] : 1;
-                if (retry['on_timeout'] === true && effectiveMaxAttempts === 1) {
-                    warnings.push({
-                        code: 'ON_TIMEOUT_SINGLE_ATTEMPT',
-                        severity: resolveSeverity('ON_TIMEOUT_SINGLE_ATTEMPT'),
+                else {
+                    const retry = step['retry'];
+                    // The one population gate both retry advisories (W5 + RETRY_INERT_NON_AUTO) share:
+                    // the registry's own retry cell for this step's kind. `inert` = admitted-but-unread
+                    // (agent/guard). On `consumed` (auto) neither advisory applies; on `prohibited`
+                    // (finalizer) the #517 refusal above is the whole story and an advisory beside it
+                    // would contradict it; on a malformed kind the invalid-execution error is the verdict.
+                    const retryCellIsInert = VALID_EXECUTIONS.has(step['execution']) &&
+                        STEP_KEY_REGISTRY.retry[step['execution']].c === 'inert';
+                    // WARN (do not reject) on an unknown retry-block key — same non-breaking posture as the
+                    // step/workflow-level checks (issue #140). Noun overridden to 'retry' (not 'step') since
+                    // this is a nested block, not the step itself.
+                    warnings.push(...findUnknownKeys(retry, KNOWN_RETRY_KEYS, {
                         scope: 'step',
+                        code: 'UNKNOWN_RETRY_KEY',
                         step: stepName,
-                        message: `Step '${stepName}': 'retry.on_timeout: true' has no effect with an effective ` +
-                            `'max_attempts' of 1 — there is no second attempt to retry into.`,
-                    });
-                }
-                // W2: the cap can never cover even a single full-length attempt — (a) an EXPLICIT cap
-                // below an EXPLICIT timeout_seconds, or (b) on_timeout: true with a cap at-or-below the
-                // effective per-attempt timeout (retry-defeating: the opt-in can never yield a viable
-                // second attempt). Both conditions require an EXPLICIT total_timeout_seconds — the
-                // AMENDED default cap (the worst-case schedule) is, by construction, never below a
-                // single attempt for max_attempts ≥ 2, so this never fires on the bare 3600s-default
-                // population.
-                const explicitCapSeconds = typeof retry['total_timeout_seconds'] === 'number'
-                    ? retry['total_timeout_seconds']
-                    : undefined;
-                if (explicitCapSeconds !== undefined) {
-                    const explicitTimeoutSeconds = typeof step['timeout_seconds'] === 'number' ? step['timeout_seconds'] : undefined;
-                    const effectivePerAttemptSeconds = explicitTimeoutSeconds ?? DEFAULT_EXECUTION_TIMEOUT_SECONDS;
-                    const belowExplicitAttempt = explicitTimeoutSeconds !== undefined && explicitCapSeconds < explicitTimeoutSeconds;
-                    const capTooTightForRetry = retry['on_timeout'] === true && explicitCapSeconds <= effectivePerAttemptSeconds;
-                    if (belowExplicitAttempt || capTooTightForRetry) {
+                        noun: 'retry',
+                        positionOf: (key) => sourceMap.posOf(['steps', stepName, 'retry', key]),
+                    }));
+                    if ('backoff' in retry &&
+                        retry['backoff'] !== 'fixed' &&
+                        retry['backoff'] !== 'linear' &&
+                        retry['backoff'] !== 'exponential') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.backoff' must be 'fixed', 'linear', or 'exponential'`));
+                    }
+                    if ('max_attempts' in retry &&
+                        (!Number.isInteger(retry['max_attempts']) || retry['max_attempts'] < 1)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.max_attempts' must be a positive integer`));
+                    }
+                    if ('base_delay_ms' in retry &&
+                        (typeof retry['base_delay_ms'] !== 'number' || retry['base_delay_ms'] < 0)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.base_delay_ms' must be a non-negative number`));
+                    }
+                    if ('max_delay_ms' in retry &&
+                        (typeof retry['max_delay_ms'] !== 'number' || retry['max_delay_ms'] < 0)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.max_delay_ms' must be a non-negative number`));
+                    }
+                    // --- issue #140: on_timeout / total_timeout_seconds --------------------------------
+                    // E3: on_timeout must be a boolean (kills the 'on_timeout: "true"' silent-inert case).
+                    if ('on_timeout' in retry && typeof retry['on_timeout'] !== 'boolean') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.on_timeout' must be a boolean`));
+                    }
+                    // E2: total_timeout_seconds must be a positive integer — same convention as
+                    // timeout_seconds (0 is rejected here at load; a hand-built definition bypassing the
+                    // loader may still set 0 and have the engine's resolveCapMs honor it as a present cap).
+                    if ('total_timeout_seconds' in retry &&
+                        (!Number.isInteger(retry['total_timeout_seconds']) ||
+                            retry['total_timeout_seconds'] <= 0)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.total_timeout_seconds' must be a positive integer`));
+                    }
+                    // E1: on_timeout: true requires idempotent: true — declared, never inferred. Strict
+                    // `=== true` on both loci, provably matching the engine's own conjunct.
+                    if (retry['on_timeout'] === true && step['idempotent'] !== true) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.on_timeout: true' requires 'idempotent: true' declared ` +
+                            `on the step — a timeout-retry can run concurrently with the still-in-flight ` +
+                            `original attempt, so the step must explicitly attest that any partial prior ` +
+                            `application is harmless to re-apply. Declare 'idempotent: true' or remove ` +
+                            `'on_timeout'.`));
+                    }
+                    // W5 (CAP-ONLY advisory — the on_timeout half of this is already an E1 hard error, so
+                    // it never reaches here as a warning): the total-time cap only bounds `execution: 'auto'`
+                    // dispatch — inert on any other step type that LEGALLY declares `retry:`. The gate is
+                    // the registry's own retry cell: the advisory fires only where retry is admitted-but-
+                    // inert (agent/guard), never beside the finalizer refusal it would contradict, and
+                    // never on a malformed kind (already refused by the invalid-execution error).
+                    if (retryCellIsInert && retry['total_timeout_seconds'] !== undefined) {
                         warnings.push({
-                            code: 'TOTAL_TIMEOUT_BELOW_ATTEMPT',
-                            severity: resolveSeverity('TOTAL_TIMEOUT_BELOW_ATTEMPT'),
+                            code: 'TOTAL_TIMEOUT_NON_AUTO',
+                            severity: resolveSeverity('TOTAL_TIMEOUT_NON_AUTO'),
                             scope: 'step',
                             step: stepName,
-                            message: `Step '${stepName}': 'retry.total_timeout_seconds: ${explicitCapSeconds}' is at ` +
-                                `or below its own effective per-attempt timeout (${effectivePerAttemptSeconds}s) ` +
-                                `— the cap can never cover a single full-length attempt, so a retry can never ` +
-                                `occur before the cap fires.`,
+                            message: `Step '${stepName}': 'retry.total_timeout_seconds' is inert on execution: ` +
+                                `'${String(step['execution'])}' steps — the cap only bounds 'execution: auto' ` +
+                                `dispatch; no other kind's dispatch ever consumes it.`,
                         });
                     }
+                    // issue #218 (extends the W5 family): the BARE-KEYS advisory — no explicit
+                    // total_timeout_seconds (that shape is W5's, above), but retry: is present on a step no
+                    // dispatching retry loop ever consumes it on. Complementary to W5's own `!== undefined`
+                    // conjunct on the SAME registry-derived inert gate, so for any admitted-but-inert retry
+                    // block exactly ONE of {W5, RETRY_INERT_NON_AUTO} ever fires — never both, never
+                    // neither. The gate EXCLUDES the prohibited kind (finalizer): errors accumulate rather
+                    // than halt, so the old `!== 'auto'` gate leaked this advisory beside the finalizer
+                    // refusal, where every clause of it was false ("never throws" — the drain throws
+                    // routinely; "may still consume" — no dispatcher can reach a finalizer's retry;
+                    // "not an invalid one" — the co-fired error says it IS invalid). Registry-derived:
+                    // it fires exactly where the retry cell is inert (agent/guard).
+                    if (retryCellIsInert && retry['total_timeout_seconds'] === undefined) {
+                        const isAgent = step['execution'] === 'agent';
+                        const message = isAgent
+                            ? `Step '${stepName}': 'retry' is inert on execution: 'agent' steps — the built-in ` +
+                                `dispatch path never throws for agent steps, so this block can never mint a second ` +
+                                `attempt here (for schema-repair budgets, use the CLI drive's '--schema-retries' ` +
+                                `flag instead). An embedder-supplied throwing dispatcher may still consume this ` +
+                                `config — a deliberate public-API capability, not an invalid one.`
+                            : `Step '${stepName}': 'retry' is inert on execution: '${String(step['execution'])}' ` +
+                                `steps — a guard's evaluation never traverses the dispatch path (its conditions ` +
+                                `are evaluated inline, with no dispatcher and no retry read), so this block can ` +
+                                `never mint a second attempt here.`;
+                        warnings.push({
+                            code: 'RETRY_INERT_NON_AUTO',
+                            severity: resolveSeverity('RETRY_INERT_NON_AUTO'),
+                            scope: 'step',
+                            step: stepName,
+                            message,
+                        });
+                    }
+                    // W1: on_timeout with an effective max_attempts of 1 (explicit OR absent, since the
+                    // loader admits an absent max_attempts and the engine then defaults it to 1) — there is
+                    // no second attempt for the opt-in to retry into.
+                    const effectiveMaxAttempts = typeof retry['max_attempts'] === 'number' ? retry['max_attempts'] : 1;
+                    if (retry['on_timeout'] === true && effectiveMaxAttempts === 1) {
+                        warnings.push({
+                            code: 'ON_TIMEOUT_SINGLE_ATTEMPT',
+                            severity: resolveSeverity('ON_TIMEOUT_SINGLE_ATTEMPT'),
+                            scope: 'step',
+                            step: stepName,
+                            message: `Step '${stepName}': 'retry.on_timeout: true' has no effect with an effective ` +
+                                `'max_attempts' of 1 — there is no second attempt to retry into.`,
+                        });
+                    }
+                    // W2 (issue #524 correction): the declared cap is at or below the per-attempt timeout —
+                    // (a) an EXPLICIT cap below an EXPLICIT timeout_seconds, or (b) on_timeout: true with a
+                    // cap at-or-below the effective per-attempt timeout. This does NOT mean "no retry can
+                    // ever occur": `willRetry`'s first disjunct (execution-loop.ts) has no cap conjunct, so
+                    // a retryable failure that returns faster than the (clipped) attempt bound still retries
+                    // while 'max_attempts' allows another attempt — only an attempt that runs OUT its full
+                    // bound exhausts the cap with nothing left for a retry. Both arms require an EXPLICIT
+                    // total_timeout_seconds — the AMENDED default cap (the worst-case schedule) is, by
+                    // construction, never below a single attempt for max_attempts ≥ 2, so this never fires
+                    // on the bare 3600s-default population.
+                    const explicitCapSeconds = typeof retry['total_timeout_seconds'] === 'number'
+                        ? retry['total_timeout_seconds']
+                        : undefined;
+                    if (explicitCapSeconds !== undefined) {
+                        const explicitTimeoutSeconds = typeof step['timeout_seconds'] === 'number' ? step['timeout_seconds'] : undefined;
+                        const effectivePerAttemptSeconds = explicitTimeoutSeconds ?? DEFAULT_EXECUTION_TIMEOUT_SECONDS;
+                        const belowExplicitAttempt = explicitTimeoutSeconds !== undefined && explicitCapSeconds < explicitTimeoutSeconds;
+                        const capTooTightForRetry = retry['on_timeout'] === true && explicitCapSeconds <= effectivePerAttemptSeconds;
+                        if (belowExplicitAttempt || capTooTightForRetry) {
+                            warnings.push({
+                                code: 'TOTAL_TIMEOUT_BELOW_ATTEMPT',
+                                severity: resolveSeverity('TOTAL_TIMEOUT_BELOW_ATTEMPT'),
+                                scope: 'step',
+                                step: stepName,
+                                message: `Step '${stepName}': 'retry.total_timeout_seconds: ${explicitCapSeconds}' is at ` +
+                                    `or below its per-attempt timeout (${effectivePerAttemptSeconds}s` +
+                                    `${explicitTimeoutSeconds === undefined ? ', the default' : ''}) — each attempt ` +
+                                    `is bounded by what remains of the cap, so an attempt that runs to its bound ` +
+                                    `exhausts the cap with no retry; a faster failure still retries while ` +
+                                    `'max_attempts' allows another attempt and its backoff wait fits the remaining cap.`,
+                            });
+                        }
+                    }
                 }
             }
-        }
-        if ('service_method' in step && !VALID_SERVICE_METHODS.has(step['service_method'])) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': invalid service_method '${String(step['service_method'])}'; must be 'fetch', 'create', 'update', or 'delete'`));
-        }
-        // Validate input_map: only valid on execution: auto steps (both uses_service and handler).
-        if (step['input_map'] !== undefined) {
-            if (step['execution'] !== 'auto') {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'input_map' is only valid on execution: auto steps`));
+            if ('service_method' in step &&
+                !VALID_SERVICE_METHODS.has(step['service_method'])) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': invalid service_method '${String(step['service_method'])}'; must be 'fetch', 'create', 'update', or 'delete'`));
             }
-            else {
+            // Validate input_map VALUES (auto only — the kind half is minted by the #517 walk; the
+            // explicit conjunct preserves the old else-branch: a wrong-kind step gets only the minted
+            // refusal, never the value noise).
+            if (step['input_map'] !== undefined && step['execution'] === 'auto') {
                 // issue #392: input_map's errors are minted deep inside a recursive walk that knows only
                 // its path string, not the step's position. Collected here and suffixed on the way out,
                 // so ONE step's error list never mixes positioned and bare messages — a reader seeing
-                // "(line 12)" on three of five errors would reasonably wonder what is different about
+                // "(step at line 12)" on three of five errors would reasonably wonder what is different about
                 // the other two, and nothing is.
                 const inputMapErrors = [];
                 validateInputMapNode(step['input_map'], `Step '${stepName}': input_map`, inputMapErrors, 0);
                 errors.push(...inputMapErrors.map((e) => withStepLine(stepName, e)));
             }
-        }
-        // Step config may hold any JSON value (scalars, arrays, nested objects). It is passed through
-        // opaquely to handlers (context.config) and merged into adapter config for uses_service steps;
-        // the adapter's config_schema (below) remains the real validator for uses_service config.
-        // Validate step config against adapter config_schema (requires registry).
-        if (step['config'] !== undefined && step['uses_service'] !== undefined) {
-            const serviceName = step['uses_service'];
-            const services = doc['services'];
-            const service = services?.[serviceName];
-            const adapterName = service?.['adapter'];
-            const adapter = adapterName !== undefined ? registry?.getAdapter(adapterName) : undefined;
-            if (adapter !== undefined && adapter.config_schema === undefined) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'config' declared but adapter '${adapterName}' does not declare 'config_schema'`));
-            }
-            else if (adapter?.config_schema !== undefined) {
-                const ajv = new Ajv();
-                const valid = ajv.validate(adapter.config_schema, step['config']);
-                if (!valid) {
-                    const errMessages = ajv.errors?.map((e) => e.message ?? '').join('; ') ?? 'unknown error';
-                    errors.push(withStepLine(stepName, `Step '${stepName}': config validation failed against adapter config_schema: ${errMessages}`));
+            // Step config may hold any JSON value (scalars, arrays, nested objects). It is passed through
+            // opaquely to handlers (context.config) and merged into adapter config for uses_service steps;
+            // the adapter's config_schema (below) remains the real validator for uses_service config.
+            // Validate step config against adapter config_schema (requires registry).
+            if (step['config'] !== undefined && step['uses_service'] !== undefined) {
+                const serviceName = step['uses_service'];
+                const services = doc['services'];
+                const service = services?.[serviceName];
+                const adapterName = service?.['adapter'];
+                const adapter = adapterName !== undefined ? registry?.getAdapter(adapterName) : undefined;
+                if (adapter !== undefined && adapter.config_schema === undefined) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'config' declared but adapter '${adapterName}' does not declare 'config_schema'`));
+                }
+                else if (adapter?.config_schema !== undefined) {
+                    const ajv = new Ajv();
+                    const valid = ajv.validate(adapter.config_schema, step['config']);
+                    if (!valid) {
+                        const errMessages = ajv.errors?.map((e) => e.message ?? '').join('; ') ?? 'unknown error';
+                        errors.push(withStepLine(stepName, `Step '${stepName}': config validation failed against adapter config_schema: ${errMessages}`));
+                    }
                 }
             }
-        }
-        // Validate uses_resources: each listed step ID must exist in the workflow.
-        if (step['handler'] !== undefined && registry !== undefined) {
-            const handlerName = step['handler'];
-            const handler = registry.getHandler(handlerName);
-            if (handler !== undefined && handler.uses_resources !== undefined) {
-                for (const resourceStepId of handler.uses_resources) {
-                    if (!(resourceStepId in stepsRaw)) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': handler '${handlerName}' declares uses_resources '${resourceStepId}' ` +
-                            `but no step with that ID exists in this workflow`));
+            // Validate uses_resources: each listed step ID must exist in the workflow.
+            if (step['handler'] !== undefined && registry !== undefined) {
+                const handlerName = step['handler'];
+                const handler = registry.getHandler(handlerName);
+                if (handler !== undefined && handler.uses_resources !== undefined) {
+                    for (const resourceStepId of handler.uses_resources) {
+                        if (!(resourceStepId in stepsRaw)) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': handler '${handlerName}' declares uses_resources '${resourceStepId}' ` +
+                                `but no step with that ID exists in this workflow`));
+                        }
                     }
                 }
             }
-        }
-        // Validate trigger_rule.
-        if ('trigger_rule' in step) {
-            if (!VALID_TRIGGER_RULES.has(step['trigger_rule'])) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': invalid trigger_rule '${String(step['trigger_rule'])}'; must be one of ${[...VALID_TRIGGER_RULES].join(', ')}`));
+            // Validate trigger_rule.
+            if ('trigger_rule' in step) {
+                if (!VALID_TRIGGER_RULES.has(step['trigger_rule'])) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': invalid trigger_rule '${String(step['trigger_rule'])}'; must be one of ${[...VALID_TRIGGER_RULES].join(', ')}`));
+                }
             }
-        }
-        // Validate depends_on: must be an array of existing step names.
-        if ('depends_on' in step && step['depends_on'] !== undefined) {
-            if (!Array.isArray(step['depends_on'])) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'depends_on' must be an array`));
+            // Validate depends_on: must be an array of existing step names.
+            if ('depends_on' in step && step['depends_on'] !== undefined) {
+                if (!Array.isArray(step['depends_on'])) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'depends_on' must be an array`));
+                }
+                else {
+                    for (const dep of step['depends_on']) {
+                        if (typeof dep !== 'string') {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': depends_on entries must be strings`));
+                        }
+                        else if (dep === stepName) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': a step cannot depend on itself`));
+                        }
+                        else if (!(dep in stepsRaw)) {
+                            errors.push(withStepLine(stepName, `Step '${stepName}': depends_on references unknown step '${dep}'`));
+                        }
+                        else if (stepsRaw[dep]['execution'] === 'finalizer') {
+                            // A domain step depending on a held-out finalizer would deadlock: the finalizer
+                            // never enters the eligible set, so this step never becomes eligible and the run
+                            // never seals.
+                            errors.push(withStepLine(stepName, `Step '${stepName}': depends_on references finalizer step '${dep}' — finalizers ` +
+                                `run at the terminal transition and are held out of the DAG; a step cannot depend on one.`));
+                        }
+                    }
+                }
             }
-            else {
-                for (const dep of step['depends_on']) {
-                    if (typeof dep !== 'string') {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': depends_on entries must be strings`));
+            // Validate when: string | string[] of single-comparison/bare-path leaves (implicit AND).
+            if ('when' in step && step['when'] !== undefined) {
+                const rawWhen = step['when'];
+                if (typeof rawWhen === 'string') {
+                    if (rawWhen.trim() === '') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a non-empty string`));
                     }
-                    else if (dep === stepName) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': a step cannot depend on itself`));
+                    else {
+                        validateConditionLeaf('when', rawWhen, stepName, dependsOn, stepKind, errors, withStepLine);
                     }
-                    else if (!(dep in stepsRaw)) {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': depends_on references unknown step '${dep}'`));
+                }
+                else if (Array.isArray(rawWhen)) {
+                    if (rawWhen.length === 0) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array must not be empty`));
                     }
-                    else if (stepsRaw[dep]['execution'] === 'finalizer') {
-                        // A domain step depending on a held-out finalizer would deadlock: the finalizer
-                        // never enters the eligible set, so this step never becomes eligible and the run
-                        // never seals.
-                        errors.push(withStepLine(stepName, `Step '${stepName}': depends_on references finalizer step '${dep}' — finalizers ` +
-                            `run at the terminal transition and are held out of the DAG; a step cannot depend on one.`));
+                    else {
+                        for (const leaf of rawWhen) {
+                            if (typeof leaf !== 'string' || leaf.trim() === '') {
+                                errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array entries must be non-empty strings`));
+                            }
+                            else {
+                                validateConditionLeaf('when', leaf, stepName, dependsOn, stepKind, errors, withStepLine);
+                            }
+                        }
                     }
                 }
+                else {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a string or an array of strings`));
+                }
             }
-        }
-        // Validate when: string | string[] of single-comparison/bare-path leaves (implicit AND).
-        if ('when' in step && step['when'] !== undefined) {
-            const rawWhen = step['when'];
-            if (typeof rawWhen === 'string') {
-                if (rawWhen.trim() === '') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a non-empty string`));
+            // Validate abort_unless leaf shape (guard steps only; the LEGACY depends_on/run.params
+            // reference check is when-only — but issue #220 §4c's `$settlement` one-hop check fires here
+            // too, via the hoisted `dependsOn`, SCOPED to `$settlement.`-prefixed paths only).
+            if (step['abort_unless'] !== undefined && step['execution'] === 'guard') {
+                const rawAbort = step['abort_unless'];
+                if (typeof rawAbort === 'string') {
+                    if (rawAbort.trim() === '') {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a non-empty string`));
+                    }
+                    else {
+                        validateConditionLeaf('abort_unless', rawAbort, stepName, dependsOn, stepKind, errors, withStepLine);
+                    }
+                }
+                else if (Array.isArray(rawAbort)) {
+                    if (rawAbort.length === 0) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array must not be empty`));
+                    }
+                    else {
+                        for (const leaf of rawAbort) {
+                            if (typeof leaf !== 'string' || leaf.trim() === '') {
+                                errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array entries must be non-empty strings`));
+                            }
+                            else {
+                                validateConditionLeaf('abort_unless', leaf, stepName, dependsOn, stepKind, errors, withStepLine);
+                            }
+                        }
+                    }
                 }
                 else {
-                    validateConditionLeaf('when', rawWhen, stepName, dependsOn, errors, withStepLine);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a string or an array of strings`));
                 }
             }
-            else if (Array.isArray(rawWhen)) {
-                if (rawWhen.length === 0) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array must not be empty`));
+            // Validate preconditions leaf shape (each must be a single comparison). Reference check is
+            // `$settlement`-scoped only (issue #220 §4c) — a non-`$settlement` precondition has no
+            // depends_on/run.params check (unchanged from before this PR).
+            if (step['preconditions'] !== undefined) {
+                const rawPre = step['preconditions'];
+                if (!Array.isArray(rawPre)) {
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' must be an array of strings`));
                 }
                 else {
-                    for (const leaf of rawWhen) {
+                    for (const leaf of rawPre) {
                         if (typeof leaf !== 'string' || leaf.trim() === '') {
-                            errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array entries must be non-empty strings`));
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' entries must be non-empty strings`));
                         }
                         else {
-                            validateConditionLeaf('when', leaf, stepName, dependsOn, errors, withStepLine);
+                            validateConditionLeaf('preconditions', leaf, stepName, dependsOn, stepKind, errors, withStepLine);
                         }
                     }
                 }
             }
-            else {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a string or an array of strings`));
-            }
-        }
-        // Validate abort_unless leaf shape (guard steps only; the LEGACY depends_on/run.params
-        // reference check is when-only — but issue #220 §4c's `$settlement` one-hop check fires here
-        // too, via the hoisted `dependsOn`, SCOPED to `$settlement.`-prefixed paths only).
-        if (step['abort_unless'] !== undefined && step['execution'] === 'guard') {
-            const rawAbort = step['abort_unless'];
-            if (typeof rawAbort === 'string') {
-                if (rawAbort.trim() === '') {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a non-empty string`));
-                }
-                else {
-                    validateConditionLeaf('abort_unless', rawAbort, stepName, dependsOn, errors, withStepLine);
-                }
-            }
-            else if (Array.isArray(rawAbort)) {
-                if (rawAbort.length === 0) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array must not be empty`));
+            // issue #362 — REJECT A PROVABLY-DEAD FAILURE CONDITION.
+            //
+            // `$settlement.<dep>.failed == true` under a trigger rule that structurally excludes a failed
+            // `<dep>` can never be true. The trigger gate runs BEFORE the condition gate, and both
+            // `all_success` and `none_failed` carry an explicit "no dep in failed_steps" conjunct — so if
+            // the rule is satisfied, `<dep>` did not fail, and the condition is false by construction.
+            //
+            // The author's compensation step therefore never runs. It is not silent at runtime — the run
+            // record says `trigger_rule_unsatisfiable` — but it names the RULE and the blocking dep, never
+            // the condition the author wrote, so the diagnosis points away from the mistake. This is an
+            // authoring-time error precisely because the fix is one word and no legitimate use of the
+            // shape exists.
+            dead_condition: {
+                const rule = step['execution'] === 'guard' ? 'all_success' : (step['trigger_rule'] ?? 'all_success');
+                // A guard may not declare `trigger_rule` at all (it is a prohibited field), so a guard that
+                // declares one must NOT be able to suppress this check by doing so.
+                const ruleDeclared = step['execution'] !== 'guard' && step['trigger_rule'] !== undefined;
+                if (step['execution'] !== 'guard' && !VALID_TRIGGER_RULES.has(rule)) {
+                    break dead_condition; // an invalid rule already has its own error — adding noise helps nobody
                 }
-                else {
-                    for (const leaf of rawAbort) {
-                        if (typeof leaf !== 'string' || leaf.trim() === '') {
-                            errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array entries must be non-empty strings`));
+                if (rule !== 'all_success' && rule !== 'none_failed')
+                    break dead_condition;
+                const asLeaves = (v) => Array.isArray(v)
+                    ? v.filter((x) => typeof x === 'string')
+                    : typeof v === 'string'
+                        ? [v]
+                        : [];
+                const surfaces = [
+                    { surface: 'when', leaves: asLeaves(step['when']) },
+                    // `abort_unless` is only validated (and only meaningful) on guards; on anything else the
+                    // loader leaves it alone and the engine never reads it.
+                    {
+                        surface: 'abort_unless',
+                        leaves: step['execution'] === 'guard' ? asLeaves(step['abort_unless']) : [],
+                    },
+                    // `preconditions` is collected for EVERY step kind, but it is INERT on a guard: the sole
+                    // `checkPreconditions` call site is `executeStep` (execution-loop.ts:1380), and a guard
+                    // goes through `executeGuardStep`, which evaluates only `abort_unless`. That is why the
+                    // guard arm's consequence below is forked — collapsing it back into one shared string
+                    // would make the error claim a wedge that cannot happen.
+                    //
+                    // Post-#369 a guard declaring `preconditions` is REFUSED outright — since #517, by
+                    // the registry mint near the top of Step 3 — so this arm now only ever fires ALONGSIDE
+                    // that refusal: errors accumulate rather than short-circuit, and the mint runs first, so both messages reach the author
+                    // with the prohibition printed above this one. The arm is kept, not deleted — it is what
+                    // stops the dead-condition message from claiming a wedge that a guard cannot have, and a
+                    // definition reaching this code by any path other than a fresh YAML load (a
+                    // store-registered definition, an inline object) is never re-parsed and never sees the
+                    // prohibition at all.
+                    { surface: 'preconditions', leaves: asLeaves(step['preconditions']) },
+                ];
+                for (const { surface, leaves } of surfaces) {
+                    for (const leaf of leaves) {
+                        const split = splitComparison(leaf);
+                        // Two spellings are equally dead: the explicit `== true`, and the BARE PATH, which the
+                        // engine coerces with `Boolean()`. `preconditions` refuses bare paths anyway.
+                        const lhsPath = split.kind === 'comparison' && split.op === '==' && split.rhsRaw.trim() === 'true'
+                            ? split.lhsPath
+                            : split.kind === 'path'
+                                ? split.path
+                                : undefined;
+                        if (lhsPath === undefined)
+                            continue;
+                        // EXACTLY three segments. `$settlement.x.failed.deep` is also dead, but for a different
+                        // reason, so the trigger-rule remedy would be wrong advice there.
+                        const segments = lhsPath.trim().split('.');
+                        if (segments.length !== 3 ||
+                            segments[0] !== '$settlement' ||
+                            segments[2] !== 'failed') {
+                            continue;
+                        }
+                        const dep = segments[1];
+                        // Without the dep actually being a dependency, the one-hop error fires on its own AND
+                        // the trigger gate returns true unconditionally for a step with no deps — so the leaf
+                        // is not dead-by-trigger here and the remedy would be false advice.
+                        if (!dependsOn.includes(dep))
+                            continue;
+                        const ruleText = ruleDeclared ? `'${rule}'` : `the default '${rule}'`;
+                        const guardPrecondition = step['execution'] === 'guard' && surface === 'preconditions';
+                        const consequence = surface === 'when'
+                            ? `if '${dep}' fails the step is skipped as trigger_rule_unsatisfiable before the condition is evaluated; if '${dep}' succeeds the condition evaluates to false (when_false) — either way the step never runs`
+                            : surface === 'preconditions'
+                                ? guardPrecondition
+                                    ? // NOT the wedge: an unevaluated condition cannot block anything.
+                                        `the run behaves identically whether this condition is present or absent`
+                                    : `the step never settles — the run WEDGES in a blocked envelope`
+                                : `the guard aborts the run on every execution`;
+                        if (step['execution'] === 'guard') {
+                            // Guards cannot declare a trigger rule, so the trigger-rule remedy is wrong advice
+                            // here. This is a v1 SCOPE narrowing, not an architectural statement — issue #366
+                            // carries the design question.
+                            //
+                            // The middle clause forks with the consequence: "by the time this is evaluated" is
+                            // itself false for `preconditions`, which a guard never evaluates at all.
+                            const cause = guardPrecondition
+                                ? `and on an execution: guard step it is never evaluated at all: a guard evaluates ` +
+                                    `only 'abort_unless', so this condition is inert (${consequence})`
+                                : `a guard runs under ${ruleText} and 'trigger_rule' is not a valid field on ` +
+                                    `execution: guard steps, so '${dep}' has always succeeded by the time this is ` +
+                                    `evaluated (${consequence})`;
+                            errors.push(withStepLine(stepName, `Step '${stepName}': '${surface}' condition "${leaf}" can never be true — ${cause}. ` +
+                                `Guards run only when their dependencies succeeded; for work that must happen AFTER a ` +
+                                `failure, use an 'execution: finalizer' step (see issue #366 for widening guards).`));
                         }
                         else {
-                            validateConditionLeaf('abort_unless', leaf, stepName, dependsOn, errors, withStepLine);
+                            const remedies = ['all_done', 'one_failed'];
+                            if (new Set(dependsOn).size === 1)
+                                remedies.push('all_failed');
+                            const tail = new Set(dependsOn).size > 1
+                                ? ` ('all_failed' fires only if EVERY dependency fails; 'one_success' only if at least one other dependency succeeds.)`
+                                : '';
+                            errors.push(withStepLine(stepName, `Step '${stepName}': '${surface}' condition "${leaf}" can never be true — under ` +
+                                `${ruleText} trigger rule, '${dep}' can never be in failed_steps when this step is ` +
+                                `evaluated (${consequence}). To run this step when '${dep}' fails, set trigger_rule to ` +
+                                `one of: ${remedies.join(', ')}.${tail}`));
                         }
                     }
                 }
             }
-            else {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a string or an array of strings`));
+            // Validate tools × handler (the COMPOUND half of the old tools rule — #517 split it: the
+            // non-agent kinds are minted from the registry above; this hand-written check keeps ONLY
+            // the agent-with-handler arm, whose predicate is a companion conflict, not a kind rule).
+            // Populations are disjoint by construction (this fires only on execution: 'agent'; the
+            // mint only on non-agent kinds), so the old multi-fire cannot re-appear.
+            if (step['tools'] !== undefined &&
+                step['execution'] === 'agent' &&
+                step['handler'] !== undefined) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' is only valid on execution: agent steps without 'handler' defined`));
             }
-        }
-        // Validate preconditions leaf shape (each must be a single comparison). Reference check is
-        // `$settlement`-scoped only (issue #220 §4c) — a non-`$settlement` precondition has no
-        // depends_on/run.params check (unchanged from before this PR).
-        if (step['preconditions'] !== undefined) {
-            const rawPre = step['preconditions'];
-            if (!Array.isArray(rawPre)) {
-                errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' must be an array of strings`));
+            // issue #413: `tool_timeout` requires `tools`. It bounds ONE tool call inside the agentic
+            // loop (run-agent.ts), and a step with no tools never enters that loop — so the key sits
+            // there bounding nothing while its author believes tool calls are capped.
+            //
+            // An EMPTY list counts as missing, and that is not pedantry: run-agent gates the tools path
+            // on `tools.length > 0`, so `tools: []` is exactly as toolless at runtime as no key at all.
+            // This one helper is also the shape check's complement further down, which is what makes
+            // "exactly one error" true by construction rather than by coincidence.
+            //
+            // NOT extended to non-array `tools` spellings — that is #391, still open. Under the
+            // `!toolsMissing` complement below, a non-array `tools` still lets the shape check fire, so
+            // nothing is silently exempted here.
+            const toolsMissing = step['tools'] === undefined ||
+                (Array.isArray(step['tools']) && step['tools'].length === 0);
+            if (step['tool_timeout'] !== undefined && toolsMissing) {
+                errors.push(withKeyLine(stepName, 'tool_timeout', `Step '${stepName}': 'tool_timeout' requires 'tools' (a declared, non-empty list) — ` +
+                    'without tool calls there is ' +
+                    'nothing for it to bound, so the step would carry a bound with nothing to bind. ' +
+                    "In realm's own drive each tool call is capped at tool_timeout seconds (default " +
+                    '30); declare at least one tool or remove the key.'));
             }
-            else {
-                for (const leaf of rawPre) {
-                    if (typeof leaf !== 'string' || leaf.trim() === '') {
-                        errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' entries must be non-empty strings`));
-                    }
-                    else {
-                        validateConditionLeaf('preconditions', leaf, stepName, dependsOn, errors, withStepLine);
+            // Validate tools: requires input_schema.
+            if (step['tools'] !== undefined && step['input_schema'] === undefined) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' requires 'input_schema' to be defined — the agentic loop needs a schema for final output extraction`));
+            }
+            // Validate tools: entries must be in server_id:tool_name format.
+            if (step['tools'] !== undefined && Array.isArray(step['tools'])) {
+                for (const entry of step['tools']) {
+                    if (!/^[^:]+:[^:]+$/.test(entry)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': tools entry '${entry}' must be in 'server_id:tool_name' format`));
                     }
                 }
             }
-        }
-        // issue #362 — REJECT A PROVABLY-DEAD FAILURE CONDITION.
-        //
-        // `$settlement.<dep>.failed == true` under a trigger rule that structurally excludes a failed
-        // `<dep>` can never be true. The trigger gate runs BEFORE the condition gate, and both
-        // `all_success` and `none_failed` carry an explicit "no dep in failed_steps" conjunct — so if
-        // the rule is satisfied, `<dep>` did not fail, and the condition is false by construction.
-        //
-        // The author's compensation step therefore never runs. It is not silent at runtime — the run
-        // record says `trigger_rule_unsatisfiable` — but it names the RULE and the blocking dep, never
-        // the condition the author wrote, so the diagnosis points away from the mistake. This is an
-        // authoring-time error precisely because the fix is one word and no legitimate use of the
-        // shape exists.
-        dead_condition: {
-            const rule = step['execution'] === 'guard' ? 'all_success' : (step['trigger_rule'] ?? 'all_success');
-            // A guard may not declare `trigger_rule` at all (it is a prohibited field), so a guard that
-            // declares one must NOT be able to suppress this check by doing so.
-            const ruleDeclared = step['execution'] !== 'guard' && step['trigger_rule'] !== undefined;
-            if (step['execution'] !== 'guard' && !VALID_TRIGGER_RULES.has(rule)) {
-                break dead_condition; // an invalid rule already has its own error — adding noise helps nobody
+            // issue #338: the check below only runs when an `mcp_servers` block EXISTS, so the absent-block
+            // variant loaded clean — and every disclosure this loader has for tools lives inside that same
+            // fork, so the corner produced no error, no warning, and a run where the declared tools were
+            // simply never offered. ONE error per step, not one per entry: the entries are not individually
+            // wrong, the workflow is.
+            if (step['tools'] !== undefined &&
+                Array.isArray(step['tools']) &&
+                step['tools'].length > 0 &&
+                !Array.isArray(doc['mcp_servers'])) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': declares tools but the workflow defines no mcp_servers — no drive ` +
+                    `can ever offer these tools, so the declaration can never be satisfied. Define an ` +
+                    `mcp_servers block, or remove 'tools'.`));
             }
-            if (rule !== 'all_success' && rule !== 'none_failed')
-                break dead_condition;
-            const asLeaves = (v) => Array.isArray(v)
-                ? v.filter((x) => typeof x === 'string')
-                : typeof v === 'string'
-                    ? [v]
-                    : [];
-            const surfaces = [
-                { surface: 'when', leaves: asLeaves(step['when']) },
-                // `abort_unless` is only validated (and only meaningful) on guards; on anything else the
-                // loader leaves it alone and the engine never reads it.
-                {
-                    surface: 'abort_unless',
-                    leaves: step['execution'] === 'guard' ? asLeaves(step['abort_unless']) : [],
-                },
-                // `preconditions` is collected for EVERY step kind, but it is INERT on a guard: the sole
-                // `checkPreconditions` call site is `executeStep` (execution-loop.ts:1380), and a guard
-                // goes through `executeGuardStep`, which evaluates only `abort_unless`. That is why the
-                // guard arm's consequence below is forked — collapsing it back into one shared string
-                // would make the error claim a wedge that cannot happen.
-                //
-                // Post-#369 a guard declaring `preconditions` is REFUSED outright by the guard block
-                // above, so this arm now only ever fires ALONGSIDE that refusal: errors accumulate rather
-                // than short-circuit, and the guard block runs first, so both messages reach the author
-                // with the prohibition printed above this one. The arm is kept, not deleted — it is what
-                // stops the dead-condition message from claiming a wedge that a guard cannot have, and a
-                // definition reaching this code by any path other than a fresh YAML load (a
-                // store-registered definition, an inline object) is never re-parsed and never sees the
-                // prohibition at all.
-                { surface: 'preconditions', leaves: asLeaves(step['preconditions']) },
-            ];
-            for (const { surface, leaves } of surfaces) {
-                for (const leaf of leaves) {
-                    const split = splitComparison(leaf);
-                    // Two spellings are equally dead: the explicit `== true`, and the BARE PATH, which the
-                    // engine coerces with `Boolean()`. `preconditions` refuses bare paths anyway.
-                    const lhsPath = split.kind === 'comparison' && split.op === '==' && split.rhsRaw.trim() === 'true'
-                        ? split.lhsPath
-                        : split.kind === 'path'
-                            ? split.path
-                            : undefined;
-                    if (lhsPath === undefined)
-                        continue;
-                    // EXACTLY three segments. `$settlement.x.failed.deep` is also dead, but for a different
-                    // reason, so the trigger-rule remedy would be wrong advice there.
-                    const segments = lhsPath.trim().split('.');
-                    if (segments.length !== 3 || segments[0] !== '$settlement' || segments[2] !== 'failed') {
-                        continue;
-                    }
-                    const dep = segments[1];
-                    // Without the dep actually being a dependency, the one-hop error fires on its own AND
-                    // the trigger gate returns true unconditionally for a step with no deps — so the leaf
-                    // is not dead-by-trigger here and the remedy would be false advice.
-                    if (!dependsOn.includes(dep))
-                        continue;
-                    const ruleText = ruleDeclared ? `'${rule}'` : `the default '${rule}'`;
-                    const guardPrecondition = step['execution'] === 'guard' && surface === 'preconditions';
-                    const consequence = surface === 'when'
-                        ? `if '${dep}' fails the step is skipped as trigger_rule_unsatisfiable before the condition is evaluated; if '${dep}' succeeds the condition evaluates to false (when_false) — either way the step never runs`
-                        : surface === 'preconditions'
-                            ? guardPrecondition
-                                ? // NOT the wedge: an unevaluated condition cannot block anything.
-                                    `the run behaves identically whether this condition is present or absent`
-                                : `the step never settles — the run WEDGES in a blocked envelope`
-                            : `the guard aborts the run on every execution`;
-                    if (step['execution'] === 'guard') {
-                        // Guards cannot declare a trigger rule, so the trigger-rule remedy is wrong advice
-                        // here. This is a v1 SCOPE narrowing, not an architectural statement — issue #366
-                        // carries the design question.
-                        //
-                        // The middle clause forks with the consequence: "by the time this is evaluated" is
-                        // itself false for `preconditions`, which a guard never evaluates at all.
-                        const cause = guardPrecondition
-                            ? `and on an execution: guard step it is never evaluated at all: a guard evaluates ` +
-                                `only 'abort_unless', so this condition is inert (${consequence})`
-                            : `a guard runs under ${ruleText} and 'trigger_rule' is not a valid field on ` +
-                                `execution: guard steps, so '${dep}' has always succeeded by the time this is ` +
-                                `evaluated (${consequence})`;
-                        errors.push(withStepLine(stepName, `Step '${stepName}': '${surface}' condition "${leaf}" can never be true — ${cause}. ` +
-                            `Guards run only when their dependencies succeeded; for work that must happen AFTER a ` +
-                            `failure, use an 'execution: finalizer' step (see issue #366 for widening guards).`));
-                    }
-                    else {
-                        const remedies = ['all_done', 'one_failed'];
-                        if (new Set(dependsOn).size === 1)
-                            remedies.push('all_failed');
-                        const tail = new Set(dependsOn).size > 1
-                            ? ` ('all_failed' fires only if EVERY dependency fails; 'one_success' only if at least one other dependency succeeds.)`
-                            : '';
-                        errors.push(withStepLine(stepName, `Step '${stepName}': '${surface}' condition "${leaf}" can never be true — under ` +
-                            `${ruleText} trigger rule, '${dep}' can never be in failed_steps when this step is ` +
-                            `evaluated (${consequence}). To run this step when '${dep}' fails, set trigger_rule to ` +
-                            `one of: ${remedies.join(', ')}.${tail}`));
+            // Validate tools: server_id must reference a defined mcp_server.
+            if (step['tools'] !== undefined &&
+                Array.isArray(step['tools']) &&
+                Array.isArray(doc['mcp_servers'])) {
+                const serverIds = new Set(doc['mcp_servers'].map((s) => s.id));
+                for (const entry of step['tools']) {
+                    const serverId = entry.split(':')[0] ?? '';
+                    if (!serverIds.has(serverId)) {
+                        errors.push(withStepLine(stepName, `Step '${stepName}': tools entry '${entry}' references unknown MCP server '${serverId}'`));
                     }
                 }
             }
+            // Validate max_tool_calls: must be a positive integer.
+            if (step['max_tool_calls'] !== undefined &&
+                (!Number.isInteger(step['max_tool_calls']) || step['max_tool_calls'] <= 0)) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'max_tool_calls' must be a positive integer`));
+            }
+            // Validate max_fan_out: must be a positive integer.
+            if (step['max_fan_out'] !== undefined &&
+                (!Number.isInteger(step['max_fan_out']) || step['max_fan_out'] <= 0)) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'max_fan_out' must be a positive integer`));
+            }
+            // Validate tool_timeout: must be a positive integer. Skipped where the key is not valid at
+            // all (issue #413's requires-tools check above already reported that) — the same convention
+            // as `timeout_seconds` below: an author told BOTH that the key does not belong here and that
+            // its value has the wrong shape is being pointed at the shape, which is not the problem.
+            // The `!toolsMissing` complement is the SAME helper the prohibition keys on, so the two are
+            // exhaustive and disjoint by construction: `tools: []` with a negative value reports once.
+            if (step['tool_timeout'] !== undefined &&
+                !toolsMissing &&
+                (!Number.isInteger(step['tool_timeout']) || step['tool_timeout'] <= 0)) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'tool_timeout' must be a positive integer`));
+            }
+            // Validate timeout_seconds: must be a positive integer (issue A3). Skipped on
+            // execution: guard and agent — the #517 registry mint already flatly rejects
+            // 'timeout_seconds' on both kinds; re-checking its shape here would double-report the
+            // same root cause under a second, confusing message (an author told BOTH that the key is
+            // invalid here and that its value has the wrong shape is being pointed at the shape,
+            // which is not the problem).
+            if (step['timeout_seconds'] !== undefined &&
+                step['execution'] !== 'guard' &&
+                step['execution'] !== 'agent' &&
+                (!Number.isInteger(step['timeout_seconds']) || step['timeout_seconds'] <= 0)) {
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'timeout_seconds' must be a positive integer`));
+            }
         }
-        // Validate tools: only valid on execution: agent steps without handler.
-        if (step['tools'] !== undefined &&
-            (step['execution'] !== 'agent' || step['handler'] !== undefined)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' is only valid on execution: agent steps without 'handler' defined`));
-        }
-        // issue #413: `tool_timeout` requires `tools`. It bounds ONE tool call inside the agentic
-        // loop (run-agent.ts), and a step with no tools never enters that loop — so the key sits
-        // there bounding nothing while its author believes tool calls are capped.
-        //
-        // An EMPTY list counts as missing, and that is not pedantry: run-agent gates the tools path
-        // on `tools.length > 0`, so `tools: []` is exactly as toolless at runtime as no key at all.
-        // This one helper is also the shape check's complement further down, which is what makes
-        // "exactly one error" true by construction rather than by coincidence.
-        //
-        // NOT extended to non-array `tools` spellings — that is #391, still open. Under the
-        // `!toolsMissing` complement below, a non-array `tools` still lets the shape check fire, so
-        // nothing is silently exempted here.
-        const toolsMissing = step['tools'] === undefined ||
-            (Array.isArray(step['tools']) && step['tools'].length === 0);
-        if (step['tool_timeout'] !== undefined && toolsMissing) {
-            errors.push(withKeyLine(stepName, 'tool_timeout', `Step '${stepName}': 'tool_timeout' requires 'tools' (a declared, non-empty list) — ` +
-                'without tool calls there is ' +
-                'nothing for it to bound, so the step would carry a bound with nothing to bind. ' +
-                "In realm's own drive each tool call is capped at tool_timeout seconds (default " +
-                '30); declare at least one tool or remove the key.'));
-        }
-        // Validate tools: requires input_schema.
-        if (step['tools'] !== undefined && step['input_schema'] === undefined) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' requires 'input_schema' to be defined — the agentic loop needs a schema for final output extraction`));
-        }
-        // Validate tools: entries must be in server_id:tool_name format.
-        if (step['tools'] !== undefined && Array.isArray(step['tools'])) {
-            for (const entry of step['tools']) {
-                if (!/^[^:]+:[^:]+$/.test(entry)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': tools entry '${entry}' must be in 'server_id:tool_name' format`));
+        // Require at least one non-finalizer step: a workflow of only finalizers is meaningless
+        // (nothing runs in the DAG, so it would seal immediately with no domain work).
+        const stepEntries = Object.values(stepsRaw).filter((s) => typeof s === 'object' && s !== null && !Array.isArray(s));
+        if (stepEntries.length > 0 && stepEntries.every((s) => s['execution'] === 'finalizer')) {
+            errors.push(`Workflow has only finalizer steps — at least one non-finalizer step is required ` +
+                `(finalizers run at the terminal transition of the DAG's domain steps).`);
+        }
+        // Reject depends_on cycles (issue #153): a transitive cycle among otherwise-valid edges is
+        // loadable today (the per-step check above only validates one hop at a time), and at runtime
+        // the cyclic steps are mutually ineligible forever — the run silently seals `completed` with
+        // the stranded steps in NO step set and zero evidence. Build the graph over VALID edges only
+        // (dep exists, isn't self, isn't a finalizer) — the self/unknown/finalizer-dep cases are
+        // already reported by the per-step check above; a real cycle runs entirely through valid
+        // edges, so excluding the already-errored ones here avoids double-reporting them.
+        const dependencyEdges = new Map();
+        for (const stepName of Object.keys(stepsRaw)) {
+            dependencyEdges.set(stepName, []);
+        }
+        for (const [stepName, stepRaw] of Object.entries(stepsRaw)) {
+            if (typeof stepRaw !== 'object' || stepRaw === null || Array.isArray(stepRaw))
+                continue;
+            const dependsOn = stepRaw['depends_on'];
+            if (!Array.isArray(dependsOn))
+                continue;
+            for (const dep of dependsOn) {
+                if (typeof dep === 'string' &&
+                    dep !== stepName &&
+                    dep in stepsRaw &&
+                    stepsRaw[dep]['execution'] !== 'finalizer') {
+                    dependencyEdges.get(stepName).push(dep);
                 }
             }
         }
-        // issue #338: the check below only runs when an `mcp_servers` block EXISTS, so the absent-block
-        // variant loaded clean — and every disclosure this loader has for tools lives inside that same
-        // fork, so the corner produced no error, no warning, and a run where the declared tools were
-        // simply never offered. ONE error per step, not one per entry: the entries are not individually
-        // wrong, the workflow is.
-        if (step['tools'] !== undefined &&
-            Array.isArray(step['tools']) &&
-            step['tools'].length > 0 &&
-            !Array.isArray(doc['mcp_servers'])) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': declares tools but the workflow defines no mcp_servers — no drive ` +
-                `can ever offer these tools, so the declaration can never be satisfied. Define an ` +
-                `mcp_servers block, or remove 'tools'.`));
+        for (const cycle of detectDependencyCycles(dependencyEdges)) {
+            errors.push(`Workflow has a dependency cycle: ${cycle.join(' → ')}`);
         }
-        // Validate tools: server_id must reference a defined mcp_server.
-        if (step['tools'] !== undefined &&
-            Array.isArray(step['tools']) &&
-            Array.isArray(doc['mcp_servers'])) {
-            const serverIds = new Set(doc['mcp_servers'].map((s) => s.id));
-            for (const entry of step['tools']) {
-                const serverId = entry.split(':')[0] ?? '';
-                if (!serverIds.has(serverId)) {
-                    errors.push(withStepLine(stepName, `Step '${stepName}': tools entry '${entry}' references unknown MCP server '${serverId}'`));
+        // Validate mcp_servers: ids must be unique (workflow-level check).
+        if (Array.isArray(doc['mcp_servers'])) {
+            const seen = new Set();
+            for (const server of doc['mcp_servers']) {
+                if (seen.has(server.id)) {
+                    errors.push(`mcp_servers: duplicate server id '${server.id}'`);
                 }
+                seen.add(server.id);
             }
         }
-        // Validate max_tool_calls: must be a positive integer.
-        if (step['max_tool_calls'] !== undefined &&
-            (!Number.isInteger(step['max_tool_calls']) || step['max_tool_calls'] <= 0)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'max_tool_calls' must be a positive integer`));
-        }
-        // Validate max_fan_out: must be a positive integer.
-        if (step['max_fan_out'] !== undefined &&
-            (!Number.isInteger(step['max_fan_out']) || step['max_fan_out'] <= 0)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'max_fan_out' must be a positive integer`));
-        }
-        // Validate tool_timeout: must be a positive integer. Skipped where the key is not valid at
-        // all (issue #413's requires-tools check above already reported that) — the same convention
-        // as `timeout_seconds` below: an author told BOTH that the key does not belong here and that
-        // its value has the wrong shape is being pointed at the shape, which is not the problem.
-        // The `!toolsMissing` complement is the SAME helper the prohibition keys on, so the two are
-        // exhaustive and disjoint by construction: `tools: []` with a negative value reports once.
-        if (step['tool_timeout'] !== undefined &&
-            !toolsMissing &&
-            (!Number.isInteger(step['tool_timeout']) || step['tool_timeout'] <= 0)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'tool_timeout' must be a positive integer`));
-        }
-        // Validate timeout_seconds: must be a positive integer (issue A3). Skipped on
-        // execution: guard — the guard-prohibited-fields check above already flatly rejects
-        // 'timeout_seconds' there ('is not valid on execution: guard steps'); re-checking its
-        // shape here would double-report the same root cause under a second, confusing message.
-        // Same suppression for the agent prohibition (issue #402), for the same reason: an author
-        // told BOTH that the key is invalid here and that its value has the wrong shape is being
-        // pointed at the shape, which is not the problem.
-        if (step['timeout_seconds'] !== undefined &&
-            step['execution'] !== 'guard' &&
-            step['execution'] !== 'agent' &&
-            (!Number.isInteger(step['timeout_seconds']) || step['timeout_seconds'] <= 0)) {
-            errors.push(withStepLine(stepName, `Step '${stepName}': 'timeout_seconds' must be a positive integer`));
-        }
-    }
-    // Require at least one non-finalizer step: a workflow of only finalizers is meaningless
-    // (nothing runs in the DAG, so it would seal immediately with no domain work).
-    const stepEntries = Object.values(stepsRaw).filter((s) => typeof s === 'object' && s !== null && !Array.isArray(s));
-    if (stepEntries.length > 0 && stepEntries.every((s) => s['execution'] === 'finalizer')) {
-        errors.push(`Workflow has only finalizer steps — at least one non-finalizer step is required ` +
-            `(finalizers run at the terminal transition of the DAG's domain steps).`);
-    }
-    // Reject depends_on cycles (issue #153): a transitive cycle among otherwise-valid edges is
-    // loadable today (the per-step check above only validates one hop at a time), and at runtime
-    // the cyclic steps are mutually ineligible forever — the run silently seals `completed` with
-    // the stranded steps in NO step set and zero evidence. Build the graph over VALID edges only
-    // (dep exists, isn't self, isn't a finalizer) — the self/unknown/finalizer-dep cases are
-    // already reported by the per-step check above; a real cycle runs entirely through valid
-    // edges, so excluding the already-errored ones here avoids double-reporting them.
-    const dependencyEdges = new Map();
-    for (const stepName of Object.keys(stepsRaw)) {
-        dependencyEdges.set(stepName, []);
-    }
-    for (const [stepName, stepRaw] of Object.entries(stepsRaw)) {
-        if (typeof stepRaw !== 'object' || stepRaw === null || Array.isArray(stepRaw))
-            continue;
-        const dependsOn = stepRaw['depends_on'];
-        if (!Array.isArray(dependsOn))
-            continue;
-        for (const dep of dependsOn) {
-            if (typeof dep === 'string' &&
-                dep !== stepName &&
-                dep in stepsRaw &&
-                stepsRaw[dep]['execution'] !== 'finalizer') {
-                dependencyEdges.get(stepName).push(dep);
+        // Validate services: Ajv-strict entry schema (closed key set) + rate_limit fields.
+        if (typeof doc['services'] === 'object' && doc['services'] !== null) {
+            for (const [serviceName, serviceRaw] of Object.entries(doc['services'])) {
+                if (typeof serviceRaw !== 'object' || serviceRaw === null)
+                    continue;
+                const service = serviceRaw;
+                // PERMANENT targeted rejection — must win over the generic unknown-key error.
+                if ('auth' in service || 'token_from' in service) {
+                    errors.push(`Service '${serviceName}': 'auth.token_from' was removed in v0.14.0 — bind ` +
+                        `credentials in your deployment manifest (realm.yaml); see the migration note.`);
+                }
+                else {
+                    const serviceAjv = new Ajv({ strict: true, allErrors: true });
+                    if (!serviceAjv.validate(SERVICE_ENTRY_JSON_SCHEMA, service)) {
+                        for (const err of serviceAjv.errors ?? []) {
+                            const detail = err.keyword === 'additionalProperties'
+                                ? `unknown key '${String(err.params.additionalProperty)}'`
+                                : `${err.instancePath.replace(/^\//, '').replace(/\//g, '.') || 'entry'} ${err.message ?? 'invalid'}`;
+                            errors.push(`Service '${serviceName}': ${detail}`);
+                        }
+                    }
+                }
+                const rateLimit = service['rate_limit'];
+                if (rateLimit === undefined)
+                    continue;
+                if (typeof rateLimit !== 'object' || rateLimit === null) {
+                    errors.push(`Service '${serviceName}': 'rate_limit' must be an object`);
+                    continue;
+                }
+                const rl = rateLimit;
+                if ('requests_per_second' in rl &&
+                    (!Number.isInteger(rl['requests_per_second']) ||
+                        rl['requests_per_second'] < 1)) {
+                    errors.push(`Service '${serviceName}': 'rate_limit.requests_per_second' must be a positive integer (≥ 1)`);
+                }
+                if ('burst' in rl) {
+                    if (!Number.isInteger(rl['burst']) || rl['burst'] < 1) {
+                        errors.push(`Service '${serviceName}': 'rate_limit.burst' must be a positive integer (≥ 1)`);
+                    }
+                    if (!('requests_per_second' in rl)) {
+                        errors.push(`Service '${serviceName}': 'rate_limit.burst' requires 'rate_limit.requests_per_second' to be set`);
+                    }
+                }
+                if ('fallback_retry_seconds' in rl &&
+                    (typeof rl['fallback_retry_seconds'] !== 'number' ||
+                        rl['fallback_retry_seconds'] <= 0)) {
+                    errors.push(`Service '${serviceName}': 'rate_limit.fallback_retry_seconds' must be a positive number (> 0)`);
+                }
+                if ('min_retry_seconds' in rl &&
+                    (typeof rl['min_retry_seconds'] !== 'number' || rl['min_retry_seconds'] <= 0)) {
+                    errors.push(`Service '${serviceName}': 'rate_limit.min_retry_seconds' must be a positive number (> 0)`);
+                }
+                if ('max_retry_seconds' in rl &&
+                    (!Number.isInteger(rl['max_retry_seconds']) || rl['max_retry_seconds'] < 1)) {
+                    errors.push(`Service '${serviceName}': 'rate_limit.max_retry_seconds' must be a positive integer (≥ 1)`);
+                }
             }
         }
-    }
-    for (const cycle of detectDependencyCycles(dependencyEdges)) {
-        errors.push(`Workflow has a dependency cycle: ${cycle.join(' → ')}`);
-    }
-    // Validate mcp_servers: ids must be unique (workflow-level check).
-    if (Array.isArray(doc['mcp_servers'])) {
-        const seen = new Set();
-        for (const server of doc['mcp_servers']) {
-            if (seen.has(server.id)) {
-                errors.push(`mcp_servers: duplicate server id '${server.id}'`);
+        // Step 3b: Trigger block validation (schema-driven — see trigger-schema.ts)
+        const triggerRaw = doc['trigger'];
+        if (triggerRaw !== undefined) {
+            normalizeTriggerFilter(triggerRaw); // canonicalise shorthand BEFORE validation
+            errors.push(...validateTriggerStructure(triggerRaw));
+        }
+        // Step 3c: workflow-level context blocks (issue #553). These four rules need nothing but the
+        // text, so they belong to every surface — file, string, `validate --registered`, the public
+        // `loadWorkflowFromString`. They lived in the file loader until #553 and were therefore
+        // invisible to `validate` (which parsed extension-free workflows from string) and to
+        // `--registered`; the public string loader silently accepted all four shapes. Pushed, never
+        // thrown: the accumulator mints `Invalid workflow:` once and the #425 per-line grammar composes.
+        const contextWrapperRaw = doc['context_wrapper'];
+        if (contextWrapperRaw !== undefined) {
+            const VALID_WRAPPER_FORMATS = new Set(['xml', 'brackets', 'none']);
+            if (!VALID_WRAPPER_FORMATS.has(contextWrapperRaw)) {
+                errors.push(withTopLevelLine(['context_wrapper'], `'context_wrapper' must be 'xml', 'brackets', or 'none' (found: '${String(contextWrapperRaw)}')`));
             }
-            seen.add(server.id);
         }
-    }
-    // Validate services: Ajv-strict entry schema (closed key set) + rate_limit fields.
-    if (typeof doc['services'] === 'object' && doc['services'] !== null) {
-        for (const [serviceName, serviceRaw] of Object.entries(doc['services'])) {
-            if (typeof serviceRaw !== 'object' || serviceRaw === null)
-                continue;
-            const service = serviceRaw;
-            // PERMANENT targeted rejection — must win over the generic unknown-key error.
-            if ('auth' in service || 'token_from' in service) {
-                errors.push(`Service '${serviceName}': 'auth.token_from' was removed in v0.14.0 — bind ` +
-                    `credentials in your deployment manifest (realm.yaml); see the migration note.`);
-            }
-            else {
-                const serviceAjv = new Ajv({ strict: true, allErrors: true });
-                if (!serviceAjv.validate(SERVICE_ENTRY_JSON_SCHEMA, service)) {
-                    for (const err of serviceAjv.errors ?? []) {
-                        const detail = err.keyword === 'additionalProperties'
-                            ? `unknown key '${String(err.params.additionalProperty)}'`
-                            : `${err.instancePath.replace(/^\//, '').replace(/\//g, '.') || 'entry'} ${err.message ?? 'invalid'}`;
-                        errors.push(`Service '${serviceName}': ${detail}`);
-                    }
+        const workflowContextRaw = doc['workflow_context'];
+        if (workflowContextRaw !== undefined) {
+            for (const [name, entry] of Object.entries(workflowContextRaw)) {
+                if (name.endsWith('.raw')) {
+                    errors.push(withTopLevelLine(['workflow_context', name], `workflow_context entry '${name}' must not end with '.raw'`));
                 }
-            }
-            const rateLimit = service['rate_limit'];
-            if (rateLimit === undefined)
-                continue;
-            if (typeof rateLimit !== 'object' || rateLimit === null) {
-                errors.push(`Service '${serviceName}': 'rate_limit' must be an object`);
-                continue;
-            }
-            const rl = rateLimit;
-            if ('requests_per_second' in rl &&
-                (!Number.isInteger(rl['requests_per_second']) || rl['requests_per_second'] < 1)) {
-                errors.push(`Service '${serviceName}': 'rate_limit.requests_per_second' must be a positive integer (≥ 1)`);
-            }
-            if ('burst' in rl) {
-                if (!Number.isInteger(rl['burst']) || rl['burst'] < 1) {
-                    errors.push(`Service '${serviceName}': 'rate_limit.burst' must be a positive integer (≥ 1)`);
+                if (!/^[\w.]+$/.test(name)) {
+                    errors.push(withTopLevelLine(['workflow_context', name], `workflow_context entry '${name}' must match [\\w.]+ (underscores and dots only — no hyphens)`));
                 }
-                if (!('requests_per_second' in rl)) {
-                    errors.push(`Service '${serviceName}': 'rate_limit.burst' requires 'rate_limit.requests_per_second' to be set`);
+                const rawEntry = entry;
+                const rawSource = rawEntry?.['source'];
+                if (rawSource === undefined || typeof rawSource['path'] !== 'string') {
+                    // The ENTRY's line: the missing key has no line, and a cite must never name an absent
+                    // key.
+                    errors.push(withTopLevelLine(['workflow_context', name], `workflow_context.${name}.source.path is required`));
                 }
             }
-            if ('fallback_retry_seconds' in rl &&
-                (typeof rl['fallback_retry_seconds'] !== 'number' ||
-                    rl['fallback_retry_seconds'] <= 0)) {
-                errors.push(`Service '${serviceName}': 'rate_limit.fallback_retry_seconds' must be a positive number (> 0)`);
-            }
-            if ('min_retry_seconds' in rl &&
-                (typeof rl['min_retry_seconds'] !== 'number' || rl['min_retry_seconds'] <= 0)) {
-                errors.push(`Service '${serviceName}': 'rate_limit.min_retry_seconds' must be a positive number (> 0)`);
-            }
-            if ('max_retry_seconds' in rl &&
-                (!Number.isInteger(rl['max_retry_seconds']) || rl['max_retry_seconds'] < 1)) {
-                errors.push(`Service '${serviceName}': 'rate_limit.max_retry_seconds' must be a positive integer (≥ 1)`);
-            }
         }
+        if (errors.length > 0) {
+            throw new WorkflowError(`Invalid workflow: ${errors.join('; ')}`, {
+                // issue #425: the pre-join strings — see the profile collector above.
+                errors: [...errors],
+                code: 'VALIDATION_WORKFLOW_SCHEMA',
+                category: 'VALIDATION',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+        // Step 4: Stamp schema version and return typed result
+        const definition = doc;
+        definition.schema_version = CURRENT_WORKFLOW_SCHEMA_VERSION;
+        return { definition, warnings };
     }
-    // Step 3b: Trigger block validation (schema-driven — see trigger-schema.ts)
-    const triggerRaw = doc['trigger'];
-    if (triggerRaw !== undefined) {
-        normalizeTriggerFilter(triggerRaw); // canonicalise shorthand BEFORE validation
-        errors.push(...validateTriggerStructure(triggerRaw));
-    }
-    if (errors.length > 0) {
-        throw new WorkflowError(`Invalid workflow: ${errors.join('; ')}`, {
-            code: 'VALIDATION_WORKFLOW_SCHEMA',
-            category: 'VALIDATION',
-            agentAction: 'report_to_user',
-            retryable: false,
-        });
+    catch (err) {
+        if (err instanceof WorkflowError)
+            attachLoaderWarnings(err, warnings);
+        throw err;
     }
-    // Step 4: Stamp schema version and return typed result
-    const definition = doc;
-    definition.schema_version = CURRENT_WORKFLOW_SCHEMA_VERSION;
-    return { definition, warnings };
 }
 /** Returns true if any step in the raw steps map declares use_template. */
 function hasUseTemplateInSteps(steps) {