@bldrs-ai/conway 1.373.1180 → 1.375.1183

package/compiled/examples/cli-bundled.cjs

@@ -18570,6 +18570,240 @@ var EntityTypesIfc;
 var EntityTypesIfcCount = 909;
 var entity_types_ifc_gen_default = EntityTypesIfc;
 
+// compiled/src/step/step_buffer_provider.js
+var DEFAULT_CHUNK_BYTES = 4 * 1024 * 1024;
+var DEFAULT_MAX_RESIDENT_CHUNKS = 16;
+var STEP_BUFFER_BASE = Symbol("stepBufferBase");
+function stepBufferBase(buffer) {
+  return buffer[STEP_BUFFER_BASE] ?? 0;
+}
+function tagBufferBase(buffer, base) {
+  if (base !== 0) {
+    Object.defineProperty(buffer, STEP_BUFFER_BASE, { value: base });
+  }
+  return buffer;
+}
+var StepBufferNotResidentError = class extends Error {
+  /**
+   * Construct this for a byte range.
+   *
+   * @param address Absolute start of the range.
+   * @param length Length of the range.
+   */
+  constructor(address, length) {
+    super(`STEP source range [${address}, ${address + length}) is not resident \u2014 call ensureResident before synchronous extraction`);
+    this.address = address;
+    this.length = length;
+    this.name = "StepBufferNotResidentError";
+  }
+};
+var ResidentStepBufferProvider = class {
+  /**
+   * Construct this over the resident source buffer.
+   *
+   * @param buffer_ The full source bytes.
+   */
+  constructor(buffer_) {
+    this.buffer_ = buffer_;
+  }
+  /**
+   * Total logical size of the source bytes.
+   *
+   * @return {number} The byte length.
+   */
+  get byteLength() {
+    return this.buffer_.byteLength;
+  }
+  /**
+   * Bytes currently held resident — the whole buffer.
+   *
+   * @return {number} The byte length.
+   */
+  get residentBytes() {
+    return this.buffer_.byteLength;
+  }
+  /**
+   * Acquire the whole buffer at offset 0.
+   *
+   * @return {StepBufferAcquisition} The acquisition.
+   */
+  acquire() {
+    return { buffer: this.buffer_, offset: 0 };
+  }
+  /**
+   * Always resident.
+   *
+   * @return {Promise< void >} Resolved promise.
+   */
+  ensureResident() {
+    return Promise.resolve();
+  }
+};
+var WindowedStepBufferProvider = class {
+  /**
+   * Construct this over an external byte store.
+   *
+   * @param store_ The store holding the source bytes.
+   * @param chunkBytes Chunk size in bytes (default 4MiB).
+   * @param maxResidentChunks LRU residency cap in chunks (default 16).
+   */
+  constructor(store_, chunkBytes = DEFAULT_CHUNK_BYTES, maxResidentChunks = DEFAULT_MAX_RESIDENT_CHUNKS) {
+    this.store_ = store_;
+    this.chunks_ = /* @__PURE__ */ new Map();
+    this.loading_ = /* @__PURE__ */ new Map();
+    this.ensurePins_ = /* @__PURE__ */ new Map();
+    if (chunkBytes <= 0 || !Number.isInteger(chunkBytes)) {
+      throw new Error(`Invalid chunkBytes ${chunkBytes}`);
+    }
+    this.chunkBytes_ = chunkBytes;
+    this.maxResidentChunks_ = Math.max(1, maxResidentChunks);
+  }
+  /**
+   * Total logical size of the source bytes.
+   *
+   * @return {number} The byte length.
+   */
+  get byteLength() {
+    return this.store_.byteLength;
+  }
+  /**
+   * Bytes currently held resident by the provider.
+   *
+   * @return {number} The resident byte count.
+   */
+  get residentBytes() {
+    let total = 0;
+    for (const chunk of this.chunks_.values()) {
+      total += chunk.byteLength;
+    }
+    return total;
+  }
+  /**
+   * Number of resident chunks (telemetry/tests).
+   *
+   * @return {number} The chunk count.
+   */
+  get residentChunkCount() {
+    return this.chunks_.size;
+  }
+  /**
+   * Touch a chunk for LRU recency.
+   *
+   * @param chunkIndex The chunk to touch.
+   * @param chunk The chunk bytes.
+   */
+  touch_(chunkIndex, chunk) {
+    this.chunks_.delete(chunkIndex);
+    this.chunks_.set(chunkIndex, chunk);
+  }
+  /**
+   * Synchronously acquire a view containing a byte range.
+   *
+   * Single-chunk ranges are served as the chunk itself (zero copy);
+   * straddling ranges get a standalone merged copy spanning exactly
+   * the requested range.
+   *
+   * @param address Absolute start of the range.
+   * @param length Length of the range.
+   * @throws { StepBufferNotResidentError } When any covering chunk isn't resident.
+   * @return {StepBufferAcquisition} The view and its base address.
+   */
+  acquire(address, length) {
+    const chunkBytes = this.chunkBytes_;
+    const firstChunk = Math.floor(address / chunkBytes);
+    const lastChunk = Math.floor((address + Math.max(length, 1) - 1) / chunkBytes);
+    if (firstChunk === lastChunk) {
+      const chunk = this.chunks_.get(firstChunk);
+      if (chunk === void 0) {
+        throw new StepBufferNotResidentError(address, length);
+      }
+      this.touch_(firstChunk, chunk);
+      return { buffer: chunk, offset: firstChunk * chunkBytes };
+    }
+    const merged = tagBufferBase(new Uint8Array(length), address);
+    for (let chunkIndex = firstChunk; chunkIndex <= lastChunk; ++chunkIndex) {
+      const chunk = this.chunks_.get(chunkIndex);
+      if (chunk === void 0) {
+        throw new StepBufferNotResidentError(address, length);
+      }
+      this.touch_(chunkIndex, chunk);
+      const chunkBase = chunkIndex * chunkBytes;
+      const copyFrom = Math.max(address, chunkBase);
+      const copyTo = Math.min(address + length, chunkBase + chunk.byteLength);
+      if (copyTo > copyFrom) {
+        merged.set(chunk.subarray(copyFrom - chunkBase, copyTo - chunkBase), copyFrom - address);
+      }
+    }
+    return { buffer: merged, offset: address };
+  }
+  /**
+   * Make a byte range resident, paging missing chunks from the store
+   * and evicting least-recently-used chunks beyond the cap (never the
+   * chunks needed by this call).
+   *
+   * @param address Absolute start of the range.
+   * @param length Length of the range.
+   * @return {Promise< void >} Resolves when resident.
+   */
+  async ensureResident(address, length) {
+    const chunkBytes = this.chunkBytes_;
+    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);
+    }
+    try {
+      const loads = [];
+      for (let chunkIndex = firstChunk; chunkIndex <= lastChunk; ++chunkIndex) {
+        const resident = this.chunks_.get(chunkIndex);
+        if (resident !== void 0) {
+          this.touch_(chunkIndex, resident);
+          continue;
+        }
+        let inflight = this.loading_.get(chunkIndex);
+        if (inflight === void 0) {
+          const chunkBase = chunkIndex * chunkBytes;
+          const chunkLength = Math.min(chunkBytes, this.store_.byteLength - chunkBase);
+          inflight = this.store_.read(chunkBase, chunkLength).then((chunk) => {
+            tagBufferBase(chunk, chunkBase);
+            this.chunks_.set(chunkIndex, chunk);
+            this.loading_.delete(chunkIndex);
+            return chunk;
+          }, (error) => {
+            this.loading_.delete(chunkIndex);
+            throw error;
+          });
+          this.loading_.set(chunkIndex, inflight);
+        }
+        loads.push(inflight.then(() => void 0));
+      }
+      if (loads.length > 0) {
+        await Promise.all(loads);
+      }
+      if (this.chunks_.size > this.maxResidentChunks_) {
+        for (const candidate of this.chunks_.keys()) {
+          if (this.chunks_.size <= this.maxResidentChunks_) {
+            break;
+          }
+          if ((this.ensurePins_.get(candidate) ?? 0) > 0) {
+            continue;
+          }
+          this.chunks_.delete(candidate);
+        }
+      }
+    } 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);
+        }
+      }
+    }
+  }
+};
+
 // compiled/src/step/parsing/step_vtable_builder.js
 var StepVtableBuilder = class {
   /**
@@ -19010,6 +19244,7 @@ var StepModelBase = class {
     this.descriptorCache_ = [];
     this.elementMemoization = true;
     this.nullOnErrors = true;
+    this.bufferProvider_ = new ResidentStepBufferProvider(buffer_);
     const localElementIndex = elementIndex;
     let where = 0;
     const firstInlineElement = localElementIndex.length;
@@ -19125,6 +19360,16 @@ var StepModelBase = class {
           item.vtable = void 0;
           item.vtableCount = void 0;
           item.vtableIndex = void 0;
+          item.multiEntity = void 0;
+          if (item.multiMapping !== void 0) {
+            for (const mapped of item.multiMapping) {
+              mapped.buffer = void 0;
+              mapped.entity = void 0;
+              mapped.vtable = void 0;
+              mapped.vtableCount = void 0;
+              mapped.vtableIndex = void 0;
+            }
+          }
         }
       }
     } else {
@@ -19150,14 +19395,16 @@ var StepModelBase = class {
     if (element.vtableIndex !== void 0 || element.typeID === 0) {
       return true;
     }
-    const extratedEntry = this.schema.parser.extractDataEntry(this.buffer_, element.address, element.address + element.length, this.vtableBuilder_);
+    const acquisition = this.bufferProvider_.acquire(element.address, element.length);
+    const viewAddress = element.address - acquisition.offset;
+    const extratedEntry = this.schema.parser.extractDataEntry(acquisition.buffer, viewAddress, viewAddress + element.length, this.vtableBuilder_);
     if (extratedEntry === void 0) {
       return false;
     }
     element.vtableIndex = extratedEntry[0];
     element.vtableCount = extratedEntry[1];
     element.endCursor = extratedEntry[2];
-    element.buffer = this.buffer_;
+    element.buffer = acquisition.buffer;
     element.vtable = this.vtableBuilder_.buffer;
     return true;
   }
@@ -19174,19 +19421,7 @@ var StepModelBase = class {
       throw new Error(`Invalid localID ${localID}`);
     }
     const element = this.entry(localID);
-    if (element.vtableIndex !== void 0 || element.typeID === 0) {
-      return true;
-    }
-    const extratedEntry = this.schema.parser.extractDataEntry(this.buffer_, element.address, element.address + element.length, this.vtableBuilder_);
-    if (extratedEntry === void 0) {
-      return false;
-    }
-    element.vtableIndex = extratedEntry[0];
-    element.vtableCount = extratedEntry[1];
-    element.endCursor = extratedEntry[2];
-    element.buffer = this.buffer_;
-    element.vtable = this.vtableBuilder_.buffer;
-    return true;
+    return this.populateVtableEntryRaw(element);
   }
   /**
    * Force the population of the the buffer entry for a particular element.
@@ -19199,7 +19434,7 @@ var StepModelBase = class {
       throw new Error(`Invalid localID ${localID}`);
     }
     const element = this.entry(localID);
-    element.buffer = this.buffer_;
+    element.buffer = this.bufferProvider_.acquire(element.address, element.length).buffer;
   }
   /**
    * Get the size in bytes of the backing buffer for this.
@@ -19207,7 +19442,99 @@ var StepModelBase = class {
    * @return {number} The number of elements.
    */
   get bufferBytesize() {
-    return this.buffer_.byteLength;
+    return this.bufferProvider_.byteLength;
+  }
+  /**
+   * Are the source bytes held externally (spilled), i.e. windowed in
+   * on demand rather than fully resident?
+   *
+   * @return {boolean} True after a successful `spillSourceToExternalStore`.
+   */
+  get isSourceExternal() {
+    return this.buffer_ === void 0;
+  }
+  /**
+   * Bytes of source currently held resident by the buffer provider
+   * (the whole buffer before a spill; the windowed working set after).
+   *
+   * @return {number} The resident byte count.
+   */
+  get residentSourceBytes() {
+    return this.bufferProvider_.residentBytes;
+  }
+  /**
+   * Release the resident source buffer and serve subsequent record
+   * reads from fixed-size windows paged in from an external store.
+   *
+   * The store must contain EXACTLY the model's source bytes (same
+   * length; byte-identical content is the caller's responsibility —
+   * typically the original file already sitting in OPFS). All cached
+   * descriptors/entities are invalidated, since they hold views over
+   * the released buffer; they rematerialise on demand through the
+   * windowed provider.
+   *
+   * After this, synchronous extraction of a record whose range isn't
+   * resident throws StepBufferNotResidentError — async API surfaces
+   * must call `ensureResidentByExpressID` / `ensureResidentByLocalID`
+   * first. Parse and geometry extraction always run before any spill,
+   * so those paths are unaffected.
+   *
+   * @param store The external store holding the source bytes.
+   * @param chunkBytes Optional window size in bytes.
+   * @param maxResidentChunks Optional residency cap in windows.
+   */
+  spillSourceToExternalStore(store, chunkBytes, maxResidentChunks) {
+    if (store.byteLength !== this.bufferProvider_.byteLength) {
+      throw new Error(`External store byteLength ${store.byteLength} does not match source byteLength ${this.bufferProvider_.byteLength}`);
+    }
+    this.bufferProvider_ = new WindowedStepBufferProvider(store, chunkBytes, maxResidentChunks);
+    this.buffer_ = void 0;
+    this.invalidate(true);
+  }
+  /**
+   * Page in the byte range(s) backing a record so following
+   * synchronous extraction of it succeeds. Covers the record's own
+   * range (which contains any inline elements) and, for complex /
+   * external-mapped records, each mapped class record's range.
+   *
+   * No-op (fast resolved promise) while the source is fully resident.
+   *
+   * @param localID The local ID of the record.
+   * @return {Promise< void >} Resolves when resident.
+   */
+  async ensureResidentByLocalID(localID) {
+    if (!this.isSourceExternal) {
+      return;
+    }
+    if (localID >= this.count_) {
+      throw new Error(`Invalid localID ${localID}`);
+    }
+    await this.bufferProvider_.ensureResident(this.address_[localID], this.length_[localID]);
+    const complex = this.complexEntries_?.get(localID);
+    if (complex?.multiMapping !== void 0) {
+      for (const mapped of complex.multiMapping) {
+        await this.bufferProvider_.ensureResident(mapped.address, mapped.length);
+      }
+    }
+  }
+  /**
+   * Page in the byte range(s) backing a record by express ID — see
+   * `ensureResidentByLocalID`. Unknown express IDs resolve silently
+   * (the following read will surface the miss the same way it does
+   * for a fully-resident model).
+   *
+   * @param expressID The express ID of the record.
+   * @return {Promise< void >} Resolves when resident.
+   */
+  async ensureResidentByExpressID(expressID) {
+    if (!this.isSourceExternal) {
+      return;
+    }
+    const localID = this.expressIDMap_.get(expressID);
+    if (localID === void 0) {
+      return;
+    }
+    await this.ensureResidentByLocalID(localID);
   }
   /**
    * Get the number of elements/entities in this model.
@@ -24145,6 +24472,10 @@ var IfcTokenType;
   IfcTokenType2[IfcTokenType2["SET_END"] = 8] = "SET_END";
   IfcTokenType2[IfcTokenType2["LINE_END"] = 9] = "LINE_END";
 })(IfcTokenType || (IfcTokenType = {}));
+function extractInlineElementAddress(buffer, cursor, endCursor) {
+  const relative = stepExtractInlineElemement(buffer, cursor, endCursor);
+  return relative === void 0 ? void 0 : relative + stepBufferBase(buffer);
+}
 function merge(to, from) {
   for (const key of Object.keys(from)) {
     if (!to.hasOwnProperty(key)) {
@@ -24262,8 +24593,7 @@ var StepEntityBase = class {
       if (!optional) {
         throw new Error("Value in STEP was incorrectly typed");
       }
-      const buffer2 = this.buffer;
-      if (!this.model.nullOnErrors && stepExtractOptional(buffer2, cursor, endCursor) !== null) {
+      if (!this.model.nullOnErrors && stepExtractOptional(buffer, cursor, endCursor) !== null) {
         throw new Error("Value in STEP was incorrectly typed");
       }
       return null;
@@ -24299,11 +24629,9 @@ var StepEntityBase = class {
     return value;
   }
   extractReference(offset, baseOffset, depth, optional) {
-    const cursor = this.getOffsetCursor(offset, baseOffset, depth);
-    const buffer = this.buffer;
-    const endCursor = buffer.length;
+    const [cursor, endCursor, buffer] = this.getOffsetAndEndCursor(offset, baseOffset, depth);
     const expressID = stepExtractReference(buffer, cursor, endCursor);
-    const value = expressID !== void 0 ? this.model.getElementByExpressID(expressID) : this.model.getInlineElementByAddress(stepExtractInlineElemement(buffer, cursor, endCursor));
+    const value = expressID !== void 0 ? this.model.getElementByExpressID(expressID) : this.model.getInlineElementByAddress(extractInlineElementAddress(buffer, cursor, endCursor));
     if (value === void 0) {
       if (!optional) {
         throw new Error("Value in STEP was incorrectly typed");
@@ -24365,8 +24693,8 @@ var StepEntityBase = class {
   extractLineArguments() {
     this.guaranteeBuffer();
     const internalReference = this.internalReference_;
-    const cursor = internalReference.address;
     const buffer = internalReference.buffer;
+    const cursor = internalReference.address - stepBufferBase(buffer);
     const endCursor = cursor + internalReference.length;
     const subArray = buffer.subarray(cursor, endCursor);
     return subArray;
@@ -24381,7 +24709,7 @@ var StepEntityBase = class {
    */
   extractBufferReference(buffer, cursor, endCursor) {
     const expressID = stepExtractReference(buffer, cursor, endCursor);
-    const value = expressID !== void 0 ? this.model.getElementByExpressID(expressID) : this.model.getInlineElementByAddress(stepExtractInlineElemement(buffer, cursor, endCursor));
+    const value = expressID !== void 0 ? this.model.getElementByExpressID(expressID) : this.model.getInlineElementByAddress(extractInlineElementAddress(buffer, cursor, endCursor));
     return value;
   }
   /**
@@ -24452,7 +24780,7 @@ var StepEntityBase = class {
     const [cursor, endCursor, buffer] = this.getOffsetAndEndCursor(offset, baseOffset, depth);
     const model = this.model;
     const expressID = stepExtractReference(buffer, cursor, endCursor);
-    const value = expressID !== void 0 ? model.getTypedElementByExpressID(expressID, entityConstructor) : model.getTypedInlineElementByAddress(stepExtractInlineElemement(buffer, cursor, endCursor), entityConstructor);
+    const value = expressID !== void 0 ? model.getTypedElementByExpressID(expressID, entityConstructor) : model.getTypedInlineElementByAddress(extractInlineElementAddress(buffer, cursor, endCursor), entityConstructor);
     if (value === void 0) {
       if (!optional) {
         throw new Error("Value in STEP was incorrectly typed");
@@ -24481,7 +24809,7 @@ var StepEntityBase = class {
   extractBufferElement(buffer, cursor, endCursor, entityConstructor) {
     const model = this.model;
     const expressID = stepExtractReference(buffer, cursor, endCursor);
-    const value = expressID !== void 0 ? model.getTypedElementByExpressID(expressID, entityConstructor) : model.getTypedInlineElementByAddress(stepExtractInlineElemement(buffer, cursor, endCursor), entityConstructor);
+    const value = expressID !== void 0 ? model.getTypedElementByExpressID(expressID, entityConstructor) : model.getTypedInlineElementByAddress(extractInlineElementAddress(buffer, cursor, endCursor), entityConstructor);
     if (value === void 0) {
       return;
     }
@@ -24524,7 +24852,7 @@ var StepEntityBase = class {
     if (offset >= internalReference.vtableCount) {
       throw new Error("Couldn't read field due to too few fields in record");
     }
-    const buffer = this.buffer;
+    const buffer = internalReference.buffer;
     const vtableSlot = internalReference.vtableIndex + offset;
     const cursor = internalReference.vtable[vtableSlot];
     const nextSlot = vtableSlot + 1;
@@ -24660,8 +24988,8 @@ var StepEntityBase = class {
         if (!populated) {
           throw new Error("Entity does not have matching table entry to read from model");
         }
-        this.internalReference_.buffer = classReference.buffer;
       }
+      this.internalReference_.buffer = classReference.buffer;
       return classReference;
     }
     const internalReference = this.internalReference_;
@@ -85955,7 +86283,7 @@ var IfcSceneBuilder = class {
 };
 
 // compiled/src/version/version.js
-var versionString = "Conway Web-Ifc Shim v1.373.1180";
+var versionString = "Conway Web-Ifc Shim v1.375.1183";
 
 // compiled/src/statistics/statistics.js
 var Statistics = class {