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

package/src/executor/StepExecutor.mjs

@@ -127,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);
@@ -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,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'
     });
   }
@@ -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);

package/src/executor/WorkflowExecutor.cjs

@@ -810,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
@@ -891,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,

package/src/executor/WorkflowExecutor.mjs

@@ -796,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
@@ -877,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,

package/types/runner.d.ts

@@ -1254,7 +1254,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 +1262,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 +1278,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 +1295,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>;
 }
 
 /**
@@ -2049,8 +2059,12 @@ export declare 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.
      */
-    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 +2091,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 +2116,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 +2228,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;
 }