@usearazzo/runner 0.0.0-stage → 1.0.1-alpha.11

package/types/runner.d.ts

@@ -0,0 +1,2410 @@
+import { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+import { CriterionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { FailureActionElement } 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';
+import { OperationElement as OperationElement_3 } from '@speclynx/apidom-ns-openapi-3-1';
+import type { ParseResultElement } from '@usearazzo/parser';
+import type { PartialDeep } from 'type-fest';
+import { PathItemElement } from '@speclynx/apidom-ns-openapi-2';
+import { PathItemElement as PathItemElement_2 } from '@speclynx/apidom-ns-openapi-3-0';
+import { PathItemElement as PathItemElement_3 } from '@speclynx/apidom-ns-openapi-3-1';
+import { RequestBodyElement } from '@speclynx/apidom-ns-arazzo-1';
+import type { SourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { StepElement } from '@speclynx/apidom-ns-arazzo-1';
+import { StepOnFailureElement } from '@speclynx/apidom-ns-arazzo-1';
+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 { toYAML } from '@speclynx/apidom-core';
+import { WorkflowElement } from '@speclynx/apidom-ns-arazzo-1';
+import type { WorkflowOutputsElement } from '@speclynx/apidom-ns-arazzo-1';
+
+/**
+ * Selects the actions to take for a step outcome from its `onSuccess` /
+ * `onFailure` list.
+ *
+ * Actions are tried in order and every one whose `criteria` all pass is
+ * returned (an action with no criteria always matches). Action elements are
+ * returned as-is — interpreting them (branching on `type`, reading
+ * `stepId`/`workflowId`/`retryAfter`/`retryLimit`) is the caller's concern, and
+ * keeping them elements preserves the document provenance. The usual caller
+ * acts on the first and takes an empty result as "no action matched", applying
+ * the path default — the next sequential step on success, break-and-return on
+ * failure.
+ *
+ * A step's list is the only list there is: Reusable Object entries are already
+ * inlined by workflow normalization, and the workflow-level
+ * `successActions` / `failureActions` a step falls back to are inherited into
+ * `onSuccess` / `onFailure` by the same pass, so a well-formed document reaches
+ * this point as the step's own list of concrete action elements.
+ * @public
+ */
+export declare class ActionResolver {
+    #private;
+    /**
+     * Returns every `onSuccess` action whose criteria are all met, in list order.
+     *
+     * The whole matching chain rather than only the first, because the caller
+     * needs both: it acts on `[0]`, and the one honoring "retryLimit exhausted
+     * prior to subsequent failure actions" walks the rest, falling from an
+     * exhausted `retry` to the next matching action without re-evaluating
+     * criteria. Empty when the list is absent or nothing matches.
+     *
+     * `scope` names the step this list belongs to, for a thrown
+     * {@link ResolverError}.
+     *
+     * A well-formed list whose entry is not a Success/Failure Action Object
+     * throws rather than being skipped: an unrecognized entry is indistinguishable
+     * from a step that deliberately declared no action for it, and the `goto` /
+     * `end` its author was reaching for would otherwise never happen without a
+     * word said about why.
+     */
+    resolveOnSuccess(actions: StepOnSuccessElement | undefined, isCriterionMet: CriterionPredicate, scope: StepScope): SuccessActionElement[];
+    /**
+     * Returns every `onFailure` action whose criteria are all met, in list order.
+     *
+     * Same matching and error behavior as {@link ActionResolver.resolveOnSuccess} —
+     * see there for the full rationale — mirrored for the step's other list.
+     */
+    resolveOnFailure(actions: StepOnFailureElement | undefined, isCriterionMet: CriterionPredicate, scope: StepScope): FailureActionElement[];
+}
+
+/**
+ * Base document held by the document registry.
+ * @public
+ */
+export declare abstract class APIDocument {
+    abstract readonly type: string;
+    readonly uri: string;
+    readonly parseResult: ParseResultElement;
+    protected constructor(uri: string, parseResult: ParseResultElement);
+    /**
+     * Returns a JSON-serializable representation of the document's API element.
+     * Compatible with JSON.stringify() — JSON.stringify(doc) produces correct output.
+     */
+    toJSON(): unknown;
+    /**
+     * Serializes the document's API element to a YAML string.
+     */
+    toYAML(...args: Parameters<typeof toYAML> extends [unknown, ...infer R] ? R : []): string;
+}
+
+/**
+ * An Arazzo document held by the document registry: the parse result together
+ * with the indexes the provider built over it — a container, not a logic
+ * bearer. The methods below are thin reads of the source description index.
+ * @public
+ */
+export declare class ArazzoDocument extends APIDocument {
+    readonly type: "arazzo";
+    isEntry: boolean;
+    /**
+     * WorkflowId → JSON Pointer to the workflow within the parse result.
+     */
+    readonly workflowIndex: ArazzoWorkflowIndex;
+    /**
+     * WorkflowId → stepId → JSON Pointer to the step within the parse result.
+     * Built by the provider, like {@link ArazzoDocument.workflowIndex}.
+     */
+    readonly stepIndex: ArazzoStepIndex;
+    /**
+     * Name → source description element and canonical URI (already resolved
+     * against this document's base URI). Built by the provider, like
+     * {@link ArazzoDocument.workflowIndex}.
+     */
+    readonly sourceDescriptionIndex: ArazzoSourceDescriptionIndex;
+    constructor(uri: string, parseResult: ParseResultElement, workflowIndex: ArazzoWorkflowIndex, stepIndex: ArazzoStepIndex, sourceDescriptionIndex: ArazzoSourceDescriptionIndex, isEntry?: boolean);
+    /**
+     * Type guard for ArazzoDocument.
+     */
+    static is(doc: APIDocument): doc is ArazzoDocument;
+    /**
+     * Resolves a source description name to its canonical URI — precomputed by
+     * the provider, resolved against this document's base URI.
+     */
+    resolveSourceDescriptionURI(sourceDescriptionName: string): string | undefined;
+    /**
+     * Resolves a field of a source description object (e.g. `url`, `type`).
+     *
+     * The `url` field resolves to the canonical URI (resolved against this
+     * document's base URI, as `resolveSourceDescriptionURI` does); every other
+     * field resolves to its literal value. Returns `undefined` when the source
+     * description or the field is absent.
+     */
+    resolveSourceDescriptionField(sourceDescriptionName: string, field: string): unknown;
+    /**
+     * The canonical URIs of this document's source descriptions, resolved against
+     * this document's base URI, in declaration order. Sources without a resolvable
+     * url are omitted.
+     */
+    sourceDescriptionURIs(): string[];
+}
+
+/**
+ * Provides ArazzoDocument instances for the DocumentRegistry.
+ *
+ * Parses the Arazzo document and builds its workflow and source description
+ * indexes — the document itself is a container.
+ * @public
+ */
+export declare class ArazzoDocumentRegistryProvider extends DocumentRegistryProvider {
+    #private;
+    constructor(options?: ArazzoDocumentRegistryProviderOptions);
+    canProvide(uri: string): Promise<boolean>;
+    /**
+     * Loads an Arazzo document from a URI and produces an ArazzoDocument.
+     */
+    provide(uri: string): Promise<ArazzoDocument>;
+}
+
+/**
+ * Options for loading an Arazzo document.
+ * @public
+ */
+export declare type ArazzoDocumentRegistryProviderOptions = DocumentRegistryProviderOptions;
+
+/**
+ * Runs the workflows of one Arazzo document.
+ *
+ * A thin facade over the building blocks: it wires a {@link DocumentRegistry},
+ * an {@link OpenAPIOperationExecutor}, a {@link StepExecutor} and a
+ * {@link WorkflowExecutor} with their defaults, so running a workflow takes a
+ * `load` and an `execute`. The building blocks stay public for callers that
+ * need to compose them differently.
+ * @public
+ */
+export declare class ArazzoRunner {
+    #private;
+    readonly document: ArazzoDocument;
+    readonly registry: DocumentRegistry;
+    /**
+     * Loads the entry Arazzo document at `uri` (a file system path or URL) and
+     * returns a runner bound to it.
+     *
+     * @throws UnmatchedProviderError - When no provider can load the document
+     * @throws InvalidEntryDocumentError - When the document is not an Arazzo
+     * document, or the given registry already backs another entry document
+     */
+    static load(uri: string, options?: ArazzoRunnerLoadOptions): Promise<ArazzoRunner>;
+    /**
+     * Binds a runner to an entry document the caller already acquired.
+     *
+     * @throws InvalidEntryDocumentError - When `document` is not the entry document of `registry`
+     */
+    constructor(options: ArazzoRunnerOptions);
+    /**
+     * Runs the named workflow to completion, returning its outcome; see
+     * {@link WorkflowExecutor.execute}.
+     */
+    execute(workflowId: WorkflowId, options?: WorkflowExecuteOptions): Promise<WorkflowExecutionResult>;
+}
+
+/** @public */
+export declare class ArazzoRunnerError extends ApiDOMStructuredError {
+}
+
+/**
+ * Options for {@link ArazzoRunner.load}.
+ *
+ * Every option is a seam of a building block the runner wires: `registry` is
+ * the {@link DocumentRegistry} the documents load into (a fresh one with the
+ * default providers when omitted), `httpClient` and `requestInterceptor` go to
+ * the {@link OpenAPIOperationExecutor}, and the rest go to the
+ * {@link WorkflowExecutor}.
+ * @public
+ */
+export declare interface ArazzoRunnerLoadOptions extends Pick<OpenAPIOperationExecutorOptions, 'httpClient' | 'requestInterceptor'>, Pick<WorkflowExecutorOptions, 'maxSteps' | 'maxWorkflowDepth' | 'sleep' | 'now'> {
+    /**
+     * The registry to load the documents into. A registry backs one entry
+     * document: loading a different one into it throws.
+     */
+    readonly registry?: DocumentRegistry;
+}
+
+/**
+ * Options for the ArazzoRunner constructor.
+ * @public
+ */
+export declare interface ArazzoRunnerOptions extends Omit<ArazzoRunnerLoadOptions, 'registry'> {
+    /**
+     * The entry Arazzo document holding the workflows to run.
+     */
+    readonly document: ArazzoDocument;
+    /**
+     * The document registry whose entry document is `document`.
+     */
+    readonly registry: DocumentRegistry;
+}
+
+/**
+ * Index mapping a source description name to its element and canonical URI in
+ * an Arazzo document.
+ * @public
+ */
+export declare class ArazzoSourceDescriptionIndex extends Map<SourceDescriptionName, SourceDescriptionEntry> {
+}
+
+/**
+ * Extracts a step from an Arazzo workflow by stepId.
+ *
+ * Searches the workflow's steps array for the matching stepId.
+ * The workflow should be already extracted via ArazzoWorkflowExtractor.
+ * @public
+ */
+export declare class ArazzoStepExtractor {
+    /**
+     * Extracts a step element by stepId from a workflow.
+     */
+    extract(workflow: WorkflowElement, stepId: string): StepElement;
+}
+
+/**
+ * Index mapping workflowId → stepId → JSON Pointer to the step in an Arazzo
+ * document. Steps are unique only within their workflow, hence the nesting.
+ * @public
+ */
+export declare class ArazzoStepIndex extends Map<WorkflowId, Map<StepId, JSONPointer>> {
+    /**
+     * The JSON Pointer of a step, or `undefined` when the workflow or step is absent.
+     */
+    getStep(workflowId: WorkflowId, stepId: StepId): JSONPointer | undefined;
+}
+
+/**
+ * Normalizes an extracted Arazzo step.
+ *
+ * Currently acts as an identity function. Steps are already dereferenced as part
+ * of workflow normalization, which also inherits the workflow's `parameters`
+ * into them — a step reaching here has no inherited properties left to merge.
+ * @public
+ */
+export declare class ArazzoStepNormalizer {
+    /**
+     * Normalizes a step element against its parent document.
+     */
+    normalize(step: StepElement, _document: ArazzoDocument): Promise<StepElement>;
+}
+
+/**
+ * Base of every resolver of authored Arazzo values — the single home of the
+ * literal-vs-expression rule they all share.
+ *
+ * Per Arazzo 1.0.1, an authored value (a parameter's `value`, an `outputs`
+ * entry, a `requestBody` replacement value) is either a literal or a whole
+ * runtime expression — there is no embedded/interpolated expression. So a
+ * value that is a string is resolved as an expression only when the entire
+ * string is a valid runtime expression; every other value (a non-expression
+ * string such as `"{$inputs.x}"`, a number, boolean, object, array, or null)
+ * is a literal and is used as-is. This is deliberately not template
+ * interpolation. The one exception is a `requestBody` payload, which "can
+ * contain" runtime expressions — {@link RequestBodyResolver} walks it instead.
+ * @public
+ */
+export declare abstract class ArazzoValueResolver {
+    /**
+     * Resolves one authored value element by the rule above.
+     */
+    protected resolveValue(element: unknown, resolve: RuntimeExpressionResolver): unknown;
+}
+
+/**
+ * Extracts a workflow from an Arazzo document by workflowId.
+ *
+ * The workflow is already fully dereferenced in the document,
+ * so no additional processing is needed.
+ * @public
+ */
+export declare class ArazzoWorkflowExtractor {
+    /**
+     * Extracts a workflow element by workflowId.
+     */
+    extract(document: ArazzoDocument, workflowId: WorkflowId): WorkflowElement;
+}
+
+/**
+ * Index mapping workflowId to its JSON Pointer in an Arazzo document.
+ * @public
+ */
+export declare class ArazzoWorkflowIndex extends Map<WorkflowId, JSONPointer> {
+}
+
+/**
+ * A canonical Arazzo workflow locator: the Arazzo document that owns the
+ * workflow and the workflow's id within it.
+ *
+ * A workflow reference names its target in one of two ways — a plain
+ * `workflowId` of the current document, or a
+ * `$sourceDescriptions.{name}.{workflowId}` runtime expression naming a
+ * workflow of another Arazzo document. Both are locators for the same thing;
+ * the normalizer reduces either to this single canonical form. `workflowId`
+ * is the bare id either way — the key run state (`$workflows.{id}`) is
+ * recorded under, which the runtime-expression grammar can only express
+ * unqualified.
+ * @public
+ */
+export declare interface ArazzoWorkflowLocator {
+    readonly document: ArazzoDocument;
+    readonly workflowId: string;
+}
+
+/**
+ * Normalizes a workflow reference to a canonical {@link ArazzoWorkflowLocator}
+ * — the Arazzo document and the workflow's id within it.
+ *
+ * A reference appears in four author-facing positions — a sub-workflow step's
+ * `workflowId`, a `dependsOn` entry, a `retry` action's `workflowId`
+ * reference, and a `goto` action's transfer target — and is either a plain id
+ * of the referencing document or a whole
+ * `$sourceDescriptions.{name}.{workflowId}` runtime expression naming a
+ * workflow of another Arazzo document. Only that dotted expression form is a
+ * workflow reference; the resolver package's
+ * `$sourceDescriptions.{name}#/json/pointer` form is a `$ref`-time construct,
+ * not a runtime expression, and does not parse here.
+ *
+ * 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).
+ * @public
+ */
+export declare class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
+    #private;
+    /**
+     * 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.
+     */
+    normalize(reference: string, document: ArazzoDocument, context: WorkflowReferenceContext): Promise<ArazzoWorkflowLocator>;
+}
+
+/**
+ * Normalizes an extracted Arazzo workflow.
+ *
+ * Dereferences the workflow subtree ($components.* references),
+ * producing a self-contained workflow element, then inherits the workflow's
+ * "applicable for all steps" defaults — its `parameters`, and its
+ * `successActions` / `failureActions` — into each of its steps.
+ *
+ * All passes mutate, and what they mutate is the document itself: the extractor
+ * hands over the live workflow node out of `document.parseResult`, and
+ * dereferencing runs `immutable: false`, returning that same instance. Writing
+ * through to the document is what lets the registry act as a natural cache —
+ * a workflow reached a second time is already dereferenced and already
+ * inherited into, so no pass repeats. The inheritance is idempotent for
+ * exactly that reason.
+ *
+ * The writes differ in kind, which is worth knowing before sharing a
+ * registry. Dereferencing only *resolves* what the document already says — a
+ * `$ref` replaced by its target means the same thing. Inheritance *synthesizes*:
+ * afterwards a step carries `parameters` or an `onSuccess` its source never
+ * declared, so a consumer that reads the document back (`APIDocument.toJSON()`)
+ * sees one that no longer matches the file it was parsed from. The OpenAPI
+ * normalizers write inherited servers, parameters and security requirements into
+ * their documents the same way, so this is the layer's established contract
+ * rather than a property of Arazzo.
+ * @public
+ */
+export declare class ArazzoWorkflowNormalizer {
+    #private;
+    constructor(options?: ArazzoWorkflowNormalizerOptions);
+    /**
+     * Dereferences the workflow subtree against its parent document, then inherits
+     * the workflow's `parameters` and default actions into its steps.
+     */
+    normalize(workflow: WorkflowElement, document: ArazzoDocument): Promise<WorkflowElement>;
+}
+
+/**
+ * Options for normalizing an Arazzo workflow.
+ * @public
+ */
+export declare type ArazzoWorkflowNormalizerOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/** @public */
+export declare class AssemblerError extends ArazzoRunnerError {
+    readonly operationId?: string;
+    readonly uri?: string;
+}
+
+/** @public */
+export declare class ClientError extends ArazzoRunnerError {
+    readonly operationId?: string;
+    readonly operationPath?: string;
+    readonly uri?: string;
+}
+
+/**
+ * A read-only source of the runtime expression context for a step.
+ *
+ * The step executor only reads accumulated run state — it produces the
+ * pre-request context (`toContext()`) and the post-request context
+ * (`toContext(request, response)`) — and never mutates it, so it depends on
+ * this narrow interface rather than the full execution state.
+ * @public
+ */
+export declare interface ContextSource {
+    toContext(request?: RuntimeExpressionContext['request'], response?: RuntimeExpressionResponseContext): RuntimeExpressionContext;
+}
+
+/**
+ * Resolves a runtime expression to a value during criterion evaluation.
+ *
+ * Used both for a criterion's `context` (regex/jsonpath/xpath) and for the
+ * expressions embedded in a `simple` condition. It should resolve leniently —
+ * an unresolvable reference returning `undefined` fails the criterion rather
+ * than throwing (a common way to drive it is
+ * `(expression) => runtimeExpressionEvaluator.evaluate(expression)` with a
+ * lenient evaluator).
+ * @public
+ */
+export declare type CriterionContextResolver = (expression: string) => unknown;
+
+/** @public */
+export declare class CriterionError extends ArazzoRunnerError {
+    readonly condition?: string;
+    readonly type?: string;
+    readonly reason?: string;
+}
+
+/**
+ * Evaluates an Arazzo Criterion Object to a boolean.
+ *
+ * Dispatches on the criterion's `type` (defaulting to `simple` when omitted):
+ * - `simple` — evaluates the condition directly, resolving the runtime
+ *   expressions embedded in it.
+ * - `regex` — resolves the `context` runtime expression, then applies the
+ *   pattern to the resolved value.
+ * - `jsonpath` — resolves the `context` runtime expression, then applies the
+ *   JSONPath query to the resolved value (met when the query matches). Only the
+ *   `rfc9535` version is supported (the spec default); an explicit other version
+ *   throws.
+ * - `xpath` — resolves the `context` runtime expression, then applies the XPath
+ *   3.1 query to the resolved XML value (met by the Effective Boolean Value).
+ *   Only the `xpath-31` version is supported (the spec default); an explicit
+ *   other version throws.
+ *
+ * The evaluator is agnostic about how runtime expressions are resolved: the
+ * caller supplies a {@link CriterionContextResolver} per evaluation, keeping
+ * runtime-state, document, and registry concerns in the runtime expression
+ * evaluator rather than duplicated here.
+ * @public
+ */
+export declare class CriterionEvaluator {
+    #private;
+    constructor(options?: CriterionEvaluatorOptions);
+    /**
+     * Evaluates a criterion element, returning whether the condition is met.
+     *
+     * `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;
+}
+
+/**
+ * Options for the CriterionEvaluator.
+ * @public
+ */
+export declare interface CriterionEvaluatorOptions {
+    /**
+     * Simple condition evaluator. Injectable for testing.
+     */
+    readonly simple?: SimpleCriterionEvaluator;
+    /**
+     * Regex condition evaluator. Injectable for testing.
+     */
+    readonly regex?: RegexCriterionEvaluator;
+    /**
+     * JSONPath condition evaluator. Injectable for testing.
+     */
+    readonly jsonpath?: JSONPathCriterionEvaluator;
+    /**
+     * XPath condition evaluator. Injectable for testing.
+     */
+    readonly xpath?: XPathCriterionEvaluator;
+}
+
+/**
+ * Determines whether a single criterion is met.
+ *
+ * Bridged to a criterion evaluator
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * unresolvable/failing criterion is `false`, not an error.
+ * @public
+ */
+export declare type CriterionPredicate = (criterion: CriterionElement) => boolean;
+
+/**
+ * Registry for API documents keyed by canonical URI.
+ *
+ * Acts as an LRU cache for parsed documents. The entry Arazzo document
+ * is pinned and never evicted. Providers are tried in order to detect
+ * and load documents.
+ * @public
+ */
+export declare class DocumentRegistry {
+    #private;
+    constructor(options?: DocumentRegistryOptions);
+    /**
+     * Returns the entry Arazzo document, or undefined if not yet registered.
+     */
+    get entryDocument(): ArazzoDocument | undefined;
+    /**
+     * Acquires a document by URI. Returns cached document if available,
+     * otherwise detects the format, loads via the matching provider,
+     * caches, and returns it.
+     */
+    acquire(uri: string): Promise<APIDocument>;
+    /**
+     * Returns an already-loaded document by URI, or undefined if not cached.
+     *
+     * Synchronous counterpart to `acquire`: it never loads a document, only
+     * returns one the registry already holds, marking it most recently used like
+     * any other access. Consumers that must resolve a reference without awaiting
+     * (e.g. runtime expression evaluation) use this; the executor is responsible
+     * for having acquired the document beforehand.
+     */
+    get(uri: string): APIDocument | undefined;
+    /**
+     * Acquires the entry Arazzo document and marks it with `isEntry: true`.
+     * Validates that the document is an Arazzo specification.
+     */
+    acquireEntryDocument(uri: string): Promise<ArazzoDocument>;
+    clear(): void;
+}
+
+/**
+ * Options for the DocumentRegistry.
+ * @public
+ */
+export declare interface DocumentRegistryOptions {
+    readonly providers?: DocumentRegistryProvider[];
+}
+
+/**
+ * Base class for document registry providers.
+ *
+ * Subclasses implement `canProvide()` for format detection and `provide()` for loading.
+ * @public
+ */
+export declare abstract class DocumentRegistryProvider {
+    /**
+     * Checks if the content at the URI can be handled by this provider.
+     */
+    abstract canProvide(uri: string): Promise<boolean>;
+    /**
+     * Loads and produces a document from a URI.
+     */
+    abstract provide(uri: string): Promise<APIDocument>;
+}
+
+/**
+ * Options for a document registry provider.
+ * @public
+ */
+export declare type DocumentRegistryProviderOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/** @public */
+export declare class ExecutionError extends ArazzoRunnerError {
+    readonly stepId?: string;
+    readonly workflowId?: string;
+    readonly reason?: string;
+    /**
+     * The chain of workflowIds the error concerns — the loop A → B → A for a
+     * cycle, or the call chain in progress when a budget ran out.
+     */
+    readonly path?: readonly string[];
+}
+
+/** @public */
+export declare class ExtractionError extends ArazzoRunnerError {
+    readonly workflowId?: string;
+    readonly stepId?: string;
+    readonly operationId?: string;
+    readonly pointer?: string;
+    readonly uri?: string;
+}
+
+/**
+ * The pluggable HTTP transport seam.
+ *
+ * Receives the finalized {@link OpenAPIOperationRequest} and resolves with the
+ * raw WHATWG `Response`. The contract is deliberately minimal so any HTTP
+ * stack (undici, got, a recording stub, …) drops in with a few lines:
+ *
+ * - resolve with a `Response` for every HTTP status — a non-2xx is a valid
+ *   Arazzo outcome judged by a step's `successCriteria`, never an error;
+ * - throw (or reject) only on transport failure — the executor wraps the
+ *   error as a `ClientError`;
+ * - honor `request.signal` when present.
+ *
+ * Response normalization (content-type dispatch, header mapping) happens on
+ * the executor side for every client, so `$response.body` semantics stay
+ * identical no matter which transport is plugged in.
+ * @public
+ */
+export declare type HTTPClient = (request: OpenAPIOperationRequest) => Promise<Response>;
+
+/**
+ * The default {@link HTTPClient}: global fetch.
+ *
+ * Mirrors swagger-client's own transport line — the request object doubles as
+ * fetch init, so `method`, `headers`, `body`, `credentials`, and `signal` are
+ * picked up from it directly.
+ * @public
+ */
+export declare const httpClientFetch: HTTPClient;
+
+/** @public */
+export declare class InvalidEntryDocumentError extends ArazzoRunnerError {
+    readonly uri?: string;
+}
+
+/**
+ * Evaluates a `jsonpath` Arazzo criterion condition against a resolved context value.
+ *
+ * The condition is a JSONPath query (RFC 9535, per the Criterion Expression
+ * Type Object's pinned version) applied to the resolved `context`. The criterion
+ * is met when the query yields a non-empty node list.
+ *
+ * Per Arazzo 1.1.0, a `null` or `undefined` context fails the condition. The
+ * context is a plain runtime value (the runtime expression evaluator has already
+ * converted any ApiDOM element), so the default JSON evaluation realm applies.
+ * @public
+ */
+export declare class JSONPathCriterionEvaluator {
+    /**
+     * Runs the JSONPath `condition` against the resolved context value, returning
+     * whether it matched anything.
+     *
+     * Returns `false` when the context is `null` or `undefined`. Throws
+     * {@link CriterionError} when the condition is not a valid JSONPath query.
+     */
+    evaluate(condition: string, context: unknown): boolean;
+}
+
+/** @public */
+export declare class NormalizationError extends ArazzoRunnerError {
+    readonly workflowId?: string;
+    readonly operationId?: string;
+    readonly operationPointer?: string;
+    readonly pathItemPointer?: string;
+    readonly uri?: string;
+}
+
+/**
+ * Assembles a standalone OpenAPI 2.0 (Swagger) document from a
+ * normalized operation element.
+ *
+ * The assembled document is a valid Swagger 2.0 specification containing
+ * only the single operation with its host, basePath, schemes, and
+ * referenced security definitions from the source document.
+ * @public
+ */
+export declare class OpenAPI2DocumentAssembler {
+    #private;
+    /**
+     * Assembles a standalone Swagger 2.0 document from a normalized operation.
+     */
+    assemble(operation: OperationElement, document: OpenAPIDocument): OpenAPIDocument;
+}
+
+/**
+ * Version-specific normalization for OpenAPI 2.0 (Swagger) operations.
+ *
+ * Dereferences the operation subtree and handles merging of
+ * parameters and security from path item and root levels.
+ * OpenAPI 2.0 does not support servers at path item or operation level;
+ * host/basePath/schemes are root-level only and handled at execution time.
+ * @public
+ */
+export declare class OpenAPI2OperationNormalizer {
+    #private;
+    constructor(options?: OpenAPI2OperationNormalizerOptions);
+    normalize(operation: OperationElement, document: OpenAPIDocument): Promise<OperationElement>;
+}
+
+/**
+ * Options for normalizing an OpenAPI 2.0 operation.
+ * @public
+ */
+export declare type OpenAPI2OperationNormalizerOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Assembles a standalone OpenAPI 3.0 document from a
+ * normalized operation element.
+ *
+ * The assembled document is a valid OpenAPI 3.0 specification containing
+ * only the single operation with its servers, and referenced security
+ * schemes from the source document's components.
+ * @public
+ */
+export declare class OpenAPI30DocumentAssembler {
+    #private;
+    /**
+     * Assembles a standalone OpenAPI 3.0 document from a normalized operation.
+     */
+    assemble(operation: OperationElement_2, document: OpenAPIDocument): OpenAPIDocument;
+}
+
+/**
+ * Version-specific normalization for OpenAPI 3.0 operations.
+ *
+ * Dereferences the operation subtree and handles merging of servers,
+ * parameters, and security from path item and root levels.
+ * @public
+ */
+export declare class OpenAPI30OperationNormalizer {
+    #private;
+    constructor(options?: OpenAPI30OperationNormalizerOptions);
+    normalize(operation: OperationElement_2, document: OpenAPIDocument): Promise<OperationElement_2>;
+}
+
+/**
+ * Options for normalizing an OpenAPI 3.0 operation.
+ * @public
+ */
+export declare type OpenAPI30OperationNormalizerOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Assembles a standalone OpenAPI 3.1 document from a
+ * normalized operation element.
+ *
+ * The assembled document is a valid OpenAPI 3.1 specification containing
+ * only the single operation with its servers, and referenced security
+ * schemes from the source document's components.
+ * @public
+ */
+export declare class OpenAPI31DocumentAssembler {
+    #private;
+    /**
+     * Assembles a standalone OpenAPI 3.1 document from a normalized operation.
+     */
+    assemble(operation: OperationElement_3, document: OpenAPIDocument): OpenAPIDocument;
+}
+
+/**
+ * Version-specific normalization for OpenAPI 3.1 operations.
+ *
+ * Dereferences the operation subtree and handles merging of servers,
+ * parameters, and security from path item and root levels.
+ * Same inheritance rules as 3.0 but with JSON Schema $id semantics
+ * for schema resolution.
+ * @public
+ */
+export declare class OpenAPI31OperationNormalizer {
+    #private;
+    constructor(options?: OpenAPI31OperationNormalizerOptions);
+    normalize(operation: OperationElement_3, document: OpenAPIDocument): Promise<OperationElement_3>;
+}
+
+/**
+ * Options for normalizing an OpenAPI 3.1 operation.
+ * @public
+ */
+export declare type OpenAPI31OperationNormalizerOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * An OpenAPI document held by the document registry.
+ * @public
+ */
+export declare class OpenAPIDocument extends APIDocument {
+    readonly type: "openapi";
+    readonly operationIndex: OpenAPIOperationIndex;
+    constructor(uri: string, parseResult: ParseResultElement, operationIndex: OpenAPIOperationIndex);
+    /**
+     * Type guard for OpenAPIDocument.
+     */
+    static is(doc: APIDocument): doc is OpenAPIDocument;
+}
+
+/**
+ * Facade for assembling standalone OpenAPI documents across all supported versions.
+ *
+ * Detects the OpenAPI version from the source document and delegates to the
+ * appropriate version-specific assembler (2.0, 3.0, or 3.1).
+ *
+ * Custom assembler instances can be provided via constructor options.
+ * @public
+ */
+export declare class OpenAPIDocumentAssembler {
+    #private;
+    constructor(options?: OpenAPIDocumentAssemblerOptions);
+    /**
+     * Assembles a standalone OpenAPI document by delegating to the version-specific assembler.
+     */
+    assemble(operation: OpenAPIOperationElement, document: OpenAPIDocument): OpenAPIDocument;
+}
+
+/**
+ * Options for the OpenAPI document assembler facade.
+ * @public
+ */
+export declare interface OpenAPIDocumentAssemblerOptions {
+    readonly openapi2?: OpenAPI2DocumentAssembler;
+    readonly openapi30?: OpenAPI30DocumentAssembler;
+    readonly openapi31?: OpenAPI31DocumentAssembler;
+}
+
+/**
+ * Provides OpenAPIDocument instances for the DocumentRegistry.
+ *
+ * Parses, dereferences, and builds an OperationIndex for OpenAPI documents.
+ * @public
+ */
+export declare class OpenAPIDocumentRegistryProvider extends DocumentRegistryProvider {
+    #private;
+    constructor(options?: OpenAPIDocumentRegistryProviderOptions);
+    canProvide(uri: string): Promise<boolean>;
+    /**
+     * Loads an OpenAPI document from a URI and produces an OpenAPIDocument.
+     */
+    provide(uri: string): Promise<OpenAPIDocument>;
+}
+
+/**
+ * Options for loading an OpenAPI document.
+ * @public
+ */
+export declare type OpenAPIDocumentRegistryProviderOptions = DocumentRegistryProviderOptions;
+
+/**
+ * Union of OperationElement across all supported OpenAPI versions.
+ * @public
+ */
+export declare type OpenAPIOperationElement = OperationElement | OperationElement_2 | OperationElement_3;
+
+/**
+ * Options for executing an OpenAPI operation.
+ *
+ * All fields are forwarded to the vendored swagger-client `buildRequest`
+ * (which owns parameter serialization, security application, and server URL
+ * resolution), except `requestInterceptor`, which the executor runs between
+ * building the request and sending it.
+ *
+ * Typed here are the options the runner itself drives and the ones callers
+ * routinely reach for. The rest of `buildRequest`'s surface (`securities`,
+ * `scheme`, `parameterBuilders`, `attachContentTypeForEmptyPayload`, …) is
+ * deliberately left untyped and passes through the bag's open tail unchanged —
+ * see {@link OpenAPIOperationExecuteOptionsBag}. Authentication in particular
+ * is not modeled: Arazzo is auth-agnostic, so credentials are applied with a
+ * {@link RequestInterceptor}.
+ * @public
+ */
+export declare interface OpenAPIOperationExecuteOptions {
+    readonly parameters?: Record<string, unknown>;
+    readonly requestBody?: unknown;
+    /**
+     * The media type of the request body, sent as the `Content-Type` header (the
+     * Arazzo `requestBody.contentType`). Matched against the media types the
+     * operation declares under `requestBody.content`, ignoring case and any
+     * parameters it carries, and accepting a declared range (`type/*`, or the
+     * all-media-types range) as covering a concrete type. The authored value is
+     * sent in full whichever declaration it matched.
+     *
+     * The form media types are the exception: `application/x-www-form-urlencoded`
+     * and `multipart/form-data` decide how the body is encoded, so they must be
+     * declared exactly rather than by a range. A media type matching nothing
+     * throws rather than sending an empty or wrongly encoded body.
+     */
+    readonly requestContentType?: string;
+    /**
+     * The media type to ask for in the response, sent as the `Accept` header.
+     * When omitted, `Accept` is derived from the media types the operation
+     * declares for its 2xx responses.
+     */
+    readonly responseContentType?: string;
+    /**
+     * The server to send the request to. A value matching a declared server's
+     * `url` selects it and brings that server's variable defaults along; any
+     * other value is used as the base URL directly, so pointing a workflow at
+     * another environment needs no special option. Relative values resolve
+     * against the document's own URL. Works the same for OpenAPI 2.0 and 3.x.
+     *
+     * Defaults to the first server the operation declares (for 2.0, the
+     * document's `schemes`/`host`/`basePath`), resolved against the URL the
+     * document was loaded from.
+     */
+    readonly server?: string;
+    /**
+     * Substitutions for a selected server's URL template, layered over the
+     * variable defaults declared in the document. OpenAPI 3.x only, and only for
+     * a declared server — an override carries no declared variables.
+     */
+    readonly serverVariables?: Record<string, string>;
+    readonly signal?: AbortSignal;
+    readonly requestInterceptor?: RequestInterceptor;
+}
+
+/**
+ * The execute options forwarded to {@link OpenAPIOperationExecutor.execute}.
+ *
+ * The {@link OpenAPIOperationExecuteOptions} fields are surfaced for
+ * type-checked callers, while the open `Record` tail keeps the bag opaque so
+ * the rest of `buildRequest`'s surface (`scheme`, `parameterBuilders`,
+ * `attachContentTypeForEmptyPayload`, …) passes through untouched.
+ *
+ * Nothing routine belongs in the tail. Credentials go through a
+ * {@link RequestInterceptor} and `server` covers every case that once needed a
+ * `contextUrl`, so reaching for either of those here means an edge case: tests
+ * standing in for a document fetched over HTTP, or credentials applied from the
+ * document's own security schemes.
+ *
+ * Two kinds of entry are inert rather than honored, since the executor owns
+ * what they used to control. The operation target always comes from the
+ * locator, so `operationId`/`operationPath` have no effect; and the options
+ * only swagger-client's `execute()` ever read — `userFetch` and
+ * `responseInterceptor`, which the runner replaces with `httpClient` and
+ * `responseNormalizer` — reach `buildRequest` but nothing acts on them.
+ * @public
+ */
+export declare type OpenAPIOperationExecuteOptionsBag = OpenAPIOperationExecuteOptions & Record<string, unknown>;
+
+/**
+ * Executes a single OpenAPI operation named by a canonical
+ * {@link OpenAPIOperationLocator}.
+ *
+ * The pipeline extracts the operation from its owning document, normalizes it,
+ * assembles a minimal standalone OpenAPI document containing just that
+ * operation, builds the HTTP request with the vendored swagger-client
+ * `buildRequest` (parameter serialization, securities, server resolution),
+ * sends it through the pluggable {@link HTTPClient}, and normalizes the raw
+ * `Response` into the runner's response model. A non-2xx status is a valid
+ * outcome (judged by a step's `successCriteria`) and is returned, never
+ * thrown; a transport failure is wrapped as a {@link ClientError}.
+ *
+ * The executor is Arazzo-agnostic: it neither locates the operation (that is
+ * the operation locator normalizer's concern) nor resolves parameters or
+ * request bodies from runtime expressions (the step executor's concern). It
+ * receives an already-resolved locator and an opaque bag of execute options,
+ * and returns the normalized operation response carrying the request that was
+ * actually sent, so `$url` / `$method` / `$request.*` can be evaluated after
+ * execution.
+ * @public
+ */
+export declare class OpenAPIOperationExecutor {
+    #private;
+    constructor(options?: OpenAPIOperationExecutorOptions);
+    /**
+     * Executes the located operation, returning the normalized operation
+     * response.
+     *
+     * `executeOptions` is an opaque bag of `buildRequest` options (e.g. resolved
+     * `parameters`, a `requestBody` and its `requestContentType`, or a `server`).
+     * The operation target always takes precedence over it: the
+     * locator's JSON Pointer selects the operation in the assembled document, so
+     * `operationId`/`operationPath` entries in the bag cannot hijack the
+     * operation.
+     */
+    execute(locator: OpenAPIOperationLocator, executeOptions?: OpenAPIOperationExecuteOptionsBag): Promise<OpenAPIOperationResponse>;
+}
+
+/**
+ * Options for the OpenAPIOperationExecutor.
+ * @public
+ */
+export declare interface OpenAPIOperationExecutorOptions {
+    /**
+     * The transport that sends the built request and resolves with the raw
+     * WHATWG `Response`. Defaults to {@link httpClientFetch} (global fetch).
+     */
+    readonly httpClient?: HTTPClient;
+    /**
+     * Decorates every built request (e.g. an `Authorization` header) before the
+     * per-call interceptor from the execute options bag runs.
+     */
+    readonly requestInterceptor?: RequestInterceptor;
+    /**
+     * Normalizes the raw `Response` into the runner's response model. Defaults
+     * to a fresh {@link OpenAPIOperationResponseNormalizer}.
+     */
+    readonly responseNormalizer?: OpenAPIOperationResponseNormalizer;
+    /**
+     * Extracts the operation element from its owning document. Defaults to a
+     * fresh {@link OpenAPIOperationExtractor}.
+     */
+    readonly operationExtractor?: OpenAPIOperationExtractor;
+    /**
+     * Normalizes the extracted operation (servers, parameters, securities).
+     * Defaults to a fresh {@link OpenAPIOperationNormalizer}.
+     */
+    readonly operationNormalizer?: OpenAPIOperationNormalizer;
+    /**
+     * Assembles the standalone OpenAPI document for the operation. Defaults to a
+     * fresh {@link OpenAPIDocumentAssembler}.
+     */
+    readonly documentAssembler?: OpenAPIDocumentAssembler;
+}
+
+/**
+ * Extracts an operation from an OpenAPI document.
+ *
+ * Locates the operation by operationId or operationPath (JSON Pointer)
+ * and attaches metadata (pointer, method, path) to the element.
+ * The extracted operation is not dereferenced or normalized.
+ * @public
+ */
+export declare class OpenAPIOperationExtractor {
+    /**
+     * Extracts an operation by operationId.
+     */
+    extract(document: OpenAPIDocument, operationId: OperationId): OpenAPIOperationElement;
+    /**
+     * Extracts an operation by JSON Pointer (operationPath).
+     */
+    extractByPointer(document: OpenAPIDocument, pointer: JSONPointer): OpenAPIOperationElement;
+}
+
+/**
+ * Index mapping operationId to its JSON Pointer in an OpenAPI document.
+ *
+ * Only used when an Arazzo step references an operation by `operationId`.
+ * When a step uses `operationPath` (a JSON Pointer), the index is bypassed
+ * and the pointer is used directly to locate the operation.
+ *
+ * Only operations with an operationId are indexed; operations without one
+ * are only reachable via `operationPath`.
+ * @public
+ */
+export declare class OpenAPIOperationIndex extends Map<OperationId, JSONPointer> {
+}
+
+/**
+ * A canonical OpenAPI operation locator: the OpenAPI document that owns the
+ * operation and a JSON Pointer locating the operation within it
+ * (`/paths/{path}/{method}`).
+ *
+ * A step names its operation in one of several ways — a plain `operationId`, a
+ * `$sourceDescriptions` runtime expression, or an `operationPath` — which are
+ * all locators for the same thing. The normalizer reduces any of them to this
+ * single canonical form.
+ * @public
+ */
+export declare interface OpenAPIOperationLocator {
+    readonly document: OpenAPIDocument;
+    readonly jsonPointer: string;
+}
+
+/**
+ * Normalizes a step's OpenAPI operation locator to a canonical
+ * {@link OpenAPIOperationLocator} — the OpenAPI document and a JSON Pointer to
+ * the operation within it.
+ *
+ * A step names its operation with either `operationId` or `operationPath`:
+ * - `operationId` is a plain operation name, or a whole runtime expression
+ *   `$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.
+ * - `operationPath` embeds a `{$sourceDescriptions.{name}.url}` runtime
+ *   expression followed by a JSON Pointer to the operation.
+ *
+ * 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
+ * normalizer acquires the referenced source documents from the registry on
+ * demand.
+ * @public
+ */
+export declare class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
+    #private;
+    /**
+     * 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.
+     */
+    normalizeOperationId(operationId: string, document: ArazzoDocument): Promise<OpenAPIOperationLocator>;
+    /**
+     * Normalizes an `operationPath` —
+     * `{$sourceDescriptions.{name}.url}#/json/pointer` — to a canonical locator.
+     *
+     * The reference is interpolated (resolving
+     * `{$sourceDescriptions.{name}.url}` to the source's URL) into a URI
+     * reference; its fragment is the JSON Pointer to the operation (decoded from
+     * the URI fragment representation) and the part before the fragment is the
+     * source document to acquire.
+     *
+     * 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.
+     */
+    normalizeOperationPath(operationPath: string, document: ArazzoDocument): Promise<OpenAPIOperationLocator>;
+}
+
+/**
+ * Facade for normalizing OpenAPI operations across all supported versions.
+ *
+ * Detects the OpenAPI version from the document and delegates to the
+ * appropriate version-specific normalizer (2.0, 3.0, or 3.1).
+ *
+ * Custom normalizer instances can be provided via constructor options.
+ * @public
+ */
+export declare class OpenAPIOperationNormalizer {
+    #private;
+    constructor(options?: OpenAPIOperationNormalizerOptions);
+    /**
+     * Normalizes the operation by delegating to the version-specific normalizer.
+     */
+    normalize(operation: OpenAPIOperationElement, document: OpenAPIDocument): Promise<OpenAPIOperationElement>;
+}
+
+/**
+ * Options for the OpenAPI operation normalizer facade.
+ * @public
+ */
+export declare interface OpenAPIOperationNormalizerOptions {
+    readonly openapi2?: OpenAPI2OperationNormalizer;
+    readonly openapi30?: OpenAPI30OperationNormalizer;
+    readonly openapi31?: OpenAPI31OperationNormalizer;
+}
+
+/**
+ * Resolves the `parameters` of a step targeting an OpenAPI operation into the
+ * map the operation is executed with.
+ *
+ * Values follow the family-wide literal-vs-expression rule of
+ * {@link ArazzoValueResolver}. Keys and their first-wins claiming are
+ * `ParameterDelivery`'s: `'{in}.{name}'` for a location the client
+ * can address — a parameter is unique by `(name, in)`, so keying by name
+ * alone would collapse two parameters that differ only in their location into
+ * one entry and silently drop the other, where an operation legally declaring
+ * `token` both as a header and as a query parameter must receive both — and
+ * the bare name for Arazzo's `querystring`, which names no OpenAPI location.
+ * First-wins is the override order the specification requires: the list is
+ * ordered by precedence, most specific first, as `ArazzoWorkflowNormalizer`
+ * leaves it once a step's own parameters have been merged with the ones it
+ * inherits.
+ *
+ * What the map reports, this resolver judges. A parameter without a location
+ * throws {@link ResolverError}: a step targeting an operation requires one
+ * (the normalizer does not inherit input-shaped workflow parameters into such
+ * steps, so this is the step's own authoring error), and delivering it bare
+ * instead would let it capture *every* declared location of that name — see
+ * `ParameterDelivery` for the lookup order that makes it so. A
+ * non-string location throws for the same reason it deduplicates with nothing
+ * in the normalizer: it names no location. And two *different* parameters the
+ * map reports as colliding cannot both be delivered, so a collision throws
+ * rather than silently dropping one — whether they collide on one key (the
+ * scheme is not injective: a `querystring` parameter named `header.token` and
+ * a header parameter named `token` both produce `header.token`) or across a
+ * bare/qualified pair sharing a name (a `querystring` `token` next to a
+ * header `token`), where the client would consult the bare name first and
+ * silently capture the qualified value.
+ * @public
+ */
+export declare class OpenAPIOperationParameterResolver extends StepParameterResolver {
+    /**
+     * Resolves each parameter's `value`, returning a
+     * `ParameterDelivery`-keyed record. Returns an empty object when
+     * there are no parameters.
+     *
+     * `scope` names the step in a thrown {@link ResolverError}.
+     */
+    resolve(parameters: StepParametersElement | undefined, resolve: RuntimeExpressionResolver, scope: StepScope): Record<string, unknown>;
+}
+
+/**
+ * The HTTP request built for an OpenAPI operation.
+ *
+ * Produced by the vendored swagger-client `buildRequest` from the assembled
+ * single-operation document — the URL is fully resolved (server + path +
+ * serialized query string), parameters are serialized per their style/explode
+ * rules, and securities are already applied to headers/query. The object is
+ * intentionally mutable: request interceptors may edit it (or return a
+ * replacement) before it is handed to the {@link HTTPClient}.
+ *
+ * The open tail carries whatever extra fields a builder attaches; the default
+ * transport passes the whole object as fetch init, so standard `RequestInit`
+ * fields (`credentials`, `signal`, …) take effect on the wire.
+ * @public
+ */
+export declare interface OpenAPIOperationRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+    [key: string]: unknown;
+}
+
+/**
+ * The HTTP request an OpenAPI operation was executed with.
+ *
+ * An immutable snapshot of the request as actually sent, recorded by the
+ * executor after the interceptors ran and before the transport was called, so
+ * runtime expressions (`$url`, `$method`, `$request.header.*`, `$request.body`)
+ * can be evaluated against it after execution. `headers` is a copy taken at
+ * capture time; `body` shares its reference with the sent request.
+ * @public
+ */
+export declare interface OpenAPIOperationRequestInfo {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body?: unknown;
+}
+
+/**
+ * Response from an OpenAPI operation execution.
+ * @public
+ */
+export declare class OpenAPIOperationResponse {
+    readonly ok: boolean;
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: Record<string, string>;
+    readonly text: string;
+    readonly body: unknown;
+    readonly request: OpenAPIOperationRequestInfo | undefined;
+    constructor(raw: {
+        ok: boolean;
+        url: string;
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        text: string;
+        body: unknown;
+        request?: OpenAPIOperationRequestInfo;
+    });
+}
+
+/**
+ * Normalizes a raw WHATWG `Response` into an {@link OpenAPIOperationResponse}.
+ *
+ * Wraps the vendored swagger-client response deserializer (upstream
+ * `serializeRes`, aliased at the vendor boundary), whose battle-tested
+ * content-type dispatch (JSON/XML/YAML/text vs binary) means the response
+ * model runtime expressions and criteria see is defined here, on the runner's
+ * side of the {@link HTTPClient} seam, and stays identical across transports.
+ * Headers are taken from the `Response` directly rather than from the
+ * deserializer, which splits every value containing `", "` into an array:
+ * values stay strings as sent, with repeated fields (`Set-Cookie` included)
+ * combined by `Headers.get`.
+ * @public
+ */
+export declare class OpenAPIOperationResponseNormalizer {
+    /**
+     * Deserializes the response body by content type and maps the result into the
+     * runner's response model. `request` is the request the operation was
+     * executed with; its `url` doubles as the fallback when the `Response`
+     * carries none (e.g. a stubbed transport).
+     */
+    normalize(response: Response, request?: OpenAPIOperationRequestInfo): Promise<OpenAPIOperationResponse>;
+}
+
+/**
+ * Union of PathItemElement across all supported OpenAPI versions.
+ * @public
+ */
+export declare type OpenAPIPathItemElement = PathItemElement | PathItemElement_2 | PathItemElement_3;
+
+/**
+ * Unique identifier of an OpenAPI operation.
+ * @public
+ */
+export declare type OperationId = string;
+
+/**
+ * Resolves a step's or workflow's `outputs` to a plain map of name → value.
+ *
+ * The spec types `outputs` as `Map[string, {expression}]`, so a whole runtime
+ * expression is the *only* authored form — unlike a parameter's `value` or a
+ * `requestBody` payload (typed `Any`), where {@link ArazzoValueResolver} lets a
+ * literal through. An output that is not a valid runtime expression is an
+ * authoring error and throws a {@link ResolverError}.
+ *
+ * The result is the map an executor stores into the workflow execution state so
+ * later steps can read `$steps.{id}.outputs.{name}` / `$outputs.{name}`.
+ * @public
+ */
+export declare class OutputResolver extends ArazzoValueResolver {
+    /**
+     * Resolves each output value, returning a `name` → value map. Returns an empty
+     * object when there are no outputs.
+     *
+     * `scope` names the step or workflow the outputs belong to, for a thrown
+     * {@link ResolverError}. An output value that is not a valid runtime
+     * expression throws with `reason: 'invalid-expression'`.
+     */
+    resolve(outputs: StepOutputsElement | WorkflowOutputsElement | undefined, resolve: RuntimeExpressionResolver, scope: ResolverScope): Record<string, unknown>;
+}
+
+/**
+ * Evaluates a `regex` Arazzo criterion condition against a resolved context value.
+ *
+ * The Arazzo specification does not pin a regular expression dialect for the
+ * `regex` criterion type. This evaluator uses ECMA-262 (the native `RegExp`
+ * dialect), matching OpenAPI, which pins ECMA-262 for `pattern` via JSON Schema.
+ * The pattern is applied with search (not full-match) semantics — anchoring is
+ * the author's responsibility via `^`/`$`, consistent with the spec's `^200$`
+ * example.
+ *
+ * Per Arazzo 1.1.0, a `null` or `undefined` context fails the condition. A
+ * non-scalar context is serialized with `JSON.stringify` (matching how the
+ * runtime expression evaluator stringifies values for interpolation), so a
+ * pattern can match against an object/array body; scalars are coerced with
+ * `String()`.
+ *
+ * The pattern is a native `RegExp`, which has no execution timeout; a
+ * pathological author pattern (catastrophic backtracking) against a long
+ * context can stall. Patterns originate from the Arazzo document, so this is
+ * treated as trusted input rather than guarded here.
+ * @public
+ */
+export declare class RegexCriterionEvaluator {
+    #private;
+    /**
+     * Tests the resolved context value against the regular expression `condition`.
+     *
+     * The context is coerced to a string before matching. Returns `false` when the
+     * context is `null` or `undefined`. Throws {@link CriterionError} when the
+     * condition is not a valid regular expression.
+     */
+    evaluate(condition: string, context: unknown): boolean;
+}
+
+/**
+ * Resolves a step's `requestBody` to a concrete payload.
+ *
+ * The `payload` is resolved first. Per the specification it "can contain"
+ * runtime expressions, so it is walked: every string in it — the payload
+ * itself, or any value nested in its objects and arrays — that is a whole
+ * runtime expression resolves to its typed value, and every other string has
+ * its embedded `{expression}` occurrences interpolated (tolerantly, so literal
+ * braces such as a JSON template's own are kept). Object keys and resolved
+ * values are never evaluated.
+ *
+ * An unresolved expression reads as "not provided": an object member is
+ * omitted, while a whole-expression payload, an array element or an embedded
+ * expression — none of which can be omitted — throws {@link ResolverError}
+ * (`unresolved-expression`), as does an invalid embedded expression
+ * (`invalid-expression`).
+ *
+ * Then each `replacements` entry is applied — its `value` is resolved by the
+ * family-wide literal-vs-expression rule of {@link ArazzoValueResolver} and set
+ * into the payload at the replacement's `target` JSON Pointer. A replacement
+ * whose value does not resolve is skipped, leaving the payload as authored.
+ *
+ * `target` may be a JSON Pointer or an XPath per the specification; only JSON
+ * Pointer targets are supported — an XPath target throws {@link ResolverError}.
+ * @public
+ */
+export declare class RequestBodyResolver extends ArazzoValueResolver {
+    #private;
+    /**
+     * Resolves the request body, returning its payload and content type. Returns
+     * `undefined` when there is no request body.
+     *
+     * `scope` names the step in a thrown {@link ResolverError}.
+     */
+    resolve(requestBody: RequestBodyElement | undefined, resolve: RuntimeExpressionResolver, scope: StepScope): ResolvedRequestBody | undefined;
+}
+
+/**
+ * Decorates the built request before it is handed to the {@link HTTPClient}.
+ *
+ * Receives the finalized {@link OpenAPIOperationRequest} and may mutate it in
+ * place or return a replacement; returning nothing keeps the received request.
+ * May be synchronous or asynchronous.
+ * @public
+ */
+export declare type RequestInterceptor = (request: OpenAPIOperationRequest) => OpenAPIOperationRequest | void | Promise<OpenAPIOperationRequest | void>;
+
+/**
+ * A resolved request body: the payload with all replacements applied, plus the
+ * declared content type when present.
+ * @public
+ */
+export declare interface ResolvedRequestBody {
+    readonly payload: unknown;
+    readonly contentType?: string;
+}
+
+/** @public */
+export declare class ResolverError extends ArazzoRunnerError {
+    readonly stepId?: string;
+    readonly workflowId?: string;
+    readonly target?: string;
+    readonly reason?: string;
+}
+
+/**
+ * Identifies the step or workflow a resolver is resolving for. The wider
+ * union {@link OutputResolver} takes, since it resolves both a step's
+ * `outputs` and a workflow's — the one case with no step to name.
+ * @public
+ */
+export declare type ResolverScope = StepScope | {
+    readonly workflowId: string;
+};
+
+/**
+ * One run of a `retry` action's `stepId` / `workflowId` reference — "the
+ * reference is executed and the context is returned, after which the current
+ * step is retried". Fires once per firing of its action (i.e. once before every
+ * attempt the action grants, not once for the whole retry chain).
+ * @public
+ */
+export declare interface RetryReferenceRecord {
+    /**
+     * Which field the action carried: `stepId` runs one step of the current
+     * workflow; `workflowId` runs another workflow to completion.
+     */
+    readonly kind: 'step' | 'workflow';
+    /**
+     * The referenced `stepId` or `workflowId`, as written — a cross-document
+     * workflow reference stays in its
+     * `$sourceDescriptions.{name}.{workflowId}` form.
+     */
+    readonly id: string;
+    /**
+     * Whether the reference completed successfully. For `kind: 'workflow'`, this
+     * is whether the referenced run's transfer chain settled `status !== 'failed'`
+     * — a reference to a workflow that transferred is judged by where control
+     * ended up, not by the intermediate `'transferred'` status. Does not gate the
+     * retry: the retry proceeds either way, since the spec speaks of the
+     * reference's *completion*, not its success.
+     */
+    readonly successful: boolean;
+    /**
+     * The nested run, when the reference invoked a workflow — either directly
+     * (`kind: 'workflow'`) or because the referenced step itself targets a
+     * `workflowId` (`kind: 'step'`).
+     */
+    readonly subWorkflow?: WorkflowExecutionResult;
+}
+
+/**
+ * Identifies a step that calls a workflow, for the context its criteria,
+ * outputs and actions are evaluated against.
+ * @public
+ */
+export declare interface RuntimeExpressionCalledWorkflowContext {
+    /**
+     * The id of the calling step, the one whose expressions are evaluated.
+     */
+    readonly stepId: string;
+    /**
+     * The id of the workflow that step called.
+     */
+    readonly workflowId: string;
+}
+
+/**
+ * The runtime state an Arazzo runtime expression is evaluated against.
+ *
+ * Each field maps to an AST node produced by the runtime expression parser:
+ * - `request.url` / `request.method` back `$url` / `$method`
+ * - `request.header` / `.query` / `.path` / `.body` back `$request.{source}`
+ * - `response.statusCode` backs `$statusCode`
+ * - `response.header` / `.body` back `$response.{source}`
+ * - `inputs` backs `$inputs.{name}`
+ * - `outputs` backs `$outputs.{name}`
+ * - `steps` backs `$steps.{stepId}.outputs.{name}`
+ * - `workflows` backs `$workflows.{workflowId}.{inputs|outputs}.{name}`
+ * - `calledWorkflow` marks a step that calls a workflow: such a step made no
+ *   HTTP call, so `$url`, `$method`, `$statusCode`, `$request.{source}` and
+ *   `$response.{source}` are authoring errors there rather than unresolved
+ *   references, and `outputs` holds the called workflow's outputs
+ *
+ * The context holds only genuinely runtime state. Static, document-sourced
+ * expressions — `$components.{field}.{name}` and
+ * `$sourceDescriptions.{name}.{reference}` — are resolved on demand by the
+ * evaluator against the document registry, not carried here.
+ *
+ * Payload-bearing values (`request.body`, `response.body`, step/workflow output
+ * values) are drilled through a composed JSON Pointer realm, so they may be
+ * either plain JS values or ApiDOM elements.
+ * @public
+ */
+export declare interface RuntimeExpressionContext {
+    readonly request?: RuntimeExpressionRequestContext;
+    readonly response?: RuntimeExpressionResponseContext;
+    readonly inputs?: unknown;
+    readonly outputs?: unknown;
+    readonly steps?: Record<string, RuntimeExpressionStepContext>;
+    readonly workflows?: Record<string, RuntimeExpressionWorkflowContext>;
+    readonly calledWorkflow?: RuntimeExpressionCalledWorkflowContext;
+}
+
+/** @public */
+export declare class RuntimeExpressionError extends ArazzoRunnerError {
+    readonly expression?: string;
+    readonly reason?: string;
+}
+
+/**
+ * Evaluates Arazzo runtime expressions against a context.
+ *
+ * A single evaluator is bound to one context and can evaluate many expressions
+ * against it — matching how a step executor resolves a step's parameters,
+ * success criteria, and outputs from the same state.
+ *
+ * The context holds only runtime state (`$inputs`, `$steps`, `$request`,
+ * `$response`, …). Static, document-sourced expressions are resolved on demand:
+ * `$components` and `$workflows.{workflowId}.steps.{stepId}` from the
+ * evaluator's document, and `$sourceDescriptions` from the external document
+ * (via the registry) the source name points at. A step reference resolves to
+ * the Step Object as authored — a locator, not the step's execution result.
+ *
+ * A reference resolves to `undefined` when it is absent. Runtime values
+ * originate from JSON (or ApiDOM), which cannot represent `undefined` — an
+ * absent value is a missing property and an explicit null is `null` — so
+ * `undefined` unambiguously marks "unresolved".
+ *
+ * Three modes are supported:
+ * - {@link RuntimeExpressionEvaluator.evaluate} resolves a pure expression
+ *   (e.g. `$response.body#/id`) to its typed value.
+ * - {@link RuntimeExpressionEvaluator.interpolate} renders a template with
+ *   embedded `{expression}` occurrences to a string.
+ * - {@link RuntimeExpressionEvaluator.resolve} applies Arazzo "value" semantics:
+ *   a value that is itself a complete expression resolves to a typed value,
+ *   otherwise the value is interpolated to a string.
+ * @public
+ */
+export declare class RuntimeExpressionEvaluator {
+    #private;
+    constructor(context: RuntimeExpressionContext, options?: RuntimeExpressionEvaluatorOptions);
+    /**
+     * Evaluates a pure runtime expression to its typed value.
+     *
+     * The expression must be the bare form without surrounding braces
+     * (e.g. `$inputs.username`, `$response.body#/pets/0/id`). In strict mode an
+     * unresolvable reference throws; otherwise it returns `undefined`.
+     */
+    evaluate(expression: string): unknown;
+    /**
+     * Renders a template string, replacing each embedded `{expression}` with the
+     * string form of its evaluated value. Returns a string.
+     *
+     * Object and array values are serialized with `JSON.stringify`. In non-strict
+     * mode, unresolvable references render as an empty string. A `{…}` that is not
+     * a valid embedded expression (e.g. a literal JSON payload) is left unchanged.
+     */
+    interpolate(template: string): string;
+    /**
+     * Resolves an Arazzo "value" string.
+     *
+     * A value that is itself a complete runtime expression (the unbraced form,
+     * e.g. `$inputs.userId`) resolves to its typed value — "runtime expressions
+     * preserve the type of the referenced value". Any other string is an
+     * expression-string template: embedded `{expression}` occurrences are
+     * interpolated and a string is returned, so a whole-string `{expression}`
+     * yields the string representation of its value, not the typed value. A
+     * string containing no expressions is returned unchanged.
+     */
+    resolve(value: string): unknown;
+}
+
+/**
+ * Options for the RuntimeExpressionEvaluator.
+ * @public
+ */
+export declare interface RuntimeExpressionEvaluatorOptions {
+    /**
+     * When `true` (default), an unresolvable reference throws a
+     * RuntimeExpressionError. When `false`, unresolvable references evaluate to
+     * `undefined`. Parse failures always throw regardless of this setting.
+     */
+    readonly strict?: boolean;
+    /**
+     * The Arazzo document the expression is evaluated within. Required to resolve
+     * `$components.{field}.{name}` and `$workflows.{workflowId}.steps.{stepId}`
+     * (both read from this document) and `$sourceDescriptions.{name}.{reference}`
+     * (whose source name is resolved against this document). Absent references
+     * resolve to `undefined`.
+     */
+    readonly document?: ArazzoDocument;
+    /**
+     * The document registry, used to reach the external document a
+     * `$sourceDescriptions` reference points at. The referenced document must
+     * already be loaded — resolution is synchronous and never triggers a fetch.
+     */
+    readonly registry?: DocumentRegistry;
+}
+
+/**
+ * Request-side data available to runtime expressions.
+ *
+ * Populated by the step executor from the HTTP request that was (or will be) sent.
+ * Header lookup is case-insensitive because the runtime expression parser
+ * lowercases header tokens.
+ * @public
+ */
+export declare interface RuntimeExpressionRequestContext {
+    readonly url?: string;
+    readonly method?: string;
+    readonly header?: Record<string, unknown>;
+    readonly query?: Record<string, unknown>;
+    readonly path?: Record<string, unknown>;
+    readonly body?: unknown;
+}
+
+/**
+ * Resolves a runtime expression to its value.
+ *
+ * Bridged to a lenient runtime expression evaluator
+ * (`(expression) => runtimeExpressionEvaluator.evaluate(expression)`), so an
+ * unresolvable reference yields `undefined` rather than throwing.
+ * @public
+ */
+export declare type RuntimeExpressionResolver = (expression: string) => unknown;
+
+/**
+ * Response-side data available to runtime expressions.
+ *
+ * Populated by the step executor from the HTTP response that was received.
+ * Header lookup is case-insensitive because the runtime expression parser
+ * lowercases header tokens.
+ * @public
+ */
+export declare interface RuntimeExpressionResponseContext {
+    readonly statusCode?: number;
+    readonly header?: Record<string, unknown>;
+    readonly body?: unknown;
+}
+
+/**
+ * Per-step state available to `$steps.{stepId}.outputs.{name}` expressions.
+ * @public
+ */
+export declare interface RuntimeExpressionStepContext {
+    readonly outputs?: Record<string, unknown>;
+}
+
+/**
+ * Per-workflow state available to `$workflows.{workflowId}.{inputs|outputs}.{name}` expressions.
+ * @public
+ */
+export declare interface RuntimeExpressionWorkflowContext {
+    readonly inputs?: Record<string, unknown>;
+    readonly outputs?: Record<string, unknown>;
+}
+
+/**
+ * The action selected for a step outcome — a Success or Failure Action element.
+ * @public
+ */
+export declare type SelectedAction = SuccessActionElement | FailureActionElement;
+
+/**
+ * The result a transfer chain settled on: `result` itself when its `status`
+ * isn't `'transferred'`, otherwise the terminal, non-`'transferred'` result at
+ * the end of its `transferredTo` chain.
+ *
+ * For the success/failure verdict alone, prefer
+ * {@link WorkflowExecutionResult.settledStatus} — every result already
+ * carries it, computed eagerly, so no call is needed. Reach for this function
+ * when the terminal result *itself* is wanted (its `outputs`, `steps`,
+ * `workflowId`), not just where it landed. Iterative, not recursive: a
+ * chain's length is bounded only by `maxWorkflowDepth`, and this must not add
+ * a matching bound on call-stack depth.
+ * @public
+ */
+export declare function settledResult(result: WorkflowExecutionResult): WorkflowExecutionResult;
+
+/**
+ * Evaluates a `simple` Arazzo criterion condition.
+ *
+ * A simple condition embeds runtime expressions directly in the condition
+ * (e.g. `$statusCode == 200 && $response.body.status == 'available'`), so —
+ * unlike `regex`/`jsonpath`/`xpath` — it has no separate `context`. Parsing,
+ * loose/case-insensitive comparison, and member/index navigation are delegated
+ * to `@swaggerexpert/arazzo-criterion`; each embedded runtime expression is
+ * resolved through the supplied resolver.
+ *
+ * An operand that resolves to `undefined` (a lenient miss) does not throw; it is
+ * compared per the library's rules (e.g. `undefined == x` and relational
+ * comparisons are false, matching the spec's "null equals only null"), so a
+ * negated or disjunctive condition may still pass. A malformed condition throws
+ * {@link CriterionError}.
+ * @public
+ */
+export declare class SimpleCriterionEvaluator {
+    /**
+     * Evaluates the simple `condition`, resolving each embedded runtime
+     * expression via `resolve`.
+     */
+    evaluate(condition: string, resolve: CriterionContextResolver): boolean;
+}
+
+/**
+ * One indexed source description: the parsed element and its canonical URI —
+ * already resolved against the owning document's base URI, in the exact form
+ * the document registry keys on — or `undefined` for a source with no
+ * resolvable `url`.
+ * @public
+ */
+export declare interface SourceDescriptionEntry {
+    readonly element: SourceDescriptionElement;
+    readonly uri: string | undefined;
+}
+
+/**
+ * Unique name of a source description within an Arazzo document.
+ * @public
+ */
+export declare type SourceDescriptionName = string;
+
+/**
+ * Base of the locator normalizers that resolve
+ * `$sourceDescriptions.{name}.{reference}` runtime expressions — the OpenAPI
+ * operation locator and the Arazzo workflow locator. Owns the registry handle
+ * and the one grammar-facing parse, so the expression node's name and field
+ * shape are encoded once rather than per subclass.
+ * @public
+ */
+export declare abstract class SourceDescriptionsLocatorNormalizer {
+    protected readonly registry: DocumentRegistry;
+    constructor(registry: DocumentRegistry);
+    /**
+     * Parses a `$sourceDescriptions.{name}.{reference}` expression, or returns
+     * `undefined` when the string is not one (whether it fails to parse or
+     * parses to another expression kind) — each subclass raises its own error
+     * type, message, and context for its own position.
+     */
+    protected parseSourceDescriptionsExpression(expression: string): {
+        sourceName: string;
+        reference: string;
+    } | undefined;
+}
+
+/**
+ * The outcome of executing a single step.
+ * @public
+ */
+export declare interface StepExecutionResult {
+    readonly stepId: string;
+    readonly response: OpenAPIOperationResponse;
+    readonly successful: boolean;
+    readonly outputs: Record<string, unknown>;
+    /**
+     * The action to take for this outcome — the first of {@link StepExecutionResult.matchedActions},
+     * or `undefined` when none matched (the caller then applies the path default).
+     */
+    readonly action: SelectedAction | undefined;
+    /**
+     * Every `onSuccess` / `onFailure` action whose criteria matched this outcome,
+     * in list order. Usually the caller acts on `action` (the first); the workflow
+     * executor walks the full list to honor "retryLimit exhausted prior to
+     * subsequent failure actions" — falling from an exhausted `retry` to the next
+     * matching action. Empty when none matched.
+     */
+    readonly matchedActions: readonly SelectedAction[];
+}
+
+/**
+ * Executes a single Arazzo step that invokes an OpenAPI operation.
+ *
+ * The pipeline locates the step's operation (`operationId` / `operationPath`),
+ * resolves the step's parameters and request body against the pre-request
+ * context, delegates to {@link OpenAPIOperationExecutor} to run the located
+ * operation, then evaluates `successCriteria`, resolves `outputs`, and selects
+ * the `onSuccess`/`onFailure` action against the post-request context.
+ *
+ * It reads run state through a {@link ContextSource} and mutates nothing — the
+ * caller records the returned outputs and interprets the returned action. A step
+ * targeting a `workflowId` (a sub-workflow) is not an operation step and throws
+ * {@link ExecutionError}; running sub-workflows is the workflow executor's
+ * concern. A received response with unmet criteria is a normal
+ * `successful: false` outcome; malformed input (e.g. an invalid criterion or
+ * expression) throws, as does a run the caller has cancelled through an
+ * `AbortSignal` in the execute options.
+ * @public
+ */
+export declare class StepExecutor {
+    #private;
+    constructor(options: StepExecutorOptions);
+    /**
+     * A step executor bound to the given document, sharing this one's registry
+     * and operation executor — this instance itself when the document is
+     * already the one it is bound to.
+     *
+     * A step executor's identity includes the document its steps belong to: a
+     * plain `operationId` resolves against *that* document's source
+     * descriptions, and `$components` / `$sourceDescriptions` expressions
+     * resolve against it too. A cross-document workflow run therefore derives
+     * a sibling per foreign document rather than re-pointing this one.
+     */
+    forDocument(document: ArazzoDocument): StepExecutor;
+    /**
+     * Executes the step against the given run state, returning its outcome.
+     *
+     * `executeOptions` is an opaque bag passed through to the operation executor
+     * (e.g. a `server` to run the step against, or an `AbortSignal`). The
+     * Arazzo-derived options (`operationId`, `parameters`, `requestBody`) always
+     * take precedence over it.
+     *
+     * A `signal` in that bag is honored here and not only at the transport: an
+     * already-aborted signal throws `reason: 'aborted'` instead of issuing a
+     * 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.
+     */
+    execute(step: StepElement, state: ContextSource, executeOptions?: Record<string, unknown>): Promise<StepExecutionResult>;
+    /**
+     * Evaluates the step's `successCriteria`; all criteria must pass. A step with
+     * no criteria succeeds on a received response.
+     *
+     * 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;
+    /**
+     * Selects every matching `onSuccess` / `onFailure` action for the outcome, in
+     * list order, gating each action's criteria against the context.
+     *
+     * 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
+     * {@link ArazzoWorkflowNormalizer} — the same place a step's inherited
+     * `parameters` come from — so there is no fallback left to apply at selection
+     * time.
+     *
+     * The full matching list (not just the first) is returned so the caller can
+     * honor "retryLimit exhausted prior to subsequent failure actions"; the common
+     * caller simply takes the first.
+     *
+     * Public because selecting a step's actions is meaningful beyond running one:
+     * the workflow executor selects them for a step targeting a `workflowId`, which
+     * 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.
+     */
+    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext): SelectedAction[];
+}
+
+/**
+ * Options for the StepExecutor.
+ * @public
+ */
+export declare interface StepExecutorOptions {
+    /**
+     * The Arazzo document the steps belong to — typically the entry document;
+     * used to resolve each step's operation locator against its source
+     * descriptions, and to resolve `$components` / `$sourceDescriptions` in
+     * expressions. For a step of a workflow in another document, derive a
+     * sibling executor with {@link StepExecutor.forDocument}.
+     */
+    readonly document: ArazzoDocument;
+    /**
+     * The document registry holding the already-loaded source documents.
+     */
+    readonly registry: DocumentRegistry;
+    /**
+     * The operation engine each step's located operation is delegated to. Build it
+     * with the client factory (or a deterministic stub in tests) and pass it in —
+     * the step executor is agnostic to how the operation reaches the live API.
+     */
+    readonly operationExecutor: OpenAPIOperationExecutor;
+}
+
+/**
+ * Unique identifier of a step within an Arazzo workflow.
+ * @public
+ */
+export declare type StepId = string;
+
+/**
+ * Resolves a step's `parameters` to a plain map of resolved values.
+ *
+ * What a parameter's `value` means is the family-wide rule of
+ * {@link ArazzoValueResolver}; how the resolved values are *keyed* is the subclass's
+ * policy, one per step target — {@link OpenAPIOperationParameterResolver} keys
+ * request delivery for a step targeting an operation,
+ * {@link WorkflowParameterResolver} keys a sub-workflow's inputs for a step
+ * targeting a `workflowId`. Each executor constructs the one resolver its kind
+ * of step calls for.
+ * @public
+ */
+export declare abstract class StepParameterResolver extends ArazzoValueResolver {
+    /**
+     * Resolves each parameter's `value`, returning the map keyed by the
+     * subclass's policy. Returns an empty object when there are no parameters.
+     *
+     * `scope` names the step these parameters belong to, so a thrown
+     * {@link ResolverError} can say which step it came from — the caller always
+     * has it, the same way {@link ActionResolver.resolveOnSuccess} is handed
+     * `scope`.
+     */
+    abstract resolve(parameters: StepParametersElement | undefined, resolve: RuntimeExpressionResolver, scope: StepScope): Record<string, unknown>;
+}
+
+/**
+ * The trace of a single step execution within a workflow run.
+ * @public
+ */
+export declare interface StepRunRecord {
+    readonly stepId: string;
+    readonly successful: boolean;
+    readonly action: SelectedAction | undefined;
+    /**
+     * How many times the step ran — 1 with no retries, more when a `retry` action
+     * fired. The final `successful` / `action` reflect the last attempt.
+     */
+    readonly attempts: number;
+    /**
+     * Elapsed time the step took, covering every attempt and the `retryAfter`
+     * waits between them. Measured on a monotonic clock by default, so it may be
+     * fractional and is unaffected by system clock changes.
+     */
+    readonly durationMs: number;
+    /**
+     * The sub-workflow runs this step produced, in attempt order — present only on
+     * a step targeting a `workflowId`.
+     *
+     * A list rather than a single result because a retried sub-workflow step runs
+     * its sub-workflow once per attempt, and each run is a trace of its own; the
+     * last entry is the run this record's `successful` / `action` describe.
+     */
+    readonly subWorkflows?: readonly WorkflowExecutionResult[];
+    /**
+     * The `retry` reference runs this step's attempts produced, in firing order —
+     * present only when a `retry` failure action that fired carried a `stepId` /
+     * `workflowId` reference. Kept separate from {@link StepRunRecord.subWorkflows}
+     * because a reference is a repair the *retry* invokes, not the step's own
+     * target.
+     */
+    readonly retryReferences?: readonly RetryReferenceRecord[];
+}
+
+/**
+ * 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},
+ * {@link WorkflowParameterResolver}, {@link RequestBodyResolver},
+ * {@link ActionResolver} — takes this.
+ * @public
+ */
+export declare interface StepScope {
+    readonly stepId: string;
+}
+
+/** @public */
+export declare class UnmatchedProviderError extends ArazzoRunnerError {
+    readonly uri?: string;
+}
+
+/**
+ * Per-call options for {@link WorkflowExecutor.execute}.
+ * @public
+ */
+export declare interface WorkflowExecuteOptions {
+    /**
+     * The workflow's inputs, read via `$inputs`.
+     */
+    readonly inputs?: Record<string, unknown>;
+    /**
+     * The opaque client-specific bag forwarded verbatim to every
+     * {@link StepExecutor.execute} (e.g. a `server` to run against).
+     */
+    readonly executeOptions?: Record<string, unknown>;
+    /**
+     * Inputs for the workflows run implicitly to satisfy `dependsOn`, keyed by
+     * the `dependsOn` entry as written — the bare workflowId for a
+     * same-document dependency, the whole
+     * `$sourceDescriptions.{name}.{workflowId}` expression for a
+     * cross-document one; consulted for transitive dependencies too. A
+     * dependency with no entry runs with no inputs.
+     *
+     * The Arazzo Specification gives `dependsOn` no input-mapping mechanism of its
+     * own (unlike a sub-workflow *step*, which maps inputs through its
+     * `parameters`), so this is the only channel by which a dependency that
+     * requires inputs can receive them.
+     */
+    readonly dependencyInputs?: Record<string, Record<string, unknown>>;
+    /**
+     * Whether to run the workflows named by `dependsOn` before the workflow's own
+     * steps. Defaults to `true`.
+     *
+     * Pass `false` to assert the dependencies were already satisfied out-of-band —
+     * "MUST be completed before" does not mean *completed by this engine in this
+     * run*, and re-running them may duplicate side effects. Opting out records no
+     * `$workflows.{dependencyId}.outputs`, so expressions reading a dependency's
+     * outputs then resolve to `undefined`.
+     *
+     * It applies to **the workflow named in this call only**. A sub-workflow it
+     * calls still runs its own prerequisites: those are an implementation detail
+     * the caller may not know exists, so skipping them on their behalf would run
+     * that workflow against state nobody claimed to have prepared.
+     */
+    readonly runDependencies?: boolean;
+    /**
+     * Cancels the run. Observed before every step attempt — including each retry,
+     * each sub-workflow step, and each `dependsOn` prerequisite — and during the
+     * `retryAfter` waits between attempts, so an aborted run stops at the next
+     * boundary rather than working its way to the end of the workflow.
+     *
+     * An aborted run throws {@link ExecutionError} with `reason: 'aborted'`,
+     * naming the boundary it stopped at and carrying the signal's own `reason` as
+     * the error's `cause`. It does not resolve as a `failed` result: cancellation
+     * is not something the steps did, and the steps that never ran were not
+     * decided against.
+     *
+     * The signal is also forwarded to the transport (through the same
+     * `executeOptions` bag it may be passed in), so the request in flight when the
+     * abort lands is cancelled rather than merely awaited. A `signal` passed in
+     * that bag instead is observed here too — it cancels the run just as this
+     * option does — and this option wins when both are given.
+     */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * The outcome of executing a workflow.
+ *
+ * `status` is `completed` when the steps ran to the end of the list, `ended`
+ * when an `end` action stopped the run early, `failed` when a step failed and no
+ * matching `onFailure` action redirected it (the break-and-return default) — or
+ * when a `dependsOn` workflow did not complete — and `transferred` when a `goto`
+ * action handed control one-way to another workflow: this run's own steps stop
+ * at that point, and its `outputs` declaration is never evaluated, since the run
+ * never reaches its own end. See {@link WorkflowExecutionResult.settledStatus}
+ * for the success/failure verdict a `'transferred'` result defers to.
+ * @public
+ */
+export declare interface WorkflowExecutionResult {
+    readonly workflowId: string;
+    readonly outputs: Record<string, unknown>;
+    readonly steps: readonly StepRunRecord[];
+    readonly status: 'completed' | 'ended' | 'failed' | 'transferred';
+    /**
+     * Where this run's outcome actually settled: `status` itself when it isn't
+     * `'transferred'`, otherwise the terminal, non-`'transferred'` status at the
+     * end of the {@link WorkflowExecutionResult.transferredTo} chain — computed
+     * once, eagerly, when this result is built, so it costs nothing to read and
+     * nothing to forget.
+     *
+     * `status` alone is not a success/failure verdict: `'transferred'` records
+     * *where* control went, not whether the run succeeded, so comparing it
+     * directly against `'failed'` — the natural thing to write — silently
+     * misses a failure buried in the chain. `settledStatus` is that comparison,
+     * already made, always present (even when `status` isn't `'transferred'`,
+     * where it simply repeats `status`): prefer
+     * `result.settledStatus === 'failed'` over `result.status === 'failed'`
+     * for "did this run succeed", including on the top-level result
+     * {@link WorkflowExecutor.execute} itself returns.
+     */
+    readonly settledStatus: 'completed' | 'ended' | 'failed';
+    /**
+     * Elapsed time the run took, including its dependencies, sub-workflows, and
+     * retry waits — and, for a `'transferred'` run, the whole chain nested
+     * under {@link WorkflowExecutionResult.transferredTo}, since running the
+     * target is what this run's own time was spent on. Measured on a monotonic
+     * clock by default, so it may be fractional and is unaffected by system
+     * clock changes.
+     */
+    readonly durationMs: number;
+    /**
+     * The runs of the workflows named by `dependsOn`, in declaration order —
+     * present only when the workflow declares dependencies and they were run.
+     *
+     * A dependency already completed earlier in the same run is not run again; its
+     * one result is reported here for each dependent that declares it.
+     */
+    readonly dependencies?: readonly WorkflowExecutionResult[];
+    /**
+     * The target workflow's own run, present only when `status` is `transferred`.
+     *
+     * Nested rather than spliced in, like {@link WorkflowExecutionResult.dependencies}
+     * — this run's `workflowId` stays the workflow that was called, not the one
+     * control ended up in. If the target itself transfers onward, the chain is
+     * reachable by following `transferredTo.transferredTo`, recursively; its own
+     * `outputs` are the only place the transfer's actual output values live, since
+     * this run's top-level `outputs` is always `{}`.
+     */
+    readonly transferredTo?: WorkflowExecutionResult;
+}
+
+/**
+ * Accumulates the runtime state of a workflow run and produces the context a
+ * runtime expression is evaluated against.
+ *
+ * It holds only workflow-scoped state that grows as the run proceeds and is read
+ * back through `$`-expressions: `$inputs`, `$steps.{id}.outputs`,
+ * `$workflows.{id}.{inputs,outputs}`, and the workflow's own `$outputs`. Static,
+ * document-sourced expressions (`$components`, `$sourceDescriptions`) are
+ * resolved on demand by the evaluator and are not stored here; control-flow
+ * position, retries, and traces belong to the executor, not to this state.
+ *
+ * Resolving a step's `outputs` declaration to values is the executor's job; the
+ * resolved values are handed here as plain objects, keeping this state free of
+ * ApiDOM and evaluation concerns. The step-scoped request/response of the
+ * current step are layered on at read time via {@link WorkflowExecutionState.toContext}.
+ * @public
+ */
+export declare class WorkflowExecutionState {
+    #private;
+    constructor(options?: WorkflowExecutionStateOptions);
+    /**
+     * Records the resolved outputs of a completed step, read via
+     * `$steps.{stepId}.outputs.{name}`.
+     */
+    setStepOutputs(stepId: string, outputs: Record<string, unknown>): void;
+    /**
+     * Sets a single workflow output, read via `$outputs.{name}`.
+     */
+    setOutput(name: string, value: unknown): void;
+    /**
+     * Records the resolved inputs and outputs of a workflow (typically a called
+     * sub-workflow), read via `$workflows.{workflowId}.{inputs,outputs}.{name}`.
+     */
+    setWorkflow(workflowId: string, workflow: {
+        inputs?: Record<string, unknown>;
+        outputs?: Record<string, unknown>;
+    }): void;
+    /**
+     * The workflow's own accumulated outputs. Read-only by contract, like the
+     * context produced by `toContext`; treat the returned object as immutable.
+     */
+    get outputs(): Readonly<Record<string, unknown>>;
+    /**
+     * The inputs/outputs already recorded for `workflowId`, or `undefined` if
+     * none has been recorded yet. A narrow read of a single entry, for a caller
+     * that needs one without reconstructing the whole context via `toContext`.
+     */
+    getWorkflow(workflowId: string): Readonly<{
+        inputs?: Record<string, unknown>;
+        outputs?: Record<string, unknown>;
+    }> | undefined;
+    /**
+     * Produces the runtime expression context for the current evaluation site.
+     *
+     * The accumulated workflow-scoped state is combined with the optional
+     * step-scoped `request`/`response` of the step being evaluated. Omit both when
+     * evaluating before a request is made (e.g. resolving parameters), so that
+     * `$request`/`$response`/`$statusCode` correctly resolve to `undefined`.
+     */
+    toContext(request?: RuntimeExpressionRequestContext, response?: RuntimeExpressionResponseContext): RuntimeExpressionContext;
+}
+
+/**
+ * Options for the WorkflowExecutionState.
+ * @public
+ */
+export declare interface WorkflowExecutionStateOptions {
+    /**
+     * The workflow inputs, fixed for the run and read via `$inputs`.
+     */
+    readonly inputs?: Record<string, unknown>;
+}
+
+/**
+ * Executes an Arazzo workflow: the stateful loop that turns "run one step" into
+ * "run a workflow".
+ *
+ * It iterates a workflow's steps in list order, delegating each to
+ * {@link StepExecutor}, records the resolved step outputs into a
+ * {@link WorkflowExecutionState} so later steps read `$steps.{id}.outputs.{name}`,
+ * and interprets the {@link SelectedAction} the step executor selects but does
+ * not act on — advancing to the next step, jumping via `goto`, transferring
+ * one-way to another workflow via a `goto` naming a `workflowId`, or stopping on
+ * `end` / the failure break-default. After the loop it resolves the workflow's
+ * `outputs` against the final state — unless the run transferred, in which case
+ * it never reaches its own end and `outputs` stays `{}`.
+ *
+ * A step targeting a `workflowId` is a sub-workflow call the executor runs
+ * itself, recursively; the workflows named by `dependsOn` are run to completion
+ * before the workflow's own steps. Both recurse through one call tree, guarded
+ * by a shared step budget, a nesting-depth ceiling, and cycle detection. A
+ * `goto`'s transfer joins the same call tree, entered via `'goto'`, but is not
+ * charged against the step budget: it fires once per step evaluation, unlike a
+ * retry reference, which can fire repeatedly from the same frame.
+ *
+ * State is created fresh per {@link WorkflowExecutor.execute} call — and per
+ * workflow invocation within it — and owned here; the returned result is
+ * read-only. Authoring errors (missing workflow, unknown `goto` target, a cycle,
+ * budget overflow) throw {@link ExecutionError}, as does a run the caller
+ * cancels through {@link WorkflowExecuteOptions.signal}; a step that
+ * legitimately fails and breaks, or a dependency that fails, is a normal
+ * `status: 'failed'` result, not a throw — the same split {@link StepExecutor}
+ * draws.
+ *
+ * A workflow reference — a sub-workflow step's `workflowId`, a `dependsOn`
+ * entry, a `retry` action's reference, a `goto`'s transfer — may also name a
+ * workflow of another Arazzo document, as
+ * `$sourceDescriptions.{name}.{workflowId}`. The run then follows that
+ * document for the foreign workflow: its id lookups, its steps' operations,
+ * and its expressions all resolve against the document that owns it, while
+ * the `$workflows.{workflowId}` run state stays keyed by the bare id — the
+ * only form the runtime-expression grammar can express.
+ * @public
+ */
+export declare class WorkflowExecutor {
+    #private;
+    constructor(options: WorkflowExecutorOptions);
+    /**
+     * Runs the named workflow to completion, returning its outcome.
+     *
+     * The workflows the target names in `dependsOn` are run first (see
+     * {@link WorkflowExecuteOptions.runDependencies}), then its own steps.
+     *
+     * All run-scoped state — the execution state, the step trace, the control-flow
+     * position, the call stack, the step budget, and the completed-dependency
+     * ledger — is local to this call, so concurrent `execute` calls on one executor
+     * do not interfere.
+     */
+    execute(workflowId: WorkflowId, options?: WorkflowExecuteOptions): Promise<WorkflowExecutionResult>;
+}
+
+/**
+ * Options for the WorkflowExecutor.
+ * @public
+ */
+export declare interface WorkflowExecutorOptions {
+    /**
+     * The entry Arazzo document holding the workflows to run; also the
+     * `$components` / `$sourceDescriptions` base for every entry-document
+     * workflow's expressions. A workflow reached through a cross-document
+     * reference resolves against its own document instead — the document
+     * follows the invocation, not this option.
+     */
+    readonly document: ArazzoDocument;
+    /**
+     * The document registry holding the already-loaded source documents.
+     */
+    readonly registry: DocumentRegistry;
+    /**
+     * The per-step engine every step is delegated to. Build it with the client
+     * factory (or a deterministic stub in tests) and pass it in — the workflow
+     * executor is agnostic to how a step reaches the live API.
+     */
+    readonly stepExecutor: StepExecutor;
+    /**
+     * Upper bound on the number of step attempts in a single run — every attempt
+     * of every step counts, including each `retry` and each entry into a
+     * sub-workflow step. Guards against a runaway `goto` loop, a runaway `retry`,
+     * and a runaway tree of sub-workflow calls alike. Defaults to 1000.
+     *
+     * The budget is shared by the whole call tree, not granted afresh per
+     * workflow: a sub-workflow spinning on its own `goto` must not escape the
+     * ceiling the caller set.
+     */
+    readonly maxSteps?: number;
+    /**
+     * Upper bound on how deeply workflows may nest — a workflow entered while
+     * this many are already in progress throws `reason: 'workflow-depth'`.
+     * Bounds *legitimate* (acyclic) nesting; a genuine cycle is caught earlier and
+     * separately by `reason: 'workflow-cycle'`. Defaults to 32.
+     *
+     * The count includes the workflow `execute` was called with, so `1` permits
+     * that workflow and forbids all nesting; a value below 1 leaves no room for
+     * even the top-level run.
+     */
+    readonly maxWorkflowDepth?: number;
+    /**
+     * Delays for the given number of milliseconds — awaited between a step's retry
+     * attempts (`retryAfter`). Injected so tests pass a no-op and real runs delay;
+     * defaults to a real timer.
+     *
+     * The run's {@link WorkflowExecuteOptions.signal} is forwarded to it, so the
+     * default timer stops waiting when the run is cancelled; an injected sleep
+     * that ignores it merely postpones the cancellation until its wait ends.
+     */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Reads the current time in milliseconds, used for the `durationMs` of each
+     * run and step. Injected so tests assert exact durations; defaults to
+     * `performance.now`, which is monotonic — `Date.now` would yield a wrong or
+     * negative duration if the system clock were adjusted mid-run.
+     */
+    readonly now?: () => number;
+}
+
+/**
+ * Unique identifier of an Arazzo workflow.
+ * @public
+ */
+export declare type WorkflowId = string;
+
+/**
+ * Resolves the `parameters` of a step targeting a `workflowId` into the
+ * sub-workflow's inputs.
+ *
+ * Values follow the family-wide literal-vs-expression rule of
+ * {@link ArazzoValueResolver}. Keys are bare parameter names: per the
+ * specification, "when the step in context specifies a `workflowId`, then all
+ * parameters map to workflow inputs" — which are keyed by name alone, even
+ * for an inherited parameter that carries an `in`. Locations are not
+ * consulted, so two parameters differing only in `in` collapse by name here,
+ * which for inputs is the override mechanism, not a loss.
+ *
+ * The first parameter to claim a name wins: the list is ordered by
+ * precedence, most specific first, as `ArazzoWorkflowNormalizer` leaves it
+ * once a step's own parameters have been merged with the ones it inherits —
+ * the override order the specification requires.
+ * @public
+ */
+export declare class WorkflowParameterResolver extends StepParameterResolver {
+    /**
+     * Resolves each parameter's `value`, returning a `name` → value map.
+     * Returns an empty object when there are no parameters.
+     *
+     * `scope` names the step in a thrown {@link ResolverError}.
+     */
+    resolve(parameters: StepParametersElement | undefined, resolve: RuntimeExpressionResolver, scope: StepScope): Record<string, unknown>;
+}
+
+/**
+ * The referencing context a reference is resolved in: the workflow (and step,
+ * when the reference sits on one) making the reference, stamped onto every
+ * error.
+ * @public
+ */
+export declare interface WorkflowReferenceContext {
+    /**
+     * The workflow the reference appears in.
+     */
+    readonly workflowId: string;
+    /**
+     * The step the reference appears on, when it sits on one (a sub-workflow
+     * step's `workflowId`, or a `retry` / `goto` action's reference).
+     */
+    readonly stepId?: string;
+}
+
+/**
+ * Evaluates an `xpath` Arazzo criterion condition against a resolved context value.
+ *
+ * The condition is an XPath 3.1 query applied to the resolved `context`, which
+ * must be XML. A string context is parsed as XML; an already-parsed DOM node is
+ * used as-is. The criterion is met by the query's Effective Boolean Value
+ * (XPath 3.1 §19.1.2), as the Arazzo specification mandates — so a boolean
+ * predicate (`//status = 'ok'`), a non-empty node set, a non-zero number, and a
+ * non-empty string all evaluate to `true`.
+ *
+ * Only XPath 3.1 is supported (`fontoxpath`'s engine); version gating happens in
+ * the facade. Per Arazzo 1.1.0, a `null` or `undefined` context fails the
+ * condition. An invalid query throws {@link CriterionError}.
+ * @public
+ */
+export declare class XPathCriterionEvaluator {
+    #private;
+    /**
+     * Evaluates the XPath `condition` against the resolved context value, returning
+     * its Effective Boolean Value.
+     *
+     * Returns `false` when the context is `null` or `undefined`. Throws
+     * {@link CriterionError} when the context is not XML or the query is invalid.
+     */
+    evaluate(condition: string, context: unknown): boolean;
+}
+
+export { }