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

package/types/runner.d.ts

@@ -369,11 +369,12 @@ export declare interface ArazzoWorkflowLocator {
  * The `type` declared on a source description is not trusted (it may be
  * absent or wrong); a source is classified by what it actually parses to,
  * the same convention the OpenAPI operation locator follows. Source
- * documents are acquired from the registry on demand. Whether the resolved
- * document *defines* the workflow is deliberately left to the caller, which
- * owns the timing of that check (eager for a `dependsOn` list validated
- * before any prerequisite runs, lazy for a sub-workflow step resolved per
- * attempt).
+ * documents are acquired from the registry on demand. A reference to a
+ * workflow the resolved document does not define is rejected here, so every
+ * returned locator names an existing workflow; a caller controls when that
+ * check happens by when it normalizes (eagerly for a `dependsOn` list
+ * validated before any prerequisite runs, lazily for a sub-workflow step
+ * resolved on its first attempt).
  * @public
  */
 export declare class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
@@ -382,7 +383,9 @@ export declare class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsL
      * Resolves a reference — a plain workflowId or a
      * `$sourceDescriptions.{name}.{workflowId}` expression, as written — to the
      * canonical locator: the Arazzo document that owns the target workflow,
-     * and the bare id within it.
+     * and the bare id within it. Rejects a workflow that document does not
+     * define as `workflow-not-found`, attributed to the referencing context
+     * like every other error raised here.
      */
     normalize(reference: string, document: ArazzoDocument, context: WorkflowReferenceContext): Promise<ArazzoWorkflowLocator>;
 }
@@ -1251,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.
  *
@@ -1259,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 {
@@ -1267,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.
@@ -1284,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>;
 }
 
 /**
@@ -2046,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
@@ -2074,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
@@ -2097,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'>;
 }
 
 /**
@@ -2207,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;
 }