@bldrs-ai/conway 1.563.1540 → 1.566.1541

package/compiled/examples/browser-bundled.cjs

@@ -30,7 +30,7 @@ var import_node_process = require("node:process");
 var readline = __toESM(require("node:readline"), 1);
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.563.1540";
+var versionString = "Conway v1.566.1541";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

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.563.1540";
+var versionString = "Conway v1.566.1541";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {
@@ -89338,6 +89338,9 @@ var FACES_FIELD_DEPTH = 4;
 var REL_AGGREGATES_RELATED_OFFSET = 5;
 var REL_AGGREGATES_RELATED_BASE = 4;
 var REL_AGGREGATES_RELATED_DEPTH = 3;
+var REL_AGGREGATES_RELATING_OFFSET = 4;
+var REL_AGGREGATES_RELATING_BASE = 4;
+var REL_AGGREGATES_RELATING_DEPTH = 3;
 var REL_ASSOCIATES_RELATED_OFFSET = 4;
 var REL_ASSOCIATES_RELATED_BASE = 4;
 var REL_ASSOCIATES_RELATED_DEPTH = 2;
@@ -94031,7 +94034,16 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
    * acquire: the relationship, the relating product (and its voids)
    * and every related product.
    *
+   * The whole relationship at once, which is what a caller that extracts
+   * it in one synchronous call needs. A caller that steps the
+   * relationship (the demand pump, through
+   * {@link extractRelAggregateGeometryIncremental}) wants
+   * {@link beginAggregateExtract} instead: this one pins every related
+   * product's closure simultaneously, which on an aggregate-structured
+   * model is the whole file (conway#561 §5).
+   *
    * @param relAggregate The relationship to prefetch.
+   * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
    * @return {Promise<Set<number>>} Pinned local IDs — caller must unpin
    * after extract.
    */
@@ -94040,11 +94052,163 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
       return /* @__PURE__ */ new Set();
     }
     const pinned = /* @__PURE__ */ new Set();
-    const hop = [];
+    await this.ensureResidentForAggregateBase(relAggregate, pinned, leafSpans);
+    const products = this.relatedAggregateProductLocalIDs(relAggregate);
+    if (products === void 0) {
+      await this.ensureResidentForRelatedObjectsByGetter(relAggregate, pinned, leafSpans);
+      return pinned;
+    }
+    await this.ensureResidentForAggregateProducts(products, 0, products.length, pinned, leafSpans);
+    return pinned;
+  }
+  /**
+   * The part of an aggregate prefetch that has to be resident for the
+   * WHOLE relationship: the relationship record itself and the relating
+   * product's closure (its rel-voids become the master override every
+   * related product is cut with).
+   *
+   * Only the RELATING object's record is paged ahead of the getter that
+   * hydrates it, deliberately — not the relationship's whole 1-hop, which
+   * is what this used to do. On a model whose products are all aggregate
+   * targets the 1-hop is every related product's record, scattered the
+   * length of the file, so pinning it pins essentially every chunk before
+   * a single mesh exists: 384 MiB held against a 64 MiB window on
+   * SKYLARK250 (conway#561 §5). The related records are paged by the
+   * caller instead, per product or per wave.
+   *
+   * Seam for {@link AggregateExtractPager}, which lives in this module.
+   *
+   * @param relAggregate The relationship to prefetch.
+   * @param pinned Set to extend — caller unpins.
+   * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
+   * @return {Promise<void>} Resolves when the base is resident.
+   */
+  async ensureResidentForAggregateBase(relAggregate, pinned, leafSpans) {
+    if (!this.model.isSourceExternal) {
+      return;
+    }
     this.model.pinByLocalID(relAggregate.localID);
     pinned.add(relAggregate.localID);
+    await this.model.ensureResidentByLocalID(relAggregate.localID);
+    const relatingLocalID = relAggregate.extractReferenceLocalID(REL_AGGREGATES_RELATING_OFFSET, REL_AGGREGATES_RELATING_BASE, REL_AGGREGATES_RELATING_DEPTH, true);
+    if (relatingLocalID !== null) {
+      this.model.pinByLocalID(relatingLocalID);
+      await this.model.ensureResidentByLocalID(relatingLocalID);
+    }
+    try {
+      const relating = relAggregate.RelatingObject;
+      if (relating !== null && relating !== void 0) {
+        await this.ensureResidentForProductExtract(relating.localID, pinned, leafSpans);
+      }
+    } finally {
+      if (relatingLocalID !== null) {
+        this.model.unpinByLocalID(relatingLocalID);
+      }
+    }
+  }
+  /**
+   * The local IDs one relationship's aggregates pass will actually extract:
+   * its RelatedObjects that are `IfcProduct`s, in record order.
+   *
+   * The n-th entry is the product
+   * {@link extractRelAggregateGeometryIncremental} extracts for its n-th
+   * yield — that pass materialises every related object, extracts and
+   * yields for the ones that are products, and walks past the rest. So a
+   * prefetch keyed on this list is in exact lockstep with the stepper, and
+   * a run of non-products between two products costs it nothing.
+   *
+   * **Non-products are dropped, not skipped-but-paged.** Deciding an entry
+   * is not a product costs no source bytes: `getTypedElementByExpressID`
+   * builds its descriptor from the columns, and only
+   * {@link extractProductGeometry} — products only — reads a record. Swept
+   * that exact path (materialise as `IfcObjectDefinition`, test
+   * `instanceof IfcProduct`) over every record of SKYLARK250 (7,818,778),
+   * SEESTRASSE (294,704) and the whole in-repo corpus behind a deliberately
+   * exhausted 4 KiB x 4 window: 0 throws, 0 store bytes read. Paging a
+   * non-product's closure is therefore work that serves nothing — and it is
+   * unbounded work, because a wave that had to span a run of them would
+   * page the whole run at once, `waveSize` notwithstanding (conway#566
+   * review). An `IfcTypeObject` carrying `RepresentationMaps` measures
+   * 1,607 records of closure on its own.
+   *
+   * Classification goes through {@link relatedProductByExpressID_}, the same
+   * call the pass itself makes — one test rather than two that have to
+   * agree. A typeID-column test does NOT agree: a STEP complex instance is
+   * recorded as type 0 (`EXTERNALMAPPINGCONTAINER`) while the pass finds the
+   * `IfcProduct` among its `multiMapping` variants, and the product would
+   * then be extracted without ever being paged (conway#566 review).
+   *
+   * Note {@link aggregateTargetLocalIDs} still reads the column, and has the
+   * same blind spot — a complex product is not deferred, so it is extracted
+   * by both passes. That is pre-existing and independent of paging: it costs
+   * a duplicate extraction, not a non-resident read.
+   *
+   * Seam for {@link AggregateExtractPager}, which lives in this module.
+   *
+   * @param relAggregate The relationship to read.
+   * @return {number[] | undefined} The related products' local IDs, or
+   * undefined when the list holds something only the generated getter can
+   * resolve (see {@link relatedObjectExpressIDs_}).
+   */
+  relatedAggregateProductLocalIDs(relAggregate) {
+    const relatedExpressIDs = this.relatedObjectExpressIDs_(relAggregate);
+    if (relatedExpressIDs === void 0) {
+      return void 0;
+    }
+    const productLocalIDs = [];
+    for (const relatedExpressID of relatedExpressIDs) {
+      let relatedProduct;
+      try {
+        relatedProduct = this.relatedProductByExpressID_(relatedExpressID);
+      } catch {
+        break;
+      }
+      if (relatedProduct !== void 0) {
+        productLocalIDs.push(relatedProduct.localID);
+      }
+    }
+    return productLocalIDs;
+  }
+  /**
+   * Page the closures of a contiguous run of
+   * {@link relatedAggregateProductLocalIDs} entries.
+   *
+   * Seam for {@link AggregateExtractPager}, which lives in this module.
+   *
+   * @param productLocalIDs The related products, in record order.
+   * @param from First index to page.
+   * @param to One past the last index to page.
+   * @param pinned Set to extend — caller unpins.
+   * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
+   * @return {Promise<void>} Resolves when the run is resident.
+   */
+  async ensureResidentForAggregateProducts(productLocalIDs, from, to, pinned, leafSpans) {
+    for (let where = from; where < to; ++where) {
+      await this.ensureResidentForProductExtract(productLocalIDs[where], pinned, leafSpans);
+    }
+  }
+  /**
+   * Whole-relationship prefetch for a RelatedObjects list that
+   * {@link relatedAggregateProductLocalIDs} could not read as references — an
+   * inline entity, `$` or junk.
+   *
+   * Only the generated getter can resolve (or reject) such a list, and it
+   * materialises the whole array at once, so there is no per-entry cursor
+   * to page against: this path keeps the pre-#561 shape, whole 1-hop and
+   * all, because it is the one case that genuinely cannot be paged
+   * incrementally. It is also the path that needs the 1-hop pinned — the
+   * getter reads every related record while it materialises them.
+   *
+   * Seam for {@link AggregateExtractPager}, which lives in this module.
+   *
+   * @param relAggregate The relationship to prefetch.
+   * @param pinned Set to extend — caller unpins.
+   * @param leafSpans Coalesced Faces[] pin ranges — caller unpins.
+   * @return {Promise<void>} Resolves when the relationship is resident.
+   */
+  async ensureResidentForRelatedObjectsByGetter(relAggregate, pinned, leafSpans) {
+    const hop = [];
     try {
-      await this.model.ensureResidentByLocalID(relAggregate.localID);
       for (const expressID of this.model.referencedExpressIDs(relAggregate.localID)) {
         const localID = this.model.resolveExpressID(expressID);
         if (localID === void 0 || pinned.has(localID)) {
@@ -94054,34 +94218,37 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
         hop.push(localID);
         await this.model.ensureResidentByLocalID(localID);
       }
-      const relating = relAggregate.RelatingObject;
-      if (relating !== null && relating !== void 0) {
-        await this.ensureResidentForProductExtract(relating.localID, pinned, leafSpans);
-      }
-      const relatedExpressIDs = this.relatedObjectExpressIDs_(relAggregate);
-      if (relatedExpressIDs === void 0) {
-        const related = relAggregate.RelatedObjects;
-        if (related !== null && related !== void 0) {
-          for (const product of related) {
-            await this.ensureResidentForProductExtract(product.localID, pinned, leafSpans);
-          }
-        }
-      } else {
-        for (const relatedExpressID of relatedExpressIDs) {
-          const relatedLocalID = this.model.resolveExpressID(relatedExpressID);
-          if (relatedLocalID === void 0) {
-            continue;
-          }
-          await this.ensureResidentForProductExtract(relatedLocalID, pinned, leafSpans);
+      const related = relAggregate.RelatedObjects;
+      if (related !== null && related !== void 0) {
+        for (const product of related) {
+          await this.ensureResidentForProductExtract(product.localID, pinned, leafSpans);
         }
       }
-      return pinned;
     } finally {
       for (const localID of hop) {
         this.model.unpinByLocalID(localID);
       }
     }
   }
+  /**
+   * Begin a WAVE-PAGED residency for one relationship, for a caller that
+   * steps it through {@link extractRelAggregateGeometryIncremental}.
+   *
+   * The windowed twin of {@link ensureResidentForAggregateExtract}: same
+   * records, paged a wave at a time as the stepper reaches them and
+   * released a wave at a time behind it, instead of all of them before the
+   * first step. See {@link AggregateExtractPager}.
+   *
+   * @param relAggregate The relationship to prefetch.
+   * @param waveSize Related products paged and held at once.
+   * @return {Promise<AggregateExtractPager>} The paging handle — caller
+   * must {@link AggregateExtractPager.release} it.
+   */
+  async beginAggregateExtract(relAggregate, waveSize = _IfcGeometryExtraction.AGGREGATE_PREFETCH_WAVE_SIZE_) {
+    const pager = new AggregateExtractPager(this, relAggregate, waveSize);
+    await pager.begin();
+    return pager;
+  }
   /**
    * The whole-model walk's SECOND product pass, shared with the demand
    * pump: for every IfcRelAggregates, re-extract the related products
@@ -94140,6 +94307,47 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
     });
     return allReferences ? expressIDs : void 0;
   }
+  /**
+   * How the rel-aggregates pass classifies ONE `RelatedObjects` entry: the
+   * product it will extract, or undefined for an entry it walks past.
+   *
+   * **The single definition of "is this related object a product".** Both
+   * the pass itself ({@link extractRelAggregateGeometryIncremental}) and the
+   * prefetch that has to page ahead of it
+   * ({@link relatedAggregateProductLocalIDs}) go through here, so they
+   * cannot disagree — which they did, twice, when the prefetch derived its
+   * own answer from the typeID column. A STEP complex/external-mapping
+   * instance is the case that breaks a column test: the parser records the
+   * container as type 0 (`EXTERNALMAPPINGCONTAINER`, see step_parser.ts)
+   * while `getTypedElementByExpressID` searches the entry's `multiMapping`
+   * variants and hands back the `IfcProduct` among them. On a windowed
+   * source a prefetch that missed one would leave the pass reading a
+   * non-resident record, and its permissive catch abandons the REST of the
+   * relationship — geometry lost with a log line, not an error
+   * (conway#566 review).
+   *
+   * Materialising the entry is what makes the two agree, and it is cheap:
+   * `getTypedElementByExpressID` builds from the columns and reads no
+   * source bytes. Measured by sweeping this exact call over every record of
+   * SKYLARK250 (7,818,778), SEESTRASSE (294,704) and the in-repo corpus
+   * behind a deliberately exhausted 4 KiB x 4 window — 0 throws, 0 store
+   * bytes. The pass materialises every entry anyway; the prefetch just
+   * reaches them first.
+   *
+   * @param relatedExpressID The RelatedObjects entry to classify.
+   * @throws {Error} When the reference resolves to nothing, or to something
+   * that is not an `IfcObjectDefinition` — what the generated getter throws
+   * for the same entry, and what the pass has always thrown here.
+   * @return {IfcProduct | undefined} The product to extract, or undefined
+   * for a related object that is not one.
+   */
+  relatedProductByExpressID_(relatedExpressID) {
+    const relatedObject = this.model.getTypedElementByExpressID(relatedExpressID, IfcObjectDefinition);
+    if (relatedObject === void 0) {
+      throw new Error("Value in STEP was incorrectly typed");
+    }
+    return relatedObject instanceof IfcProduct ? relatedObject : void 0;
+  }
   /**
    * Extract one IfcRelAggregates' related products with the relating
    * object's ("master") rel-voids — the shared per-item body of the
@@ -94199,12 +94407,9 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
         }
       } else {
         for (const relatedExpressID of relatedExpressIDs) {
-          const relatedObject = this.model.getTypedElementByExpressID(relatedExpressID, IfcObjectDefinition);
-          if (relatedObject === void 0) {
-            throw new Error("Value in STEP was incorrectly typed");
-          }
-          if (relatedObject instanceof IfcProduct) {
-            this.extractProductGeometry(relatedObject, masterRelVoids);
+          const relatedProduct = this.relatedProductByExpressID_(relatedExpressID);
+          if (relatedProduct !== void 0) {
+            this.extractProductGeometry(relatedProduct, masterRelVoids);
             yield ++extractedCount;
           }
         }
@@ -94476,6 +94681,98 @@ var IfcGeometryExtraction = class _IfcGeometryExtraction {
   }
 };
 IfcGeometryExtraction.AGGREGATE_TARGET_WAVE_SIZE_ = 512;
+IfcGeometryExtraction.AGGREGATE_PREFETCH_WAVE_SIZE_ = 8;
+var AggregateExtractPager = class {
+  /**
+   * Construct paging for one relationship.
+   *
+   * @param extraction_ The extraction whose model is being paged.
+   * @param relAggregate_ The relationship this pages for.
+   * @param waveSize Related products paged and held at once.
+   */
+  constructor(extraction_, relAggregate_, waveSize) {
+    this.extraction_ = extraction_;
+    this.relAggregate_ = relAggregate_;
+    this.basePins_ = /* @__PURE__ */ new Set();
+    this.baseSpans_ = [];
+    this.wavePins_ = /* @__PURE__ */ new Set();
+    this.waveSpans_ = [];
+    this.waveStart_ = 0;
+    this.pagedThrough_ = 0;
+    this.released_ = false;
+    this.waveSize_ = Math.max(1, Math.floor(waveSize));
+  }
+  /**
+   * Page what has to be resident for every step of this relationship.
+   *
+   * @return {Promise<void>} Resolves when the base is resident.
+   */
+  async begin() {
+    if (!this.extraction_.model.isSourceExternal) {
+      return;
+    }
+    await this.extraction_.ensureResidentForAggregateBase(this.relAggregate_, this.basePins_, this.baseSpans_);
+    this.products_ = this.extraction_.relatedAggregateProductLocalIDs(this.relAggregate_);
+    if (this.products_ !== void 0) {
+      return;
+    }
+    await this.extraction_.ensureResidentForRelatedObjectsByGetter(this.relAggregate_, this.basePins_, this.baseSpans_);
+  }
+  /**
+   * Make the product the stepper extracts for yield `step` resident,
+   * rolling the wave forward if it does not already cover it.
+   *
+   * At most `waveSize` product closures are pinned at any moment, whatever
+   * the related-object list holds between them.
+   *
+   * @param step Zero-based index of the stepper's next yield.
+   * @return {Promise<void>} Resolves when that product is resident.
+   */
+  async ensureForStep(step) {
+    const products = this.products_;
+    if (products === void 0 || step >= products.length) {
+      return;
+    }
+    if (step < this.pagedThrough_) {
+      return;
+    }
+    this.releaseWave_();
+    this.waveStart_ = step;
+    this.pagedThrough_ = Math.min(products.length, step + this.waveSize_);
+    await this.extraction_.ensureResidentForAggregateProducts(products, this.waveStart_, this.pagedThrough_, this.wavePins_, this.waveSpans_);
+  }
+  /**
+   * Drop every pin this holds. Idempotent.
+   */
+  release() {
+    if (this.released_) {
+      return;
+    }
+    this.released_ = true;
+    this.releaseWave_();
+    const model = this.extraction_.model;
+    model.releaseSourceViews(this.basePins_);
+    model.unpinLocalIDs(this.basePins_);
+    this.basePins_.clear();
+    for (const span of this.baseSpans_) {
+      model.unpinAddressRange(span.address, span.length);
+    }
+    this.baseSpans_.length = 0;
+  }
+  /**
+   * Drop the current wave's pins and views.
+   */
+  releaseWave_() {
+    const model = this.extraction_.model;
+    model.releaseSourceViews(this.wavePins_);
+    model.unpinLocalIDs(this.wavePins_);
+    for (const span of this.waveSpans_) {
+      model.unpinAddressRange(span.address, span.length);
+    }
+    this.wavePins_ = /* @__PURE__ */ new Set();
+    this.waveSpans_ = [];
+  }
+};
 
 // compiled/src/ifc/ifc_property_extraction.js
 var PropertyExtractResult;

package/compiled/examples/cli-step-bundled.cjs

@@ -15943,7 +15943,7 @@ var ParsingBuffer = class {
 };
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.563.1540";
+var versionString = "Conway v1.566.1541";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 function pThreadsAllowed() {

package/compiled/examples/validator-bundled.cjs

@@ -944,7 +944,7 @@ var EntityTypesIfcCount = 909;
 var entity_types_ifc_gen_default = EntityTypesIfc;
 
 // compiled/src/version/version.js
-var versionString = "Conway v1.563.1540";
+var versionString = "Conway v1.566.1541";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";

package/compiled/src/compat/web-ifc/aggregate_prefetch_paging.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=aggregate_prefetch_paging.test.d.ts.map

package/compiled/src/compat/web-ifc/aggregate_prefetch_paging.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate_prefetch_paging.test.d.ts","sourceRoot":"","sources":["../../../../src/compat/web-ifc/aggregate_prefetch_paging.test.ts"],"names":[],"mappings":""}