@bldrs-ai/conway 1.509.1435 → 1.511.1441

package/compiled/examples/cli-bundled.cjs

@@ -14965,7 +14965,7 @@ ${t5.join("\n")}` : "";
 var import_process = require("process");
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.509.1435";
+var versionString = "Conway v1.511.1441";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {
@@ -18440,7 +18440,9 @@ var StepParser = class extends StepHeaderParser {
       if (next.done === true) {
         return next.value;
       }
-      onProgress?.(next.value);
+      if (typeof next.value === "number") {
+        onProgress?.(next.value);
+      }
     }
   }
   /**
@@ -18452,7 +18454,8 @@ var StepParser = class extends StepHeaderParser {
    *
    * @param input The input parsing buffer, positioned at the data section.
    * @param onRecordBoundary Called at each top-level record boundary with the
-   * buffer; the callback may rebase the buffer's window in place.
+   * buffer; the callback may rebase the buffer's window in place. Must be
+   * synchronous on this driver — a returned Promise is a caller bug.
    * @param onRecordIndexed Called as each top-level record is indexed, with
    * its localID, expressID and typeID (0 for external-mapping records) — the
    * seam for incremental semantic consumers (type index, roots registry,
@@ -18468,6 +18471,9 @@ var StepParser = class extends StepHeaderParser {
       if (next.done === true) {
         return next.value;
       }
+      if (typeof next.value !== "number") {
+        throw new Error("parseDataBlockStreamed: async window slide requires parseDataBlockStreamedAsync");
+      }
       onProgress?.(next.value);
     }
   }
@@ -18480,7 +18486,9 @@ var StepParser = class extends StepHeaderParser {
    *
    * @param input The input parsing buffer, positioned at the data section.
    * @param onRecordBoundary Called at each top-level record boundary with the
-   * buffer; the callback may rebase the buffer's window in place.
+   * buffer; the callback may rebase the buffer's window in place. May return
+   * a Promise when the slide itself is I/O (an async ByteSource); this
+   * driver awaits it before the next record is lexed.
    * @param onRecordIndexed Called as each top-level record is indexed — see
    * parseDataBlockStreamed.
    * @param onProgress Optional byte-cursor progress callback.
@@ -18497,6 +18505,10 @@ var StepParser = class extends StepHeaderParser {
       if (next.done === true) {
         return next.value;
       }
+      if (typeof next.value !== "number") {
+        await next.value;
+        continue;
+      }
       onProgress?.(next.value);
       if (Date.now() - lastYield >= yieldIntervalMs) {
         await yieldToEventLoop();
@@ -18524,7 +18536,9 @@ var StepParser = class extends StepHeaderParser {
       if (next.done === true) {
         return next.value;
       }
-      onProgress?.(next.value);
+      if (typeof next.value === "number") {
+        onProgress?.(next.value);
+      }
       if (Date.now() - lastYield >= yieldIntervalMs) {
         await yieldToEventLoop();
         lastYield = Date.now();
@@ -18688,7 +18702,10 @@ var StepParser = class extends StepHeaderParser {
       if ((++parsedElementCount & PARSE_PROGRESS_ELEMENT_MASK) === 0) {
         yield input.cursor;
       }
-      onRecordBoundary?.(input);
+      const slide = onRecordBoundary?.(input);
+      if (slide !== void 0 && typeof slide.then === "function") {
+        yield slide;
+      }
       if (!charws(HASH2)) {
         if (tokenws(END_SECTION)) {
           return parseResult(ParseResult.COMPLETE);
@@ -20231,6 +20248,70 @@ var EntityTypesIfc;
 var EntityTypesIfcCount = 909;
 var entity_types_ifc_gen_default = EntityTypesIfc;
 
+// compiled/src/step/parsing/express_ref_scan.js
+var HASH3 = 35;
+var QUOTE4 = 39;
+var DQUOTE = 34;
+var ZERO5 = 48;
+var NINE2 = 57;
+var SLASH3 = 47;
+var STAR2 = 42;
+function scanExpressRefs(bytes, from = 0, length = bytes.length - from) {
+  const refs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const end = Math.min(from + length, bytes.length);
+  let cursor = from;
+  while (cursor < end) {
+    const byte = bytes[cursor];
+    if (byte === QUOTE4) {
+      cursor = skipQuoted_(bytes, cursor + 1, end, QUOTE4, true);
+      continue;
+    }
+    if (byte === DQUOTE) {
+      cursor = skipQuoted_(bytes, cursor + 1, end, DQUOTE, false);
+      continue;
+    }
+    if (byte === SLASH3 && cursor + 1 < end && bytes[cursor + 1] === STAR2) {
+      cursor += 2;
+      while (cursor + 1 < end && !(bytes[cursor] === STAR2 && bytes[cursor + 1] === SLASH3)) {
+        ++cursor;
+      }
+      cursor += 2;
+      continue;
+    }
+    if (byte === HASH3) {
+      let value = 0;
+      let digit = cursor + 1;
+      while (digit < end && bytes[digit] >= ZERO5 && bytes[digit] <= NINE2) {
+        value = value * 10 + (bytes[digit] - ZERO5);
+        ++digit;
+      }
+      if (digit > cursor + 1 && value !== 0 && !seen.has(value)) {
+        seen.add(value);
+        refs.push(value);
+      }
+      cursor = digit;
+      continue;
+    }
+    ++cursor;
+  }
+  return refs;
+}
+function skipQuoted_(bytes, from, end, quote, doubledEscape) {
+  let cursor = from;
+  while (cursor < end) {
+    if (bytes[cursor] === quote) {
+      if (doubledEscape && cursor + 1 < end && bytes[cursor + 1] === quote) {
+        cursor += 2;
+        continue;
+      }
+      return cursor + 1;
+    }
+    ++cursor;
+  }
+  return end;
+}
+
 // compiled/src/step/step_buffer_provider.js
 var DEFAULT_CHUNK_BYTES = 4 * 1024 * 1024;
 var DEFAULT_MAX_RESIDENT_CHUNKS = 16;
@@ -20411,7 +20492,7 @@ var WindowedStepBufferProvider = class {
     const firstChunk = Math.floor(address / chunkBytes);
     const lastChunk = Math.floor((address + Math.max(length, 1) - 1) / chunkBytes);
     for (let chunkIndex = firstChunk; chunkIndex <= lastChunk; ++chunkIndex) {
-      this.ensurePins_.set(chunkIndex, (this.ensurePins_.get(chunkIndex) ?? 0) + 1);
+      this.addPin_(chunkIndex, 1);
     }
     try {
       const loads = [];
@@ -20454,15 +20535,63 @@ var WindowedStepBufferProvider = class {
       }
     } finally {
       for (let chunkIndex = firstChunk; chunkIndex <= lastChunk; ++chunkIndex) {
-        const pins = this.ensurePins_.get(chunkIndex) ?? 0;
-        if (pins <= 1) {
-          this.ensurePins_.delete(chunkIndex);
-        } else {
-          this.ensurePins_.set(chunkIndex, pins - 1);
-        }
+        this.addPin_(chunkIndex, -1);
       }
     }
   }
+  /**
+   * Hold a range against LRU eviction until {@link unpinRange}.
+   *
+   * @param address Absolute start of the range.
+   * @param length Length of the range.
+   */
+  pinRange(address, length) {
+    for (const chunkIndex of this.chunkSpan_(address, length)) {
+      this.addPin_(chunkIndex, 1);
+    }
+  }
+  /**
+   * Drop one {@link pinRange} hold.
+   *
+   * @param address Absolute start of the range.
+   * @param length Length of the range.
+   */
+  unpinRange(address, length) {
+    for (const chunkIndex of this.chunkSpan_(address, length)) {
+      this.addPin_(chunkIndex, -1);
+    }
+  }
+  /**
+   * Chunk indices covering `[address, address + length)`.
+   *
+   * @param address Absolute start.
+   * @param length Length in bytes.
+   * @return {number[]} Inclusive chunk indices.
+   */
+  chunkSpan_(address, length) {
+    const chunkBytes = this.chunkBytes_;
+    const firstChunk = Math.floor(address / chunkBytes);
+    const lastChunk = Math.floor((address + Math.max(length, 1) - 1) / chunkBytes);
+    const span = [];
+    for (let chunkIndex = firstChunk; chunkIndex <= lastChunk; ++chunkIndex) {
+      span.push(chunkIndex);
+    }
+    return span;
+  }
+  /**
+   * Adjust a chunk's pin count, deleting the entry at zero.
+   *
+   * @param chunkIndex The chunk.
+   * @param delta +1 pin or -1 unpin.
+   */
+  addPin_(chunkIndex, delta) {
+    const pins = (this.ensurePins_.get(chunkIndex) ?? 0) + delta;
+    if (pins <= 0) {
+      this.ensurePins_.delete(chunkIndex);
+    } else {
+      this.ensurePins_.set(chunkIndex, pins);
+    }
+  }
 };
 
 // compiled/src/step/parsing/step_vtable_builder.js
@@ -20532,7 +20661,7 @@ var StepVtableBuilder = class {
 var OPEN_PAREN3 = parsing_constants_default.OPEN_PAREN;
 var CLOSE_PAREN3 = parsing_constants_default.CLOSE_PAREN;
 var COMMA3 = parsing_constants_default.COMMA;
-var ZERO5 = parsing_constants_default.ZERO;
+var ZERO6 = parsing_constants_default.ZERO;
 var WHITESPACE4 = parsing_constants_default.WHITE_SPACE_SET;
 var Uint32Sink = class {
   /**
@@ -20648,7 +20777,7 @@ function extractUnsignedIntegerListAt(buffer, cursor, endCursor, sink) {
         return void 0;
       }
     }
-    const digit = buffer[cursor] - ZERO5;
+    const digit = buffer[cursor] - ZERO6;
     if (digit < 0 || digit > 9) {
       sink.truncate(marked);
       return void 0;
@@ -20656,7 +20785,7 @@ function extractUnsignedIntegerListAt(buffer, cursor, endCursor, sink) {
     let value = digit;
     ++cursor;
     while (cursor < endCursor) {
-      const next = buffer[cursor] - ZERO5;
+      const next = buffer[cursor] - ZERO6;
       if (next < 0 || next > 9) {
         break;
       }
@@ -21451,6 +21580,141 @@ var StepModelBase = class {
     }
     await this.ensureResidentByLocalID(localID);
   }
+  /**
+   * Page in the byte ranges a record *and every `#ref` reachable from
+   * its text* will need, so a following synchronous extract of that
+   * subgraph succeeds on a windowed source. Inverse relationships
+   * (not written in the record) are not discovered — callers that
+   * need them (rel-voids, styled items) pass their local IDs as
+   * `extraLocalIDs`.
+   *
+   * No-op while the source is fully resident.
+   *
+   * @param localID Seed record.
+   * @param extraLocalIDs Additional seeds (voids, styles, materials).
+   * @param seen Optional set to extend (also skips already-pinned IDs).
+   * @return {Promise<Set<number>>} The local IDs that were visited.
+   */
+  async ensureResidentClosureByLocalID(localID, extraLocalIDs, seen = /* @__PURE__ */ new Set()) {
+    if (!this.isSourceExternal) {
+      return seen;
+    }
+    const stack = [localID];
+    if (extraLocalIDs !== void 0) {
+      for (const extra of extraLocalIDs) {
+        stack.push(extra);
+      }
+    }
+    while (stack.length > 0) {
+      const id = stack.pop();
+      if (seen.has(id) || id >= this.count_) {
+        continue;
+      }
+      seen.add(id);
+      await this.ensureResidentByLocalID(id);
+      this.pinByLocalID(id);
+      for (const expressID of this.scanRecordRefs_(id)) {
+        const referenced = this.expressIDMap_.get(expressID);
+        if (referenced !== void 0 && !seen.has(referenced)) {
+          stack.push(referenced);
+        }
+      }
+    }
+    return seen;
+  }
+  /**
+   * Hold a record's source range against windowed LRU eviction until
+   * {@link unpinByLocalID}. No-op while the source is fully resident.
+   *
+   * @param localID The record to pin.
+   */
+  pinByLocalID(localID) {
+    if (!this.isSourceExternal || localID >= this.count_) {
+      return;
+    }
+    this.bufferProvider_.pinRange?.(this.address_[localID], this.length_[localID]);
+  }
+  /**
+   * Drop one {@link pinByLocalID} hold.
+   *
+   * @param localID The record to unpin.
+   */
+  unpinByLocalID(localID) {
+    if (!this.isSourceExternal || localID >= this.count_) {
+      return;
+    }
+    this.bufferProvider_.unpinRange?.(this.address_[localID], this.length_[localID]);
+  }
+  /**
+   * Unpin every local ID in `localIDs` (best-effort; missing IDs are
+   * ignored). Use after {@link ensureResidentClosureByLocalID}, which
+   * pins as it walks.
+   *
+   * @param localIDs The records to unpin.
+   */
+  unpinLocalIDs(localIDs) {
+    for (const localID of localIDs) {
+      this.unpinByLocalID(localID);
+    }
+  }
+  /**
+   * Express-ID twin of {@link ensureResidentClosureByLocalID}. Unknown
+   * IDs resolve to an empty visit set.
+   *
+   * @param expressID Seed record.
+   * @param extraLocalIDs Additional seeds (local IDs).
+   * @return {Promise<Set<number>>} The local IDs that were visited.
+   */
+  async ensureResidentClosureByExpressID(expressID, extraLocalIDs, seen) {
+    if (!this.isSourceExternal) {
+      return seen ?? /* @__PURE__ */ new Set();
+    }
+    const localID = this.expressIDMap_.get(expressID);
+    if (localID === void 0) {
+      return seen ?? /* @__PURE__ */ new Set();
+    }
+    return this.ensureResidentClosureByLocalID(localID, extraLocalIDs, seen);
+  }
+  /**
+   * Express IDs referenced by a resident record (`#<id>` tokens in its
+   * text, including multi-mapped class records). The record itself
+   * must already be resident.
+   *
+   * @param localID The record to scan.
+   * @return {number[]} Distinct referenced express IDs.
+   */
+  referencedExpressIDs(localID) {
+    return this.scanRecordRefs_(localID);
+  }
+  /**
+   * Scan a resident record's bytes for `#<expressID>` references.
+   *
+   * @param localID The record to scan.
+   * @return {number[]} Distinct referenced express IDs.
+   */
+  scanRecordRefs_(localID) {
+    const address = this.address_[localID];
+    const length = this.length_[localID];
+    const acquisition = this.bufferProvider_.acquire(address, length);
+    const viewStart = address - acquisition.offset;
+    const refs = scanExpressRefs(acquisition.buffer, viewStart, length);
+    const complex = this.complexEntries_?.get(localID);
+    if (complex?.multiMapping === void 0) {
+      return refs;
+    }
+    const seen = new Set(refs);
+    for (const mapped of complex.multiMapping) {
+      const mappedAcquisition = this.bufferProvider_.acquire(mapped.address, mapped.length);
+      const mappedStart = mapped.address - mappedAcquisition.offset;
+      for (const expressID of scanExpressRefs(mappedAcquisition.buffer, mappedStart, mapped.length)) {
+        if (!seen.has(expressID)) {
+          seen.add(expressID);
+          refs.push(expressID);
+        }
+      }
+    }
+    return refs;
+  }
   /**
    * Get the number of elements/entities in this model.
    *
@@ -26607,6 +26871,38 @@ var StepEntityBase = class {
     }
     return value;
   }
+  /**
+   * Resolve a single reference field to its local ID without
+   * constructing the target entity. Prep maps that only store
+   * `Item.localID` (IfcStyledItem → faceset) must not hydrate the
+   * target: on a windowed source that would pin the faceset record
+   * (often megabytes) for every styled item at once.
+   *
+   * @param offset The offset in the vtable to extract from.
+   * @param baseOffset The base offset of the class in the vtable.
+   * @param depth The depth in the inheritance hierarchy.
+   * @param optional Is this an optional field?
+   * @return {number | null} The referenced local ID, or null if the
+   * field is unset/optional-null.
+   */
+  extractReferenceLocalID(offset, baseOffset, depth, optional) {
+    const [cursor, endCursor, buffer] = this.getOffsetAndEndCursor(offset, baseOffset, depth);
+    const expressID = stepExtractReference(buffer, cursor, endCursor);
+    if (expressID !== void 0) {
+      return this.model.resolveExpressID(expressID) ?? null;
+    }
+    const inline = this.model.getInlineElementByAddress(extractInlineElementAddress(buffer, cursor, endCursor));
+    if (inline !== void 0) {
+      return inline.localID;
+    }
+    if (!optional) {
+      throw new Error("Value in STEP was incorrectly typed");
+    }
+    if (!this.model.nullOnErrors && stepExtractOptional(buffer, cursor, endCursor) !== null) {
+      throw new Error("Value in STEP was incorrectly typed");
+    }
+    return null;
+  }
   /**
    *
    * @param buffer
@@ -87347,11 +87643,88 @@ function buildIndexStreaming(source, parser210, pool3, onRecordIndexed, sink) {
   }
 }
 var MIN_WINDOW = 4 * 1024;
+async function readSource(source, offset, length, into, intoOffset) {
+  return await source.read(offset, length, into, intoOffset);
+}
+async function buildIndexStreamingAsync(source, parser210, pool3, onRecordIndexed, sink, onProgress, yieldIntervalMs) {
+  const fileSize = source.byteLength;
+  let windowBytes = Math.max(pool3, MIN_WINDOW);
+  for (; ; ) {
+    const window2 = new Uint8Array(windowBytes);
+    let windowStartFile = 0;
+    let windowLen = await readSource(source, 0, windowBytes, window2, 0);
+    let bytesRead = windowLen;
+    const input = new ParsingBuffer(window2, 0, windowLen);
+    const [header, headerResult] = parser210.parseHeader(input);
+    if (headerResult !== ParseResult.COMPLETE) {
+      return {
+        header,
+        elements: [],
+        result: headerResult,
+        stats: { pool: pool3, windowBytes, slides: 0, maxRecordLen: 0, bytesRead }
+      };
+    }
+    const slideThreshold = windowBytes >> 1;
+    let slides = 0;
+    let maxRecordLen = 0;
+    let prevBoundaryFile = windowStartFile + input.cursor;
+    const onRecordBoundary = (buffer) => {
+      const cursor = buffer.cursor;
+      const recordFileStart = windowStartFile + cursor;
+      const recordLen = recordFileStart - prevBoundaryFile;
+      if (recordLen > maxRecordLen) {
+        maxRecordLen = recordLen;
+      }
+      prevBoundaryFile = recordFileStart;
+      if (windowStartFile + windowLen >= fileSize) {
+        return;
+      }
+      if (cursor < slideThreshold) {
+        return;
+      }
+      const tail = windowLen - cursor;
+      window2.copyWithin(0, cursor, windowLen);
+      const want = windowBytes - tail;
+      const fillAt = windowStartFile + windowLen;
+      return readSource(source, fillAt, want, window2, tail).then((got) => {
+        bytesRead += got;
+        windowLen = tail + got;
+        windowStartFile = recordFileStart;
+        buffer.rebaseWindow(window2, 0, windowLen, windowStartFile);
+        ++slides;
+      });
+    };
+    const progressTick = onProgress !== void 0 ? (cursor) => onProgress(windowStartFile + cursor) : void 0;
+    const [index, result] = await parser210.parseDataBlockStreamedAsync(input, onRecordBoundary, onRecordIndexed, progressTick, sink, yieldIntervalMs);
+    const stoppedShort = result !== ParseResult.COMPLETE;
+    const notAtEof = windowStartFile + windowLen < fileSize;
+    if (stoppedShort && notAtEof) {
+      windowBytes *= 2;
+      sink?.reset();
+      continue;
+    }
+    const lastRecordLen = windowStartFile + input.cursor - prevBoundaryFile;
+    if (lastRecordLen > maxRecordLen) {
+      maxRecordLen = lastRecordLen;
+    }
+    return {
+      header,
+      elements: index.elements,
+      result,
+      stats: { pool: pool3, windowBytes, slides, maxRecordLen, bytesRead }
+    };
+  }
+}
 function buildColumnarIndexStreaming(source, parser210, pool3, onRecordIndexed) {
   const sink = new ColumnarIndexSink();
   const { header, result, stats } = buildIndexStreaming(source, parser210, pool3, onRecordIndexed, sink);
   return { header, columns: sink.finalize(), result, stats };
 }
+async function buildColumnarIndexStreamingAsync(source, parser210, pool3, onRecordIndexed, onProgress, yieldIntervalMs) {
+  const sink = new ColumnarIndexSink();
+  const { header, result, stats } = await buildIndexStreamingAsync(source, parser210, pool3, onRecordIndexed, sink, onProgress, yieldIntervalMs);
+  return { header, columns: sink.finalize(), result, stats };
+}
 
 // compiled/src/ifc/ifc_step_parser.js
 var DEFAULT_STREAM_POOL_BYTES = 1024 * 1024;
@@ -87421,6 +87794,27 @@ var IfcStepParser = class extends StepParser {
     const provider = new WindowedStepBufferProvider(store, opts?.chunkBytes, opts?.maxResidentChunks);
     return [result, new IfcStepModel(void 0, columns, provider)];
   }
+  /**
+   * Cooperative twin of {@link parseStreamToModel}: the index build
+   * yields to the event loop and can fill windows from an async
+   * {@link ReadableByteSource} (an OPFS `File.slice()` store). The
+   * model is still windowed — geometry extract must
+   * `ensureResident` first.
+   *
+   * @param source Sync or async byte source feeding the parse.
+   * @param store Async external store backing the windowed model.
+   * @param opts Optional window sizing plus parse progress.
+   * @return {Promise<[ParseResult, IfcStepModel | undefined]>} The
+   * parse result and the windowed model.
+   */
+  async parseStreamToModelAsync(source, store, opts) {
+    if (store.byteLength !== source.byteLength) {
+      throw new Error(`Streaming store byteLength ${store.byteLength} does not match source byteLength ${source.byteLength}`);
+    }
+    const { columns, result } = await buildColumnarIndexStreamingAsync(source, this, opts?.pool ?? DEFAULT_STREAM_POOL_BYTES, void 0, opts?.onProgress);
+    const provider = new WindowedStepBufferProvider(store, opts?.chunkBytes, opts?.maxResidentChunks);
+    return [result, new IfcStepModel(void 0, columns, provider)];
+  }
 };
 IfcStepParser.Instance = new IfcStepParser();
 var ifc_step_parser_default = IfcStepParser;
@@ -91946,8 +92340,9 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
     const styledItems = this.model.types(IfcStyledItem);
     for (const styledItem of styledItems) {
       try {
-        if (styledItem.Item !== null) {
-          this.materials.styledItemMap.set(styledItem.Item.localID, styledItem.localID);
+        const itemLocalID = styledItem.extractReferenceLocalID(0, 0, 1, true);
+        if (itemLocalID !== null) {
+          this.materials.styledItemMap.set(itemLocalID, styledItem.localID);
         }
       } catch (ex) {
         this.handleMapPrepError_("IfcStyledItem", styledItem.expressID, ex);
@@ -92203,6 +92598,137 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
     this.extractProductGeometry(element);
     return true;
   }
+  /**
+   * Page in every record {@link prepareDemandExtraction} will read, so
+   * the relationship sweeps succeed on a windowed source. Call before
+   * the first prepare on a model whose source is external.
+   *
+   * Pins the prep-type records themselves (and a 1-hop of product /
+   * material records the relationship getters hydrate). Does **not**
+   * BFS-pin styled-item Item closures — those are facesets, and
+   * walking them here pulled most of the file into the windowed LRU
+   * before the first product extract.
+   *
+   * @return {Promise<Set<number>>} Pinned local IDs — caller must
+   * {@link StepModelBase.unpinLocalIDs} after prepare/extract.
+   */
+  async ensureResidentForDemandPrep() {
+    const pinned = /* @__PURE__ */ new Set();
+    if (!this.model.isSourceExternal) {
+      return pinned;
+    }
+    for (const type of [IfcProject, IfcMaterialDefinitionRepresentation]) {
+      for (const expressID of this.model.expressIDsOfTypes(type)) {
+        await this.model.ensureResidentClosureByExpressID(expressID, void 0, pinned);
+      }
+    }
+    const recordOnlyTypes = [
+      IfcRelAssociatesMaterial,
+      IfcRelVoidsElement,
+      IfcStyledItem,
+      IfcRelAggregates
+    ];
+    for (const type of recordOnlyTypes) {
+      for (const expressID of this.model.expressIDsOfTypes(type)) {
+        const localID = this.model.resolveExpressID(expressID);
+        if (localID === void 0 || pinned.has(localID)) {
+          continue;
+        }
+        await this.model.ensureResidentByLocalID(localID);
+        this.model.pinByLocalID(localID);
+        pinned.add(localID);
+      }
+    }
+    const oneHopTypes = [
+      IfcRelAssociatesMaterial,
+      IfcRelVoidsElement,
+      IfcRelAggregates
+    ];
+    for (const type of oneHopTypes) {
+      for (const expressID of this.model.expressIDsOfTypes(type)) {
+        const localID = this.model.resolveExpressID(expressID);
+        if (localID === void 0) {
+          continue;
+        }
+        for (const refExpressID of this.model.referencedExpressIDs(localID)) {
+          const refLocalID = this.model.resolveExpressID(refExpressID);
+          if (refLocalID === void 0 || pinned.has(refLocalID)) {
+            continue;
+          }
+          await this.model.ensureResidentByLocalID(refLocalID);
+          this.model.pinByLocalID(refLocalID);
+          pinned.add(refLocalID);
+        }
+      }
+    }
+    return pinned;
+  }
+  /**
+   * Page in the `#ref` closure a per-product extract will acquire,
+   * including this product's voids, bound materials and styled items
+   * (those are inverse — not written in the product record).
+   *
+   * @param localID The product's local ID.
+   * @return {Promise<Set<number>>} Pinned local IDs — caller must unpin
+   * after extract.
+   */
+  async ensureResidentForProductExtract(localID, seen) {
+    if (!this.model.isSourceExternal) {
+      return seen ?? /* @__PURE__ */ new Set();
+    }
+    const extra = [];
+    const voids = this.productToVoidGeometryMap.get(localID);
+    if (voids !== void 0) {
+      extra.push(...voids);
+    }
+    const material = this.materials.relMaterialsMap.get(localID);
+    if (material !== void 0) {
+      extra.push(material);
+    }
+    const visited = await this.model.ensureResidentClosureByLocalID(localID, extra, seen);
+    const styleExtra = [];
+    for (const visitedID of visited) {
+      const styled = this.materials.styledItemMap.get(visitedID);
+      if (styled !== void 0) {
+        styleExtra.push(styled);
+      }
+      const definition = this.materials.materialDefinitionsMap.get(visitedID);
+      if (definition !== void 0) {
+        styleExtra.push(definition);
+      }
+    }
+    if (styleExtra.length > 0) {
+      await this.model.ensureResidentClosureByLocalID(localID, styleExtra, visited);
+    }
+    return visited;
+  }
+  /**
+   * Page in the records {@link extractRelAggregateGeometry} will
+   * acquire: the relationship, the relating product (and its voids)
+   * and every related product.
+   *
+   * @param relAggregate The relationship to prefetch.
+   * @return {Promise<Set<number>>} Pinned local IDs — caller must unpin
+   * after extract.
+   */
+  async ensureResidentForAggregateExtract(relAggregate) {
+    if (!this.model.isSourceExternal) {
+      return /* @__PURE__ */ new Set();
+    }
+    const pinned = await this.model.ensureResidentClosureByLocalID(relAggregate.localID);
+    const relating = relAggregate.RelatingObject;
+    if (relating !== null && relating !== void 0) {
+      await this.ensureResidentForProductExtract(relating.localID, pinned);
+    }
+    const related = relAggregate.RelatedObjects;
+    if (related === null || related === void 0) {
+      return pinned;
+    }
+    for (const product of related) {
+      await this.ensureResidentForProductExtract(product.localID, pinned);
+    }
+    return pinned;
+  }
   /**
    * The whole-model walk's SECOND product pass, shared with the demand
    * pump: for every IfcRelAggregates, re-extract the related products