@speclynx/apidom-reference 5.2.4 → 5.2.6

package/src/dereference/strategies/arazzo-1/index.mjs

@@ -5,6 +5,7 @@ import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
 import Arazzo1DereferenceVisitor from "./visitor.mjs";
+import { detachedRootSchema$ids } from "../openapi-3-1/util.mjs";
 import { dereferenceSourceDescriptions } from "./source-descriptions.mjs";
 /**
  * @public
@@ -59,7 +60,8 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
     const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new Arazzo1DereferenceVisitor({
       reference,
-      options
+      options,
+      ancestorSchema$ids: detachedRootSchema$ids(refSet.rootRef.value.result)
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
       mutable: true,
@@ -68,6 +70,17 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
       })
     });
 
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     * Replayed before source descriptions are dereferenced, so they can reuse the refs.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new Reference({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
     /**
      * Dereference source descriptions if option is enabled.
      */
@@ -82,16 +95,6 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
       parseResult.push(...sourceDescriptions);
     }
 
-    /**
-     * If immutable option is set, replay refs from the refSet.
-     */
-    if (options.dereference.immutable) {
-      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new Reference({
-        ...ref,
-        uri: ref.uri.replace(/^immutable:\/\//, '')
-      })).forEach(ref => immutableRefSet.add(ref));
-    }
-
     /**
      * Release all memory if this refSet was not provided as a configuration option.
      * If provided as configuration option, then provider is responsible for cleanup.

package/src/dereference/strategies/arazzo-1/selectors/$anchor.cjs

@@ -33,6 +33,12 @@ Object.defineProperty(exports, "isAnchor", {
     return _$anchor.isAnchor;
   }
 });
+Object.defineProperty(exports, "locate", {
+  enumerable: true,
+  get: function () {
+    return _$anchor.locate;
+  }
+});
 Object.defineProperty(exports, "parse", {
   enumerable: true,
   get: function () {

package/src/dereference/strategies/arazzo-1/selectors/$anchor.mjs

@@ -1 +1 @@
-export { isAnchor, uriToAnchor, parse, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError } from "../../openapi-3-1/selectors/$anchor.mjs";
+export { isAnchor, uriToAnchor, parse, locate, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError } from "../../openapi-3-1/selectors/$anchor.mjs";

package/src/dereference/strategies/arazzo-1/selectors/uri.cjs

@@ -21,4 +21,10 @@ Object.defineProperty(exports, "evaluate", {
     return _uri.evaluate;
   }
 });
+Object.defineProperty(exports, "locate", {
+  enumerable: true,
+  get: function () {
+    return _uri.locate;
+  }
+});
 var _uri = require("../../openapi-3-1/selectors/uri.cjs");

package/src/dereference/strategies/arazzo-1/selectors/uri.mjs

@@ -1 +1 @@
-export { evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError } from "../../openapi-3-1/selectors/uri.mjs";
+export { locate, evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError } from "../../openapi-3-1/selectors/uri.mjs";

package/src/dereference/strategies/arazzo-1/source-descriptions.cjs

@@ -1,5 +1,6 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
@@ -8,9 +9,13 @@ exports.dereferenceSourceDescriptions = dereferenceSourceDescriptions;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _apidomCore = require("@speclynx/apidom-core");
+var _ramda = require("ramda");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
 var _util = require("../../../options/util.cjs");
-var _index = _interopRequireWildcard(require("../../index.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _index2 = require("../../index.cjs");
 var _util2 = require("./util.cjs");
 /**
  * Dereferences a single source description element.
@@ -63,53 +68,64 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
   const existingParseResult = sourceDescription.meta.get('parseResult');
+  const parentRefSet = ctx.options.dereference.refSet;
+  let refSet = null;
   try {
-    let sourceDescriptionDereferenced;
-    if ((0, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      sourceDescriptionDereferenced = await (0, _index.dereferenceApiDOM)(existingParseResult, (0, _util.merge)(ctx.options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsAncestors: ctx.ancestors,
-              sourceDescriptionsDereferenced: ctx.dereferenced
-            }
-          }
-        }
-      }));
+    // source description document comes from, in order of preference:
+    // caller-supplied refSet, parse phase, or is fetched and parsed now
+    const cachedReference = parentRefSet?.find(ref => ref.uri === retrievalURI);
+    let sourceDescriptionParseResult;
+    let isFreshlyParsed = false;
+    if (cachedReference !== undefined) {
+      sourceDescriptionParseResult = cachedReference.value;
+    } else if ((0, _apidomDatamodel.isParseResultElement)(existingParseResult)) {
+      sourceDescriptionParseResult = existingParseResult;
     } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
+      sourceDescriptionParseResult = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
         parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsAncestors: ctx.ancestors,
-              sourceDescriptionsDereferenced: ctx.dereferenced
-            }
-          }
-        }
+          mediaType: 'text/plain'
+        } // allow parser plugin detection
       }));
+      isFreshlyParsed = true;
     }
 
+    // caller-supplied refSet is rooted at the entry document, but strategies dereference
+    // the root of the refSet; re-root its references at the source description
+    if (parentRefSet !== null) {
+      refSet = new _ReferenceSet.default({
+        refs: [new _Reference.default({
+          uri: retrievalURI,
+          value: sourceDescriptionParseResult
+        }), ...parentRefSet.refs.map(ref => new _Reference.default({
+          ...ref,
+          refSet: undefined
+        }))]
+      });
+    }
+    const sourceDescriptionDereferenced = await (0, _index2.dereferenceApiDOM)(sourceDescriptionParseResult, (0, _util.merge)((0, _ramda.assocPath)(['dereference', 'refSet'], refSet, ctx.options), {
+      parse: {
+        mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+      },
+      resolve: {
+        baseURI: retrievalURI
+      },
+      dereference: {
+        // freshly parsed document not reported to any refSet can be dereferenced in mutable mode
+        immutable: ctx.options.dereference.immutable && !(isFreshlyParsed && parentRefSet === null),
+        strategyOpts: {
+          // nested documents should dereference all their source descriptions
+          // (parent's name filter doesn't apply to nested documents)
+          // set at strategy-specific level to override any inherited filters
+          [ctx.strategyName]: {
+            sourceDescriptions: true,
+            sourceDescriptionsDepth: ctx.currentDepth + 1,
+            sourceDescriptionsAncestors: ctx.ancestors,
+            sourceDescriptionsDereferenced: ctx.dereferenced
+          }
+        }
+      }
+    }));
+
     // merge dereferenced result into our parse result
     for (const item of sourceDescriptionDereferenced) {
       parseResult.push(item);
@@ -121,6 +137,13 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     annotation.classes.push('error');
     parseResult.push(annotation);
     return parseResult;
+  } finally {
+    // report documents reached through the source description to the caller-supplied refSet,
+    // even when dereferencing it failed
+    if (parentRefSet !== null && refSet !== null) {
+      parentRefSet.merge(refSet);
+      parentRefSet.circular ||= refSet.circular;
+    }
   }
 
   // register dereferenced document for later references to it

package/src/dereference/strategies/arazzo-1/source-descriptions.mjs

@@ -1,9 +1,13 @@
 import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, isParseResultElement } from '@speclynx/apidom-datamodel';
 import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
 import { toValue } from '@speclynx/apidom-core';
+import { assocPath } from 'ramda';
 import * as url from "../../../util/url.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
-import dereference, { dereferenceApiDOM } from "../../index.mjs";
+import parse from "../../../parse/index.mjs";
+import { dereferenceApiDOM } from "../../index.mjs";
 import { arazzoDocumentURIs, resolveArazzo$selfField, validateSourceDescriptionAPI } from "./util.mjs";
 /**
  * Dereferences a single source description element.
@@ -56,53 +60,64 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
   const existingParseResult = sourceDescription.meta.get('parseResult');
+  const parentRefSet = ctx.options.dereference.refSet;
+  let refSet = null;
   try {
-    let sourceDescriptionDereferenced;
-    if (isParseResultElement(existingParseResult)) {
-      // use existing parsed result - just dereference it (no re-fetch/re-parse)
-      sourceDescriptionDereferenced = await dereferenceApiDOM(existingParseResult, mergeOptions(ctx.options, {
-        parse: {
-          mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
-        },
-        resolve: {
-          baseURI: retrievalURI
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsAncestors: ctx.ancestors,
-              sourceDescriptionsDereferenced: ctx.dereferenced
-            }
-          }
-        }
-      }));
+    // source description document comes from, in order of preference:
+    // caller-supplied refSet, parse phase, or is fetched and parsed now
+    const cachedReference = parentRefSet?.find(ref => ref.uri === retrievalURI);
+    let sourceDescriptionParseResult;
+    let isFreshlyParsed = false;
+    if (cachedReference !== undefined) {
+      sourceDescriptionParseResult = cachedReference.value;
+    } else if (isParseResultElement(existingParseResult)) {
+      sourceDescriptionParseResult = existingParseResult;
     } else {
-      // no existing parse result - fetch, parse, and dereference
-      sourceDescriptionDereferenced = await dereference(retrievalURI, mergeOptions(ctx.options, {
+      sourceDescriptionParseResult = await parse(retrievalURI, mergeOptions(ctx.options, {
         parse: {
-          mediaType: 'text/plain' // allow parser plugin detection
-        },
-        dereference: {
-          strategyOpts: {
-            // nested documents should dereference all their source descriptions
-            // (parent's name filter doesn't apply to nested documents)
-            // set at strategy-specific level to override any inherited filters
-            [ctx.strategyName]: {
-              sourceDescriptions: true,
-              sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsAncestors: ctx.ancestors,
-              sourceDescriptionsDereferenced: ctx.dereferenced
-            }
-          }
-        }
+          mediaType: 'text/plain'
+        } // allow parser plugin detection
       }));
+      isFreshlyParsed = true;
     }
 
+    // caller-supplied refSet is rooted at the entry document, but strategies dereference
+    // the root of the refSet; re-root its references at the source description
+    if (parentRefSet !== null) {
+      refSet = new ReferenceSet({
+        refs: [new Reference({
+          uri: retrievalURI,
+          value: sourceDescriptionParseResult
+        }), ...parentRefSet.refs.map(ref => new Reference({
+          ...ref,
+          refSet: undefined
+        }))]
+      });
+    }
+    const sourceDescriptionDereferenced = await dereferenceApiDOM(sourceDescriptionParseResult, mergeOptions(assocPath(['dereference', 'refSet'], refSet, ctx.options), {
+      parse: {
+        mediaType: 'text/plain' // allow dereference strategy detection via ApiDOM inspection
+      },
+      resolve: {
+        baseURI: retrievalURI
+      },
+      dereference: {
+        // freshly parsed document not reported to any refSet can be dereferenced in mutable mode
+        immutable: ctx.options.dereference.immutable && !(isFreshlyParsed && parentRefSet === null),
+        strategyOpts: {
+          // nested documents should dereference all their source descriptions
+          // (parent's name filter doesn't apply to nested documents)
+          // set at strategy-specific level to override any inherited filters
+          [ctx.strategyName]: {
+            sourceDescriptions: true,
+            sourceDescriptionsDepth: ctx.currentDepth + 1,
+            sourceDescriptionsAncestors: ctx.ancestors,
+            sourceDescriptionsDereferenced: ctx.dereferenced
+          }
+        }
+      }
+    }));
+
     // merge dereferenced result into our parse result
     for (const item of sourceDescriptionDereferenced) {
       parseResult.push(item);
@@ -114,6 +129,13 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     annotation.classes.push('error');
     parseResult.push(annotation);
     return parseResult;
+  } finally {
+    // report documents reached through the source description to the caller-supplied refSet,
+    // even when dereferencing it failed
+    if (parentRefSet !== null && refSet !== null) {
+      parentRefSet.merge(refSet);
+      parentRefSet.circular ||= refSet.circular;
+    }
   }
 
   // register dereferenced document for later references to it

package/src/dereference/strategies/arazzo-1/util.cjs

@@ -17,6 +17,12 @@ Object.defineProperty(exports, "resolveSchema$refField", {
     return _util.resolveSchema$refField;
   }
 });
+Object.defineProperty(exports, "resolveSchemaBaseURI", {
+  enumerable: true,
+  get: function () {
+    return _util.resolveSchemaBaseURI;
+  }
+});
 exports.validateSourceDescriptionAPI = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");

package/src/dereference/strategies/arazzo-1/util.mjs

@@ -5,7 +5,7 @@ import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
 import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
 import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
 import * as url from "../../../util/url.mjs";
-export { resolveSchema$refField, resolveSchema$idField } from "../openapi-3-1/util.mjs";
+export { resolveSchema$refField, resolveSchema$idField, resolveSchemaBaseURI } from "../openapi-3-1/util.mjs";
 /**
  * Computes the base URI of an Arazzo document per Arazzo 1.1.0 rules.
  *

package/src/dereference/strategies/arazzo-1/visitor.cjs

@@ -16,6 +16,7 @@ var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _arazzoRuntimeExpression = require("@swaggerexpert/arazzo-runtime-expression");
 var _$anchor = require("./selectors/$anchor.cjs");
 var _uri = require("./selectors/uri.cjs");
+var _jsonPointer = require("../openapi-3-1/selectors/json-pointer.cjs");
 var _util = require("../openapi-3-1/util.cjs");
 var _util2 = require("./util.cjs");
 var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
@@ -45,8 +46,23 @@ class Arazzo1DereferenceVisitor {
    */
   baseURI;
   options;
+
+  /**
+   * Index of `$id`-bearing schemas per document, shared across nested visitors
+   * of a single dereference run so it never outlives mutations of the documents.
+   */
+  schema$idIndex;
   visited;
 
+  /**
+   * `$id`s of the JSON Schema elements enclosing the traversal root within its
+   * document (outermost first). Empty when the root is the document itself; a
+   * nested visitor traversing a fragment is seeded with the `$id`s of the
+   * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
+   * against the same base as they would from the document root.
+   */
+  ancestorSchema$ids;
+
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
    * Used for cycle detection: if a referenced element is found in
@@ -57,15 +73,19 @@ class Arazzo1DereferenceVisitor {
     reference,
     options,
     indirections = [],
+    schema$idIndex = new WeakMap(),
     ancestors = new _util3.AncestorLineage(),
-    visited = new WeakSet()
+    visited = new WeakSet(),
+    ancestorSchema$ids = []
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.baseURI = (0, _util2.resolveArazzo$selfField)(reference.uri, reference.value?.result);
     this.options = options;
+    this.schema$idIndex = schema$idIndex;
     this.ancestors = new _util3.AncestorLineage(...ancestors);
     this.visited = visited;
+    this.ancestorSchema$ids = ancestorSchema$ids;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -232,34 +252,38 @@ class Arazzo1DereferenceVisitor {
       return;
     }
     const runtimeExpression = (0, _apidomCore.toValue)(referencingElement.reference);
-
-    // parse the runtime expression
-    const {
-      result,
-      tree
-    } = (0, _arazzoRuntimeExpression.parse)(runtimeExpression);
-    if (!result.success) {
-      throw new _apidomError.ApiDOMStructuredError(`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
-        runtimeExpression
-      });
-    }
-
-    // ReusableElement can only reference components
-    if (tree.type !== 'ComponentsExpression') {
-      throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
-        runtimeExpression
-      });
-    }
-
-    // evaluate runtime expression as JSON Pointer to get the referenced element
-    const jsonPointer = (0, _apidomJsonPointer.compile)(['components', tree.componentType, tree.componentName]);
     let referencedElement;
     try {
-      referencedElement = (0, _apidomJsonPointer.evaluate)(this.reference.value.result, jsonPointer);
-    } catch {
-      throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" cannot be resolved`, {
-        runtimeExpression
-      });
+      // parse the runtime expression
+      const {
+        result,
+        tree
+      } = (0, _arazzoRuntimeExpression.parse)(runtimeExpression);
+      if (!result.success) {
+        throw new _apidomError.ApiDOMStructuredError(`Invalid Reusable Object reference format: "${runtimeExpression}"`, {
+          runtimeExpression
+        });
+      }
+
+      // ReusableElement can only reference components
+      if (tree.type !== 'ComponentsExpression') {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" must be a components expression`, {
+          runtimeExpression
+        });
+      }
+
+      // evaluate runtime expression as JSON Pointer to get the referenced element
+      const jsonPointer = (0, _apidomJsonPointer.compile)(['components', tree.componentType, tree.componentName]);
+      try {
+        referencedElement = (0, _apidomJsonPointer.evaluate)(this.reference.value.result, jsonPointer);
+      } catch {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Object reference "${runtimeExpression}" cannot be resolved`, {
+          runtimeExpression
+        });
+      }
+    } catch (error) {
+      this.handleError(`Error while dereferencing Reusable Object. Cannot resolve reference "${runtimeExpression}": ${error.message}`, error, referencingElement, 'reference', runtimeExpression, path);
+      return;
     }
 
     /**
@@ -307,7 +331,11 @@ class Arazzo1DereferenceVisitor {
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(this.baseURI, referencingElement);
+      // base URI in effect at the traversal root: the document base refined by
+      // the $ids of the schemas enclosing the root when the root is a fragment
+      const rootBaseURI = (0, _util.resolveSchema$ids)(this.baseURI, this.ancestorSchema$ids);
+      const schemaBaseURI = (0, _util.resolveSchemaBaseURI)(rootBaseURI, path);
+      const $refBaseURI = (0, _util.resolveSchema$refField)(schemaBaseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new _File.default({
         uri: $refBaseURIStrippedHash
@@ -319,13 +347,32 @@ class Arazzo1DereferenceVisitor {
 
       // determining reference, proper evaluation and selection mechanism
       let referencedElement;
+      // $ids of the schemas enclosing the referenced element within its document
+      let ancestorSchema$ids;
       try {
         if (isUnknownURI || isURL) {
           // we're dealing with canonical URI or URL with possible fragment
           retrievalURI = this.toBaseURI($refBaseURI);
           const selector = $refBaseURI;
-          const referenceAsSchema = (0, _util2.maybeRefractToJSONSchemaElement)(reference.value.result);
-          referencedElement = (0, _uri.evaluate)(selector, referenceAsSchema);
+          const documentElement = reference.value.result;
+          const referenceAsSchema = (0, _util2.maybeRefractToJSONSchemaElement)(documentElement);
+          // a document that is itself a fragment detached from its source carries
+          // the $ids enclosing it only as `ancestorSchema$ids`: its $ids are then
+          // indexed against the base that chain leaves in effect, and the chain
+          // prefixes the one of the located schema. A nested visitor rooted at a
+          // fragment of a whole document indexes that document against its own base.
+          const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+          const isDocumentRoot = ((0, _apidomDatamodel.isParseResultElement)(rootNode) ? rootNode.result : rootNode) === documentElement;
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = (0, _uri.locate)(selector, referenceAsSchema, {
+            baseURI: isDocumentRoot ? rootBaseURI : this.baseURI,
+            index: this.schema$idIndex
+          }));
+          if (isDocumentRoot) {
+            ancestorSchema$ids = [...this.ancestorSchema$ids, ...ancestorSchema$ids];
+          }
           referencedElement = (0, _util2.maybeRefractToJSONSchemaElement)(referencedElement);
 
           // ignore resolving internal Schema Objects
@@ -357,7 +404,10 @@ class Arazzo1DereferenceVisitor {
           reference = await this.toReference(url.unsanitize($refBaseURI));
           const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
           const referenceAsSchema = (0, _util2.maybeRefractToJSONSchemaElement)(reference.value.result);
-          referencedElement = (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = (0, _jsonPointer.locate)(referenceAsSchema, selector));
           referencedElement = (0, _util2.maybeRefractToJSONSchemaElement)(referencedElement);
         }
       } catch (error) {
@@ -384,7 +434,10 @@ class Arazzo1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = (0, _$anchor.uriToAnchor)($refBaseURI);
             const referenceAsSchema = (0, _util2.maybeRefractToJSONSchemaElement)(reference.value.result);
-            referencedElement = (0, _$anchor.evaluate)(selector, referenceAsSchema);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = (0, _$anchor.locate)(selector, referenceAsSchema));
             referencedElement = (0, _util2.maybeRefractToJSONSchemaElement)(referencedElement);
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
@@ -405,7 +458,10 @@ class Arazzo1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
             const referenceAsSchema = (0, _util2.maybeRefractToJSONSchemaElement)(reference.value.result);
-            referencedElement = (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = (0, _jsonPointer.locate)(referenceAsSchema, selector));
             referencedElement = (0, _util2.maybeRefractToJSONSchemaElement)(referencedElement);
           }
         } else {
@@ -462,7 +518,11 @@ class Arazzo1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsArazzo.isJSONSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+      // content transplanted into the referencing site is traversed under that
+      // site's $id chain; a fragment enclosed by a different chain has its own
+      // $refs resolved in place first, by a nested visitor seeded with that chain
+      const hasDifferentEnclosingBase = (0, _util.resolveSchema$ids)((0, _util2.resolveArazzo$selfField)(reference.uri, reference.value.result), ancestorSchema$ids) !== (0, _util.resolveSchema$ids)(rootBaseURI, (0, _util.schema$idsOf)(path.getAncestorNodes().reverse()));
+      if ((isExternalReference || isNonEntryDocument || hasDifferentEnclosingBase || (0, _apidomNsArazzo.isJSONSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
         if (shouldDetectCircular) {
           this.visited.add(referencedElement);
         }
@@ -473,8 +533,10 @@ class Arazzo1DereferenceVisitor {
           reference,
           indirections: [...this.indirections],
           options: this.options,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
-          ancestors: ancestorsLineage
+          ancestors: ancestorsLineage,
+          ancestorSchema$ids
         });
         referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
           mutable: true,