@db-lyon/flowkit 0.17.3 → 0.18.0

package/dist/flow/runner.js

@@ -1,8 +1,19 @@
 import { noopLogger } from '../logger.js';
 import { DEFAULT_EXECUTION_PHASE } from '../task/base-task.js';
+import { assertTaskOptions, mergeOptionSpecs, taskClassMetadata, TaskOptionsError, } from '../task/options-schema.js';
+import { deprecationWarning, mergeWarnings } from '../task/warnings.js';
 import { AgentTask } from '../task/agent-task.js';
 import { resolveReferences } from '../references.js';
 import { resolveTaskDefinition, resolveTaskCall } from '../task/task-resolution.js';
+/** Raised (as a step or flow error) when an `action: error` check fires. */
+export class CheckFailedError extends Error {
+    outcome;
+    constructor(outcome) {
+        super(outcome.message);
+        this.name = 'CheckFailedError';
+        this.outcome = outcome;
+    }
+}
 // ---------------------------------------------------------------------------
 // FlowRunner
 // ---------------------------------------------------------------------------
@@ -17,6 +28,8 @@ export class FlowRunner {
     references;
     agents;
     nestedAgentTaskFactory;
+    optionsScope;
+    strictStepReferences;
     runDepth = 0;
     /**
      * Reference scope outside any step: the host namespaces, no step results.
@@ -34,6 +47,8 @@ export class FlowRunner {
         this.references = config.references;
         this.baseReferences = { steps: [], namespaces: this.references };
         this.agents = config.agents ?? {};
+        this.optionsScope = config.optionsScope ?? 'flat';
+        this.strictStepReferences = config.strictStepReferences ?? false;
         this.nestedAgentTaskFactory =
             config.nestedAgentTaskFactory ?? ((ctx, options) => new AgentTask(ctx, options));
         // Compile each agent into a task definition so it is runnable as a flow
@@ -76,14 +91,97 @@ export class FlowRunner {
      * sub-agent dispatch, so a task invoked several agents deep resolves its
      * configured defaults exactly as it would as a top-level step.
      */
-    contextFor(references, executionPhase = DEFAULT_EXECUTION_PHASE) {
+    contextFor(references, executionPhase = DEFAULT_EXECUTION_PHASE, sink) {
         return {
             ...this.ctx,
             taskReferenceContext: references,
             executionPhase,
             runAgent: (agentName, input, depth, ledger) => this.runAgentTool(agentName, input, depth, ledger, references),
+            ...(sink
+                ? {
+                    step: (target, options, spec) => this.runChildStep(sink, target, options ?? {}, spec),
+                }
+                : {}),
         };
     }
+    /**
+     * Run one composite child through the same machinery as a flow step: hooks,
+     * retries, option schema, deprecation and rollback capture. The child is
+     * recorded on the parent's sink and becomes `TaskResult.children`.
+     *
+     * A child's options are the composite's runtime data: they layer over the
+     * child task's configured defaults (interpolated in the parent's reference
+     * scope) verbatim. Runtime `params` and enclosing-flow overrides do not
+     * reach children, and a child flow gets `options` as its `params`.
+     */
+    async runChildStep(sink, target, options, spec) {
+        const stepNumber = sink.children.length + 1;
+        const isFlow = typeof target === 'object' && 'flow' in target;
+        const name = typeof target === 'string' ? target : 'flow' in target ? target.flow : target.task;
+        const path = sink.path ? `${sink.path}/${stepNumber}` : String(stepNumber);
+        const planStep = {
+            stepNumber,
+            type: isFlow ? 'flow' : 'task',
+            name,
+            skipped: false,
+            options,
+            ...(spec?.retries !== undefined ? { retries: spec.retries } : {}),
+            ...(spec?.retryDelay !== undefined ? { retryDelay: spec.retryDelay } : {}),
+            ...(spec?.retryOn !== undefined ? { retryOn: spec.retryOn } : {}),
+            path,
+            depth: path.split('/').length - 1,
+        };
+        // Claim the slot before running, so a composite that runs children
+        // concurrently still numbers them in the order it asked.
+        const record = { stepNumber, type: planStep.type, name, skipped: false, duration: 0, path };
+        sink.children.push(record);
+        await this.hooks.beforeStep?.(planStep);
+        const start = Date.now();
+        if (isFlow) {
+            if (!this.flows[name]) {
+                record.result = { success: false, error: new Error(`Flow "${name}" not found in configuration`) };
+            }
+            else {
+                // A child flow is never the top of a run, even under a bare runTask.
+                this.runDepth++;
+                try {
+                    const nested = await this.runWith({ flowName: name, params: options, rollbackOwnedByAncestor: sink.rollbackOwned }, {});
+                    record.result = {
+                        success: nested.success,
+                        data: { stepCount: nested.steps.length },
+                        error: nested.success ? undefined : nested.error,
+                        ...(nested.warnings ? { warnings: nested.warnings } : {}),
+                    };
+                    record.nestedSteps = nested.steps;
+                    if (nested.checks)
+                        record.checks = nested.checks;
+                }
+                catch (err) {
+                    record.result = { success: false, error: err instanceof Error ? err : new Error(String(err)) };
+                }
+                finally {
+                    this.runDepth--;
+                }
+            }
+        }
+        else {
+            const { result, attempts } = await this.withRetry(planStep, async () => {
+                let resolved;
+                try {
+                    resolved = resolveTaskCall(name, this.tasks, options, sink.references);
+                }
+                catch (err) {
+                    return { success: false, error: err instanceof Error ? err : new Error(String(err)) };
+                }
+                return this.executeTask(resolved.classPath, resolved.options, sink.references, DEFAULT_EXECUTION_PHASE, name, { path, rollbackOwned: sink.rollbackOwned });
+            });
+            record.result = result;
+            record.attempts = attempts;
+        }
+        record.duration = Date.now() - start;
+        await this.hooks.afterStep?.(planStep, record);
+        return record.result;
+    }
     /** Map an agent definition onto AgentTask options (everything but the prompt). */
     compileAgent(def) {
         const b = def.budget ?? {};
@@ -180,7 +278,156 @@ export class FlowRunner {
         catch (err) {
             return { success: false, error: err instanceof Error ? err : new Error(String(err)) };
         }
-        return this.executeTask(resolved.classPath, resolved.options, refs);
+        return this.executeTask(resolved.classPath, resolved.options, refs, DEFAULT_EXECUTION_PHASE, taskName);
+    }
+    /**
+     * Describe a configured (or registered) task: its class, merged default
+     * options, option schema, outputs and deprecation. See `TaskRegistry.describe`.
+     */
+    async describeTask(taskName) {
+        return this.registry.describe(taskName, this.tasks);
+    }
+    /** Describe a configured flow: its declared metadata and its resolved main steps. */
+    describeFlow(flowName) {
+        const flow = this.flows[flowName];
+        if (!flow)
+            throw new Error(`Flow "${flowName}" not found in configuration`);
+        const out = { name: flowName, steps: this.resolveExecutionPlan(flow, new Set()) };
+        if (flow.description != null)
+            out.description = flow.description;
+        if (flow.deprecated)
+            out.deprecated = flow.deprecated;
+        if (flow.replaced_by !== undefined)
+            out.replaced_by = flow.replaced_by;
+        if (flow.rollback_on_failure !== undefined)
+            out.rollback_on_failure = flow.rollback_on_failure;
+        if (flow.options_scope !== undefined)
+            out.options_scope = flow.options_scope;
+        if (flow.checks)
+            out.checks = flow.checks;
+        return out;
+    }
+    /**
+     * The children a composite task would run for `options`, from its class's
+     * static `expand`, without running anything. `options` layer over the task's
+     * configured defaults as `runTask` would layer them. Returns `null` when the
+     * class declares no `expand` or its `expand` cannot say.
+     */
+    async expandTask(taskName, options = {}) {
+        const { classPath, options: defaults } = resolveTaskDefinition(taskName, this.tasks);
+        const expand = await this.expandFunctionOf(classPath);
+        if (!expand)
+            return null;
+        const merged = lenientReferences({ ...defaults, ...options }, this.baseReferences);
+        return (await expand(merged, this.expandContext(taskName))) ?? null;
+    }
+    expandContext(taskName) {
+        return {
+            taskName,
+            taskDefinitions: this.tasks,
+            flows: this.flows,
+            ...(this.references ? { references: this.references } : {}),
+        };
+    }
+    /** A task class's static `expand`, or undefined (including when the class cannot load). */
+    async expandFunctionOf(classPath) {
+        try {
+            const ctor = (await this.registry.resolve(classPath));
+            return typeof ctor.expand === 'function' ? ctor.expand.bind(ctor) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Plan mode: follow each composite task row with the children its `expand`
+     * reports, one level deeper, recursively. Options are resolved as far as
+     * they can be before a run: definition defaults, the step's options and its
+     * runtime params, with host references interpolated and step references left
+     * as written.
+     */
+    async expandCompositeRows(plan, params, scope, ancestors = new Set()) {
+        const out = [];
+        for (const row of plan) {
+            out.push(row);
+            if (row.type !== 'task' || row.skipped || ancestors.has(row.name))
+                continue;
+            const { classPath, options: defaults } = resolveTaskDefinition(row.name, this.tasks);
+            const expand = await this.expandFunctionOf(classPath);
+            if (!expand)
+                continue;
+            const path = row.path ?? String(row.stepNumber);
+            let runtime = params;
+            if (scope === 'step' && params) {
+                runtime = {
+                    ...params[row.name],
+                    ...params[path],
+                };
+            }
+            const raw = { ...defaults, ...(row.options ?? {}), ...(ancestors.size === 0 ? runtime : {}) };
+            let entries = null;
+            try {
+                entries = await expand(lenientReferences(raw, this.baseReferences), this.expandContext(row.name));
+            }
+            catch (err) {
+                this.logger.warn({ task: row.name, err }, `expand() failed for ${row.name}; shown as opaque`);
+            }
+            if (!entries) {
+                row.composite = 'opaque';
+                continue;
+            }
+            row.composite = 'expanded';
+            row.path = path;
+            row.depth = row.depth ?? 0;
+            const children = entries.map((entry, i) => ({
+                stepNumber: i + 1,
+                type: 'flow' in entry ? 'flow' : 'task',
+                name: 'flow' in entry ? entry.flow : entry.task,
+                skipped: false,
+                ...(entry.options ? { options: entry.options } : {}),
+                path: `${path}/${i + 1}`,
+                depth: row.depth + 1,
+            }));
+            out.push(...(await this.expandCompositeRows(children, params, scope, new Set(ancestors).add(row.name))));
+        }
+        return out;
+    }
+    /**
+     * The deprecation notice for a task or flow, or undefined. A task's class is
+     * resolved for its static metadata; one that cannot load reports nothing
+     * here and fails where it would have anyway, at run time.
+     */
+    async deprecationOf(type, name) {
+        if (type === 'flow') {
+            const f = this.flows[name];
+            return f ? deprecationWarning('flow', name, f.deprecated, f.replaced_by) : undefined;
+        }
+        const def = this.tasks[name];
+        let meta = {};
+        try {
+            meta = taskClassMetadata(await this.registry.resolve(resolveTaskDefinition(name, this.tasks).classPath));
+        }
+        catch {
+            // Unloadable class: no static metadata to report.
+        }
+        return deprecationWarning('task', name, def?.deprecated ?? meta.deprecated, def?.replaced_by ?? meta.replacedBy);
+    }
+    /** Plan mode: mark deprecated rows and collect their warnings. */
+    async annotatePlan(plan) {
+        const warnings = [];
+        for (const step of plan) {
+            if (step.skipped)
+                continue;
+            const w = await this.deprecationOf(step.type, step.name);
+            if (!w)
+                continue;
+            const def = step.type === 'flow' ? this.flows[step.name] : this.tasks[step.name];
+            step.deprecated = def?.deprecated || true;
+            if (w.replacedBy)
+                step.replaced_by = w.replacedBy;
+            warnings.push(w);
+        }
+        return warnings;
     }
     /**
      * Instantiate and run a task with fully-resolved options (the shared leaf).
@@ -191,27 +438,190 @@ export class FlowRunner {
      * as a step, directly, as a tool, or during rollback all report failure
      * identically — and a step's `retries` cover construction, not just execution.
      * Task-to-task calls derive their equivalent context in `BaseTask.resolve`.
+     *
+     * `taskName` is the configured name the call came through. When given, the
+     * task's declared options (class `optionsSchema` refined by the definition's
+     * `options_schema`) supply defaults and are checked here, so every runner
+     * path validates the same way and a bad option fails before the task exists.
      */
-    async executeTask(classPath, options, references, executionPhase = DEFAULT_EXECUTION_PHASE) {
-        const taskCtx = this.contextFor(references, executionPhase);
+    async executeTask(classPath, options, references, executionPhase = DEFAULT_EXECUTION_PHASE, taskName, site = { path: '', rollbackOwned: false }) {
+        const sink = { ...site, children: [], references };
+        const taskCtx = this.contextFor(references, executionPhase, sink);
+        const finish = (result) => {
+            if (sink.children.length === 0)
+                return result;
+            result.children = sink.children;
+            // A child's notices (a deprecated child task, say) surface on the parent,
+            // so a flow reports them like any step's.
+            const merged = mergeWarnings(result.warnings, ...sink.children.map((c) => c.result?.warnings));
+            if (merged.length > 0)
+                result.warnings = merged;
+            return result;
+        };
         try {
-            const task = await this.registry.create(classPath, taskCtx, options);
-            return task.run();
+            let finalOptions = options;
+            let deprecation;
+            if (taskName !== undefined) {
+                const meta = taskClassMetadata(await this.registry.resolve(classPath));
+                const def = this.tasks[taskName];
+                deprecation = deprecationWarning('task', taskName, def?.deprecated ?? meta.deprecated, def?.replaced_by ?? meta.replacedBy);
+                if (deprecation)
+                    this.logger.warn({ task: taskName }, deprecation.message);
+                const specs = mergeOptionSpecs(meta.optionsSchema, def?.options_schema);
+                try {
+                    finalOptions = assertTaskOptions(taskName, specs, options);
+                }
+                catch (err) {
+                    return withWarnings({ success: false, error: err }, deprecation);
+                }
+            }
+            const task = await this.registry.create(classPath, taskCtx, finalOptions);
+            return finish(withWarnings(await task.run(), deprecation));
         }
         catch (err) {
             return { success: false, error: err instanceof Error ? err : new Error(String(err)) };
         }
     }
-    async runWith(options, parentOptions) {
+    async runWith(options, parentOptions, frame) {
         this.runDepth++;
         const isTopLevel = this.runDepth === 1;
         try {
-            return await this.executeFlow(options, isTopLevel, parentOptions);
+            return await this.executeFlow(options, isTopLevel, parentOptions, frame);
         }
         finally {
             this.runDepth--;
         }
     }
+    /** Path of a main step inside a frame: `3` at the root, `2/3` inside step 2's flow. */
+    stepPath(frame, stepNumber) {
+        return frame.pathPrefix ? `${frame.pathPrefix}/${stepNumber}` : String(stepNumber);
+    }
+    /**
+     * The runtime option layer one step receives. Flat: all of `params`.
+     * Step-scoped: the options under the step's task name, then under its path.
+     */
+    runtimeOptionsFor(step, frame, params) {
+        if (frame.scope === 'flat' || !params)
+            return params;
+        const byName = params[step.name];
+        // Hook steps carry synthetic step numbers and are addressed by name only.
+        const byPath = step.phase === undefined
+            ? params[this.stepPath(frame, step.stepNumber)]
+            : undefined;
+        if (!byName && !byPath)
+            return undefined;
+        return { ...byName, ...byPath };
+    }
+    /**
+     * Every selector a step-scoped `params` key may use for a run of `flowName`:
+     * task names anywhere in the tree (main and hook steps, nested flows
+     * included) and the paths of main task steps.
+     */
+    collectSelectors(flowName, pathPrefix, ancestors, out) {
+        const flow = this.flows[flowName];
+        if (!flow || ancestors.has(flowName))
+            return;
+        const nextAncestors = new Set(ancestors).add(flowName);
+        const visit = (step, path) => {
+            if (step.name === 'None')
+                return;
+            if (step.type === 'task') {
+                out.names.add(step.name);
+                if (path !== undefined)
+                    out.paths.add(path);
+            }
+            else {
+                this.collectSelectors(step.name, path ?? `${pathPrefix}/${step.phase}`, nextAncestors, out);
+            }
+        };
+        for (const step of this.resolveExecutionPlan(flow, new Set())) {
+            visit(step, pathPrefix ? `${pathPrefix}/${step.stepNumber}` : String(step.stepNumber));
+        }
+        for (const phase of ['on_start', 'on_success', 'on_failure', 'finally']) {
+            for (const step of this.planHookSteps(flow[phase], phase, new Set(), 0))
+                visit(step, undefined);
+        }
+    }
+    /**
+     * Find `${steps.<id>...}` references that cannot be bound to exactly one
+     * earlier main step: ambiguous names, unknown ids and forward references.
+     * Scans the flow's main and hook steps (`options` of task steps, `when`, and
+     * check `when`s) and, recursively, every flow they nest. It does not scan
+     * task definition defaults, which are resolved in whatever step runs them.
+     */
+    checkStepReferences(flowName) {
+        const issues = [];
+        this.collectReferenceIssues(flowName, new Set(), issues);
+        return issues;
+    }
+    collectReferenceIssues(flowName, seen, issues) {
+        const flow = this.flows[flowName];
+        if (!flow || seen.has(flowName))
+            return;
+        seen.add(flowName);
+        const main = this.resolveExecutionPlan(flow, new Set());
+        const byName = new Map();
+        for (const st of main) {
+            if (st.name === 'None')
+                continue;
+            byName.set(st.name, [...(byName.get(st.name) ?? []), st.stepNumber]);
+        }
+        const numbers = new Set(main.filter((st) => st.name !== 'None').map((st) => st.stepNumber));
+        const scan = (st) => {
+            const texts = [st.when, ...(st.checks ?? []).map((c) => c.when)];
+            // A flow step's options are overrides for tasks inside the child flow and
+            // resolve against the child's steps, not this flow's.
+            if (st.type === 'task')
+                texts.push(st.options);
+            for (const ref of stepReferencesIn(texts)) {
+                const issue = bindStepReference(ref, st, byName, numbers);
+                if (issue) {
+                    issues.push({
+                        flowName,
+                        stepNumber: st.stepNumber,
+                        ...(st.phase ? { phase: st.phase } : {}),
+                        reference: `\${steps.${ref}}`,
+                        ...issue,
+                    });
+                }
+            }
+        };
+        for (const st of main) {
+            if (st.name === 'None')
+                continue;
+            scan(st);
+            if (st.type === 'flow')
+                this.collectReferenceIssues(st.name, seen, issues);
+        }
+        for (const phase of ['on_start', 'on_success', 'on_failure', 'finally']) {
+            for (const st of this.planHookSteps(flow[phase], phase, new Set(), 0)) {
+                if (st.name === 'None')
+                    continue;
+                scan(st);
+                if (st.type === 'flow')
+                    this.collectReferenceIssues(st.name, seen, issues);
+            }
+        }
+    }
+    /** Reject step-scoped `params` that address nothing or are not option objects. */
+    checkScopedParams(flowName, params) {
+        if (!params)
+            return;
+        const selectors = { names: new Set(), paths: new Set() };
+        this.collectSelectors(flowName, '', new Set(), selectors);
+        const problems = [];
+        for (const [key, value] of Object.entries(params)) {
+            if (!selectors.names.has(key) && !selectors.paths.has(key)) {
+                problems.push(`"${key}" matches no task name or step path in flow "${flowName}"`);
+            }
+            else if (!value || typeof value !== 'object' || Array.isArray(value)) {
+                problems.push(`"${key}" must map to an object of options`);
+            }
+        }
+        if (problems.length > 0) {
+            throw new Error(`Invalid step-scoped params: ${problems.join('; ')}`);
+        }
+    }
     resolveExecutionPlan(flow, skipSet) {
         const sortedKeys = Object.keys(flow.steps)
             .map(Number)
@@ -222,6 +632,9 @@ export class FlowRunner {
         if (step.task === 'None') {
             return { stepNumber, type: 'task', name: 'None', skipped: true };
         }
+        if (step.flow === 'None') {
+            return { stepNumber, type: 'flow', name: 'None', skipped: true };
+        }
         const name = (step.task ?? step.flow);
         const type = step.task ? 'task' : 'flow';
         return {
@@ -235,6 +648,7 @@ export class FlowRunner {
             retryOn: step.retryOn,
             when: step.when,
             ignore_failure: step.ignore_failure,
+            ...(step.checks ? { checks: step.checks } : {}),
         };
     }
     planHookSteps(hookSteps, phase, skipSet, baseStepNumber) {
@@ -283,7 +697,7 @@ export class FlowRunner {
      * constructor seed: a `finally` hook gating on `context.executionPhase`
      * would otherwise be told `'task'` and run when it meant to skip.
      */
-    async evaluateWhen(when, completedSteps, params, executionPhase, errorCtx) {
+    async evaluateWhen(when, completedSteps, params, executionPhase, errorCtx, gate) {
         if (when === undefined)
             return true;
         if (typeof when === 'boolean')
@@ -302,6 +716,10 @@ export class FlowRunner {
                 params,
                 context: executionPhase === this.ctx.executionPhase ? this.ctx : { ...this.ctx, executionPhase },
                 error,
+                ...(this.references ? { references: this.references } : {}),
+                ...(gate?.step ? { step: gate.step } : {}),
+                ...(gate?.check ? { check: gate.check } : {}),
+                ...(gate?.flowName ? { flowName: gate.flowName } : {}),
             });
         }
         // Built-in fallback: resolve ${...} references, then test truthiness.
@@ -312,10 +730,132 @@ export class FlowRunner {
         });
         return truthy(resolved);
     }
+    /**
+     * Evaluate declared checks in order. Never throws: an evaluator failure is
+     * reported on the outcome.
+     */
+    async evaluateChecks(checks, scope, flowName, completedSteps, params, executionPhase, step, path, errorCtx) {
+        const out = [];
+        for (const check of checks ?? []) {
+            const outcome = {
+                scope,
+                flowName,
+                ...(step ? { stepNumber: step.stepNumber, name: step.name } : {}),
+                ...(path !== undefined ? { path } : {}),
+                when: check.when,
+                action: check.action,
+                message: check.message ?? defaultCheckMessage(check, scope === 'flow' ? flowName : step?.name),
+                triggered: false,
+            };
+            try {
+                outcome.triggered = await this.evaluateWhen(check.when, completedSteps, params, executionPhase, errorCtx, { step, check, flowName });
+            }
+            catch (err) {
+                outcome.error = err instanceof Error ? err : new Error(String(err));
+            }
+            out.push(outcome);
+        }
+        return out;
+    }
+    /**
+     * Fold evaluated checks into a verdict. Fired checks go to `fired`, fired
+     * `warn` checks to `warnings`. The first fired `error` check wins; an
+     * evaluator failure is returned separately so the caller can treat it like a
+     * `when:` that throws.
+     */
+    applyChecks(outcomes, fired, warnings) {
+        let error;
+        let evalError;
+        let skip = false;
+        for (const o of outcomes) {
+            if (o.error) {
+                evalError ??= new Error(`Check on "${o.name ?? o.flowName}" could not be evaluated: ${o.error.message}`);
+                continue;
+            }
+            if (!o.triggered)
+                continue;
+            fired.push(o);
+            if (o.action === 'error')
+                error ??= new CheckFailedError(o);
+            else if (o.action === 'skip')
+                skip = true;
+            else {
+                warnings.push(checkWarning(o));
+                this.logger.warn({ flow: o.flowName, step: o.stepNumber }, o.message);
+            }
+        }
+        return { error, skip, evalError };
+    }
+    /**
+     * Evaluate every declared check of a flow and its steps without running
+     * anything. Checks see no step results (nothing has run) and the runtime
+     * `params`; one that needs a step result reports an evaluation error and the
+     * row's status is `unknown`. Nested flows are expanded, with paths as in an
+     * expanded plan; hook steps are listed under their phase.
+     */
+    async preflight(flowName, params, options = {}) {
+        const flow = this.flows[flowName];
+        if (!flow)
+            throw new Error(`Flow "${flowName}" not found in configuration`);
+        const skipSet = new Set(options.skip ?? []);
+        const flowChecks = await this.evaluateChecks(flow.checks, 'flow', flowName, [], params, DEFAULT_EXECUTION_PHASE);
+        const steps = [];
+        await this.preflightFlow(flow, flowName, params, skipSet, '', 0, new Set([flowName]), steps);
+        const all = [...flowChecks, ...steps.flatMap((s) => s.checks)];
+        const warnings = mergeWarnings(all.filter((c) => c.triggered && c.action === 'warn').map(checkWarning), await this.annotatePlan(steps.filter((s) => s.status !== 'skip')));
+        const result = {
+            flowName,
+            ok: !all.some((c) => c.triggered && c.action === 'error'),
+            checks: flowChecks,
+            steps,
+        };
+        if (warnings.length > 0)
+            result.warnings = warnings;
+        return result;
+    }
+    async preflightFlow(flow, flowName, params, skipSet, pathPrefix, depth, ancestors, out) {
+        const at = (p) => (pathPrefix ? `${pathPrefix}/${p}` : p);
+        const rows = [
+            ...this.resolveExecutionPlan(flow, skipSet).map((step) => ({ step, path: at(String(step.stepNumber)) })),
+            ...['on_start', 'on_success', 'on_failure', 'finally'].flatMap((phase) => this.planHookSteps(flow[phase], phase, skipSet, 0).map((step, i) => ({
+                step,
+                path: at(`${phase}/${i + 1}`),
+            }))),
+        ];
+        for (const { step, path } of rows) {
+            const row = {
+                stepNumber: step.stepNumber,
+                type: step.type,
+                name: step.name,
+                path,
+                depth,
+                ...(step.phase ? { phase: step.phase } : {}),
+                status: 'run',
+                checks: [],
+            };
+            out.push(row);
+            if (step.skipped) {
+                row.status = 'skip';
+                row.skipReason = 'static';
+                continue;
+            }
+            row.checks = await this.evaluateChecks(step.checks, 'step', flowName, [], params, step.phase ?? DEFAULT_EXECUTION_PHASE, step, path);
+            const child = step.type === 'flow' && !ancestors.has(step.name) ? this.flows[step.name] : undefined;
+            if (child) {
+                row.checks.push(...(await this.evaluateChecks(child.checks, 'flow', step.name, [], params, DEFAULT_EXECUTION_PHASE)));
+            }
+            row.status = checkStatus(row.checks);
+            if (row.status === 'skip')
+                row.skipReason = 'check';
+            if (child && row.status !== 'skip') {
+                await this.preflightFlow(child, step.name, params, skipSet, path, depth + 1, new Set(ancestors).add(step.name), out);
+            }
+        }
+    }
     // ---------------------------------------------------------------------------
     // Internal
     // ---------------------------------------------------------------------------
-    async executeFlow(options, isTopLevel, parentOptions) {
+    async executeFlow(options, isTopLevel, parentOptions, inheritedFrame) {
         const startTime = Date.now();
         const skipSet = new Set(options.skip ?? []);
         const completedSteps = [];
@@ -331,11 +871,41 @@ export class FlowRunner {
         // This level must not invoke them as well.
         const ancestorOwnsRollback = options.rollbackOwnedByAncestor === true;
         const executionPlan = this.resolveExecutionPlan(flow, skipSet);
+        const flowDeprecation = deprecationWarning('flow', options.flowName, flow.deprecated, flow.replaced_by);
+        // The flow a run starts on fixes how its params are addressed; nested
+        // flows inherit that rather than reading their own `options_scope`.
+        const frame = inheritedFrame ?? {
+            pathPrefix: '',
+            scope: options.optionsScope ?? flow.options_scope ?? this.optionsScope,
+        };
+        if (!inheritedFrame && frame.scope === 'step') {
+            try {
+                this.checkScopedParams(options.flowName, options.params);
+            }
+            catch (err) {
+                return { success: false, steps: [], duration: Date.now() - startTime, error: err };
+            }
+        }
+        if (!inheritedFrame && this.strictStepReferences) {
+            const issues = this.checkStepReferences(options.flowName);
+            if (issues.length > 0) {
+                const detail = issues.map((i) => `${i.flowName} step ${i.stepNumber}: ${i.message}`).join('; ');
+                return {
+                    success: false,
+                    steps: [],
+                    duration: Date.now() - startTime,
+                    error: new Error(`Unbindable step references: ${detail}`),
+                };
+            }
+        }
         // Plan mode — dump all phases for visibility, nothing runs.
         if (options.plan) {
-            const mainPlan = options.expandNestedFlows
+            let mainPlan = options.expandNestedFlows
                 ? executionPlan.flatMap((s) => this.expandPlanStep(s, parentOptions, String(s.stepNumber), 0, new Set([options.flowName]), skipSet))
                 : executionPlan;
+            if (options.expandComposites) {
+                mainPlan = await this.expandCompositeRows(mainPlan, options.params, frame.scope);
+            }
             const fullPlan = [
                 ...this.planHookSteps(flow.on_start, 'on_start', skipSet, -3000),
                 ...mainPlan,
@@ -343,7 +913,8 @@ export class FlowRunner {
                 ...this.planHookSteps(flow.on_failure, 'on_failure', skipSet, 20_000),
                 ...this.planHookSteps(flow.finally, 'finally', skipSet, 30_000),
             ];
-            return {
+            const planWarnings = mergeWarnings(flowDeprecation ? [flowDeprecation] : [], await this.annotatePlan(fullPlan));
+            const planResult = {
                 success: true,
                 steps: fullPlan.map((s) => ({
                     stepNumber: s.stepNumber,
@@ -352,20 +923,60 @@ export class FlowRunner {
                     skipped: s.skipped,
                     duration: 0,
                     ...(s.path !== undefined ? { path: s.path, depth: s.depth } : {}),
+                    ...(s.composite ? { composite: s.composite } : {}),
+                    ...(s.deprecated ? { deprecated: s.deprecated } : {}),
+                    ...(s.replaced_by !== undefined ? { replaced_by: s.replaced_by } : {}),
                 })),
                 duration: 0,
             };
+            if (planWarnings.length > 0)
+                planResult.warnings = planWarnings;
+            return planResult;
+        }
+        // Flow-level checks gate everything, hooks included, so they run before
+        // the run is announced to `beforeRun`.
+        const firedChecks = [];
+        const checkWarnings = [];
+        if (flow.checks?.length) {
+            const outcomes = await this.evaluateChecks(flow.checks, 'flow', options.flowName, [], options.params, DEFAULT_EXECUTION_PHASE);
+            const verdict = this.applyChecks(outcomes, firedChecks, checkWarnings);
+            const failure = verdict.error ?? verdict.evalError;
+            if (failure || verdict.skip) {
+                const done = {
+                    success: !failure,
+                    steps: !failure
+                        ? executionPlan.map((s) => ({
+                            stepNumber: s.stepNumber,
+                            type: s.type,
+                            name: s.name,
+                            skipped: true,
+                            duration: 0,
+                            skipReason: 'check',
+                        }))
+                        : [],
+                    duration: Date.now() - startTime,
+                    ...(failure ? { error: failure } : {}),
+                    ...(firedChecks.length > 0 ? { checks: firedChecks } : {}),
+                };
+                const w = mergeWarnings(flowDeprecation ? [flowDeprecation] : [], checkWarnings);
+                if (w.length > 0)
+                    done.warnings = w;
+                return done;
+            }
         }
         if (isTopLevel) {
             await this.hooks.beforeRun?.(options.flowName, executionPlan);
         }
+        if (flowDeprecation)
+            this.logger.warn({ flow: options.flowName }, flowDeprecation.message);
+        const hookWarnings = [];
         let flowError;
         let flowErrorStepName;
         // ---- on_start ----
         {
             const startPlan = this.planHookSteps(flow.on_start, 'on_start', skipSet, -3000);
             for (const hookStep of startPlan) {
-                const ok = await this.runHookStep(hookStep, options, completedSteps, parentOptions, undefined, hookErrors);
+                const ok = await this.runHookStep(hookStep, options, completedSteps, parentOptions, undefined, hookErrors, hookWarnings, frame);
                 if (!ok) {
                     flowError = hookErrors[hookErrors.length - 1]?.error;
                     flowErrorStepName = hookStep.name;
@@ -421,12 +1032,54 @@ export class FlowRunner {
                     await this.hooks.afterStep?.(planStep, sr);
                     continue;
                 }
+                // Declared checks, after `when` has decided the step would run.
+                const stepFired = [];
+                if (planStep.checks?.length) {
+                    const outcomes = await this.evaluateChecks(planStep.checks, 'step', options.flowName, completedSteps, options.params, DEFAULT_EXECUTION_PHASE, planStep, this.stepPath(frame, planStep.stepNumber));
+                    const verdict = this.applyChecks(outcomes, stepFired, checkWarnings);
+                    firedChecks.push(...stepFired);
+                    if (verdict.error || verdict.skip || verdict.evalError) {
+                        const sr = {
+                            stepNumber: planStep.stepNumber,
+                            type: planStep.type,
+                            name: planStep.name,
+                            skipped: !verdict.error && !verdict.evalError,
+                            duration: 0,
+                            ...(stepFired.length > 0 ? { checks: [...stepFired] } : {}),
+                        };
+                        if (sr.skipped) {
+                            sr.skipReason = 'check';
+                        }
+                        else {
+                            sr.result = { success: false, error: (verdict.error ?? verdict.evalError) };
+                        }
+                        completedSteps.push(sr);
+                        await this.hooks.afterStep?.(planStep, sr);
+                        if (sr.skipped)
+                            continue;
+                        // A check that could not be evaluated fails like a `when:` that
+                        // throws, and honours ignore_failure. A fired `error` check is a
+                        // gate and aborts regardless.
+                        if (!verdict.error && planStep.ignore_failure) {
+                            sr.ignoredFailure = true;
+                            continue;
+                        }
+                        flowError = sr.result.error;
+                        flowErrorStepName = planStep.name;
+                        await this.hooks.onStepError?.(planStep, flowError, completedSteps);
+                        break;
+                    }
+                }
                 await this.hooks.beforeStep?.(planStep);
                 const stepStart = Date.now();
+                let nestedChecks;
                 try {
                     let stepResult;
                     if (planStep.type === 'task') {
-                        const { result: taskResult, attempts } = await this.executeTaskStepWithRetry(planStep, options.params, completedSteps, parentOptions);
+                        const { result: taskResult, attempts } = await this.executeTaskStepWithRetry(planStep, this.runtimeOptionsFor(planStep, frame, options.params), completedSteps, parentOptions, undefined, {
+                            path: this.stepPath(frame, planStep.stepNumber),
+                            rollbackOwned: rollbackEnabled || ancestorOwnsRollback,
+                        });
                         stepResult = {
                             stepNumber: planStep.stepNumber,
                             type: 'task',
@@ -443,13 +1096,9 @@ export class FlowRunner {
                         // is pushed last and performRollback walks the array backwards, so
                         // the partial write is undone first and the earlier steps unwind
                         // after it.
-                        if (taskResult.rollback) {
-                            rollbackRecords.push({
-                                taskName: taskResult.rollback.taskName,
-                                payload: taskResult.rollback.payload,
-                                fromFailedStep: !taskResult.success,
-                            });
-                        }
+                        // A composite's children ran before it finished, so their records
+                        // go first and unwind after the composite's own.
+                        harvestRollbacks(taskResult, rollbackRecords);
                     }
                     else {
                         const childParentOptions = this.mergeParentOptions(parentOptions, planStep.options);
@@ -458,7 +1107,10 @@ export class FlowRunner {
                             flowName: planStep.name,
                             plan: false,
                             rollbackOwnedByAncestor: rollbackEnabled || ancestorOwnsRollback,
-                        }, childParentOptions);
+                        }, childParentOptions, { ...frame, pathPrefix: this.stepPath(frame, planStep.stepNumber) });
+                        nestedChecks = nestedResult.checks;
+                        if (nestedChecks)
+                            firedChecks.push(...nestedChecks);
                         stepResult = {
                             stepNumber: planStep.stepNumber,
                             type: 'flow',
@@ -467,6 +1119,7 @@ export class FlowRunner {
                                 success: nestedResult.success,
                                 data: { stepCount: nestedResult.steps.length },
                                 error: nestedResult.success ? undefined : nestedResult.error,
+                                ...(nestedResult.warnings ? { warnings: nestedResult.warnings } : {}),
                             },
                             skipped: false,
                             duration: Date.now() - stepStart,
@@ -477,15 +1130,13 @@ export class FlowRunner {
                         // failing main step's does: the part that landed still needs
                         // undoing, and the child is the only place that knows what it was.
                         for (const s of nestedResult.steps) {
-                            if (s.result?.rollback) {
-                                rollbackRecords.push({
-                                    taskName: s.result.rollback.taskName,
-                                    payload: s.result.rollback.payload,
-                                    fromFailedStep: !s.result.success,
-                                });
-                            }
+                            if (s.type === 'task' && s.result)
+                                harvestRollbacks(s.result, rollbackRecords);
                         }
                     }
+                    const stepChecks = [...stepFired, ...(nestedChecks ?? [])];
+                    if (stepChecks.length > 0)
+                        stepResult.checks = stepChecks;
                     completedSteps.push(stepResult);
                     await this.hooks.afterStep?.(planStep, stepResult);
                     if (!stepResult.result?.success) {
@@ -529,13 +1180,13 @@ export class FlowRunner {
         if (flowError) {
             const failPlan = this.planHookSteps(flow.on_failure, 'on_failure', skipSet, 20_000);
             for (const hookStep of failPlan) {
-                await this.runHookStep(hookStep, options, completedSteps, parentOptions, { error: flowError, step: flowErrorStepName }, hookErrors);
+                await this.runHookStep(hookStep, options, completedSteps, parentOptions, { error: flowError, step: flowErrorStepName }, hookErrors, hookWarnings, frame);
             }
         }
         else {
             const successPlan = this.planHookSteps(flow.on_success, 'on_success', skipSet, 10_000);
             for (const hookStep of successPlan) {
-                await this.runHookStep(hookStep, options, completedSteps, parentOptions, undefined, hookErrors);
+                await this.runHookStep(hookStep, options, completedSteps, parentOptions, undefined, hookErrors, hookWarnings, frame);
             }
         }
         // ---- rollback ----
@@ -547,7 +1198,7 @@ export class FlowRunner {
         {
             const finallyPlan = this.planHookSteps(flow.finally, 'finally', skipSet, 30_000);
             for (const hookStep of finallyPlan) {
-                await this.runHookStep(hookStep, options, completedSteps, parentOptions, flowError ? { error: flowError, step: flowErrorStepName } : undefined, hookErrors);
+                await this.runHookStep(hookStep, options, completedSteps, parentOptions, flowError ? { error: flowError, step: flowErrorStepName } : undefined, hookErrors, hookWarnings, frame);
             }
         }
         const result = {
@@ -558,12 +1209,17 @@ export class FlowRunner {
             hookErrors: hookErrors.length > 0 ? hookErrors : undefined,
             rollback: rollbackResult,
         };
+        const warnings = mergeWarnings(flowDeprecation ? [flowDeprecation] : [], checkWarnings, ...completedSteps.map((s) => s.result?.warnings), hookWarnings);
+        if (warnings.length > 0)
+            result.warnings = warnings;
+        if (firedChecks.length > 0)
+            result.checks = firedChecks;
         if (isTopLevel) {
             await this.hooks.afterRun?.(result);
         }
         return result;
     }
-    async runHookStep(hookStep, options, completedSteps, parentOptions, errorCtx, hookErrors) {
+    async runHookStep(hookStep, options, completedSteps, parentOptions, errorCtx, hookErrors, hookWarnings, frame) {
         if (hookStep.skipped)
             return true;
         // Hook steps honor `when:` too — a falsy condition skips them silently.
@@ -582,6 +1238,17 @@ export class FlowRunner {
                 return false;
             }
         }
+        if (hookStep.checks?.length) {
+            const outcomes = await this.evaluateChecks(hookStep.checks, 'step', options.flowName, completedSteps, options.params, hookStep.phase ?? DEFAULT_EXECUTION_PHASE, hookStep, undefined, errorCtx);
+            const verdict = this.applyChecks(outcomes, [], hookWarnings);
+            const failure = verdict.error ?? verdict.evalError;
+            if (failure) {
+                hookErrors.push({ phase: hookStep.phase, name: hookStep.name, error: failure });
+                return false;
+            }
+            if (verdict.skip)
+                return true;
+        }
         try {
             if (hookStep.type === 'flow') {
                 const childParentOptions = this.mergeParentOptions(parentOptions, hookStep.options);
@@ -593,7 +1260,12 @@ export class FlowRunner {
                     // harvest, so nothing above will unwind it. It owns its own,
                     // whatever the run that triggered the hook is doing.
                     rollbackOwnedByAncestor: false,
-                }, childParentOptions);
+                }, childParentOptions, 
+                // Hook flows are addressed by task name only; the phase keeps their
+                // steps off every main-step path.
+                { ...frame, pathPrefix: `${frame.pathPrefix ? `${frame.pathPrefix}/` : ''}${hookStep.phase}` });
+                if (nested.warnings)
+                    hookWarnings.push(...nested.warnings);
                 if (!nested.success) {
                     hookErrors.push({
                         phase: hookStep.phase,
@@ -604,7 +1276,9 @@ export class FlowRunner {
                 }
                 return true;
             }
-            const { result } = await this.executeTaskStepWithRetry(hookStep, options.params, completedSteps, parentOptions, errorCtx);
+            const { result } = await this.executeTaskStepWithRetry(hookStep, this.runtimeOptionsFor(hookStep, frame, options.params), completedSteps, parentOptions, errorCtx);
+            if (result.warnings)
+                hookWarnings.push(...result.warnings);
             if (!result.success) {
                 hookErrors.push({
                     phase: hookStep.phase,
@@ -624,15 +1298,22 @@ export class FlowRunner {
             return false;
         }
     }
-    async executeTaskStepWithRetry(step, flowParams, completedSteps, parentOptions, errorCtx) {
+    async executeTaskStepWithRetry(step, flowParams, completedSteps, parentOptions, errorCtx, site) {
+        return this.withRetry(step, () => this.executeTaskStep(step, flowParams, completedSteps, parentOptions, errorCtx, site));
+    }
+    /** A step's retry policy (`retries`, `retryDelay`, `retryOn`) around one attempt function. */
+    async withRetry(step, attemptOnce) {
         const maxAttempts = Math.max(1, 1 + (step.retries ?? 0));
         const delayMs = step.retryDelay ?? 0;
         const retryOn = step.retryOn;
         let lastResult = { success: false, error: new Error('no attempts executed') };
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-            lastResult = await this.executeTaskStep(step, flowParams, completedSteps, parentOptions, errorCtx);
+            lastResult = await attemptOnce();
             if (lastResult.success)
                 return { result: lastResult, attempts: attempt };
+            // Bad options fail the same way every time; retrying cannot help.
+            if (lastResult.error instanceof TaskOptionsError)
+                return { result: lastResult, attempts: attempt };
             const errMsg = lastResult.error?.message ?? '';
             const retryMatches = retryOn == null || errMsg.includes(retryOn);
             if (attempt < maxAttempts && retryMatches) {
@@ -645,7 +1326,7 @@ export class FlowRunner {
         }
         return { result: lastResult, attempts: maxAttempts };
     }
-    async executeTaskStep(step, flowParams, completedSteps, parentOptions, errorCtx) {
+    async executeTaskStep(step, flowParams, completedSteps, parentOptions, errorCtx, site) {
         const taskDef = resolveTaskDefinition(step.name, this.tasks);
         // Precedence (low → high): task default → enclosing-flow override → step inline → runtime params.
         // Every layer here is configuration, so the merge is interpolated as a whole.
@@ -678,7 +1359,7 @@ export class FlowRunner {
             };
         }
         this.logger.info({ step: step.stepNumber, task: step.name, type: step.type }, `Executing step ${step.stepNumber}: ${step.name}`);
-        return this.executeTask(taskDef.classPath, mergedOptions, refCtx, step.phase ?? DEFAULT_EXECUTION_PHASE);
+        return this.executeTask(taskDef.classPath, mergedOptions, refCtx, step.phase ?? DEFAULT_EXECUTION_PHASE, step.name, site);
     }
     async performRollback(records) {
         const result = { attempted: 0, succeeded: 0, errors: [] };
@@ -692,7 +1373,7 @@ export class FlowRunner {
                 // `${...}` captured in recorded data is neither substituted nor thrown
                 // on — which the catch below would turn into a silently failed rollback.
                 const resolved = resolveTaskCall(rec.taskName, this.tasks, rec.payload, this.baseReferences);
-                const r = await this.executeTask(resolved.classPath, resolved.options, this.baseReferences, 'rollback');
+                const r = await this.executeTask(resolved.classPath, resolved.options, this.baseReferences, 'rollback', rec.taskName);
                 if (r.success) {
                     result.succeeded++;
                 }
@@ -715,6 +1396,130 @@ export class FlowRunner {
         return result;
     }
 }
+const STEP_REF = /\$\{steps\.([^}]+)\}/g;
+/** Every `${steps.<ref>}` body in the strings found anywhere inside `values`. */
+function stepReferencesIn(values) {
+    const out = [];
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            for (const m of v.matchAll(STEP_REF))
+                out.push(m[1]);
+        }
+        else if (Array.isArray(v)) {
+            v.forEach(walk);
+        }
+        else if (v && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype) {
+            Object.values(v).forEach(walk);
+        }
+    };
+    values.forEach(walk);
+    return out;
+}
+/**
+ * Bind one reference the way the resolver does (longest id prefix first,
+ * a number is a step number, anything else a step name) and report why it
+ * cannot be bound to exactly one earlier main step.
+ */
+function bindStepReference(ref, from, byName, numbers) {
+    const segments = ref.split('.');
+    // Hook steps run after every main step that ran.
+    const before = (n) => from.phase !== undefined || n < from.stepNumber;
+    for (let i = segments.length; i >= 1; i--) {
+        const id = segments.slice(0, i).join('.');
+        if (/^\d+$/.test(id)) {
+            const n = Number(id);
+            if (!numbers.has(n))
+                return { kind: 'unknown', message: `\${steps.${ref}} names step ${id}, which does not exist` };
+            if (!before(n)) {
+                return { kind: 'forward', message: `\${steps.${ref}} names step ${id}, which has not run yet` };
+            }
+            return undefined;
+        }
+        const matches = byName.get(id);
+        if (!matches)
+            continue;
+        if (matches.length > 1) {
+            return {
+                kind: 'ambiguous',
+                message: `\${steps.${ref}}: "${id}" is the name of steps ${matches.join(', ')}; reference one by number`,
+            };
+        }
+        if (!before(matches[0])) {
+            return { kind: 'forward', message: `\${steps.${ref}}: step "${id}" has not run yet` };
+        }
+        return undefined;
+    }
+    return { kind: 'unknown', message: `\${steps.${ref}} matches no step number or name in the flow` };
+}
+/**
+ * Interpolate what can be interpolated before a run: host namespaces resolve,
+ * and anything that throws (a step reference, nothing having run) is left as
+ * written.
+ */
+function lenientReferences(value, refs) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        try {
+            out[k] = resolveReferences(v, refs);
+        }
+        catch {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Harvest a task result's rollback records, its composite children's first
+ * (recursively, child flows' steps included), then its own.
+ */
+function harvestRollbacks(result, into) {
+    for (const child of result.children ?? [])
+        harvestStep(child, into);
+    if (result.rollback) {
+        into.push({
+            taskName: result.rollback.taskName,
+            payload: result.rollback.payload,
+            fromFailedStep: !result.success,
+        });
+    }
+}
+function harvestStep(step, into) {
+    if (step.result)
+        harvestRollbacks(step.result, into);
+    for (const nested of step.nestedSteps ?? [])
+        harvestStep(nested, into);
+}
+/** Status a set of evaluated checks gives a preflight row. Error beats skip beats unknown. */
+function checkStatus(outcomes) {
+    if (outcomes.some((o) => o.triggered && o.action === 'error'))
+        return 'error';
+    if (outcomes.some((o) => o.triggered && o.action === 'skip'))
+        return 'skip';
+    if (outcomes.some((o) => o.error))
+        return 'unknown';
+    return 'run';
+}
+function defaultCheckMessage(check, subject) {
+    const cond = typeof check.when === 'string' ? check.when : String(check.when);
+    return `Check on ${subject ? `"${subject}"` : 'step'} fired (${check.action}): ${cond}`;
+}
+/** The warning a fired `warn` check contributes to a run. */
+function checkWarning(o) {
+    return {
+        code: 'check',
+        message: o.message,
+        name: o.scope === 'flow' ? o.flowName : (o.name ?? o.flowName),
+        kind: o.scope === 'flow' ? 'flow' : undefined,
+        ...(o.stepNumber !== undefined ? { stepNumber: o.stepNumber } : {}),
+    };
+}
+/** Append a runner notice to a task's result without dropping any the task added itself. */
+function withWarnings(result, warning) {
+    if (!warning)
+        return result;
+    result.warnings = [...(result.warnings ?? []), warning];
+    return result;
+}
 /** Truthiness of a resolved `when:` value, with string special-cases. */
 function truthy(value) {
     if (typeof value === 'boolean')