@usearazzo/runner 1.0.1-alpha.22 → 1.0.1-alpha.24

package/src/resolver/RequestBodyResolver.cjs

@@ -75,7 +75,7 @@ class RequestBodyResolver extends _ArazzoValueResolver.default {
       throw new _ResolverError.default('`requestBody` is present but is not a map', {
         ...scope,
         target: 'requestBody',
-        reason: 'malformed-request-body'
+        reason: _ResolverError.default.MalformedRequestBody
       });
     }
     const authoredPayload = (0, _apidomCore.toValue)(requestBody.payload);
@@ -87,7 +87,7 @@ class RequestBodyResolver extends _ArazzoValueResolver.default {
         throw new _ResolverError.default('`requestBody.replacements` is present but is not a list', {
           ...scope,
           target: 'requestBody.replacements',
-          reason: 'malformed-replacements'
+          reason: _ResolverError.default.MalformedReplacements
         });
       }
       for (const replacement of requestBody.replacements) {
@@ -152,7 +152,7 @@ class RequestBodyResolver extends _ArazzoValueResolver.default {
         throw new _ResolverError.default(`Invalid runtime expression "${text}" in ${this.#payloadTarget(tokens)}`, {
           ...scope,
           target: this.#payloadTarget(tokens),
-          reason: 'invalid-expression'
+          reason: _ResolverError.default.InvalidExpression
         });
       }
     });
@@ -171,7 +171,7 @@ class RequestBodyResolver extends _ArazzoValueResolver.default {
     return new _ResolverError.default(`Runtime expression "${expression}" in ${target} did not resolve`, {
       ...scope,
       target,
-      reason: 'unresolved-expression'
+      reason: _ResolverError.default.UnresolvedExpression
     });
   }
 
@@ -195,7 +195,7 @@ class RequestBodyResolver extends _ArazzoValueResolver.default {
       throw new _ResolverError.default(`Unsupported requestBody replacement target "${target}" (expected JSON Pointer)`, {
         ...scope,
         target,
-        reason: 'unsupported-target'
+        reason: _ResolverError.default.UnsupportedTarget
       });
     }
 
@@ -209,7 +209,7 @@ class RequestBodyResolver extends _ArazzoValueResolver.default {
       throw new _ResolverError.default(`requestBody replacement target "${target}" does not resolve in the payload`, {
         ...scope,
         target,
-        reason: 'unresolved-target'
+        reason: _ResolverError.default.UnresolvedTarget
       });
     }
     return (0, _ramda.assocPath)(tokens, value, payload);

package/src/resolver/RequestBodyResolver.mjs

@@ -68,7 +68,7 @@ class RequestBodyResolver extends ArazzoValueResolver {
       throw new ResolverError('`requestBody` is present but is not a map', {
         ...scope,
         target: 'requestBody',
-        reason: 'malformed-request-body'
+        reason: ResolverError.MalformedRequestBody
       });
     }
     const authoredPayload = toValue(requestBody.payload);
@@ -80,7 +80,7 @@ class RequestBodyResolver extends ArazzoValueResolver {
         throw new ResolverError('`requestBody.replacements` is present but is not a list', {
           ...scope,
           target: 'requestBody.replacements',
-          reason: 'malformed-replacements'
+          reason: ResolverError.MalformedReplacements
         });
       }
       for (const replacement of requestBody.replacements) {
@@ -145,7 +145,7 @@ class RequestBodyResolver extends ArazzoValueResolver {
         throw new ResolverError(`Invalid runtime expression "${text}" in ${this.#payloadTarget(tokens)}`, {
           ...scope,
           target: this.#payloadTarget(tokens),
-          reason: 'invalid-expression'
+          reason: ResolverError.InvalidExpression
         });
       }
     });
@@ -164,7 +164,7 @@ class RequestBodyResolver extends ArazzoValueResolver {
     return new ResolverError(`Runtime expression "${expression}" in ${target} did not resolve`, {
       ...scope,
       target,
-      reason: 'unresolved-expression'
+      reason: ResolverError.UnresolvedExpression
     });
   }
 
@@ -188,7 +188,7 @@ class RequestBodyResolver extends ArazzoValueResolver {
       throw new ResolverError(`Unsupported requestBody replacement target "${target}" (expected JSON Pointer)`, {
         ...scope,
         target,
-        reason: 'unsupported-target'
+        reason: ResolverError.UnsupportedTarget
       });
     }
 
@@ -202,7 +202,7 @@ class RequestBodyResolver extends ArazzoValueResolver {
       throw new ResolverError(`requestBody replacement target "${target}" does not resolve in the payload`, {
         ...scope,
         target,
-        reason: 'unresolved-target'
+        reason: ResolverError.UnresolvedTarget
       });
     }
     return assocPath(tokens, value, payload);

package/src/resolver/WorkflowParameterResolver.cjs

@@ -44,7 +44,7 @@ class WorkflowParameterResolver extends _StepParameterResolver.default {
       throw new _ResolverError.default('`parameters` is present but is not a list', {
         ...scope,
         target: 'parameters',
-        reason: 'malformed-parameters'
+        reason: _ResolverError.default.MalformedParameters
       });
     }
     for (const parameter of parameters) {

package/src/resolver/WorkflowParameterResolver.mjs

@@ -37,7 +37,7 @@ class WorkflowParameterResolver extends StepParameterResolver {
       throw new ResolverError('`parameters` is present but is not a list', {
         ...scope,
         target: 'parameters',
-        reason: 'malformed-parameters'
+        reason: ResolverError.MalformedParameters
       });
     }
     for (const parameter of parameters) {

package/types/runner.d.ts

@@ -1,3 +1,4 @@
+import type { ApiDOMErrorOptions } from '@speclynx/apidom-error';
 import { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { CriterionElement } from '@speclynx/apidom-ns-arazzo-1';
@@ -472,58 +473,62 @@ export declare interface ContextSource {
  */
 export declare type CriterionContextResolver = (expression: string) => unknown;
 
-/** @public */
-export declare class CriterionError extends ArazzoRunnerError {
-    readonly condition?: string;
-    readonly type?: string;
-    readonly reason?: CriterionErrorReason;
-}
-
 /**
- * The `reason` a {@link CriterionError} carries.
+ * Carries a `reason`, one of the class's static reason fields.
  *
- * Structural reasons mark a criterion that is malformed as written; they are
- * thrown as a plain `CriterionError`. Evaluation reasons (`InvalidSimple`,
- * `InvalidRegex`, `InvalidJSONPath`, `InvalidXPath`, `InvalidXPathContext`) mark
- * a condition that cannot be evaluated; they are thrown as a
- * {@link CriterionEvaluationError}, which `CriterionEvaluator` turns into an
- * unmet criterion.
+ * Every static on this class is a reason: {@link CriterionErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
  * @public
  */
-export declare const CriterionErrorReason: {
+export declare class CriterionError extends ArazzoRunnerError {
     /** The element is not a Criterion Object. */
-    readonly InvalidCriterion: "invalid-criterion";
+    static readonly InvalidCriterion: "invalid-criterion";
     /** The `condition` is missing or empty. */
-    readonly MissingCondition: "missing-condition";
+    static readonly MissingCondition: "missing-condition";
     /** The `type` is present but unreadable. */
-    readonly InvalidType: "invalid-type";
+    static readonly InvalidType: "invalid-type";
     /** The `type` names no known criterion type. */
-    readonly UnknownType: "unknown-type";
+    static readonly UnknownType: "unknown-type";
     /** The expression type `version` is present but not a string. */
-    readonly InvalidVersion: "invalid-version";
+    static readonly InvalidVersion: "invalid-version";
     /** The expression type `version` is not the one this runner supports. */
-    readonly UnsupportedVersion: "unsupported-version";
+    static readonly UnsupportedVersion: "unsupported-version";
     /** The `context` is not a runtime expression. */
-    readonly InvalidContext: "invalid-context";
+    static readonly InvalidContext: "invalid-context";
     /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
-    readonly MissingContext: "missing-context";
+    static readonly MissingContext: "missing-context";
     /** The `simple` condition cannot be parsed. */
-    readonly InvalidSimple: "invalid-simple";
+    static readonly InvalidSimple: "invalid-simple";
     /** The `regex` condition is not a valid regular expression. */
-    readonly InvalidRegex: "invalid-regex";
+    static readonly InvalidRegex: "invalid-regex";
     /** The `jsonpath` condition is not a valid JSONPath query. */
-    readonly InvalidJSONPath: "invalid-jsonpath";
+    static readonly InvalidJSONPath: "invalid-jsonpath";
     /** The `xpath` condition is invalid or fails to evaluate. */
-    readonly InvalidXPath: "invalid-xpath";
+    static readonly InvalidXPath: "invalid-xpath";
     /** The resolved `xpath` context is not XML. */
-    readonly InvalidXPathContext: "invalid-xpath-context";
-};
+    static readonly InvalidXPathContext: "invalid-xpath-context";
+    readonly condition?: string;
+    readonly type?: string;
+    readonly reason?: CriterionErrorReason;
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: CriterionErrorReason;
+    });
+}
 
 /**
- * One of the `CriterionErrorReason` values.
+ * One of the reasons a {@link CriterionError} carries: a `CriterionError`
+ * static such as `CriterionError.InvalidRegex`.
+ *
+ * Structural reasons mark a criterion that is malformed as written; they are
+ * thrown as a plain `CriterionError`. Evaluation reasons (`InvalidSimple`,
+ * `InvalidRegex`, `InvalidJSONPath`, `InvalidXPath`, `InvalidXPathContext`) mark
+ * a condition that cannot be evaluated; they are thrown as a
+ * {@link CriterionEvaluationError}, which `CriterionEvaluator` turns into an
+ * unmet criterion.
  * @public
  */
-export declare type CriterionErrorReason = (typeof CriterionErrorReason)[keyof typeof CriterionErrorReason];
+export declare type CriterionErrorReason = (typeof CriterionError)[Exclude<keyof typeof CriterionError, keyof typeof ArazzoRunnerError | 'prototype'>];
 
 /**
  * A criterion condition that cannot be evaluated: a syntax error in the
@@ -562,10 +567,10 @@ export declare interface CriterionEvaluationRecord {
     readonly diagnostic?: {
         /**
          * Machine-readable: the `reason` of the error that failed the criterion, a
-         * `CriterionErrorReason` value or `'unavailable-expression'` for an
-         * HTTP-exchange expression in a step that calls a workflow.
+         * `CriterionErrorReason` or `RuntimeExpressionError.UnavailableExpression`
+         * for an HTTP-exchange expression in a step that calls a workflow.
          */
-        readonly code?: CriterionErrorReason | 'unavailable-expression';
+        readonly code?: CriterionErrorReason | typeof RuntimeExpressionError.UnavailableExpression;
         /**
          * Human-readable: names the condition or expression and, for a syntax
          * error, what is wrong with it; never request or response data.
@@ -763,18 +768,83 @@ export declare abstract class DocumentRegistryProvider {
  */
 export declare type DocumentRegistryProviderOptions = PartialDeep<ApiDOMReferenceOptions>;
 
-/** @public */
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link ExecutionErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
+ * @public
+ */
 export declare class ExecutionError extends ArazzoRunnerError {
+    /** The run was cancelled through its `AbortSignal`; the signal's reason is the `cause`. */
+    static readonly Aborted: "aborted";
+    /** A step or a `goto`/`retry` action declares more than one mutually exclusive target. */
+    static readonly AmbiguousTarget: "ambiguous-target";
+    /** The `dependsOn` edges alone form a cycle between workflows. */
+    static readonly DependsOnCycle: "dependsOn-cycle";
+    /** A `goto` action declares neither a `stepId` nor a `workflowId`. */
+    static readonly GotoTargetMissing: "goto-target-missing";
+    /** A `goto` action's `stepId` names no step in the workflow. */
+    static readonly GotoTargetNotFound: "goto-target-not-found";
+    /** An `operationId` or `operationPath` is not a valid operation reference. */
+    static readonly InvalidOperationReference: "invalid-operation-reference";
+    /** A `workflowId` is not a valid `$sourceDescriptions.{name}.{workflowId}` expression. */
+    static readonly InvalidWorkflowReference: "invalid-workflow-reference";
+    /** A workflow's `dependsOn` is not a list or holds a non-string entry. */
+    static readonly MalformedDependsOn: "malformed-dependsOn";
+    /** A workflow's `steps` is not a list or holds an entry that is not a Step Object. */
+    static readonly MalformedSteps: "malformed-steps";
+    /** A step run as an operation declares neither an `operationId` nor an `operationPath`. */
+    static readonly MissingOperation: "missing-operation";
+    /** An operation reference locates no operation in its OpenAPI source description. */
+    static readonly OperationNotFound: "operation-not-found";
+    /** A `retry` action references a step or workflow, but no run reference was given to run it. */
+    static readonly RetryReferenceUnsupported: "retry-reference-unsupported";
+    /** A `retry` action's `stepId` names no step in the workflow. */
+    static readonly RetryTargetNotFound: "retry-target-not-found";
+    /** A workflow reference names a source description that is not an Arazzo document. */
+    static readonly SourceDescriptionNotArazzo: "source-description-not-arazzo";
+    /** A reference names a source description the Arazzo document does not define. */
+    static readonly SourceDescriptionNotFound: "source-description-not-found";
+    /** An operation reference names a source description that is not an OpenAPI document. */
+    static readonly SourceDescriptionNotOpenAPI: "source-description-not-openapi";
+    /** A workflow exceeded its budget of step attempts. */
+    static readonly StepBudget: "step-budget";
+    /** An action declares a `type` other than `end`, `goto` or `retry`. */
+    static readonly UnknownActionType: "unknown-action-type";
+    /** `execute` received an option it does not know. */
+    static readonly UnknownExecuteOption: "unknown-execute-option";
+    /** A step produced a transition the workflow executor does not recognize. */
+    static readonly UnknownTransitionKind: "unknown-transition-kind";
+    /** A sub-workflow call (alone or together with `dependsOn`) forms a cycle between workflows. */
+    static readonly WorkflowCycle: "workflow-cycle";
+    /** Workflows nest deeper than the configured limit. */
+    static readonly WorkflowDepth: "workflow-depth";
+    /** A workflow reference names a workflow the Arazzo document does not define. */
+    static readonly WorkflowNotFound: "workflow-not-found";
+    /** A step that targets a workflow was handed to the step executor, which runs operations only. */
+    static readonly WorkflowStep: "workflow-step";
     readonly stepId?: string;
     readonly workflowId?: string;
-    readonly reason?: string;
+    readonly reason?: ExecutionErrorReason;
     /**
      * The chain of workflowIds the error concerns — the loop A → B → A for a
      * cycle, or the call chain in progress when a budget ran out.
      */
     readonly path?: readonly string[];
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: ExecutionErrorReason;
+    });
 }
 
+/**
+ * One of the reasons an {@link ExecutionError} carries: an `ExecutionError`
+ * static such as `ExecutionError.OperationNotFound`.
+ * @public
+ */
+export declare type ExecutionErrorReason = (typeof ExecutionError)[Exclude<keyof typeof ExecutionError, keyof typeof ArazzoRunnerError | 'prototype'>];
+
 /** @public */
 export declare class ExtractionError extends ArazzoRunnerError {
     readonly workflowId?: string;
@@ -1254,7 +1324,7 @@ export declare interface OpenAPIOperationLocator {
  *   `$sourceDescriptions.{name}.{operationId}`. Per the Arazzo Specification, a
  *   plain name is only valid when a single (non-arazzo) source description is
  *   defined; multiple sources require the expression form. A plain name is
- *   therefore resolved against the first source description that has it.
+ *   therefore looked up in the first OpenAPI source description only.
  * - `operationPath` embeds a `{$sourceDescriptions.{name}.url}` runtime
  *   expression followed by a JSON Pointer to the operation.
  *
@@ -1262,6 +1332,14 @@ export declare interface OpenAPIOperationLocator {
  * or wrong); a source is classified by what it actually parses to. The
  * normalizer acquires the referenced source documents from the registry on
  * demand.
+ *
+ * A reference that cannot be resolved throws {@link ExecutionError}, attributed
+ * to the referencing step when a {@link StepScope} is given:
+ * `operation-not-found` when no operation answers it,
+ * `source-description-not-found` for a source name the document does not
+ * define, `source-description-not-openapi` for a source that is not an OpenAPI
+ * document, and `invalid-operation-reference` for a reference malformed as
+ * written. Every returned locator names an existing operation.
  * @public
  */
 export declare class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
@@ -1270,10 +1348,10 @@ export declare class OpenAPIOperationLocatorNormalizer extends SourceDescription
      * Normalizes a plain or expression `operationId` to a canonical locator.
      *
      * A whole runtime expression (`$sourceDescriptions.{name}.{operationId}`) is
-     * resolved against its named source; a plain name is resolved against the
-     * first source description that has it.
+     * resolved against its named source; a plain name is looked up in the first
+     * OpenAPI source description only.
      */
-    normalizeOperationId(operationId: string, document: ArazzoDocument): Promise<OpenAPIOperationLocator>;
+    normalizeOperationId(operationId: string, document: ArazzoDocument, scope?: StepScope): Promise<OpenAPIOperationLocator>;
     /**
      * Normalizes an `operationPath` —
      * `{$sourceDescriptions.{name}.url}#/json/pointer` — to a canonical locator.
@@ -1287,10 +1365,12 @@ export declare class OpenAPIOperationLocatorNormalizer extends SourceDescription
      * The runner only needs a URL and a JSON Pointer, so it does not enforce that
      * the source description is identified by a runtime expression rather than a
      * literal URL (a literal URL interpolates to itself and still resolves) — that
-     * is a conformance concern for the validator. It fails only when the URL does
-     * not resolve to an OpenAPI source or the JSON Pointer is invalid.
+     * is a conformance concern for the validator. A source name the document does
+     * not define is detected before interpolation, so it is reported as such
+     * rather than as the empty URL it would interpolate to; the JSON Pointer must
+     * locate an operation in the acquired OpenAPI document.
      */
-    normalizeOperationPath(operationPath: string, document: ArazzoDocument): Promise<OpenAPIOperationLocator>;
+    normalizeOperationPath(operationPath: string, document: ArazzoDocument, scope?: StepScope): Promise<OpenAPIOperationLocator>;
 }
 
 /**
@@ -1523,7 +1603,7 @@ export declare class OutputResolver extends ArazzoValueResolver {
      *
      * `scope` names the step or workflow the outputs belong to, for a thrown
      * {@link ResolverError}. An output value that is not a valid runtime
-     * expression throws with `reason: 'invalid-expression'`.
+     * expression throws with reason `ResolverError.InvalidExpression`.
      */
     resolve(outputs: StepOutputsElement | WorkflowOutputsElement | undefined, resolve: RuntimeExpressionResolver, scope: ResolverScope): Record<string, unknown>;
 }
@@ -1619,14 +1699,65 @@ export declare interface ResolvedRequestBody {
     readonly contentType?: string;
 }
 
-/** @public */
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link ResolverErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
+ * @public
+ */
 export declare class ResolverError extends ArazzoRunnerError {
+    /** A parameter cannot be delivered unambiguously at its location. */
+    static readonly AmbiguousDelivery: "ambiguous-delivery";
+    /** An output or a request body payload holds a value that is not a valid runtime expression. */
+    static readonly InvalidExpression: "invalid-expression";
+    /** A parameter's location (`in`) is not one of the known locations. */
+    static readonly InvalidLocation: "invalid-location";
+    /** An `onSuccess`/`onFailure` list holds an entry that is not a Success/Failure Action Object. */
+    static readonly MalformedActionEntry: "malformed-action-entry";
+    /** A step's `onSuccess` or `onFailure` is present but is not a list. */
+    static readonly MalformedActions: "malformed-actions";
+    /** A step's `successCriteria` or an action's `criteria` is present but is not a list. */
+    static readonly MalformedCriteria: "malformed-criteria";
+    /** A criteria list holds an entry that is not a Criterion Object. */
+    static readonly MalformedCriterion: "malformed-criterion";
+    /** A parameter's location (`in`) is not a string. */
+    static readonly MalformedLocation: "malformed-location";
+    /** A step's or workflow's `outputs` is present but is not a map. */
+    static readonly MalformedOutputs: "malformed-outputs";
+    /** `parameters` is present but is not a list. */
+    static readonly MalformedParameters: "malformed-parameters";
+    /** `requestBody.replacements` is present but is not a list. */
+    static readonly MalformedReplacements: "malformed-replacements";
+    /** `requestBody` is present but is not a map. */
+    static readonly MalformedRequestBody: "malformed-request-body";
+    /** A parameter of a step that targets an operation declares no location (`in`). */
+    static readonly MissingLocation: "missing-location";
+    /** A parameter has a missing or non-string `name`. */
+    static readonly MissingName: "missing-name";
+    /** A runtime expression in the request body did not resolve. */
+    static readonly UnresolvedExpression: "unresolved-expression";
+    /** A `requestBody` replacement target does not resolve in the payload. */
+    static readonly UnresolvedTarget: "unresolved-target";
+    /** A `requestBody` replacement target is not a JSON Pointer. */
+    static readonly UnsupportedTarget: "unsupported-target";
     readonly stepId?: string;
     readonly workflowId?: string;
     readonly target?: string;
-    readonly reason?: string;
+    readonly reason?: ResolverErrorReason;
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: ResolverErrorReason;
+    });
 }
 
+/**
+ * One of the reasons a {@link ResolverError} carries: a `ResolverError`
+ * static such as `ResolverError.MalformedParameters`.
+ * @public
+ */
+export declare type ResolverErrorReason = (typeof ResolverError)[Exclude<keyof typeof ResolverError, keyof typeof ArazzoRunnerError | 'prototype'>];
+
 /**
  * Identifies the step or workflow a resolver is resolving for. The wider
  * union {@link OutputResolver} takes, since it resolves both a step's
@@ -1726,12 +1857,42 @@ export declare interface RuntimeExpressionContext {
     readonly calledWorkflow?: RuntimeExpressionCalledWorkflowContext;
 }
 
-/** @public */
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link RuntimeExpressionErrorReason}
+ * is derived from the class's own statics, so a non-reason static would join
+ * the union.
+ * @public
+ */
 export declare class RuntimeExpressionError extends ArazzoRunnerError {
+    /** The expression is not a valid runtime expression. */
+    static readonly InvalidExpression: "invalid-expression";
+    /** The runtime expression parser failed on the expression. */
+    static readonly ParseError: "parse-error";
+    /**
+     * The expression reads HTTP data (`$statusCode`, `$url`, `$method`, `$request`,
+     * `$response`) in a step that calls a workflow and so made no HTTP call.
+     */
+    static readonly UnavailableExpression: "unavailable-expression";
+    /** The expression could not be resolved against the evaluation context. */
+    static readonly UnresolvedReference: "unresolved-reference";
+    /** The parsed expression contains a node the evaluator does not support. */
+    static readonly UnsupportedNode: "unsupported-node";
     readonly expression?: string;
-    readonly reason?: string;
+    readonly reason?: RuntimeExpressionErrorReason;
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: RuntimeExpressionErrorReason;
+    });
 }
 
+/**
+ * One of the reasons a {@link RuntimeExpressionError} carries: a
+ * `RuntimeExpressionError` static such as `RuntimeExpressionError.ParseError`.
+ * @public
+ */
+export declare type RuntimeExpressionErrorReason = (typeof RuntimeExpressionError)[Exclude<keyof typeof RuntimeExpressionError, keyof typeof ArazzoRunnerError | 'prototype'>];
+
 /**
  * Evaluates Arazzo runtime expressions against a context.
  *
@@ -2045,12 +2206,16 @@ export declare class StepExecutor {
      * take precedence over it.
      *
      * A `signal` in that bag is honored here and not only at the transport: an
-     * already-aborted signal throws `reason: 'aborted'` instead of issuing a
+     * already-aborted signal throws with reason `ExecutionError.Aborted` instead of issuing a
      * request nobody is waiting for, whose wire-level cancellation would surface
      * as a transport {@link ClientError} — a request that failed on its own terms
      * — rather than as the withdrawal it is.
+     *
+     * `workflowId` names the workflow the step belongs to; every error raised
+     * here then carries it alongside the `stepId`, since step ids are only
+     * unique within a workflow. The workflow executor always passes it.
      */
-    execute(step: StepElement, state: ContextSource, executeOptions?: Record<string, unknown>): Promise<StepExecutionResult>;
+    execute(step: StepElement, state: ContextSource, executeOptions?: Record<string, unknown>, workflowId?: string): Promise<StepExecutionResult>;
     /**
      * Throws {@link ResolverError} unless the step's `successCriteria` is absent
      * or a list of Criterion Objects: `malformed-criteria` for one that is
@@ -2077,9 +2242,11 @@ export declare class StepExecutor {
      * Public for the same reason as {@link StepExecutor.selectActions}: a step
      * targeting a `workflowId` is run by the workflow executor and never reaches
      * {@link StepExecutor.execute}, but its criteria are still the author's
-     * assertion about the step and must be evaluated somewhere.
+     * assertion about the step and must be evaluated somewhere. `workflowId`
+     * names the step's workflow on a thrown error, as for
+     * {@link StepExecutor.execute}.
      */
-    evaluateCriteria(step: StepElement, context: RuntimeExpressionContext): CriterionEvaluationRecord[];
+    evaluateCriteria(step: StepElement, context: RuntimeExpressionContext, workflowId?: string): CriterionEvaluationRecord[];
     /**
      * Selects every matching `onSuccess` / `onFailure` action for the outcome, in
      * list order, gating each action's criteria against the context, and records
@@ -2100,8 +2267,10 @@ export declare class StepExecutor {
      * it runs itself and which therefore never reaches
      * {@link StepExecutor.execute}. Both callers reach the criteria evaluator and
      * the expression context through this one method rather than wiring their own.
+     * `workflowId` names the step's workflow on a thrown error, as for
+     * {@link StepExecutor.execute}.
      */
-    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext): Pick<StepExecutionResult, 'matchedActions' | 'actionCriteria'>;
+    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext, workflowId?: string): Pick<StepExecutionResult, 'matchedActions' | 'actionCriteria'>;
 }
 
 /**
@@ -2210,14 +2379,21 @@ export declare interface StepRunRecord {
 }
 
 /**
- * Identifies the step a resolver is resolving for, so a thrown
- * {@link ResolverError} can say which one it came from. Every resolver that
- * only ever runs within a step's scope — {@link OpenAPIOperationParameterResolver},
+ * Identifies the step something is being resolved or located for, so a thrown
+ * error can say which one it came from. Every resolver that only ever runs
+ * within a step's scope — {@link OpenAPIOperationParameterResolver},
  * {@link WorkflowParameterResolver}, {@link RequestBodyResolver},
- * {@link ActionResolver} — takes this.
+ * {@link ActionResolver} — takes this, as does
+ * {@link OpenAPIOperationLocatorNormalizer} for the step whose operation it
+ * locates.
  * @public
  */
 export declare interface StepScope {
+    /**
+     * The workflow the step belongs to, when the caller knows it: step ids are
+     * only unique within a workflow.
+     */
+    readonly workflowId?: string;
     readonly stepId: string;
 }
 
@@ -2276,7 +2452,7 @@ export declare interface WorkflowExecuteOptions {
      * `retryAfter` waits between attempts, so an aborted run stops at the next
      * boundary rather than working its way to the end of the workflow.
      *
-     * An aborted run throws {@link ExecutionError} with `reason: 'aborted'`,
+     * An aborted run throws {@link ExecutionError} with reason `ExecutionError.Aborted`,
      * naming the boundary it stopped at and carrying the signal's own `reason` as
      * the error's `cause`. It does not resolve as a `failed` result: cancellation
      * is not something the steps did, and the steps that never ran were not
@@ -2524,9 +2700,9 @@ export declare interface WorkflowExecutorOptions {
     readonly maxSteps?: number;
     /**
      * Upper bound on how deeply workflows may nest — a workflow entered while
-     * this many are already in progress throws `reason: 'workflow-depth'`.
+     * this many are already in progress throws with reason `ExecutionError.WorkflowDepth`.
      * Bounds *legitimate* (acyclic) nesting; a genuine cycle is caught earlier and
-     * separately by `reason: 'workflow-cycle'`. Defaults to 32.
+     * separately by reason `ExecutionError.WorkflowCycle`. Defaults to 32.
      *
      * The count includes the workflow `execute` was called with, so `1` permits
      * that workflow and forbids all nesting; a value below 1 leaves no room for

package/src/criterion/CriterionErrorReason.cjs

@@ -1,51 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-/**
- * The `reason` a {@link CriterionError} carries.
- *
- * Structural reasons mark a criterion that is malformed as written; they are
- * thrown as a plain `CriterionError`. Evaluation reasons (`InvalidSimple`,
- * `InvalidRegex`, `InvalidJSONPath`, `InvalidXPath`, `InvalidXPathContext`) mark
- * a condition that cannot be evaluated; they are thrown as a
- * {@link CriterionEvaluationError}, which `CriterionEvaluator` turns into an
- * unmet criterion.
- * @public
- */
-const CriterionErrorReason = {
-  /** The element is not a Criterion Object. */
-  InvalidCriterion: 'invalid-criterion',
-  /** The `condition` is missing or empty. */
-  MissingCondition: 'missing-condition',
-  /** The `type` is present but unreadable. */
-  InvalidType: 'invalid-type',
-  /** The `type` names no known criterion type. */
-  UnknownType: 'unknown-type',
-  /** The expression type `version` is present but not a string. */
-  InvalidVersion: 'invalid-version',
-  /** The expression type `version` is not the one this runner supports. */
-  UnsupportedVersion: 'unsupported-version',
-  /** The `context` is not a runtime expression. */
-  InvalidContext: 'invalid-context',
-  /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
-  MissingContext: 'missing-context',
-  /** The `simple` condition cannot be parsed. */
-  InvalidSimple: 'invalid-simple',
-  /** The `regex` condition is not a valid regular expression. */
-  InvalidRegex: 'invalid-regex',
-  /** The `jsonpath` condition is not a valid JSONPath query. */
-  InvalidJSONPath: 'invalid-jsonpath',
-  /** The `xpath` condition is invalid or fails to evaluate. */
-  InvalidXPath: 'invalid-xpath',
-  /** The resolved `xpath` context is not XML. */
-  InvalidXPathContext: 'invalid-xpath-context'
-};
-
-/**
- * One of the `CriterionErrorReason` values.
- * @public
- */
-var _default = exports.default = CriterionErrorReason;