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

package/src/executor/StepExecutor.mjs

@@ -37,11 +37,27 @@ export const STEP_TARGET_FIELDS = ['operationId', 'operationPath', 'workflowId']
  * @public
  */
 
+/**
+ * The outcome of one criterion a step evaluated: one of its `successCriteria`,
+ * or one of the `criteria` of an action it considered.
+ * @public
+ */
+
 /**
  * The outcome of executing a single step.
  * @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.
  *
@@ -183,16 +199,22 @@ class StepExecutor {
     // 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 successful = this.evaluateCriteria(step, postContext);
+    const successCriteria = this.evaluateCriteria(step, postContext);
+    const successful = successCriteria.every(criterion => criterion.met);
     const outputs = this.#outputResolver.resolve(step.outputs, expression => this.#evaluate(postContext, expression), scope);
-    const matchedActions = this.selectActions(step, successful, postContext);
+    const {
+      matchedActions,
+      actionCriteria
+    } = this.selectActions(step, successful, postContext);
     return {
       stepId,
       response,
       successful,
       outputs,
       action: matchedActions[0],
-      matchedActions
+      matchedActions,
+      successCriteria,
+      actionCriteria
     };
   }
 
@@ -265,9 +287,12 @@ class StepExecutor {
   }
 
   /**
-   * Evaluates the step's `successCriteria`; all criteria must pass. A step with
-   * no criteria succeeds on a received response. An unreadable
-   * `successCriteria` throws, see {@link StepExecutor.assertSuccessCriteria}.
+   * Evaluates the step's `successCriteria`, returning one record per criterion
+   * in list order; the step succeeds when every record is met. Every criterion
+   * is evaluated, so the records explain each unmet one, not only the first. A
+   * step with no criteria returns no records and succeeds on a received
+   * response. An unreadable `successCriteria` throws, see
+   * {@link StepExecutor.assertSuccessCriteria}.
    *
    * Public for the same reason as {@link StepExecutor.selectActions}: a step
    * targeting a `workflowId` is run by the workflow executor and never reaches
@@ -277,15 +302,16 @@ class StepExecutor {
   evaluateCriteria(step, context) {
     this.assertSuccessCriteria(step);
     const criteria = step.successCriteria;
-    if (criteria === undefined) return true;
+    if (criteria === undefined) return [];
 
     // assertSuccessCriteria above guarantees every entry is a Criterion Object
-    return [...criteria].every(criterion => this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression)));
+    return [...criteria].map(criterion => this.#evaluateCriterion(criterion, context));
   }
 
   /**
    * Selects every matching `onSuccess` / `onFailure` action for the outcome, in
-   * list order, gating each action's criteria against the context.
+   * list order, gating each action's criteria against the context, and records
+   * the outcome of every action criterion evaluated.
    *
    * The step's own list is the whole story here: a step that declares none of
    * its own already carries the workflow-level defaults, inherited by
@@ -304,25 +330,65 @@ class StepExecutor {
    * the expression context through this one method rather than wiring their own.
    */
   selectActions(step, successful, context) {
-    const isCriterionMet = criterion => {
-      try {
-        return this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
-      } catch (error) {
-        // an action's criteria decide whether it applies to this outcome, and
-        // actions are shared — inherited from the workflow, reused from
-        // components. A condition on an HTTP exchange cannot apply to a step
-        // that calls a workflow, so the action does not match; the run does not
-        // abort over a default written for the operation steps.
-        if (error instanceof RuntimeExpressionError && error.reason === 'unavailable-expression') {
-          return false;
-        }
-        throw error;
-      }
+    const actionCriteria = [];
+    const isCriterionMet = (criterion, action) => {
+      const record = {
+        ...this.#evaluateCriterion(criterion, context),
+        actionName: toValue(action.name)
+      };
+      actionCriteria.push(record);
+      return record.met;
     };
     const scope = {
       stepId: toValue(step.stepId)
     };
-    return successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
+    const matchedActions = successful ? this.#actionResolver.resolveOnSuccess(step.onSuccess, isCriterionMet, scope) : this.#actionResolver.resolveOnFailure(step.onFailure, isCriterionMet, scope);
+    return {
+      matchedActions,
+      actionCriteria
+    };
+  }
+
+  /**
+   * Evaluates one criterion into a {@link CriterionEvaluationRecord}. A
+   * condition that cannot be evaluated is unmet and records why; any other
+   * error propagates.
+   */
+  #evaluateCriterion(criterion, context) {
+    const condition = toValue(criterion.condition);
+    try {
+      const {
+        met,
+        error
+      } = this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
+      if (error === undefined) return {
+        condition,
+        met
+      };
+      return {
+        condition,
+        met,
+        diagnostic: {
+          code: error.reason,
+          message: error.message
+        }
+      };
+    } catch (error) {
+      // 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') {
+        return {
+          condition,
+          met: false,
+          diagnostic: {
+            code: error.reason,
+            message: error.message
+          }
+        };
+      }
+      throw error;
+    }
   }
 
   /**

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

@@ -359,6 +359,8 @@ class WorkflowExecutor {
         action,
         attempts,
         durationMs: this.#now() - stepStartedAt,
+        successCriteria: outcome.successCriteria,
+        actionCriteria: outcome.actionCriteria,
         ...(subWorkflows.length > 0 ? {
           subWorkflows
         } : {}),
@@ -776,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
@@ -889,19 +885,26 @@ class WorkflowExecutor {
       // apply on top — they are the author's assertion about this step, and
       // dropping them because the step happens to target a workflow would
       // silently discard it. They see the sub-run's own outputs (`{}` when it
-      // transferred) through `$outputs` and `$workflows`.
+      // transferred) through `$outputs` and `$workflows`, and are evaluated
+      // even when the sub-run failed, so the record explains them either way.
       // the criteria and actions are the *calling* step's, so they are
       // evaluated by the parent document's step executor — only the sub-run
       // itself switched documents.
       const stepExecutor = this.#stepExecutor.forDocument(document);
-      const successful = !this.#settledFailed(result) && stepExecutor.evaluateCriteria(step, context);
-      const matchedActions = stepExecutor.selectActions(step, successful, context);
+      const successCriteria = stepExecutor.evaluateCriteria(step, context);
+      const successful = !this.#settledFailed(result) && successCriteria.every(criterion => criterion.met);
+      const {
+        matchedActions,
+        actionCriteria
+      } = stepExecutor.selectActions(step, successful, context);
       return {
         stepId,
         successful,
         outputs,
         action: matchedActions[0],
-        matchedActions
+        matchedActions,
+        successCriteria,
+        actionCriteria
       };
     };
   }
@@ -963,24 +966,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);
   }
 
@@ -988,7 +981,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

@@ -345,6 +345,8 @@ class WorkflowExecutor {
         action,
         attempts,
         durationMs: this.#now() - stepStartedAt,
+        successCriteria: outcome.successCriteria,
+        actionCriteria: outcome.actionCriteria,
         ...(subWorkflows.length > 0 ? {
           subWorkflows
         } : {}),
@@ -762,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
@@ -875,19 +871,26 @@ class WorkflowExecutor {
       // apply on top — they are the author's assertion about this step, and
       // dropping them because the step happens to target a workflow would
       // silently discard it. They see the sub-run's own outputs (`{}` when it
-      // transferred) through `$outputs` and `$workflows`.
+      // transferred) through `$outputs` and `$workflows`, and are evaluated
+      // even when the sub-run failed, so the record explains them either way.
       // the criteria and actions are the *calling* step's, so they are
       // evaluated by the parent document's step executor — only the sub-run
       // itself switched documents.
       const stepExecutor = this.#stepExecutor.forDocument(document);
-      const successful = !this.#settledFailed(result) && stepExecutor.evaluateCriteria(step, context);
-      const matchedActions = stepExecutor.selectActions(step, successful, context);
+      const successCriteria = stepExecutor.evaluateCriteria(step, context);
+      const successful = !this.#settledFailed(result) && successCriteria.every(criterion => criterion.met);
+      const {
+        matchedActions,
+        actionCriteria
+      } = stepExecutor.selectActions(step, successful, context);
       return {
         stepId,
         successful,
         outputs,
         action: matchedActions[0],
-        matchedActions
+        matchedActions,
+        successCriteria,
+        actionCriteria
       };
     };
   }
@@ -949,24 +952,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);
   }
 
@@ -974,7 +967,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 {