@usearazzo/runner 1.0.1-alpha.21 → 1.0.1-alpha.23

package/src/executor/StepExecutor.cjs

@@ -55,6 +55,16 @@ const STEP_TARGET_FIELDS = exports.STEP_TARGET_FIELDS = ['operationId', 'operati
  * @public
  */
 
+/**
+ * What one attempt at a step produced.
+ *
+ * Both kinds of step reduce to this — an operation step (whose richer
+ * {@link StepExecutionResult} satisfies this shape) and a sub-workflow step
+ * (synthesized from the sub-run's outcome) — so the retry loop drives them
+ * identically and knows nothing about either.
+ * @internal
+ */
+
 /**
  * Executes a single Arazzo step that invokes an OpenAPI operation.
  *
@@ -124,38 +134,45 @@ class StepExecutor {
    * 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,
+        ...scope,
         reason: 'ambiguous-target'
       });
     }
     if ((0, _apidomDatamodel.isStringElement)(step.workflowId)) {
       throw new _ExecutionError.default(`Step "${stepId}" targets a workflowId; use the workflow executor`, {
-        stepId,
+        ...scope,
         reason: 'workflow-step'
       });
     }
-    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);
@@ -166,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
@@ -187,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,
@@ -232,15 +245,15 @@ 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,
+    throw new _ExecutionError.default(`Step "${scope.stepId}" has no operationId or operationPath`, {
+      ...scope,
       reason: 'missing-operation'
     });
   }
@@ -294,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 [];
 
@@ -325,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 = {
@@ -337,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);

package/src/executor/StepExecutor.mjs

@@ -48,6 +48,16 @@ export const STEP_TARGET_FIELDS = ['operationId', 'operationPath', 'workflowId']
  * @public
  */
 
+/**
+ * What one attempt at a step produced.
+ *
+ * Both kinds of step reduce to this — an operation step (whose richer
+ * {@link StepExecutionResult} satisfies this shape) and a sub-workflow step
+ * (synthesized from the sub-run's outcome) — so the retry loop drives them
+ * identically and knows nothing about either.
+ * @internal
+ */
+
 /**
  * Executes a single Arazzo step that invokes an OpenAPI operation.
  *
@@ -117,38 +127,45 @@ class StepExecutor {
    * 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,
+        ...scope,
         reason: 'ambiguous-target'
       });
     }
     if (isStringElement(step.workflowId)) {
       throw new ExecutionError(`Step "${stepId}" targets a workflowId; use the workflow executor`, {
-        stepId,
+        ...scope,
         reason: 'workflow-step'
       });
     }
-    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);
@@ -159,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
@@ -180,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,
@@ -225,15 +238,15 @@ 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,
+    throw new ExecutionError(`Step "${scope.stepId}" has no operationId or operationPath`, {
+      ...scope,
       reason: 'missing-operation'
     });
   }
@@ -287,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 [];
 
@@ -318,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 = {
@@ -330,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);

package/src/executor/StepRetryRunner.cjs

@@ -9,16 +9,6 @@ var _apidomCore = require("@speclynx/apidom-core");
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
-/**
- * What one attempt at a step produced.
- *
- * Both kinds of step reduce to this — an operation step (whose richer
- * `StepExecutionResult` satisfies this shape) and a sub-workflow step
- * (synthesized from the sub-run's outcome) — so the retry loop drives them
- * identically and knows nothing about either.
- * @internal
- */
-
 /**
  * The terminal outcome of a step once its retries are settled.
  * @internal

package/src/executor/StepRetryRunner.mjs

@@ -2,15 +2,6 @@ import { toValue } from '@speclynx/apidom-core';
 import { isNumberElement, isStringElement } from '@speclynx/apidom-datamodel';
 import { isFailureActionElement } from '@speclynx/apidom-ns-arazzo-1';
 import ExecutionError from "../errors/ExecutionError.mjs";
-/**
- * What one attempt at a step produced.
- *
- * Both kinds of step reduce to this — an operation step (whose richer
- * `StepExecutionResult` satisfies this shape) and a sub-workflow step
- * (synthesized from the sub-run's outcome) — so the retry loop drives them
- * identically and knows nothing about either.
- * @internal
- */
 /**
  * The terminal outcome of a step once its retries are settled.
  * @internal

package/src/executor/WorkflowExecutor.cjs

@@ -778,12 +778,6 @@ class WorkflowExecutor {
       const locator = await this.#workflowLocatorNormalizer.normalize(reference, document, {
         workflowId
       });
-      if (!locator.document.workflowIndex.has(locator.workflowId)) {
-        throw new _ExecutionError.default(`workflow "${workflowId}" depends on "${reference}", which the Arazzo document at "${locator.document.uri}" does not define`, {
-          workflowId,
-          reason: 'workflow-not-found'
-        });
-      }
       refs.push({
         locator,
         inputsKey: reference
@@ -816,10 +810,11 @@ class WorkflowExecutor {
       callStack
     } = invocation;
     if (!(0, _apidomDatamodel.isStringElement)(step.workflowId)) {
-      return () => this.#stepExecutor.forDocument(document).execute(step, state, scope.executeOptions);
+      return () => this.#stepExecutor.forDocument(document).execute(step, state, scope.executeOptions, workflowId);
     }
     const reference = this.#subWorkflowReference(step, stepId, workflowId);
     const stepScope = {
+      workflowId,
       stepId
     };
     // the reference resolves to the same locator on every attempt, so it is
@@ -897,12 +892,12 @@ class WorkflowExecutor {
       // evaluated by the parent document's step executor — only the sub-run
       // itself switched documents.
       const stepExecutor = this.#stepExecutor.forDocument(document);
-      const successCriteria = stepExecutor.evaluateCriteria(step, context);
+      const successCriteria = stepExecutor.evaluateCriteria(step, context, workflowId);
       const successful = !this.#settledFailed(result) && successCriteria.every(criterion => criterion.met);
       const {
         matchedActions,
         actionCriteria
-      } = stepExecutor.selectActions(step, successful, context);
+      } = stepExecutor.selectActions(step, successful, context, workflowId);
       return {
         stepId,
         successful,
@@ -972,24 +967,14 @@ class WorkflowExecutor {
    *
    * Shared rather than duplicated by its two callers, which otherwise repeat
    * the identical "resolve the reference, then run with no inputs" sequence.
-   * Rejects a target its document does not define with the calling `stepId`
-   * attached, unlike {@link WorkflowExecutor.#resolveWorkflow}'s own
-   * `workflow-not-found` (reached only once `#run` itself resolves the
-   * target) — which carries no caller context at all, since it is reached
-   * generically from every kind of nested call.
+   * A target its document does not define is rejected by the normalizer,
+   * attributed to the calling workflow and `stepId`.
    */
   async #runReferencedWorkflow(reference, stepId, invocation, scope, via) {
     const locator = await this.#workflowLocatorNormalizer.normalize(reference, invocation.document, {
       workflowId: invocation.workflowId,
       stepId
     });
-    if (!locator.document.workflowIndex.has(locator.workflowId)) {
-      throw new _ExecutionError.default(`workflow "${locator.workflowId}" not found in Arazzo document at "${locator.document.uri}"`, {
-        workflowId: locator.workflowId,
-        stepId,
-        reason: 'workflow-not-found'
-      });
-    }
     return this.#run(locator, {}, scope, invocation.callStack, via);
   }
 
@@ -997,7 +982,11 @@ class WorkflowExecutor {
    * Extracts and normalizes the workflow a locator names. A workflow its
    * document does not define is the executor-level `workflow-not-found`
    * authoring error, raised here rather than leaking the extractor's
-   * `ExtractionError`.
+   * `ExtractionError`. Only the root {@link WorkflowExecutor.execute} id
+   * reaches this check unvalidated — every reference position goes through
+   * the locator normalizer, which already rejects a missing workflow with
+   * the referencing context attached — so the error's `workflowId` is the
+   * missing id itself.
    */
   async #resolveWorkflow(locator, scope) {
     const {

package/src/executor/WorkflowExecutor.mjs

@@ -764,12 +764,6 @@ class WorkflowExecutor {
       const locator = await this.#workflowLocatorNormalizer.normalize(reference, document, {
         workflowId
       });
-      if (!locator.document.workflowIndex.has(locator.workflowId)) {
-        throw new ExecutionError(`workflow "${workflowId}" depends on "${reference}", which the Arazzo document at "${locator.document.uri}" does not define`, {
-          workflowId,
-          reason: 'workflow-not-found'
-        });
-      }
       refs.push({
         locator,
         inputsKey: reference
@@ -802,10 +796,11 @@ class WorkflowExecutor {
       callStack
     } = invocation;
     if (!isStringElement(step.workflowId)) {
-      return () => this.#stepExecutor.forDocument(document).execute(step, state, scope.executeOptions);
+      return () => this.#stepExecutor.forDocument(document).execute(step, state, scope.executeOptions, workflowId);
     }
     const reference = this.#subWorkflowReference(step, stepId, workflowId);
     const stepScope = {
+      workflowId,
       stepId
     };
     // the reference resolves to the same locator on every attempt, so it is
@@ -883,12 +878,12 @@ class WorkflowExecutor {
       // evaluated by the parent document's step executor — only the sub-run
       // itself switched documents.
       const stepExecutor = this.#stepExecutor.forDocument(document);
-      const successCriteria = stepExecutor.evaluateCriteria(step, context);
+      const successCriteria = stepExecutor.evaluateCriteria(step, context, workflowId);
       const successful = !this.#settledFailed(result) && successCriteria.every(criterion => criterion.met);
       const {
         matchedActions,
         actionCriteria
-      } = stepExecutor.selectActions(step, successful, context);
+      } = stepExecutor.selectActions(step, successful, context, workflowId);
       return {
         stepId,
         successful,
@@ -958,24 +953,14 @@ class WorkflowExecutor {
    *
    * Shared rather than duplicated by its two callers, which otherwise repeat
    * the identical "resolve the reference, then run with no inputs" sequence.
-   * Rejects a target its document does not define with the calling `stepId`
-   * attached, unlike {@link WorkflowExecutor.#resolveWorkflow}'s own
-   * `workflow-not-found` (reached only once `#run` itself resolves the
-   * target) — which carries no caller context at all, since it is reached
-   * generically from every kind of nested call.
+   * A target its document does not define is rejected by the normalizer,
+   * attributed to the calling workflow and `stepId`.
    */
   async #runReferencedWorkflow(reference, stepId, invocation, scope, via) {
     const locator = await this.#workflowLocatorNormalizer.normalize(reference, invocation.document, {
       workflowId: invocation.workflowId,
       stepId
     });
-    if (!locator.document.workflowIndex.has(locator.workflowId)) {
-      throw new ExecutionError(`workflow "${locator.workflowId}" not found in Arazzo document at "${locator.document.uri}"`, {
-        workflowId: locator.workflowId,
-        stepId,
-        reason: 'workflow-not-found'
-      });
-    }
     return this.#run(locator, {}, scope, invocation.callStack, via);
   }
 
@@ -983,7 +968,11 @@ class WorkflowExecutor {
    * Extracts and normalizes the workflow a locator names. A workflow its
    * document does not define is the executor-level `workflow-not-found`
    * authoring error, raised here rather than leaking the extractor's
-   * `ExtractionError`.
+   * `ExtractionError`. Only the root {@link WorkflowExecutor.execute} id
+   * reaches this check unvalidated — every reference position goes through
+   * the locator normalizer, which already rejects a missing workflow with
+   * the referencing context attached — so the error's `workflowId` is the
+   * missing id itself.
    */
   async #resolveWorkflow(locator, scope) {
     const {