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

package/src/executor/StepExecutor.mjs

@@ -37,6 +37,12 @@ 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
@@ -183,16 +189,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 +277,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 +292,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 +320,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/WorkflowExecutor.cjs

@@ -359,6 +359,8 @@ class WorkflowExecutor {
         action,
         attempts,
         durationMs: this.#now() - stepStartedAt,
+        successCriteria: outcome.successCriteria,
+        actionCriteria: outcome.actionCriteria,
         ...(subWorkflows.length > 0 ? {
           subWorkflows
         } : {}),
@@ -889,19 +891,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
       };
     };
   }

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
         } : {}),
@@ -875,19 +877,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
       };
     };
   }

package/types/runner.d.ts

@@ -534,7 +534,45 @@ export declare class CriterionEvaluationError extends CriterionError {
 }
 
 /**
- * Evaluates an Arazzo Criterion Object to a boolean.
+ * The outcome of one criterion a step evaluated: one of its `successCriteria`,
+ * or one of the `criteria` of an action it considered.
+ * @public
+ */
+export declare interface CriterionEvaluationRecord {
+    /**
+     * The criterion's `condition`, as written.
+     */
+    readonly condition: string;
+    /**
+     * Whether the condition is met.
+     */
+    readonly met: boolean;
+    /**
+     * The `name` of the action declaring the criterion — present only on an
+     * action criterion.
+     */
+    readonly actionName?: string;
+    /**
+     * Why the condition could not be evaluated — present only then, with `met`
+     * `false`.
+     */
+    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.
+         */
+        readonly code?: CriterionErrorReason | 'unavailable-expression';
+        /**
+         * Human-readable: names the condition or expression and, for a syntax
+         * error, what is wrong with it; never request or response data.
+         */
+        readonly message: string;
+    };
+}
+
+/**
+ * Evaluates an Arazzo Criterion Object to a {@link CriterionOutcome}.
  *
  * Dispatches on the criterion's `type` (defaulting to `simple` when omitted):
  * - `simple` — evaluates the condition directly, resolving the runtime
@@ -554,12 +592,13 @@ export declare class CriterionEvaluationError extends CriterionError {
  * the 1.1.0 rule to every document, which accepts more but never evaluates a
  * query under the wrong dialect.
  *
- * A condition that cannot be evaluated fails the criterion (`false`), as
+ * A condition that cannot be evaluated fails the criterion (`met: false`), as
  * Arazzo 1.1.0 requires: a syntax error in the condition, a context the
  * condition cannot apply to (non-XML data for `xpath`), or an XPath evaluation
  * error. The type-specific evaluators report these as a
- * {@link CriterionEvaluationError}, which this facade absorbs; any other error
- * they raise propagates. A criterion that is malformed as written still throws: a
+ * {@link CriterionEvaluationError}, which this facade returns as the
+ * outcome's `error` so the caller can report it; any other error they raise
+ * propagates. A criterion that is malformed as written still throws: a
  * missing `condition`, an unknown or unreadable `type`, an unsupported
  * expression `version`, or a `context` that is missing or not a runtime
  * expression.
@@ -574,13 +613,14 @@ export declare class CriterionEvaluator {
     #private;
     constructor(options?: CriterionEvaluatorOptions);
     /**
-     * Evaluates a criterion element, returning whether the condition is met.
+     * Evaluates a criterion element, returning whether the condition is met and,
+     * when it cannot be evaluated, why.
      *
      * `resolve` turns a runtime expression into a value: for `simple` it resolves
      * the expressions embedded in the condition; for the other types it resolves
      * the criterion's `context` expression that the condition is applied to.
      */
-    evaluate(criterion: CriterionElement, resolve: CriterionContextResolver): boolean;
+    evaluate(criterion: CriterionElement, resolve: CriterionContextResolver): CriterionOutcome;
 }
 
 /**
@@ -611,14 +651,32 @@ export declare interface CriterionEvaluatorOptions {
 }
 
 /**
- * Determines whether a single criterion is met.
+ * The outcome of evaluating one criterion.
+ * @public
+ */
+export declare interface CriterionOutcome {
+    /**
+     * Whether the condition is met. `false` when it evaluates to false or cannot
+     * be evaluated; only in the latter case is {@link CriterionOutcome.error}
+     * present, saying why.
+     */
+    readonly met: boolean;
+    /**
+     * Why the condition could not be evaluated: present only when it was not.
+     */
+    readonly error?: CriterionEvaluationError;
+}
+
+/**
+ * Determines whether a single criterion of an action is met. Receives the
+ * action declaring the criterion, so a caller can attribute the outcome to it.
  *
  * Bridged to a criterion evaluator
- * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve).met`); an
  * unresolvable/failing criterion is `false`, not an error.
  * @public
  */
-export declare type CriterionPredicate = (criterion: CriterionElement) => boolean;
+export declare type CriterionPredicate = (criterion: CriterionElement, action: SelectedAction) => boolean;
 
 /** @public */
 export declare class DocumentLoadError extends ArazzoRunnerError {
@@ -1929,6 +1987,16 @@ export declare interface StepExecutionResult {
      * matching action. Empty when none matched.
      */
     readonly matchedActions: readonly SelectedAction[];
+    /**
+     * The outcome of each of the step's `successCriteria`, in list order.
+     */
+    readonly successCriteria: readonly CriterionEvaluationRecord[];
+    /**
+     * The outcome of each criterion of the actions the step considered — its
+     * `onSuccess` actions when it succeeded, its `onFailure` actions otherwise —
+     * in list order.
+     */
+    readonly actionCriteria: readonly CriterionEvaluationRecord[];
 }
 
 /**
@@ -1996,19 +2064,23 @@ export declare class StepExecutor {
      */
     assertSuccessCriteria(step: StepElement, workflowId?: string): void;
     /**
-     * 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
      * {@link StepExecutor.execute}, but its criteria are still the author's
      * assertion about the step and must be evaluated somewhere.
      */
-    evaluateCriteria(step: StepElement, context: RuntimeExpressionContext): boolean;
+    evaluateCriteria(step: StepElement, context: RuntimeExpressionContext): CriterionEvaluationRecord[];
     /**
      * 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
@@ -2026,7 +2098,7 @@ export declare class StepExecutor {
      * {@link StepExecutor.execute}. Both callers reach the criteria evaluator and
      * the expression context through this one method rather than wiring their own.
      */
-    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext): SelectedAction[];
+    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext): Pick<StepExecutionResult, 'matchedActions' | 'actionCriteria'>;
 }
 
 /**
@@ -2104,6 +2176,17 @@ export declare interface StepRunRecord {
      * fractional and is unaffected by system clock changes.
      */
     readonly durationMs: number;
+    /**
+     * The outcome of each of the step's `successCriteria` in its last attempt, in
+     * list order — why the step succeeded or failed.
+     */
+    readonly successCriteria: readonly CriterionEvaluationRecord[];
+    /**
+     * The outcome of each criterion of the actions the last attempt considered —
+     * its `onSuccess` actions when it succeeded, its `onFailure` actions
+     * otherwise — in list order: why an action matched or did not.
+     */
+    readonly actionCriteria: readonly CriterionEvaluationRecord[];
     /**
      * The sub-workflow runs this step produced, in attempt order — present only on
      * a step targeting a `workflowId`.