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

package/src/executor/OpenAPIOperationLocatorNormalizer.mjs

@@ -1,9 +1,10 @@
-import { test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
+import { extract, test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
 import { URIFragmentIdentifier, testJSONPointer } from '@swaggerexpert/json-pointer';
 import { url } from '@speclynx/apidom-reference/configuration/empty';
 import OpenAPIDocument from "../document/OpenAPIDocument.mjs";
 import RuntimeExpressionEvaluator from "../expression/RuntimeExpressionEvaluator.mjs";
-import ExtractionError from "../errors/ExtractionError.mjs";
+import OpenAPIOperationExtractor from "../extractor/OpenAPIOperationExtractor.mjs";
+import ExecutionError from "../errors/ExecutionError.mjs";
 import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNormalizer.mjs";
 /**
  * A canonical OpenAPI operation locator: the OpenAPI document that owns the
@@ -26,7 +27,7 @@ import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNorm
  *   `$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.
  *
@@ -34,21 +35,31 @@ import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNorm
  * 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
  */
 class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
+  #extractor = new OpenAPIOperationExtractor();
+
   /**
    * 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.
    */
-  async normalizeOperationId(operationId, document) {
+  async normalizeOperationId(operationId, document, scope) {
     if (isRuntimeExpression(operationId)) {
-      return this.#resolveSourced(operationId, document);
+      return this.#resolveSourced(operationId, document, scope);
     }
-    return this.#resolvePlainOperationId(operationId, document);
+    return this.#resolvePlainOperationId(operationId, document, scope);
   }
 
   /**
@@ -64,10 +75,21 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
    * 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.
    */
-  async normalizeOperationPath(operationPath, document) {
+  async normalizeOperationPath(operationPath, document, scope) {
+    for (const expression of extract(operationPath) ?? []) {
+      const parsed = this.parseSourceDescriptionsExpression(expression);
+      if (parsed !== undefined && document.resolveSourceDescriptionURI(parsed.sourceName) === undefined) {
+        throw new ExecutionError(`operationPath "${operationPath}" names source description "${parsed.sourceName}", which the Arazzo document at "${document.uri}" does not define`, {
+          ...scope,
+          reason: ExecutionError.SourceDescriptionNotFound
+        });
+      }
+    }
     const evaluator = new RuntimeExpressionEvaluator({}, {
       strict: false,
       document,
@@ -76,23 +98,35 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
     const uriReference = evaluator.interpolate(operationPath);
     const documentURI = url.sanitize(url.stripHash(uriReference));
     if (documentURI === '') {
-      throw new ExtractionError(`operationPath "${operationPath}" does not resolve to a source description URL`, {
-        pointer: operationPath,
-        uri: document.uri
+      throw new ExecutionError(`operationPath "${operationPath}" does not resolve to a source description URL`, {
+        ...scope,
+        reason: ExecutionError.InvalidOperationReference
       });
     }
     const jsonPointer = URIFragmentIdentifier.fromURIReference(uriReference);
     if (!testJSONPointer(jsonPointer)) {
-      throw new ExtractionError(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
-        pointer: operationPath,
-        uri: document.uri
+      throw new ExecutionError(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
+        ...scope,
+        reason: ExecutionError.InvalidOperationReference
       });
     }
     const source = await this.registry.acquire(documentURI);
     if (!OpenAPIDocument.is(source)) {
-      throw new ExtractionError(`operationPath "${operationPath}" does not reference an OpenAPI document`, {
-        pointer: operationPath,
-        uri: documentURI
+      throw new ExecutionError(`operationPath "${operationPath}" references "${documentURI}", which is not an OpenAPI document`, {
+        ...scope,
+        reason: ExecutionError.SourceDescriptionNotOpenAPI
+      });
+    }
+
+    // the extractor owns locating an operation by pointer; its failure here
+    // means the pointer names no operation in this document.
+    try {
+      this.#extractor.extractByPointer(source, jsonPointer);
+    } catch (error) {
+      throw new ExecutionError(`operationPath "${operationPath}" does not locate an operation in the OpenAPI document at "${source.uri}"`, {
+        cause: error,
+        ...scope,
+        reason: ExecutionError.OperationNotFound
       });
     }
     return {
@@ -100,31 +134,24 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
       jsonPointer
     };
   }
-
-  /**
-   * Parses a `$sourceDescriptions.{name}.{reference}` expression, asserting
-   * it is a source-descriptions expression.
-   */
-  #parseSourceDescriptionsExpression(expression) {
+  async #resolveSourced(expression, document, scope) {
     const parsed = this.parseSourceDescriptionsExpression(expression);
     if (parsed === undefined) {
-      throw new ExtractionError(`Unsupported operationId expression "${expression}"`, {
-        operationId: expression
+      throw new ExecutionError(`operationId "${expression}" is not a $sourceDescriptions.{name}.{operationId} expression`, {
+        ...scope,
+        reason: ExecutionError.InvalidOperationReference
       });
     }
-    return parsed;
-  }
-  async #resolveSourced(expression, document) {
     const {
       sourceName,
       reference: operationId
-    } = this.#parseSourceDescriptionsExpression(expression);
-    const openapiDocument = await this.#sourceDocument(sourceName, document);
+    } = parsed;
+    const openapiDocument = await this.#sourceDocument(sourceName, document, scope);
     const jsonPointer = openapiDocument.operationIndex.get(operationId);
     if (jsonPointer === undefined) {
-      throw new ExtractionError(`Operation "${operationId}" not found in source description "${sourceName}"`, {
-        operationId,
-        uri: openapiDocument.uri
+      throw new ExecutionError(`Operation "${operationId}" not found in source description "${sourceName}" at "${openapiDocument.uri}"`, {
+        ...scope,
+        reason: ExecutionError.OperationNotFound
       });
     }
     return {
@@ -145,15 +172,15 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
    * Non-OpenAPI (arazzo) sources are skipped. Sources are acquired one at a time
    * until the first OpenAPI source is reached.
    */
-  async #resolvePlainOperationId(operationId, document) {
+  async #resolvePlainOperationId(operationId, document, scope) {
     for (const uri of document.sourceDescriptionURIs()) {
       const source = await this.registry.acquire(uri);
       if (!OpenAPIDocument.is(source)) continue;
       const jsonPointer = source.operationIndex.get(operationId);
       if (jsonPointer === undefined) {
-        throw new ExtractionError(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
-          operationId,
-          uri: source.uri
+        throw new ExecutionError(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
+          ...scope,
+          reason: ExecutionError.OperationNotFound
         });
       }
       return {
@@ -161,26 +188,31 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
         jsonPointer
       };
     }
-    throw new ExtractionError(`Operation "${operationId}" has no OpenAPI source description`, {
-      operationId,
-      uri: document.uri
+
+    // no source was named, so this is not a missing source description: there
+    // is simply no OpenAPI document for the operation to be in.
+    throw new ExecutionError(`Operation "${operationId}" not found: the Arazzo document at "${document.uri}" has no OpenAPI source description`, {
+      ...scope,
+      reason: ExecutionError.OperationNotFound
     });
   }
 
   /**
    * Acquires a source description by name and asserts it is an OpenAPI document.
    */
-  async #sourceDocument(sourceName, document) {
+  async #sourceDocument(sourceName, document, scope) {
     const uri = document.resolveSourceDescriptionURI(sourceName);
     if (uri === undefined) {
-      throw new ExtractionError(`Source description "${sourceName}" not found`, {
-        uri: document.uri
+      throw new ExecutionError(`Source description "${sourceName}" not found in the Arazzo document at "${document.uri}"`, {
+        ...scope,
+        reason: ExecutionError.SourceDescriptionNotFound
       });
     }
     const source = await this.registry.acquire(uri);
     if (!OpenAPIDocument.is(source)) {
-      throw new ExtractionError(`Source description "${sourceName}" is not an OpenAPI document`, {
-        uri
+      throw new ExecutionError(`Source description "${sourceName}" at "${uri}" is not an OpenAPI document`, {
+        ...scope,
+        reason: ExecutionError.SourceDescriptionNotOpenAPI
       });
     }
     return source;

package/src/executor/StepExecutor.cjs

@@ -130,42 +130,49 @@ 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.
    */
-  async execute(step, state, executeOptions = {}) {
+  async execute(step, state, executeOptions = {}, workflowId) {
     const stepId = (0, _apidomCore.toValue)(step.stepId);
+    const scope = {
+      ...(workflowId === undefined ? {} : {
+        workflowId
+      }),
+      stepId
+    };
 
     // a step's target fields are mutually exclusive; declaring more than one is
     // malformed and has no defined resolution.
     const declaredTargets = STEP_TARGET_FIELDS.filter(field => (0, _apidomDatamodel.isStringElement)(step[field]));
     if (declaredTargets.length > 1) {
       throw new _ExecutionError.default(`Step "${stepId}" declares more than one of ${STEP_TARGET_FIELDS.join(', ')} (mutually exclusive)`, {
-        stepId,
-        reason: 'ambiguous-target'
+        ...scope,
+        reason: _ExecutionError.default.AmbiguousTarget
       });
     }
     if ((0, _apidomDatamodel.isStringElement)(step.workflowId)) {
       throw new _ExecutionError.default(`Step "${stepId}" targets a workflowId; use the workflow executor`, {
-        stepId,
-        reason: 'workflow-step'
+        ...scope,
+        reason: _ExecutionError.default.WorkflowStep
       });
     }
-    this.assertSuccessCriteria(step);
+    this.assertSuccessCriteria(step, workflowId);
 
     // locate which operation the step invokes — reduced to a (document, JSON
     // Pointer) locator that the operation executor extracts, normalizes,
     // assembles into a standalone doc, and runs.
-    const locator = await this.#locateOperation(step, stepId);
+    const locator = await this.#locateOperation(step, scope);
 
     // resolve parameters and request body against the pre-request context.
     // keyed by '{in}.{name}' rather than bare name, so two parameters that
     // legally differ only in their location each reach their own place.
-    const scope = {
-      stepId
-    };
     const preContext = state.toContext();
     const parameters = this.#parameterResolver.resolve(step.parameters, expression => this.#evaluate(preContext, expression), scope);
     const requestBody = this.#requestBodyResolver.resolve(step.requestBody, expression => this.#evaluate(preContext, expression), scope);
@@ -176,9 +183,7 @@ class StepExecutor {
     // live side effect. The signal stays in the bag, so a request already in
     // flight is aborted by the transport as before.
     const signal = (0, _abort.readAbortSignal)(executeOptions);
-    (0, _abort.throwIfAborted)(signal, {
-      stepId
-    });
+    (0, _abort.throwIfAborted)(signal, scope);
 
     // the Arazzo-derived parameters and request body are spread after the opaque
     // executeOptions bag so they take precedence over it. the operation executor
@@ -197,22 +202,20 @@ class StepExecutor {
       // cancelled, it did not: reporting it as the abort keeps one error shape
       // whether the run was withdrawn between two steps or mid-flight, and keeps
       // the whole feature from reading differently per transport.
-      (0, _abort.throwIfAborted)(signal, {
-        stepId
-      });
+      (0, _abort.throwIfAborted)(signal, scope);
       throw error;
     }
 
     // evaluate criteria, outputs, and the next action against the post-request
     // context (with $request / $url / $method and $response / $statusCode).
     const postContext = state.toContext(this.#requestContext(response), this.#responseContext(response));
-    const successCriteria = this.evaluateCriteria(step, postContext);
+    const successCriteria = this.evaluateCriteria(step, postContext, workflowId);
     const successful = successCriteria.every(criterion => criterion.met);
     const outputs = this.#outputResolver.resolve(step.outputs, expression => this.#evaluate(postContext, expression), scope);
     const {
       matchedActions,
       actionCriteria
-    } = this.selectActions(step, successful, postContext);
+    } = this.selectActions(step, successful, postContext, workflowId);
     return {
       stepId,
       response,
@@ -242,16 +245,16 @@ class StepExecutor {
       requestContentType: requestBody.contentType
     };
   }
-  async #locateOperation(step, stepId) {
+  async #locateOperation(step, scope) {
     if ((0, _apidomDatamodel.isStringElement)(step.operationId)) {
-      return this.#locatorNormalizer.normalizeOperationId((0, _apidomCore.toValue)(step.operationId), this.#document);
+      return this.#locatorNormalizer.normalizeOperationId((0, _apidomCore.toValue)(step.operationId), this.#document, scope);
     }
     if ((0, _apidomDatamodel.isStringElement)(step.operationPath)) {
-      return this.#locatorNormalizer.normalizeOperationPath((0, _apidomCore.toValue)(step.operationPath), this.#document);
+      return this.#locatorNormalizer.normalizeOperationPath((0, _apidomCore.toValue)(step.operationPath), this.#document, scope);
     }
-    throw new _ExecutionError.default(`Step "${stepId}" has no operationId or operationPath`, {
-      stepId,
-      reason: 'missing-operation'
+    throw new _ExecutionError.default(`Step "${scope.stepId}" has no operationId or operationPath`, {
+      ...scope,
+      reason: _ExecutionError.default.MissingOperation
     });
   }
 
@@ -282,13 +285,13 @@ class StepExecutor {
     if (!(0, _apidomDatamodel.isArrayElement)(criteria)) {
       throw new _ResolverError.default("A step's `successCriteria` is present but is not a list", {
         ...scope,
-        reason: 'malformed-criteria'
+        reason: _ResolverError.default.MalformedCriteria
       });
     }
     if (![...criteria].every(_apidomNsArazzo.isCriterionElement)) {
       throw new _ResolverError.default("A step's `successCriteria` contains an entry that is not a Criterion Object", {
         ...scope,
-        reason: 'malformed-criterion'
+        reason: _ResolverError.default.MalformedCriterion
       });
     }
   }
@@ -304,10 +307,12 @@ 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, context) {
-    this.assertSuccessCriteria(step);
+  evaluateCriteria(step, context, workflowId) {
+    this.assertSuccessCriteria(step, workflowId);
     const criteria = step.successCriteria;
     if (criteria === undefined) return [];
 
@@ -335,8 +340,10 @@ 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, successful, context) {
+  selectActions(step, successful, context, workflowId) {
     const actionCriteria = [];
     const isCriterionMet = (criterion, action) => {
       const record = {
@@ -347,6 +354,9 @@ class StepExecutor {
       return record.met;
     };
     const scope = {
+      ...(workflowId === undefined ? {} : {
+        workflowId
+      }),
       stepId: (0, _apidomCore.toValue)(step.stepId)
     };
     const matchedActions = successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
@@ -384,7 +394,7 @@ class StepExecutor {
       // a step that calls a workflow made no HTTP call, so a condition on one
       // fails like any unevaluable condition; the diagnostic keeps the
       // authoring mistake visible.
-      if (error instanceof _RuntimeExpressionError.default && error.reason === 'unavailable-expression') {
+      if (error instanceof _RuntimeExpressionError.default && error.reason === _RuntimeExpressionError.default.UnavailableExpression) {
         return {
           condition,
           met: false,

package/src/executor/StepExecutor.mjs

@@ -123,42 +123,49 @@ 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.
    */
-  async execute(step, state, executeOptions = {}) {
+  async execute(step, state, executeOptions = {}, workflowId) {
     const stepId = toValue(step.stepId);
+    const scope = {
+      ...(workflowId === undefined ? {} : {
+        workflowId
+      }),
+      stepId
+    };
 
     // a step's target fields are mutually exclusive; declaring more than one is
     // malformed and has no defined resolution.
     const declaredTargets = STEP_TARGET_FIELDS.filter(field => isStringElement(step[field]));
     if (declaredTargets.length > 1) {
       throw new ExecutionError(`Step "${stepId}" declares more than one of ${STEP_TARGET_FIELDS.join(', ')} (mutually exclusive)`, {
-        stepId,
-        reason: 'ambiguous-target'
+        ...scope,
+        reason: ExecutionError.AmbiguousTarget
       });
     }
     if (isStringElement(step.workflowId)) {
       throw new ExecutionError(`Step "${stepId}" targets a workflowId; use the workflow executor`, {
-        stepId,
-        reason: 'workflow-step'
+        ...scope,
+        reason: ExecutionError.WorkflowStep
       });
     }
-    this.assertSuccessCriteria(step);
+    this.assertSuccessCriteria(step, workflowId);
 
     // locate which operation the step invokes — reduced to a (document, JSON
     // Pointer) locator that the operation executor extracts, normalizes,
     // assembles into a standalone doc, and runs.
-    const locator = await this.#locateOperation(step, stepId);
+    const locator = await this.#locateOperation(step, scope);
 
     // resolve parameters and request body against the pre-request context.
     // keyed by '{in}.{name}' rather than bare name, so two parameters that
     // legally differ only in their location each reach their own place.
-    const scope = {
-      stepId
-    };
     const preContext = state.toContext();
     const parameters = this.#parameterResolver.resolve(step.parameters, expression => this.#evaluate(preContext, expression), scope);
     const requestBody = this.#requestBodyResolver.resolve(step.requestBody, expression => this.#evaluate(preContext, expression), scope);
@@ -169,9 +176,7 @@ class StepExecutor {
     // live side effect. The signal stays in the bag, so a request already in
     // flight is aborted by the transport as before.
     const signal = readAbortSignal(executeOptions);
-    throwIfAborted(signal, {
-      stepId
-    });
+    throwIfAborted(signal, scope);
 
     // the Arazzo-derived parameters and request body are spread after the opaque
     // executeOptions bag so they take precedence over it. the operation executor
@@ -190,22 +195,20 @@ class StepExecutor {
       // cancelled, it did not: reporting it as the abort keeps one error shape
       // whether the run was withdrawn between two steps or mid-flight, and keeps
       // the whole feature from reading differently per transport.
-      throwIfAborted(signal, {
-        stepId
-      });
+      throwIfAborted(signal, scope);
       throw error;
     }
 
     // evaluate criteria, outputs, and the next action against the post-request
     // context (with $request / $url / $method and $response / $statusCode).
     const postContext = state.toContext(this.#requestContext(response), this.#responseContext(response));
-    const successCriteria = this.evaluateCriteria(step, postContext);
+    const successCriteria = this.evaluateCriteria(step, postContext, workflowId);
     const successful = successCriteria.every(criterion => criterion.met);
     const outputs = this.#outputResolver.resolve(step.outputs, expression => this.#evaluate(postContext, expression), scope);
     const {
       matchedActions,
       actionCriteria
-    } = this.selectActions(step, successful, postContext);
+    } = this.selectActions(step, successful, postContext, workflowId);
     return {
       stepId,
       response,
@@ -235,16 +238,16 @@ class StepExecutor {
       requestContentType: requestBody.contentType
     };
   }
-  async #locateOperation(step, stepId) {
+  async #locateOperation(step, scope) {
     if (isStringElement(step.operationId)) {
-      return this.#locatorNormalizer.normalizeOperationId(toValue(step.operationId), this.#document);
+      return this.#locatorNormalizer.normalizeOperationId(toValue(step.operationId), this.#document, scope);
     }
     if (isStringElement(step.operationPath)) {
-      return this.#locatorNormalizer.normalizeOperationPath(toValue(step.operationPath), this.#document);
+      return this.#locatorNormalizer.normalizeOperationPath(toValue(step.operationPath), this.#document, scope);
     }
-    throw new ExecutionError(`Step "${stepId}" has no operationId or operationPath`, {
-      stepId,
-      reason: 'missing-operation'
+    throw new ExecutionError(`Step "${scope.stepId}" has no operationId or operationPath`, {
+      ...scope,
+      reason: ExecutionError.MissingOperation
     });
   }
 
@@ -275,13 +278,13 @@ class StepExecutor {
     if (!isArrayElement(criteria)) {
       throw new ResolverError("A step's `successCriteria` is present but is not a list", {
         ...scope,
-        reason: 'malformed-criteria'
+        reason: ResolverError.MalformedCriteria
       });
     }
     if (![...criteria].every(isCriterionElement)) {
       throw new ResolverError("A step's `successCriteria` contains an entry that is not a Criterion Object", {
         ...scope,
-        reason: 'malformed-criterion'
+        reason: ResolverError.MalformedCriterion
       });
     }
   }
@@ -297,10 +300,12 @@ 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, context) {
-    this.assertSuccessCriteria(step);
+  evaluateCriteria(step, context, workflowId) {
+    this.assertSuccessCriteria(step, workflowId);
     const criteria = step.successCriteria;
     if (criteria === undefined) return [];
 
@@ -328,8 +333,10 @@ 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, successful, context) {
+  selectActions(step, successful, context, workflowId) {
     const actionCriteria = [];
     const isCriterionMet = (criterion, action) => {
       const record = {
@@ -340,6 +347,9 @@ class StepExecutor {
       return record.met;
     };
     const scope = {
+      ...(workflowId === undefined ? {} : {
+        workflowId
+      }),
       stepId: toValue(step.stepId)
     };
     const matchedActions = successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
@@ -377,7 +387,7 @@ class StepExecutor {
       // a step that calls a workflow made no HTTP call, so a condition on one
       // fails like any unevaluable condition; the diagnostic keeps the
       // authoring mistake visible.
-      if (error instanceof RuntimeExpressionError && error.reason === 'unavailable-expression') {
+      if (error instanceof RuntimeExpressionError && error.reason === RuntimeExpressionError.UnavailableExpression) {
         return {
           condition,
           met: false,

package/src/executor/StepRetryRunner.cjs

@@ -209,7 +209,7 @@ class StepRetryRunner {
     throw new _ExecutionError.default(`retry action on step "${context.stepId}" in workflow "${context.workflowId}" carries a stepId/workflowId reference, but no runReference was given to run it`, {
       stepId: context.stepId,
       workflowId: context.workflowId,
-      reason: 'retry-reference-unsupported'
+      reason: _ExecutionError.default.RetryReferenceUnsupported
     });
   }
 }

package/src/executor/StepRetryRunner.mjs

@@ -199,7 +199,7 @@ class StepRetryRunner {
     throw new ExecutionError(`retry action on step "${context.stepId}" in workflow "${context.workflowId}" carries a stepId/workflowId reference, but no runReference was given to run it`, {
       stepId: context.stepId,
       workflowId: context.workflowId,
-      reason: 'retry-reference-unsupported'
+      reason: ExecutionError.RetryReferenceUnsupported
     });
   }
 }

package/src/executor/StepTransitionInterpreter.cjs

@@ -104,7 +104,7 @@ class StepTransitionInterpreter {
         throw new _ExecutionError.default(`goto action on step "${stepId}" in workflow "${workflowId}" declares both a stepId and a workflowId (mutually exclusive)`, {
           stepId,
           workflowId,
-          reason: 'ambiguous-target'
+          reason: _ExecutionError.default.AmbiguousTarget
         });
       }
       if (hasStepId) {
@@ -122,13 +122,13 @@ class StepTransitionInterpreter {
       throw new _ExecutionError.default(`goto action on step "${stepId}" in workflow "${workflowId}" has neither stepId nor workflowId`, {
         stepId,
         workflowId,
-        reason: 'goto-target-missing'
+        reason: _ExecutionError.default.GotoTargetMissing
       });
     }
     throw new _ExecutionError.default(`action on step "${stepId}" in workflow "${workflowId}" has unsupported type "${type}"`, {
       stepId,
       workflowId,
-      reason: 'unknown-action-type'
+      reason: _ExecutionError.default.UnknownActionType
     });
   }