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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.21",
+  "version": "1.0.1-alpha.23",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
@@ -69,12 +69,12 @@
     "@speclynx/apidom-traverse": "^6.1.2",
     "@swaggerexpert/arazzo-criterion": "^1.0.1",
     "@swaggerexpert/arazzo-runtime-expression": "^3.3.0",
-    "@swaggerexpert/cookie": "^2.0.2",
+    "@swaggerexpert/cookie": "^2.1.1",
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.2",
-    "@usearazzo/parser": "1.0.1-alpha.21",
-    "@usearazzo/resolver": "1.0.1-alpha.21",
+    "@usearazzo/parser": "1.0.1-alpha.23",
+    "@usearazzo/resolver": "1.0.1-alpha.23",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -94,5 +94,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "d342b02adbd11f5362aa4850b2417521e59448ce"
+  "gitHead": "49de409b1fb851453c8c8c19cfdc12ec88545ca1"
 }

package/src/executor/ArazzoWorkflowLocatorNormalizer.cjs

@@ -52,11 +52,12 @@ var _SourceDescriptionsLocatorNormalizer = _interopRequireDefault(require("./Sou
  * The `type` declared on a source description is not trusted (it may be
  * absent or wrong); a source is classified by what it actually parses to,
  * the same convention the OpenAPI operation locator follows. Source
- * documents are acquired from the registry on demand. Whether the resolved
- * document *defines* the workflow is deliberately left to the caller, which
- * owns the timing of that check (eager for a `dependsOn` list validated
- * before any prerequisite runs, lazy for a sub-workflow step resolved per
- * attempt).
+ * documents are acquired from the registry on demand. A reference to a
+ * workflow the resolved document does not define is rejected here, so every
+ * returned locator names an existing workflow; a caller controls when that
+ * check happens by when it normalizes (eagerly for a `dependsOn` list
+ * validated before any prerequisite runs, lazily for a sub-workflow step
+ * resolved on its first attempt).
  * @public
  */
 class ArazzoWorkflowLocatorNormalizer extends _SourceDescriptionsLocatorNormalizer.default {
@@ -64,10 +65,20 @@ class ArazzoWorkflowLocatorNormalizer extends _SourceDescriptionsLocatorNormaliz
    * Resolves a reference — a plain workflowId or a
    * `$sourceDescriptions.{name}.{workflowId}` expression, as written — to the
    * canonical locator: the Arazzo document that owns the target workflow,
-   * and the bare id within it.
+   * and the bare id within it. Rejects a workflow that document does not
+   * define as `workflow-not-found`, attributed to the referencing context
+   * like every other error raised here.
    */
   async normalize(reference, document, context) {
-    return this.#resolve(this.#parseReference(reference, context), document, context);
+    const locator = await this.#resolve(this.#parseReference(reference, context), document, context);
+    if (!locator.document.workflowIndex.has(locator.workflowId)) {
+      throw new _ExecutionError.default(`workflow reference "${reference}" in workflow "${context.workflowId}" names workflow "${locator.workflowId}", which the Arazzo document at "${locator.document.uri}" does not define`, {
+        workflowId: context.workflowId,
+        stepId: context.stepId,
+        reason: 'workflow-not-found'
+      });
+    }
+    return locator;
   }
 
   /**

package/src/executor/ArazzoWorkflowLocatorNormalizer.mjs

@@ -42,11 +42,12 @@ import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNorm
  * The `type` declared on a source description is not trusted (it may be
  * absent or wrong); a source is classified by what it actually parses to,
  * the same convention the OpenAPI operation locator follows. Source
- * documents are acquired from the registry on demand. Whether the resolved
- * document *defines* the workflow is deliberately left to the caller, which
- * owns the timing of that check (eager for a `dependsOn` list validated
- * before any prerequisite runs, lazy for a sub-workflow step resolved per
- * attempt).
+ * documents are acquired from the registry on demand. A reference to a
+ * workflow the resolved document does not define is rejected here, so every
+ * returned locator names an existing workflow; a caller controls when that
+ * check happens by when it normalizes (eagerly for a `dependsOn` list
+ * validated before any prerequisite runs, lazily for a sub-workflow step
+ * resolved on its first attempt).
  * @public
  */
 class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
@@ -54,10 +55,20 @@ class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsLocatorNormalize
    * Resolves a reference — a plain workflowId or a
    * `$sourceDescriptions.{name}.{workflowId}` expression, as written — to the
    * canonical locator: the Arazzo document that owns the target workflow,
-   * and the bare id within it.
+   * and the bare id within it. Rejects a workflow that document does not
+   * define as `workflow-not-found`, attributed to the referencing context
+   * like every other error raised here.
    */
   async normalize(reference, document, context) {
-    return this.#resolve(this.#parseReference(reference, context), document, context);
+    const locator = await this.#resolve(this.#parseReference(reference, context), document, context);
+    if (!locator.document.workflowIndex.has(locator.workflowId)) {
+      throw new ExecutionError(`workflow reference "${reference}" in workflow "${context.workflowId}" names workflow "${locator.workflowId}", which the Arazzo document at "${locator.document.uri}" does not define`, {
+        workflowId: context.workflowId,
+        stepId: context.stepId,
+        reason: 'workflow-not-found'
+      });
+    }
+    return locator;
   }
 
   /**

package/src/executor/OpenAPIOperationLocatorNormalizer.cjs

@@ -10,7 +10,8 @@ var _jsonPointer = require("@swaggerexpert/json-pointer");
 var _empty = require("@speclynx/apidom-reference/configuration/empty");
 var _OpenAPIDocument = _interopRequireDefault(require("../document/OpenAPIDocument.cjs"));
 var _RuntimeExpressionEvaluator = _interopRequireDefault(require("../expression/RuntimeExpressionEvaluator.cjs"));
-var _ExtractionError = _interopRequireDefault(require("../errors/ExtractionError.cjs"));
+var _OpenAPIOperationExtractor = _interopRequireDefault(require("../extractor/OpenAPIOperationExtractor.cjs"));
+var _ExecutionError = _interopRequireDefault(require("../errors/ExecutionError.cjs"));
 var _SourceDescriptionsLocatorNormalizer = _interopRequireDefault(require("./SourceDescriptionsLocatorNormalizer.cjs"));
 /**
  * A canonical OpenAPI operation locator: the OpenAPI document that owns the
@@ -34,7 +35,7 @@ var _SourceDescriptionsLocatorNormalizer = _interopRequireDefault(require("./Sou
  *   `$sourceDescriptions.{name}.{operationId}`. Per the Arazzo Specification, a
  *   plain name is only valid when a single (non-arazzo) source description is
  *   defined; multiple sources require the expression form. A plain name is
- *   therefore resolved against the first source description that has it.
+ *   therefore looked up in the first OpenAPI source description only.
  * - `operationPath` embeds a `{$sourceDescriptions.{name}.url}` runtime
  *   expression followed by a JSON Pointer to the operation.
  *
@@ -42,21 +43,31 @@ var _SourceDescriptionsLocatorNormalizer = _interopRequireDefault(require("./Sou
  * or wrong); a source is classified by what it actually parses to. The
  * normalizer acquires the referenced source documents from the registry on
  * demand.
+ *
+ * A reference that cannot be resolved throws {@link ExecutionError}, attributed
+ * to the referencing step when a {@link StepScope} is given:
+ * `operation-not-found` when no operation answers it,
+ * `source-description-not-found` for a source name the document does not
+ * define, `source-description-not-openapi` for a source that is not an OpenAPI
+ * document, and `invalid-operation-reference` for a reference malformed as
+ * written. Every returned locator names an existing operation.
  * @public
  */
 class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormalizer.default {
+  #extractor = new _OpenAPIOperationExtractor.default();
+
   /**
    * Normalizes a plain or expression `operationId` to a canonical locator.
    *
    * A whole runtime expression (`$sourceDescriptions.{name}.{operationId}`) is
-   * resolved against its named source; a plain name is resolved against the
-   * first source description that has it.
+   * resolved against its named source; a plain name is looked up in the first
+   * OpenAPI source description only.
    */
-  async normalizeOperationId(operationId, document) {
+  async normalizeOperationId(operationId, document, scope) {
     if ((0, _arazzoRuntimeExpression.test)(operationId)) {
-      return this.#resolveSourced(operationId, document);
+      return this.#resolveSourced(operationId, document, scope);
     }
-    return this.#resolvePlainOperationId(operationId, document);
+    return this.#resolvePlainOperationId(operationId, document, scope);
   }
 
   /**
@@ -72,10 +83,21 @@ class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormal
    * The runner only needs a URL and a JSON Pointer, so it does not enforce that
    * the source description is identified by a runtime expression rather than a
    * literal URL (a literal URL interpolates to itself and still resolves) — that
-   * is a conformance concern for the validator. It fails only when the URL does
-   * not resolve to an OpenAPI source or the JSON Pointer is invalid.
+   * is a conformance concern for the validator. A source name the document does
+   * not define is detected before interpolation, so it is reported as such
+   * rather than as the empty URL it would interpolate to; the JSON Pointer must
+   * locate an operation in the acquired OpenAPI document.
    */
-  async normalizeOperationPath(operationPath, document) {
+  async normalizeOperationPath(operationPath, document, scope) {
+    for (const expression of (0, _arazzoRuntimeExpression.extract)(operationPath) ?? []) {
+      const parsed = this.parseSourceDescriptionsExpression(expression);
+      if (parsed !== undefined && document.resolveSourceDescriptionURI(parsed.sourceName) === undefined) {
+        throw new _ExecutionError.default(`operationPath "${operationPath}" names source description "${parsed.sourceName}", which the Arazzo document at "${document.uri}" does not define`, {
+          ...scope,
+          reason: 'source-description-not-found'
+        });
+      }
+    }
     const evaluator = new _RuntimeExpressionEvaluator.default({}, {
       strict: false,
       document,
@@ -84,23 +106,35 @@ class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormal
     const uriReference = evaluator.interpolate(operationPath);
     const documentURI = _empty.url.sanitize(_empty.url.stripHash(uriReference));
     if (documentURI === '') {
-      throw new _ExtractionError.default(`operationPath "${operationPath}" does not resolve to a source description URL`, {
-        pointer: operationPath,
-        uri: document.uri
+      throw new _ExecutionError.default(`operationPath "${operationPath}" does not resolve to a source description URL`, {
+        ...scope,
+        reason: 'invalid-operation-reference'
       });
     }
     const jsonPointer = _jsonPointer.URIFragmentIdentifier.fromURIReference(uriReference);
     if (!(0, _jsonPointer.testJSONPointer)(jsonPointer)) {
-      throw new _ExtractionError.default(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
-        pointer: operationPath,
-        uri: document.uri
+      throw new _ExecutionError.default(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
+        ...scope,
+        reason: 'invalid-operation-reference'
       });
     }
     const source = await this.registry.acquire(documentURI);
     if (!_OpenAPIDocument.default.is(source)) {
-      throw new _ExtractionError.default(`operationPath "${operationPath}" does not reference an OpenAPI document`, {
-        pointer: operationPath,
-        uri: documentURI
+      throw new _ExecutionError.default(`operationPath "${operationPath}" references "${documentURI}", which is not an OpenAPI document`, {
+        ...scope,
+        reason: 'source-description-not-openapi'
+      });
+    }
+
+    // the extractor owns locating an operation by pointer; its failure here
+    // means the pointer names no operation in this document.
+    try {
+      this.#extractor.extractByPointer(source, jsonPointer);
+    } catch (error) {
+      throw new _ExecutionError.default(`operationPath "${operationPath}" does not locate an operation in the OpenAPI document at "${source.uri}"`, {
+        cause: error,
+        ...scope,
+        reason: 'operation-not-found'
       });
     }
     return {
@@ -108,31 +142,24 @@ class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormal
       jsonPointer
     };
   }
-
-  /**
-   * Parses a `$sourceDescriptions.{name}.{reference}` expression, asserting
-   * it is a source-descriptions expression.
-   */
-  #parseSourceDescriptionsExpression(expression) {
+  async #resolveSourced(expression, document, scope) {
     const parsed = this.parseSourceDescriptionsExpression(expression);
     if (parsed === undefined) {
-      throw new _ExtractionError.default(`Unsupported operationId expression "${expression}"`, {
-        operationId: expression
+      throw new _ExecutionError.default(`operationId "${expression}" is not a $sourceDescriptions.{name}.{operationId} expression`, {
+        ...scope,
+        reason: 'invalid-operation-reference'
       });
     }
-    return parsed;
-  }
-  async #resolveSourced(expression, document) {
     const {
       sourceName,
       reference: operationId
-    } = this.#parseSourceDescriptionsExpression(expression);
-    const openapiDocument = await this.#sourceDocument(sourceName, document);
+    } = parsed;
+    const openapiDocument = await this.#sourceDocument(sourceName, document, scope);
     const jsonPointer = openapiDocument.operationIndex.get(operationId);
     if (jsonPointer === undefined) {
-      throw new _ExtractionError.default(`Operation "${operationId}" not found in source description "${sourceName}"`, {
-        operationId,
-        uri: openapiDocument.uri
+      throw new _ExecutionError.default(`Operation "${operationId}" not found in source description "${sourceName}" at "${openapiDocument.uri}"`, {
+        ...scope,
+        reason: 'operation-not-found'
       });
     }
     return {
@@ -153,15 +180,15 @@ class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormal
    * Non-OpenAPI (arazzo) sources are skipped. Sources are acquired one at a time
    * until the first OpenAPI source is reached.
    */
-  async #resolvePlainOperationId(operationId, document) {
+  async #resolvePlainOperationId(operationId, document, scope) {
     for (const uri of document.sourceDescriptionURIs()) {
       const source = await this.registry.acquire(uri);
       if (!_OpenAPIDocument.default.is(source)) continue;
       const jsonPointer = source.operationIndex.get(operationId);
       if (jsonPointer === undefined) {
-        throw new _ExtractionError.default(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
-          operationId,
-          uri: source.uri
+        throw new _ExecutionError.default(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
+          ...scope,
+          reason: 'operation-not-found'
         });
       }
       return {
@@ -169,26 +196,31 @@ class OpenAPIOperationLocatorNormalizer extends _SourceDescriptionsLocatorNormal
         jsonPointer
       };
     }
-    throw new _ExtractionError.default(`Operation "${operationId}" has no OpenAPI source description`, {
-      operationId,
-      uri: document.uri
+
+    // no source was named, so this is not a missing source description: there
+    // is simply no OpenAPI document for the operation to be in.
+    throw new _ExecutionError.default(`Operation "${operationId}" not found: the Arazzo document at "${document.uri}" has no OpenAPI source description`, {
+      ...scope,
+      reason: 'operation-not-found'
     });
   }
 
   /**
    * Acquires a source description by name and asserts it is an OpenAPI document.
    */
-  async #sourceDocument(sourceName, document) {
+  async #sourceDocument(sourceName, document, scope) {
     const uri = document.resolveSourceDescriptionURI(sourceName);
     if (uri === undefined) {
-      throw new _ExtractionError.default(`Source description "${sourceName}" not found`, {
-        uri: document.uri
+      throw new _ExecutionError.default(`Source description "${sourceName}" not found in the Arazzo document at "${document.uri}"`, {
+        ...scope,
+        reason: 'source-description-not-found'
       });
     }
     const source = await this.registry.acquire(uri);
     if (!_OpenAPIDocument.default.is(source)) {
-      throw new _ExtractionError.default(`Source description "${sourceName}" is not an OpenAPI document`, {
-        uri
+      throw new _ExecutionError.default(`Source description "${sourceName}" at "${uri}" is not an OpenAPI document`, {
+        ...scope,
+        reason: 'source-description-not-openapi'
       });
     }
     return source;

package/src/executor/OpenAPIOperationLocatorNormalizer.mjs

@@ -1,9 +1,10 @@
-import { test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
+import { extract, test as isRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
 import { URIFragmentIdentifier, testJSONPointer } from '@swaggerexpert/json-pointer';
 import { url } from '@speclynx/apidom-reference/configuration/empty';
 import OpenAPIDocument from "../document/OpenAPIDocument.mjs";
 import RuntimeExpressionEvaluator from "../expression/RuntimeExpressionEvaluator.mjs";
-import ExtractionError from "../errors/ExtractionError.mjs";
+import OpenAPIOperationExtractor from "../extractor/OpenAPIOperationExtractor.mjs";
+import ExecutionError from "../errors/ExecutionError.mjs";
 import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNormalizer.mjs";
 /**
  * A canonical OpenAPI operation locator: the OpenAPI document that owns the
@@ -26,7 +27,7 @@ import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNorm
  *   `$sourceDescriptions.{name}.{operationId}`. Per the Arazzo Specification, a
  *   plain name is only valid when a single (non-arazzo) source description is
  *   defined; multiple sources require the expression form. A plain name is
- *   therefore resolved against the first source description that has it.
+ *   therefore looked up in the first OpenAPI source description only.
  * - `operationPath` embeds a `{$sourceDescriptions.{name}.url}` runtime
  *   expression followed by a JSON Pointer to the operation.
  *
@@ -34,21 +35,31 @@ import SourceDescriptionsLocatorNormalizer from "./SourceDescriptionsLocatorNorm
  * or wrong); a source is classified by what it actually parses to. The
  * normalizer acquires the referenced source documents from the registry on
  * demand.
+ *
+ * A reference that cannot be resolved throws {@link ExecutionError}, attributed
+ * to the referencing step when a {@link StepScope} is given:
+ * `operation-not-found` when no operation answers it,
+ * `source-description-not-found` for a source name the document does not
+ * define, `source-description-not-openapi` for a source that is not an OpenAPI
+ * document, and `invalid-operation-reference` for a reference malformed as
+ * written. Every returned locator names an existing operation.
  * @public
  */
 class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
+  #extractor = new OpenAPIOperationExtractor();
+
   /**
    * Normalizes a plain or expression `operationId` to a canonical locator.
    *
    * A whole runtime expression (`$sourceDescriptions.{name}.{operationId}`) is
-   * resolved against its named source; a plain name is resolved against the
-   * first source description that has it.
+   * resolved against its named source; a plain name is looked up in the first
+   * OpenAPI source description only.
    */
-  async normalizeOperationId(operationId, document) {
+  async normalizeOperationId(operationId, document, scope) {
     if (isRuntimeExpression(operationId)) {
-      return this.#resolveSourced(operationId, document);
+      return this.#resolveSourced(operationId, document, scope);
     }
-    return this.#resolvePlainOperationId(operationId, document);
+    return this.#resolvePlainOperationId(operationId, document, scope);
   }
 
   /**
@@ -64,10 +75,21 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
    * The runner only needs a URL and a JSON Pointer, so it does not enforce that
    * the source description is identified by a runtime expression rather than a
    * literal URL (a literal URL interpolates to itself and still resolves) — that
-   * is a conformance concern for the validator. It fails only when the URL does
-   * not resolve to an OpenAPI source or the JSON Pointer is invalid.
+   * is a conformance concern for the validator. A source name the document does
+   * not define is detected before interpolation, so it is reported as such
+   * rather than as the empty URL it would interpolate to; the JSON Pointer must
+   * locate an operation in the acquired OpenAPI document.
    */
-  async normalizeOperationPath(operationPath, document) {
+  async normalizeOperationPath(operationPath, document, scope) {
+    for (const expression of extract(operationPath) ?? []) {
+      const parsed = this.parseSourceDescriptionsExpression(expression);
+      if (parsed !== undefined && document.resolveSourceDescriptionURI(parsed.sourceName) === undefined) {
+        throw new ExecutionError(`operationPath "${operationPath}" names source description "${parsed.sourceName}", which the Arazzo document at "${document.uri}" does not define`, {
+          ...scope,
+          reason: 'source-description-not-found'
+        });
+      }
+    }
     const evaluator = new RuntimeExpressionEvaluator({}, {
       strict: false,
       document,
@@ -76,23 +98,35 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
     const uriReference = evaluator.interpolate(operationPath);
     const documentURI = url.sanitize(url.stripHash(uriReference));
     if (documentURI === '') {
-      throw new ExtractionError(`operationPath "${operationPath}" does not resolve to a source description URL`, {
-        pointer: operationPath,
-        uri: document.uri
+      throw new ExecutionError(`operationPath "${operationPath}" does not resolve to a source description URL`, {
+        ...scope,
+        reason: 'invalid-operation-reference'
       });
     }
     const jsonPointer = URIFragmentIdentifier.fromURIReference(uriReference);
     if (!testJSONPointer(jsonPointer)) {
-      throw new ExtractionError(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
-        pointer: operationPath,
-        uri: document.uri
+      throw new ExecutionError(`operationPath "${operationPath}" has an invalid JSON Pointer`, {
+        ...scope,
+        reason: 'invalid-operation-reference'
       });
     }
     const source = await this.registry.acquire(documentURI);
     if (!OpenAPIDocument.is(source)) {
-      throw new ExtractionError(`operationPath "${operationPath}" does not reference an OpenAPI document`, {
-        pointer: operationPath,
-        uri: documentURI
+      throw new ExecutionError(`operationPath "${operationPath}" references "${documentURI}", which is not an OpenAPI document`, {
+        ...scope,
+        reason: 'source-description-not-openapi'
+      });
+    }
+
+    // the extractor owns locating an operation by pointer; its failure here
+    // means the pointer names no operation in this document.
+    try {
+      this.#extractor.extractByPointer(source, jsonPointer);
+    } catch (error) {
+      throw new ExecutionError(`operationPath "${operationPath}" does not locate an operation in the OpenAPI document at "${source.uri}"`, {
+        cause: error,
+        ...scope,
+        reason: 'operation-not-found'
       });
     }
     return {
@@ -100,31 +134,24 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
       jsonPointer
     };
   }
-
-  /**
-   * Parses a `$sourceDescriptions.{name}.{reference}` expression, asserting
-   * it is a source-descriptions expression.
-   */
-  #parseSourceDescriptionsExpression(expression) {
+  async #resolveSourced(expression, document, scope) {
     const parsed = this.parseSourceDescriptionsExpression(expression);
     if (parsed === undefined) {
-      throw new ExtractionError(`Unsupported operationId expression "${expression}"`, {
-        operationId: expression
+      throw new ExecutionError(`operationId "${expression}" is not a $sourceDescriptions.{name}.{operationId} expression`, {
+        ...scope,
+        reason: 'invalid-operation-reference'
       });
     }
-    return parsed;
-  }
-  async #resolveSourced(expression, document) {
     const {
       sourceName,
       reference: operationId
-    } = this.#parseSourceDescriptionsExpression(expression);
-    const openapiDocument = await this.#sourceDocument(sourceName, document);
+    } = parsed;
+    const openapiDocument = await this.#sourceDocument(sourceName, document, scope);
     const jsonPointer = openapiDocument.operationIndex.get(operationId);
     if (jsonPointer === undefined) {
-      throw new ExtractionError(`Operation "${operationId}" not found in source description "${sourceName}"`, {
-        operationId,
-        uri: openapiDocument.uri
+      throw new ExecutionError(`Operation "${operationId}" not found in source description "${sourceName}" at "${openapiDocument.uri}"`, {
+        ...scope,
+        reason: 'operation-not-found'
       });
     }
     return {
@@ -145,15 +172,15 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
    * Non-OpenAPI (arazzo) sources are skipped. Sources are acquired one at a time
    * until the first OpenAPI source is reached.
    */
-  async #resolvePlainOperationId(operationId, document) {
+  async #resolvePlainOperationId(operationId, document, scope) {
     for (const uri of document.sourceDescriptionURIs()) {
       const source = await this.registry.acquire(uri);
       if (!OpenAPIDocument.is(source)) continue;
       const jsonPointer = source.operationIndex.get(operationId);
       if (jsonPointer === undefined) {
-        throw new ExtractionError(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
-          operationId,
-          uri: source.uri
+        throw new ExecutionError(`Operation "${operationId}" not found in source description at "${source.uri}"`, {
+          ...scope,
+          reason: 'operation-not-found'
         });
       }
       return {
@@ -161,26 +188,31 @@ class OpenAPIOperationLocatorNormalizer extends SourceDescriptionsLocatorNormali
         jsonPointer
       };
     }
-    throw new ExtractionError(`Operation "${operationId}" has no OpenAPI source description`, {
-      operationId,
-      uri: document.uri
+
+    // no source was named, so this is not a missing source description: there
+    // is simply no OpenAPI document for the operation to be in.
+    throw new ExecutionError(`Operation "${operationId}" not found: the Arazzo document at "${document.uri}" has no OpenAPI source description`, {
+      ...scope,
+      reason: 'operation-not-found'
     });
   }
 
   /**
    * Acquires a source description by name and asserts it is an OpenAPI document.
    */
-  async #sourceDocument(sourceName, document) {
+  async #sourceDocument(sourceName, document, scope) {
     const uri = document.resolveSourceDescriptionURI(sourceName);
     if (uri === undefined) {
-      throw new ExtractionError(`Source description "${sourceName}" not found`, {
-        uri: document.uri
+      throw new ExecutionError(`Source description "${sourceName}" not found in the Arazzo document at "${document.uri}"`, {
+        ...scope,
+        reason: 'source-description-not-found'
       });
     }
     const source = await this.registry.acquire(uri);
     if (!OpenAPIDocument.is(source)) {
-      throw new ExtractionError(`Source description "${sourceName}" is not an OpenAPI document`, {
-        uri
+      throw new ExecutionError(`Source description "${sourceName}" at "${uri}" is not an OpenAPI document`, {
+        ...scope,
+        reason: 'source-description-not-openapi'
       });
     }
     return source;