@usearazzo/runner 1.0.1-alpha.25 → 1.0.1-alpha.27

package/src/executor/WorkflowExecutor.mjs

@@ -1,6 +1,6 @@
 import { toValue } from '@speclynx/apidom-core';
 import { isArrayElement, isObjectElement, isStringElement } from '@speclynx/apidom-datamodel';
-import { isStepElement } from '@speclynx/apidom-ns-arazzo-1';
+import { isFailureActionElement, isParameterElement, isStepElement, isSuccessActionElement } from '@speclynx/apidom-ns-arazzo-1';
 import RuntimeExpressionEvaluator from "../expression/RuntimeExpressionEvaluator.mjs";
 import ArazzoWorkflowExtractor from "../extractor/ArazzoWorkflowExtractor.mjs";
 import ArazzoWorkflowNormalizer from "../normalizer/ArazzoWorkflowNormalizer.mjs";
@@ -287,6 +287,16 @@ class WorkflowExecutor {
     // 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);
+    // and to every action's `parameters`, for the same reason: an `in` the
+    // specification forbids must not cost the run the requests before the
+    // step whose action carries it.
+    // the workflow's own default actions too: one every step overrides by
+    // name never reaches a step's list, yet the validator still reports it.
+    this.#assertActionParameters([workflow.successActions, workflow.failureActions], workflowId);
+    for (const step of steps) {
+      const stepId = toValue(step.stepId);
+      this.#assertActionParameters([step.onSuccess, step.onFailure], workflowId, stepId);
+    }
     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
@@ -382,7 +392,7 @@ class WorkflowExecutor {
               stepId,
               callStack: nested
             });
-            const transferredTo = await this.#runReferencedWorkflow(transition.workflowId, stepId, invocation, scope, 'goto');
+            const transferredTo = await this.#runReferencedWorkflow(transition.workflowId, stepId, invocation, scope, 'goto', this.#actionInputs(action?.parameters, outcome, invocation, stepId));
             runOutcome = {
               kind: 'transferred',
               transferredTo
@@ -558,16 +568,16 @@ class WorkflowExecutor {
    *   for entering the reference itself, matching the "1 for the step itself
    *   plus whatever its sub-run spends" convention a sub-workflow step
    *   already follows (without it, a reference to a workflow with few or no
-   *   steps of its own would cost nothing to fire). It runs with no inputs:
-   *   the specification gives a retry reference no input-mapping mechanism
-   *   of its own (the same gap `dependsOn` has), and `{}` is the only
-   *   spec-honest fallback — see issue `#62`. Its outputs are recorded via
-   *   `state.setWorkflow`, which *is* "context transfers back" — but its
-   *   `inputs` are preserved rather than overwritten with `{}` when this
-   *   workflowId was already recorded (by an earlier `dependsOn` prerequisite
-   *   or sub-workflow step sharing the id): this call's own lack of a real
-   *   inputs value must not erase one a different, better-informed caller
-   *   already gave.
+   *   steps of its own would cost nothing to fire). Its inputs are the
+   *   action's `parameters` (`#115`), resolved again on every firing
+   *   against the attempt that fired it — `{}` without them. Its outputs are
+   *   recorded via `state.setWorkflow`, which *is* "context transfers back",
+   *   together with the inputs it ran with when the action carries
+   *   `parameters`. Without them, the recorded `inputs` are preserved rather
+   *   than overwritten with `{}` when this workflowId was already recorded
+   *   (by an earlier `dependsOn` prerequisite or sub-workflow step sharing
+   *   the id): this call's own lack of a real inputs value must not erase one
+   *   a different, better-informed caller already gave.
    * - a `stepId` reference must name a step of the current workflow (checked
    *   lazily, at fire time, via the same lookup a `goto` target uses) and
    *   runs as one more attempt at that step, through
@@ -590,7 +600,7 @@ class WorkflowExecutor {
       state,
       callStack
     } = invocation;
-    return async action => {
+    return async (action, outcome) => {
       throwIfAborted(scope.signal, {
         workflowId,
         stepId,
@@ -609,13 +619,16 @@ class WorkflowExecutor {
       }
       if (hasWorkflowId) {
         const reference = toValue(action.workflowId);
+        // resolved before the budget is charged, so an authoring error in them
+        // costs no budget unit.
+        const inputs = this.#actionInputs(action.parameters, outcome, invocation, stepId);
         this.#chargeBudget(scope, invocation, stepId);
-        const result = await this.#runReferencedWorkflow(reference, stepId, invocation, scope, 'retry');
+        const result = await this.#runReferencedWorkflow(reference, stepId, invocation, scope, 'retry', inputs);
         // the result's workflowId is the bare id the reference resolved to —
         // the key run state is recorded under, whichever document owns it.
         const refId = result.workflowId;
         state.setWorkflow(refId, {
-          inputs: state.getWorkflow(refId)?.inputs ?? {},
+          inputs: action.hasKey('parameters') ? inputs : state.getWorkflow(refId)?.inputs ?? {},
           outputs: result.outputs
         });
         retryReferences.push({
@@ -633,12 +646,12 @@ class WorkflowExecutor {
       });
       const refStep = steps[refIndex];
       const refSubWorkflows = [];
-      const outcome = await this.#chargedAttempt(this.#stepAttempt(refStep, refStepId, invocation, scope, refSubWorkflows), invocation, scope, refStepId)();
-      state.setStepOutputs(outcome.stepId, outcome.outputs);
+      const refOutcome = await this.#chargedAttempt(this.#stepAttempt(refStep, refStepId, invocation, scope, refSubWorkflows), invocation, scope, refStepId)();
+      state.setStepOutputs(refOutcome.stepId, refOutcome.outputs);
       retryReferences.push({
         kind: 'step',
         id: refStepId,
-        successful: outcome.successful,
+        successful: refOutcome.successful,
         ...(refSubWorkflows.length > 0 ? {
           subWorkflow: refSubWorkflows[0]
         } : {})
@@ -891,7 +904,8 @@ class WorkflowExecutor {
         action: matchedActions[0],
         matchedActions,
         successCriteria,
-        actionCriteria
+        actionCriteria,
+        actionContext: stepExecutor.actionContext(context, stepId, outputs)
       };
     };
   }
@@ -948,20 +962,95 @@ class WorkflowExecutor {
   /**
    * Runs a workflow an action references directly — a retry's `workflowId`
    * reference or a goto's transfer, plain id or cross-document expression —
-   * with `{}` inputs, since neither has an input-mapping mechanism of its own
-   * (issue `#62`).
+   * with the inputs its action's `parameters` resolved to (`#115`), `{}`
+   * without them.
    *
    * Shared rather than duplicated by its two callers, which otherwise repeat
-   * the identical "resolve the reference, then run with no inputs" sequence.
+   * the identical "resolve the reference, then run it" sequence.
    * 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) {
+  async #runReferencedWorkflow(reference, stepId, invocation, scope, via, inputs) {
     const locator = await this.#workflowLocatorNormalizer.normalize(reference, invocation.document, {
       workflowId: invocation.workflowId,
       stepId
     });
-    return this.#run(locator, {}, scope, invocation.callStack, via);
+    return this.#run(locator, inputs, scope, invocation.callStack, via);
+  }
+
+  /**
+   * The inputs a `goto` / `retry` action naming a `workflowId` passes its
+   * target: the action's own `parameters`, mapped by name and resolved against
+   * the context of the attempt that fired it — `$statusCode`, `$response.*`
+   * and the rest of that step outcome, plus the outputs it just produced.
+   * Resolved against the calling invocation's document, so its `$components`
+   * apply, never the target's. No `parameters` gives `{}`. Their shape was
+   * checked before the workflow's first request, by
+   * {@link WorkflowExecutor.#assertActionParameters}.
+   */
+  #actionInputs(parameters, outcome, invocation, stepId) {
+    const {
+      workflowId,
+      document
+    } = invocation;
+    return this.#parameterResolver.resolve(parameters, expression => this.#evaluate(outcome.actionContext, expression, document), {
+      workflowId,
+      stepId
+    });
+  }
+
+  /**
+   * Throws {@link ResolverError} unless every action in `lists` — a step's
+   * `onSuccess` / `onFailure`, or the workflow's own `successActions` /
+   * `failureActions` — has an absent `parameters` or a list free of inline `in`:
+   * `malformed-parameters` for one that is present but not a list,
+   * `action-parameter-location` for a Parameter Object that declares `in`. The
+   * specification says outright that "The `in` field MUST NOT be used" on
+   * them. An `in` arriving through a `$components.parameters` Reusable Object
+   * is not inline — a shared component carries `in` for the operation steps
+   * that use it — and the dereferencer marks the transcluded copy with
+   * `ref-fields`.
+   *
+   * Checked for every action, `workflowId` or not, before any step of the
+   * workflow runs: both are authoring errors the validator reports, so a run
+   * must not make requests on the way to discovering them. Valid `parameters`
+   * on an action naming no `workflowId` are still ignored, as the validator
+   * only warns about them. A list that is not an array is skipped here and left
+   * for the code that reads it to report. `stepId` is absent for the
+   * workflow's own lists, and the error then names the workflow alone.
+   */
+  #assertActionParameters(lists, workflowId, stepId) {
+    const owner = stepId === undefined ? `workflow "${workflowId}"` : `step "${stepId}" in workflow "${workflowId}"`;
+    for (const actions of lists) {
+      if (!isArrayElement(actions)) continue;
+      for (const action of actions) {
+        if (!isSuccessActionElement(action) && !isFailureActionElement(action)) continue;
+        if (!action.hasKey('parameters')) continue;
+        const scope = {
+          workflowId,
+          ...(stepId === undefined ? {} : {
+            stepId
+          }),
+          target: 'parameters'
+        };
+        const {
+          parameters
+        } = action;
+        if (!isArrayElement(parameters)) {
+          throw new ResolverError('`parameters` is present but is not a list', {
+            ...scope,
+            reason: ResolverError.MalformedParameters
+          });
+        }
+        const inline = [...parameters].some(parameter => isParameterElement(parameter) && parameter.hasKey('in') && !parameter.meta.hasKey('ref-fields'));
+        if (inline) {
+          throw new ResolverError(`An action parameter of ${owner} declares an \`in\`; action parameters map to the target workflow's inputs by name`, {
+            ...scope,
+            reason: ResolverError.ActionParameterLocation
+          });
+        }
+      }
+    }
   }
 
   /**

package/src/registry/providers/ArazzoDocumentRegistryProvider.cjs

@@ -99,7 +99,8 @@ class ArazzoDocumentRegistryProvider extends _DocumentRegistryProvider.default {
    * A source description's canonical URI is resolved here too — against the
    * document's base URI, into the exact form the document registry keys on —
    * so every consumer works with a ready-to-use, non-relative URI. The first
-   * element of a duplicated source description name wins.
+   * element of a duplicated source description name wins, and so does the
+   * first workflow of a duplicated workflowId.
    */
   #buildIndexes(uri, parseResult) {
     const workflowIndex = new _ArazzoWorkflowIndex.default();
@@ -111,6 +112,7 @@ class ArazzoDocumentRegistryProvider extends _DocumentRegistryProvider.default {
         const workflowId = (0, _apidomCore.toValue)(workflow.workflowId);
         if (typeof workflowId !== 'string') return path.skip();
         if (workflowId === '') return path.skip();
+        if (workflowIndex.has(workflowId)) return path.skip();
         const workflowPointer = path.formatPath('jsonpointer');
         workflowIndex.set(workflowId, workflowPointer);
 

package/src/registry/providers/ArazzoDocumentRegistryProvider.mjs

@@ -91,7 +91,8 @@ class ArazzoDocumentRegistryProvider extends DocumentRegistryProvider {
    * A source description's canonical URI is resolved here too — against the
    * document's base URI, into the exact form the document registry keys on —
    * so every consumer works with a ready-to-use, non-relative URI. The first
-   * element of a duplicated source description name wins.
+   * element of a duplicated source description name wins, and so does the
+   * first workflow of a duplicated workflowId.
    */
   #buildIndexes(uri, parseResult) {
     const workflowIndex = new ArazzoWorkflowIndex();
@@ -103,6 +104,7 @@ class ArazzoDocumentRegistryProvider extends DocumentRegistryProvider {
         const workflowId = toValue(workflow.workflowId);
         if (typeof workflowId !== 'string') return path.skip();
         if (workflowId === '') return path.skip();
+        if (workflowIndex.has(workflowId)) return path.skip();
         const workflowPointer = path.formatPath('jsonpointer');
         workflowIndex.set(workflowId, workflowPointer);
 

package/src/registry/providers/OpenAPIDocumentRegistryProvider.cjs

@@ -44,6 +44,7 @@ const providerOptionsOverride = exports.providerOptionsOverride = {
  * Provides OpenAPIDocument instances for the DocumentRegistry.
  *
  * Parses, dereferences, and builds an OperationIndex for OpenAPI documents.
+ * The first operation of a duplicated operationId wins.
  * @public
  */
 class OpenAPIDocumentRegistryProvider extends _DocumentRegistryProvider.default {
@@ -95,6 +96,7 @@ class OpenAPIDocumentRegistryProvider extends _DocumentRegistryProvider.default
         const operationId = (0, _apidomCore.toValue)(operation.operationId);
         if (typeof operationId !== 'string') return path.skip();
         if (operationId === '') return path.skip();
+        if (index.has(operationId)) return path.skip();
         index.set(operationId, path.formatPath('jsonpointer'));
         path.skip();
       }

package/src/registry/providers/OpenAPIDocumentRegistryProvider.mjs

@@ -36,6 +36,7 @@ export const providerOptionsOverride = {
  * Provides OpenAPIDocument instances for the DocumentRegistry.
  *
  * Parses, dereferences, and builds an OperationIndex for OpenAPI documents.
+ * The first operation of a duplicated operationId wins.
  * @public
  */
 class OpenAPIDocumentRegistryProvider extends DocumentRegistryProvider {
@@ -87,6 +88,7 @@ class OpenAPIDocumentRegistryProvider extends DocumentRegistryProvider {
         const operationId = toValue(operation.operationId);
         if (typeof operationId !== 'string') return path.skip();
         if (operationId === '') return path.skip();
+        if (index.has(operationId)) return path.skip();
         index.set(operationId, path.formatPath('jsonpointer'));
         path.skip();
       }

package/src/resolver/WorkflowParameterResolver.cjs

@@ -12,7 +12,8 @@ var _ResolverError = _interopRequireDefault(require("../errors/ResolverError.cjs
 var _StepParameterResolver = _interopRequireDefault(require("./StepParameterResolver.cjs"));
 /**
  * Resolves the `parameters` of a step targeting a `workflowId` into the
- * sub-workflow's inputs.
+ * sub-workflow's inputs — or those of a `goto` / `retry` action naming a
+ * `workflowId` into its target's.
  *
  * Values follow the family-wide literal-vs-expression rule of
  * {@link ArazzoValueResolver}. Keys are bare parameter names: per the

package/src/resolver/WorkflowParameterResolver.mjs

@@ -5,7 +5,8 @@ import ResolverError from "../errors/ResolverError.mjs";
 import StepParameterResolver from "./StepParameterResolver.mjs";
 /**
  * Resolves the `parameters` of a step targeting a `workflowId` into the
- * sub-workflow's inputs.
+ * sub-workflow's inputs — or those of a `goto` / `retry` action naming a
+ * `workflowId` into its target's.
  *
  * Values follow the family-wide literal-vs-expression rule of
  * {@link ArazzoValueResolver}. Keys are bare parameter names: per the

package/src/state/WorkflowExecutionState.cjs

@@ -37,7 +37,9 @@ class WorkflowExecutionState {
 
   /**
    * Records the resolved outputs of a completed step, read via
-   * `$steps.{stepId}.outputs.{name}`.
+   * `$steps.{stepId}.outputs.{name}`. Every run records, so a step run again
+   * (a `goto` back, a retry) or a later step sharing its `stepId` replaces
+   * the earlier outputs, even with none.
    */
   setStepOutputs(stepId, outputs) {
     this.#steps.set(stepId, outputs);

package/src/state/WorkflowExecutionState.mjs

@@ -31,7 +31,9 @@ class WorkflowExecutionState {
 
   /**
    * Records the resolved outputs of a completed step, read via
-   * `$steps.{stepId}.outputs.{name}`.
+   * `$steps.{stepId}.outputs.{name}`. Every run records, so a step run again
+   * (a `goto` back, a retry) or a later step sharing its `stepId` replaces
+   * the earlier outputs, even with none.
    */
   setStepOutputs(stepId, outputs) {
     this.#steps.set(stepId, outputs);

package/types/runner.d.ts

@@ -3,6 +3,7 @@ import { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { CriterionElement } from '@speclynx/apidom-ns-arazzo-1';
 import { FailureActionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { FailureActionParametersElement } from '@speclynx/apidom-ns-arazzo-1';
 import { JSONPointer } from '@speclynx/apidom-json-pointer';
 import { OperationElement } from '@speclynx/apidom-ns-openapi-2';
 import { OperationElement as OperationElement_2 } from '@speclynx/apidom-ns-openapi-3-0';
@@ -20,6 +21,7 @@ import { StepOnSuccessElement } from '@speclynx/apidom-ns-arazzo-1';
 import type { StepOutputsElement } from '@speclynx/apidom-ns-arazzo-1';
 import { StepParametersElement } from '@speclynx/apidom-ns-arazzo-1';
 import { SuccessActionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { SuccessActionParametersElement } from '@speclynx/apidom-ns-arazzo-1';
 import { toYAML } from '@speclynx/apidom-core';
 import { WorkflowElement } from '@speclynx/apidom-ns-arazzo-1';
 import type { WorkflowOutputsElement } from '@speclynx/apidom-ns-arazzo-1';
@@ -125,8 +127,9 @@ export declare class ArazzoDocument extends APIDocument {
     static is(doc: APIDocument): doc is ArazzoDocument;
     /**
      * The workflows of this document that can be addressed by `workflowId`, in
-     * document order. Reads this document only: source descriptions are neither
-     * loaded nor listed.
+     * document order. A duplicated `workflowId` is listed once, for its first
+     * workflow. Reads this document only: source descriptions are neither loaded
+     * nor listed.
      */
     listWorkflows(): WorkflowDescriptor[];
     /**
@@ -1085,6 +1088,7 @@ export declare interface OpenAPIDocumentAssemblerOptions {
  * Provides OpenAPIDocument instances for the DocumentRegistry.
  *
  * Parses, dereferences, and builds an OperationIndex for OpenAPI documents.
+ * The first operation of a duplicated operationId wins.
  * @public
  */
 export declare class OpenAPIDocumentRegistryProvider extends DocumentRegistryProvider {
@@ -1714,6 +1718,13 @@ export declare interface ResolvedRequestBody {
  * @public
  */
 export declare class ResolverError extends ArazzoRunnerError {
+    /**
+     * A parameter of a Success / Failure Action declares an `in` inline, which
+     * the Arazzo Specification forbids; one inherited from a
+     * `$components.parameters` Reusable Object maps by name instead. Thrown
+     * before the workflow's first request.
+     */
+    static readonly ActionParameterLocation: "action-parameter-location";
     /** A parameter cannot be delivered unambiguously at its location. */
     static readonly AmbiguousDelivery: "ambiguous-delivery";
     /** An output or a request body payload holds a value that is not a valid runtime expression. */
@@ -2167,6 +2178,18 @@ export declare interface StepExecutionResult {
      * in list order.
      */
     readonly actionCriteria: readonly CriterionEvaluationRecord[];
+    /**
+     * The runtime-expression context the step's actions are taken in: the
+     * context its action `criteria` were evaluated against, with
+     * `$steps.{stepId}.outputs` holding the outputs this attempt just resolved.
+     *
+     * An action's `parameters` resolve against it, so a `goto` or `retry` naming
+     * a `workflowId` passes values read from this step's response, request and
+     * fresh outputs. The overlay matters because run state is written only once
+     * a step's retry chain settles, so mid-chain it may still hold an earlier
+     * run's outputs.
+     */
+    readonly actionContext: RuntimeExpressionContext;
 }
 
 /**
@@ -2277,6 +2300,17 @@ export declare class StepExecutor {
      * {@link StepExecutor.execute}.
      */
     selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext, workflowId?: string): Pick<StepExecutionResult, 'matchedActions' | 'actionCriteria'>;
+    /**
+     * The context a step's actions are taken in — see
+     * {@link StepExecutionResult.actionContext}: `context` with
+     * `$steps.{stepId}.outputs` replaced by the outputs the attempt just
+     * resolved, as a fresh object, so run state is never written.
+     *
+     * Public for the same reason as {@link StepExecutor.selectActions}: the
+     * workflow executor builds this context for a step targeting a
+     * `workflowId`, which never reaches {@link StepExecutor.execute}.
+     */
+    actionContext(context: RuntimeExpressionContext, stepId: string, outputs: Record<string, unknown>): RuntimeExpressionContext;
 }
 
 /**
@@ -2586,7 +2620,9 @@ export declare class WorkflowExecutionState {
     constructor(options?: WorkflowExecutionStateOptions);
     /**
      * Records the resolved outputs of a completed step, read via
-     * `$steps.{stepId}.outputs.{name}`.
+     * `$steps.{stepId}.outputs.{name}`. Every run records, so a step run again
+     * (a `goto` back, a retry) or a later step sharing its `stepId` replaces
+     * the earlier outputs, even with none.
      */
     setStepOutputs(stepId: string, outputs: Record<string, unknown>): void;
     /**
@@ -2767,7 +2803,8 @@ export declare type WorkflowId = string;
 
 /**
  * Resolves the `parameters` of a step targeting a `workflowId` into the
- * sub-workflow's inputs.
+ * sub-workflow's inputs — or those of a `goto` / `retry` action naming a
+ * `workflowId` into its target's.
  *
  * Values follow the family-wide literal-vs-expression rule of
  * {@link ArazzoValueResolver}. Keys are bare parameter names: per the
@@ -2790,7 +2827,7 @@ export declare class WorkflowParameterResolver extends StepParameterResolver {
      *
      * `scope` names the step in a thrown {@link ResolverError}.
      */
-    resolve(parameters: StepParametersElement | undefined, resolve: RuntimeExpressionResolver, scope: StepScope): Record<string, unknown>;
+    resolve(parameters: StepParametersElement | SuccessActionParametersElement | FailureActionParametersElement | undefined, resolve: RuntimeExpressionResolver, scope: StepScope): Record<string, unknown>;
 }
 
 /**