@usearazzo/runner 1.0.1-alpha.14 → 1.0.1-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.14",
+  "version": "1.0.1-alpha.16",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -73,8 +73,8 @@
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.1",
-    "@usearazzo/parser": "1.0.1-alpha.14",
-    "@usearazzo/resolver": "1.0.1-alpha.14",
+    "@usearazzo/parser": "1.0.1-alpha.16",
+    "@usearazzo/resolver": "1.0.1-alpha.16",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "40a494596c0eed2f984fb87f544f3cf69488a6a7"
+  "gitHead": "9ff2a68d209a5d178658f9a568c2d136178d40b8"
 }

package/src/executor/StepExecutor.cjs

@@ -16,6 +16,7 @@ var _OutputResolver = _interopRequireDefault(require("../resolver/OutputResolver
 var _ActionResolver = _interopRequireDefault(require("../action/ActionResolver.cjs"));
 var _OpenAPIOperationLocatorNormalizer = _interopRequireDefault(require("./OpenAPIOperationLocatorNormalizer.cjs"));
 var _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
+var _ResolverError = _interopRequireDefault(require("../errors/ResolverError.cjs"));
 var _RuntimeExpressionError = _interopRequireDefault(require("../errors/RuntimeExpressionError.cjs"));
 var _abort = require("./abort.cjs");
 /**
@@ -136,6 +137,7 @@ class StepExecutor {
         reason: 'workflow-step'
       });
     }
+    this.assertSuccessCriteria(step);
 
     // locate which operation the step invokes — reduced to a (document, JSON
     // Pointer) locator that the operation executor extracts, normalizes,
@@ -231,9 +233,48 @@ class StepExecutor {
     });
   }
 
+  /**
+   * Throws {@link ResolverError} unless the step's `successCriteria` is absent
+   * or a list of Criterion Objects: `malformed-criteria` for one that is
+   * present but not a list, `malformed-criterion` for an entry that is not a
+   * Criterion Object. Skipping an unreadable entry would turn the author's
+   * assertion into a vacuous pass, so it is an authoring error, as an action's
+   * unreadable `criteria` is in {@link ActionResolver}.
+   *
+   * Called before the step's request is sent, so no live side effect precedes
+   * the error. Public because the workflow executor checks every step of a
+   * workflow with it before any of them runs, a step targeting a `workflowId`
+   * included. It passes `workflowId`, which the error then carries: step ids
+   * are only unique within a workflow.
+   */
+  assertSuccessCriteria(step, workflowId) {
+    const criteria = step.successCriteria;
+    if (criteria === undefined) return;
+    const scope = {
+      ...(workflowId === undefined ? {} : {
+        workflowId
+      }),
+      stepId: (0, _apidomCore.toValue)(step.stepId),
+      target: 'successCriteria'
+    };
+    if (!(0, _apidomDatamodel.isArrayElement)(criteria)) {
+      throw new _ResolverError.default("A step's `successCriteria` is present but is not a list", {
+        ...scope,
+        reason: 'malformed-criteria'
+      });
+    }
+    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'
+      });
+    }
+  }
+
   /**
    * Evaluates the step's `successCriteria`; all criteria must pass. A step with
-   * no criteria succeeds on a received response.
+   * no criteria 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
@@ -241,15 +282,12 @@ class StepExecutor {
    * assertion about the step and must be evaluated somewhere.
    */
   evaluateCriteria(step, context) {
+    this.assertSuccessCriteria(step);
     const criteria = step.successCriteria;
-    // no (or non-array) successCriteria: the step succeeds on a received response.
-    if (!(0, _apidomDatamodel.isArrayElement)(criteria)) return true;
-    for (const criterion of criteria) {
-      if (!(0, _apidomNsArazzo.isCriterionElement)(criterion)) continue;
-      const met = this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
-      if (!met) return false;
-    }
-    return true;
+    if (criteria === undefined) return true;
+
+    // assertSuccessCriteria above guarantees every entry is a Criterion Object
+    return [...criteria].every(criterion => this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression)));
   }
 
   /**

package/src/executor/StepExecutor.mjs

@@ -9,6 +9,7 @@ import OutputResolver from "../resolver/OutputResolver.mjs";
 import ActionResolver from "../action/ActionResolver.mjs";
 import OpenAPIOperationLocatorNormalizer from "./OpenAPIOperationLocatorNormalizer.mjs";
 import ExecutionError from "../errors/ExecutionError.mjs";
+import ResolverError from "../errors/ResolverError.mjs";
 import RuntimeExpressionError from "../errors/RuntimeExpressionError.mjs";
 import { readAbortSignal, throwIfAborted } from "./abort.mjs";
 /**
@@ -129,6 +130,7 @@ class StepExecutor {
         reason: 'workflow-step'
       });
     }
+    this.assertSuccessCriteria(step);
 
     // locate which operation the step invokes — reduced to a (document, JSON
     // Pointer) locator that the operation executor extracts, normalizes,
@@ -224,9 +226,48 @@ class StepExecutor {
     });
   }
 
+  /**
+   * Throws {@link ResolverError} unless the step's `successCriteria` is absent
+   * or a list of Criterion Objects: `malformed-criteria` for one that is
+   * present but not a list, `malformed-criterion` for an entry that is not a
+   * Criterion Object. Skipping an unreadable entry would turn the author's
+   * assertion into a vacuous pass, so it is an authoring error, as an action's
+   * unreadable `criteria` is in {@link ActionResolver}.
+   *
+   * Called before the step's request is sent, so no live side effect precedes
+   * the error. Public because the workflow executor checks every step of a
+   * workflow with it before any of them runs, a step targeting a `workflowId`
+   * included. It passes `workflowId`, which the error then carries: step ids
+   * are only unique within a workflow.
+   */
+  assertSuccessCriteria(step, workflowId) {
+    const criteria = step.successCriteria;
+    if (criteria === undefined) return;
+    const scope = {
+      ...(workflowId === undefined ? {} : {
+        workflowId
+      }),
+      stepId: toValue(step.stepId),
+      target: 'successCriteria'
+    };
+    if (!isArrayElement(criteria)) {
+      throw new ResolverError("A step's `successCriteria` is present but is not a list", {
+        ...scope,
+        reason: 'malformed-criteria'
+      });
+    }
+    if (![...criteria].every(isCriterionElement)) {
+      throw new ResolverError("A step's `successCriteria` contains an entry that is not a Criterion Object", {
+        ...scope,
+        reason: 'malformed-criterion'
+      });
+    }
+  }
+
   /**
    * Evaluates the step's `successCriteria`; all criteria must pass. A step with
-   * no criteria succeeds on a received response.
+   * no criteria 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
@@ -234,15 +275,12 @@ class StepExecutor {
    * assertion about the step and must be evaluated somewhere.
    */
   evaluateCriteria(step, context) {
+    this.assertSuccessCriteria(step);
     const criteria = step.successCriteria;
-    // no (or non-array) successCriteria: the step succeeds on a received response.
-    if (!isArrayElement(criteria)) return true;
-    for (const criterion of criteria) {
-      if (!isCriterionElement(criterion)) continue;
-      const met = this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression));
-      if (!met) return false;
-    }
-    return true;
+    if (criteria === undefined) return true;
+
+    // assertSuccessCriteria above guarantees every entry is a Criterion Object
+    return [...criteria].every(criterion => this.#criterionEvaluator.evaluate(criterion, expression => this.#evaluate(context, expression)));
   }
 
   /**

package/src/executor/WorkflowExecutor.cjs

@@ -297,6 +297,10 @@ class WorkflowExecutor {
     // at `#result` where it used to be resolved, means the throw lands before
     // the first request rather than after the last.
     this.#validateWorkflowOutputsShape(workflow, workflowId);
+    // and to every step's `successCriteria`, a step calling a workflow
+    // included: an unreadable assertion found at step three must not cost the
+    // run the requests of steps one and two.
+    for (const step of steps) this.#stepExecutor.assertSuccessCriteria(step, workflowId);
     const dependencies = await this.#runDependencies(workflow, invocation, scope);
     if (dependencies.some(dependency => this.#settledFailed(dependency))) {
       // a declared prerequisite did not complete, so this workflow cannot be

package/src/executor/WorkflowExecutor.mjs

@@ -283,6 +283,10 @@ class WorkflowExecutor {
     // at `#result` where it used to be resolved, means the throw lands before
     // the first request rather than after the last.
     this.#validateWorkflowOutputsShape(workflow, workflowId);
+    // and to every step's `successCriteria`, a step calling a workflow
+    // included: an unreadable assertion found at step three must not cost the
+    // run the requests of steps one and two.
+    for (const step of steps) this.#stepExecutor.assertSuccessCriteria(step, workflowId);
     const dependencies = await this.#runDependencies(workflow, invocation, scope);
     if (dependencies.some(dependency => this.#settledFailed(dependency))) {
       // a declared prerequisite did not complete, so this workflow cannot be

package/src/normalizer/ArazzoWorkflowNormalizer.cjs

@@ -159,23 +159,32 @@ class ArazzoWorkflowNormalizer {
   }
 
   /**
-   * Inherits the workflow's `successActions` / `failureActions` into each step
-   * that declares no `onSuccess` / `onFailure` of its own.
+   * Merges the workflow's `successActions` / `failureActions` into each step's
+   * `onSuccess` / `onFailure`.
    *
-   * Per Arazzo 1.0.1 both lists are "applicable for all steps described under
-   * this workflow", and a step's own list **overrides** the corresponding
-   * workflow one — wholesale, with no per-action merge, which is where this
-   * differs from the parameters above. Success and failure fall back
-   * independently: a step may override only its `onFailure` and still inherit
-   * the workflow's `successActions`.
+   * Per Arazzo both lists are "applicable for all steps described under this
+   * workflow" and "can be overridden at the step level but cannot be removed
+   * there". The required action `name` is what makes both halves hold: a
+   * step's action replaces the workflow action of the same `name`, and every
+   * workflow action the step does not name still applies. The effective list is
+   * the step's own actions in order, then the workflow actions it did not
+   * override, in theirs — order matters, as selection is first-match-wins on
+   * `criteria`. So a step with no list, or with `[]`, gets every workflow
+   * action. The step's own list is kept exactly as written, even a duplicate
+   * `name` in it, which the validator reports: inheritance only adds to it.
+   * Within the workflow's list the first action with a given `name` wins.
+   * Success and failure merge independently.
    *
-   * Presence is tested with `hasKey`, not truthiness: a step declaring an empty
-   * list (`onSuccess: []`) has *overridden* the default with an empty set of
-   * actions, not asked for one — it is skipped, as is a step whose `onSuccess`
-   * is present but not a list, for the same reason the parameters pass leaves a
-   * malformed list alone. Testing the key is also what makes the pass
-   * idempotent: after the first run the step has it, so a workflow reached again
-   * through the registry cache is skipped.
+   * An entry without a readable `name` (an unresolved Reusable Object, a
+   * scalar someone put in the list) neither overrides nor is overridden: it
+   * keeps its place, and is added only if that same element is not already in
+   * the list. A step whose `onSuccess` is present but not a list is left
+   * alone, for the same reason the parameters pass leaves a malformed list
+   * alone — overwriting it would erase what makes the document invalid.
+   *
+   * The pass is idempotent, so a workflow reached again through the registry
+   * cache is merged into once: on a second pass every inherited action is
+   * already in the step's list, under its own `name` or as the same element.
    *
    * Unlike parameters there is no step-kind filter — an action names a
    * transition within the workflow, which is as meaningful for a step targeting
@@ -202,13 +211,34 @@ class ArazzoWorkflowNormalizer {
     if (!inheritSuccess && !inheritFailure) return;
     for (const step of workflow.steps) {
       if (!(0, _apidomNsArazzo.isStepElement)(step)) continue;
-      if (inheritSuccess && !step.hasKey('onSuccess')) {
-        step.onSuccess = new _apidomNsArazzo.StepOnSuccessElement([...successActions]);
+      if (inheritSuccess && (!step.hasKey('onSuccess') || (0, _apidomDatamodel.isArrayElement)(step.onSuccess))) {
+        step.onSuccess = new _apidomNsArazzo.StepOnSuccessElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onSuccess ?? [])], [...successActions]));
+      }
+      if (inheritFailure && (!step.hasKey('onFailure') || (0, _apidomDatamodel.isArrayElement)(step.onFailure))) {
+        step.onFailure = new _apidomNsArazzo.StepOnFailureElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onFailure ?? [])], [...failureActions]));
       }
-      if (inheritFailure && !step.hasKey('onFailure')) {
-        step.onFailure = new _apidomNsArazzo.StepOnFailureElement([...failureActions]);
+    }
+  }
+
+  /**
+   * The step's actions as written, followed by each workflow action whose
+   * `name` neither the step nor an earlier workflow action carries; a nameless
+   * workflow entry is added unless that same element is already present.
+   */
+  static #mergeActions(own, inherited) {
+    const nameOf = action => (0, _apidomDatamodel.isObjectElement)(action) ? (0, _apidomCore.toValue)(action.get('name')) : undefined;
+    const names = new Set(own.map(nameOf));
+    const merged = [...own];
+    for (const action of inherited) {
+      const name = nameOf(action);
+      if (typeof name !== 'string') {
+        if (!merged.includes(action)) merged.push(action);
+      } else if (!names.has(name)) {
+        names.add(name);
+        merged.push(action);
       }
     }
+    return merged;
   }
 }
 var _default = exports.default = ArazzoWorkflowNormalizer;

package/src/normalizer/ArazzoWorkflowNormalizer.mjs

@@ -1,7 +1,7 @@
 import { uniqWith } from 'ramda';
 import { isParameterElement, isStepElement, StepParametersElement, StepOnSuccessElement, StepOnFailureElement } from '@speclynx/apidom-ns-arazzo-1';
 import { toValue } from '@speclynx/apidom-core';
-import { isArrayElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { isArrayElement, isObjectElement, isStringElement } from '@speclynx/apidom-datamodel';
 import { dereferenceArazzoElement, defaultDereferenceArazzoOptions } from '@usearazzo/resolver';
 import { mergeOptions } from '@speclynx/apidom-reference/configuration/empty';
 import ParameterIdentity from "../document/ParameterIdentity.mjs";
@@ -151,23 +151,32 @@ class ArazzoWorkflowNormalizer {
   }
 
   /**
-   * Inherits the workflow's `successActions` / `failureActions` into each step
-   * that declares no `onSuccess` / `onFailure` of its own.
+   * Merges the workflow's `successActions` / `failureActions` into each step's
+   * `onSuccess` / `onFailure`.
    *
-   * Per Arazzo 1.0.1 both lists are "applicable for all steps described under
-   * this workflow", and a step's own list **overrides** the corresponding
-   * workflow one — wholesale, with no per-action merge, which is where this
-   * differs from the parameters above. Success and failure fall back
-   * independently: a step may override only its `onFailure` and still inherit
-   * the workflow's `successActions`.
+   * Per Arazzo both lists are "applicable for all steps described under this
+   * workflow" and "can be overridden at the step level but cannot be removed
+   * there". The required action `name` is what makes both halves hold: a
+   * step's action replaces the workflow action of the same `name`, and every
+   * workflow action the step does not name still applies. The effective list is
+   * the step's own actions in order, then the workflow actions it did not
+   * override, in theirs — order matters, as selection is first-match-wins on
+   * `criteria`. So a step with no list, or with `[]`, gets every workflow
+   * action. The step's own list is kept exactly as written, even a duplicate
+   * `name` in it, which the validator reports: inheritance only adds to it.
+   * Within the workflow's list the first action with a given `name` wins.
+   * Success and failure merge independently.
    *
-   * Presence is tested with `hasKey`, not truthiness: a step declaring an empty
-   * list (`onSuccess: []`) has *overridden* the default with an empty set of
-   * actions, not asked for one — it is skipped, as is a step whose `onSuccess`
-   * is present but not a list, for the same reason the parameters pass leaves a
-   * malformed list alone. Testing the key is also what makes the pass
-   * idempotent: after the first run the step has it, so a workflow reached again
-   * through the registry cache is skipped.
+   * An entry without a readable `name` (an unresolved Reusable Object, a
+   * scalar someone put in the list) neither overrides nor is overridden: it
+   * keeps its place, and is added only if that same element is not already in
+   * the list. A step whose `onSuccess` is present but not a list is left
+   * alone, for the same reason the parameters pass leaves a malformed list
+   * alone — overwriting it would erase what makes the document invalid.
+   *
+   * The pass is idempotent, so a workflow reached again through the registry
+   * cache is merged into once: on a second pass every inherited action is
+   * already in the step's list, under its own `name` or as the same element.
    *
    * Unlike parameters there is no step-kind filter — an action names a
    * transition within the workflow, which is as meaningful for a step targeting
@@ -194,13 +203,34 @@ class ArazzoWorkflowNormalizer {
     if (!inheritSuccess && !inheritFailure) return;
     for (const step of workflow.steps) {
       if (!isStepElement(step)) continue;
-      if (inheritSuccess && !step.hasKey('onSuccess')) {
-        step.onSuccess = new StepOnSuccessElement([...successActions]);
+      if (inheritSuccess && (!step.hasKey('onSuccess') || isArrayElement(step.onSuccess))) {
+        step.onSuccess = new StepOnSuccessElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onSuccess ?? [])], [...successActions]));
+      }
+      if (inheritFailure && (!step.hasKey('onFailure') || isArrayElement(step.onFailure))) {
+        step.onFailure = new StepOnFailureElement(ArazzoWorkflowNormalizer.#mergeActions([...(step.onFailure ?? [])], [...failureActions]));
       }
-      if (inheritFailure && !step.hasKey('onFailure')) {
-        step.onFailure = new StepOnFailureElement([...failureActions]);
+    }
+  }
+
+  /**
+   * The step's actions as written, followed by each workflow action whose
+   * `name` neither the step nor an earlier workflow action carries; a nameless
+   * workflow entry is added unless that same element is already present.
+   */
+  static #mergeActions(own, inherited) {
+    const nameOf = action => isObjectElement(action) ? toValue(action.get('name')) : undefined;
+    const names = new Set(own.map(nameOf));
+    const merged = [...own];
+    for (const action of inherited) {
+      const name = nameOf(action);
+      if (typeof name !== 'string') {
+        if (!merged.includes(action)) merged.push(action);
+      } else if (!names.has(name)) {
+        names.add(name);
+        merged.push(action);
       }
     }
+    return merged;
   }
 }
 export default ArazzoWorkflowNormalizer;

package/types/runner.d.ts

@@ -1889,9 +1889,25 @@ export declare class StepExecutor {
      * — rather than as the withdrawal it is.
      */
     execute(step: StepElement, state: ContextSource, executeOptions?: Record<string, unknown>): Promise<StepExecutionResult>;
+    /**
+     * Throws {@link ResolverError} unless the step's `successCriteria` is absent
+     * or a list of Criterion Objects: `malformed-criteria` for one that is
+     * present but not a list, `malformed-criterion` for an entry that is not a
+     * Criterion Object. Skipping an unreadable entry would turn the author's
+     * assertion into a vacuous pass, so it is an authoring error, as an action's
+     * unreadable `criteria` is in {@link ActionResolver}.
+     *
+     * Called before the step's request is sent, so no live side effect precedes
+     * the error. Public because the workflow executor checks every step of a
+     * workflow with it before any of them runs, a step targeting a `workflowId`
+     * included. It passes `workflowId`, which the error then carries: step ids
+     * are only unique within a workflow.
+     */
+    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.
+     * no criteria 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