@bldrs-ai/conway 1.408.1248 → 1.413.1255

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.408.1248";
+var versionString = "Conway v1.413.1255";
 
 // compiled/dependencies/conway-geom/interface/conway_geometry.js
 var wasmType = "";
@@ -3501,8 +3501,8 @@ var StepParser = class extends StepHeaderParser {
    * @param onProgress Optional byte-cursor progress callback.
    * @return {BlockParseResult} The parsing result, including the index and result enum.
    */
-  parseDataBlockStreamed(input, onRecordBoundary, onRecordIndexed, onProgress) {
-    const parser211 = this.parseDataBlockIncremental(input, onRecordBoundary, onRecordIndexed);
+  parseDataBlockStreamed(input, onRecordBoundary, onRecordIndexed, onProgress, sink) {
+    const parser211 = this.parseDataBlockIncremental(input, onRecordBoundary, onRecordIndexed, sink);
     while (true) {
       const next = parser211.next();
       if (next.done === true) {
@@ -3548,8 +3548,14 @@ var StepParser = class extends StepHeaderParser {
    * @yields {number} The current byte cursor within the input buffer.
    * @return {BlockParseResult} The parsing result, including the index and result enum.
    */
-  *parseDataBlockIncremental(input, onRecordBoundary, onRecordIndexed) {
+  *parseDataBlockIncremental(input, onRecordBoundary, onRecordIndexed, sink) {
     const indexResult = { elements: [] };
+    let topLevelCount = 0;
+    const pushEntry = sink !== void 0 ? (entry) => {
+      sink.pushTopLevel(entry);
+    } : (entry) => {
+      indexResult.elements.push(entry);
+    };
     const match = input.match;
     const comment = () => match(commentParser2);
     const whitespace = () => {
@@ -3725,8 +3731,9 @@ var StepParser = class extends StepHeaderParser {
         if (!charws(SEMICOLON)) {
           return syntaxError();
         }
-        onRecordIndexed?.(indexResult.elements.length, expressID, 0);
-        indexResult.elements.push({
+        onRecordIndexed?.(topLevelCount, expressID, 0);
+        ++topLevelCount;
+        pushEntry({
           address: startElement2,
           length: input.address - startElement2,
           typeID: 0,
@@ -3817,8 +3824,9 @@ var StepParser = class extends StepHeaderParser {
       if (!charws(SEMICOLON)) {
         return syntaxError();
       }
-      onRecordIndexed?.(indexResult.elements.length, expressID, foundItem);
-      indexResult.elements.push({
+      onRecordIndexed?.(topLevelCount, expressID, foundItem);
+      ++topLevelCount;
+      pushEntry({
         address: startElement,
         length: input.address - startElement,
         typeID: foundItem,
@@ -4998,6 +5006,31 @@ var StepModelBase = class {
     this.elementMemoization = true;
     this.nullOnErrors = true;
     this.bufferProvider_ = provider ?? new ResidentStepBufferProvider(buffer_);
+    if (!Array.isArray(elementIndex)) {
+      const columns = elementIndex;
+      const firstInline = columns.firstInlineElement;
+      const inlineCount = columns.count - firstInline;
+      const inlineElementTable2 = new Uint32Array(inlineCount << 1);
+      for (let where2 = 0; where2 < inlineCount; ++where2) {
+        inlineElementTable2[where2 << 1] = firstInline + where2;
+        inlineElementTable2[(where2 << 1) + 1] = columns.address[firstInline + where2];
+      }
+      this.inlineAddressMap_ = new InterpolationSearchTable32(inlineElementTable2, true);
+      const expressIdTable2 = new Uint32Array(firstInline << 1);
+      for (let where2 = 0; where2 < firstInline; ++where2) {
+        expressIdTable2[where2 << 1] = where2;
+        expressIdTable2[(where2 << 1) + 1] = columns.expressID[where2];
+      }
+      this.expressIDMap_ = new InterpolationSearchTable32(expressIdTable2, columns.expressIdsSorted);
+      this.address_ = columns.address;
+      this.length_ = columns.length;
+      this.typeID_ = columns.typeID;
+      this.expressID_ = columns.expressID;
+      this.count_ = columns.count;
+      this.firstInlineElement_ = firstInline;
+      this.complexEntries_ = columns.complexEntries;
+      return;
+    }
     const localElementIndex = elementIndex;
     let where = 0;
     const firstInlineElement = localElementIndex.length;
@@ -70115,6 +70148,68 @@ var StepTypeIndexer = class {
   constructor(typeCount) {
     this.elementCounter_ = new Int32Array(typeCount << 1);
   }
+  /**
+   * Create a type index from either index form — the parsed object array or
+   * the columnar index (M7).
+   *
+   * @param index The element index, object or columnar.
+   * @return {MultiIndexSet} The created multi-set index.
+   */
+  createFor(index) {
+    return Array.isArray(index) ? this.create(index) : this.createFromColumns(index);
+  }
+  /**
+   * Create a type index straight from the columnar index — the same
+   * membership `create` produces from the unfolded object array: every row's
+   * concrete type (top-level + inline; −1 rows skipped) plus the
+   * multi-mapping subtypes of retained complex entries at their parent's
+   * dense index.
+   *
+   * @param columns The columnar index.
+   * @return {MultiIndexSet} The created multi-set index.
+   */
+  createFromColumns(columns) {
+    for (let where = 0, end = this.elementCounter_.length; where < end; where += 2) {
+      initCountCompactedElements32State(this.elementCounter_, where);
+    }
+    const elementCounter = this.elementCounter_;
+    const prefixSum = new Uint32Array((this.elementCounter_.length >>> 1) + 1);
+    const typeIDs = columns.typeID;
+    const count = columns.count;
+    const walkRows = (addOne) => {
+      const complexIterator = columns.complexEntries?.entries();
+      let nextComplex = complexIterator?.next();
+      for (let denseIndex = 0; denseIndex < count; ++denseIndex) {
+        const typeID = typeIDs[denseIndex];
+        if (typeID >= 0) {
+          addOne(denseIndex, typeID);
+        }
+        if (nextComplex !== void 0 && !nextComplex.done && nextComplex.value[0] === denseIndex) {
+          for (const subElement of nextComplex.value[1].multiMapping ?? []) {
+            const subTypeID = subElement.typeID;
+            if (subTypeID !== void 0) {
+              addOne(denseIndex, subTypeID);
+            }
+          }
+          nextComplex = complexIterator.next();
+        }
+      }
+    };
+    walkRows((denseIndex, typeID) => {
+      prefixSum[typeID + 1] = addCompactedElementCount32State(denseIndex, elementCounter, typeID << 1);
+    });
+    for (let prefixSumIndex = 2, prefixSumEnd = prefixSum.length; prefixSumIndex < prefixSumEnd; ++prefixSumIndex) {
+      prefixSum[prefixSumIndex] += prefixSum[prefixSumIndex - 1];
+    }
+    for (let where = 0, end = this.elementCounter_.length; where < end; where += 2) {
+      initCountCompactedElements32State(this.elementCounter_, where);
+    }
+    const indexOutput = new Uint32Array(prefixSum[prefixSum.length - 1] << 1);
+    walkRows((denseIndex, typeID) => {
+      addCompactedElement32State(denseIndex, elementCounter, indexOutput, typeID << 1, prefixSum[typeID] << 1);
+    });
+    return new MultiIndexSet(prefixSum, indexOutput);
+  }
   /**
    * Create a type index from a set of parsed STEP elements.
    *
@@ -70776,12 +70871,136 @@ var IfcStepModel = class extends StepModelBase {
     this.materials = new IfcMaterialCache(this);
     this.voidMaterials = new IfcMaterialCache(this, true);
     this.elementTypeIDs = entity_types_ifc_gen_default;
-    this.typeIndex = indexerInstance.create(elementIndex);
+    this.typeIndex = indexerInstance.createFor(elementIndex);
   }
 };
 
+// compiled/src/step/parsing/columnar_index.js
+var COLUMN_UNDEFINED_TYPE = -1;
+var SEGMENT_ROWS = 64 * 1024;
+var ColumnarIndexSink = class {
+  constructor() {
+    this.segments_ = [];
+    this.count_ = 0;
+    this.retained_ = /* @__PURE__ */ new Map();
+    this.expressIdsSorted_ = true;
+    this.previousExpressID_ = 0;
+  }
+  /**
+   * @return {number} Top-level records pushed so far.
+   */
+  get topLevelCount() {
+    return this.count_;
+  }
+  /**
+   * Encode one completed top-level record into the columns. The entry object
+   * is not kept unless it carries children (inline entities / multi-mapping).
+   *
+   * @param entry The completed top-level index entry.
+   */
+  pushTopLevel(entry) {
+    const localID = this.count_++;
+    const segmentIndex = Math.floor(localID / SEGMENT_ROWS);
+    const row = localID % SEGMENT_ROWS;
+    if (segmentIndex === this.segments_.length) {
+      this.segments_.push({
+        address: new Uint32Array(SEGMENT_ROWS),
+        length: new Uint32Array(SEGMENT_ROWS),
+        typeID: new Int32Array(SEGMENT_ROWS),
+        expressID: new Uint32Array(SEGMENT_ROWS)
+      });
+    }
+    const segment = this.segments_[segmentIndex];
+    segment.address[row] = entry.address;
+    segment.length[row] = entry.length;
+    segment.typeID[row] = entry.typeID === void 0 ? COLUMN_UNDEFINED_TYPE : entry.typeID;
+    segment.expressID[row] = entry.expressID;
+    if (entry.expressID < this.previousExpressID_) {
+      this.expressIdsSorted_ = false;
+    }
+    this.previousExpressID_ = entry.expressID;
+    if (entry.inlineEntities !== void 0 || entry.multiMapping !== void 0) {
+      this.retained_.set(localID, entry);
+    }
+  }
+  /**
+   * Rewind to empty (the streaming builder's grow-and-restart). The first
+   * segment is kept for reuse.
+   */
+  reset() {
+    this.segments_.length = Math.min(this.segments_.length, 1);
+    this.count_ = 0;
+    this.retained_.clear();
+    this.expressIdsSorted_ = true;
+    this.previousExpressID_ = 0;
+  }
+  /**
+   * Assemble the final columns: concatenate the top-level segments (one
+   * column at a time, bounding transient overhead to a single column's
+   * segments) and unfold retained inline entities into the inline range in
+   * the model's exact unfold order.
+   *
+   * @return {StepIndexColumns} The finished columnar index.
+   */
+  finalize() {
+    const topLevel = this.count_;
+    const unfolded = [];
+    for (const entry of this.retained_.values()) {
+      if (entry.inlineEntities !== void 0) {
+        unfolded.push(...entry.inlineEntities);
+      }
+    }
+    for (let where = 0; where < unfolded.length; ++where) {
+      const inlineEntities = unfolded[where].inlineEntities;
+      if (inlineEntities !== void 0) {
+        unfolded.push(...inlineEntities);
+      }
+    }
+    const count = topLevel + unfolded.length;
+    const address = concatColumn(this.segments_, "address", topLevel, count);
+    const length = concatColumn(this.segments_, "length", topLevel, count);
+    const typeID = new Int32Array(count);
+    for (let segment = 0; segment * SEGMENT_ROWS < topLevel; ++segment) {
+      const rows = Math.min(SEGMENT_ROWS, topLevel - segment * SEGMENT_ROWS);
+      typeID.set(this.segments_[segment].typeID.subarray(0, rows), segment * SEGMENT_ROWS);
+    }
+    const expressID = concatColumn(this.segments_, "expressID", topLevel, topLevel);
+    for (let where = 0; where < unfolded.length; ++where) {
+      const entry = unfolded[where];
+      const row = topLevel + where;
+      address[row] = entry.address;
+      length[row] = entry.length;
+      typeID[row] = entry.typeID === void 0 ? COLUMN_UNDEFINED_TYPE : entry.typeID;
+    }
+    let complexEntries;
+    for (const [localID, entry] of this.retained_) {
+      if (entry.multiMapping !== void 0) {
+        (complexEntries ??= /* @__PURE__ */ new Map()).set(localID, entry);
+      }
+    }
+    return {
+      address,
+      length,
+      typeID,
+      expressID,
+      count,
+      firstInlineElement: topLevel,
+      complexEntries,
+      expressIdsSorted: this.expressIdsSorted_
+    };
+  }
+};
+function concatColumn(segments, column, rows, finalLength) {
+  const result = new Uint32Array(finalLength);
+  for (let segment = 0; segment * SEGMENT_ROWS < rows; ++segment) {
+    const valid = Math.min(SEGMENT_ROWS, rows - segment * SEGMENT_ROWS);
+    result.set(segments[segment][column].subarray(0, valid), segment * SEGMENT_ROWS);
+  }
+  return result;
+}
+
 // compiled/src/step/parsing/streaming_index_builder.js
-function buildIndexStreaming(source, parser211, pool3, onRecordIndexed) {
+function buildIndexStreaming(source, parser211, pool3, onRecordIndexed, sink) {
   const fileSize = source.byteLength;
   let windowBytes = Math.max(pool3, MIN_WINDOW);
   for (; ; ) {
@@ -70827,11 +71046,12 @@ function buildIndexStreaming(source, parser211, pool3, onRecordIndexed) {
       buffer.rebaseWindow(window2, 0, windowLen, windowStartFile);
       ++slides;
     };
-    const [index, result] = parser211.parseDataBlockStreamed(input, onRecordBoundary, onRecordIndexed);
+    const [index, result] = parser211.parseDataBlockStreamed(input, onRecordBoundary, onRecordIndexed, void 0, sink);
     const stoppedShort = result !== ParseResult.COMPLETE;
     const notAtEof = windowStartFile + windowLen < fileSize;
     if (stoppedShort && notAtEof) {
       windowBytes *= 2;
+      sink?.reset();
       continue;
     }
     const lastRecordLen = windowStartFile + input.cursor - prevBoundaryFile;
@@ -70847,6 +71067,11 @@ function buildIndexStreaming(source, parser211, pool3, onRecordIndexed) {
   }
 }
 var MIN_WINDOW = 4 * 1024;
+function buildColumnarIndexStreaming(source, parser211, pool3, onRecordIndexed) {
+  const sink = new ColumnarIndexSink();
+  const { header, result, stats } = buildIndexStreaming(source, parser211, pool3, onRecordIndexed, sink);
+  return { header, columns: sink.finalize(), result, stats };
+}
 
 // compiled/src/ifc/ifc_step_parser.js
 var DEFAULT_STREAM_POOL_BYTES = 1024 * 1024;
@@ -70912,9 +71137,9 @@ var IfcStepParser = class extends StepParser {
     if (store.byteLength !== source.byteLength) {
       throw new Error(`Streaming store byteLength ${store.byteLength} does not match source byteLength ${source.byteLength}`);
     }
-    const { elements, result } = buildIndexStreaming(source, this, opts?.pool ?? DEFAULT_STREAM_POOL_BYTES);
+    const { columns, result } = buildColumnarIndexStreaming(source, this, opts?.pool ?? DEFAULT_STREAM_POOL_BYTES);
     const provider = new WindowedStepBufferProvider(store, opts?.chunkBytes, opts?.maxResidentChunks);
-    return [result, new IfcStepModel(void 0, elements, provider)];
+    return [result, new IfcStepModel(void 0, columns, provider)];
   }
 };
 IfcStepParser.Instance = new IfcStepParser();

package/compiled/src/AP214E3_2010/ap214_step_model.d.ts

@@ -1,6 +1,7 @@
 import EntityTypesAP214 from "./AP214E3_2010_gen/entity_types_ap214.gen.js";
 import StepModelBase from "../step/step_model_base.js";
 import { StepIndexEntry } from "../step/parsing/step_parser.js";
+import { StepIndexColumns } from "../step/parsing/columnar_index.js";
 import { MultiIndexSet } from "../indexing/multi_index_set.js";
 import { AP214ModelGeometry } from "./ap214_model_geometry.js";
 import { AP214ModelProfile } from "./ap214_model_profile.js";
@@ -26,6 +27,6 @@ export default class AP214StepModel extends StepModelBase<EntityTypesAP214> {
      * @param buffer The buffer to values from.
      * @param elementIndex The parsed index to elements in the STEP.
      */
-    constructor(buffer: Uint8Array, elementIndex: StepIndexEntry<EntityTypesAP214>[]);
+    constructor(buffer: Uint8Array, elementIndex: StepIndexEntry<EntityTypesAP214>[] | StepIndexColumns<EntityTypesAP214>);
 }
 //# sourceMappingURL=ap214_step_model.d.ts.map

package/compiled/src/AP214E3_2010/ap214_step_model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ap214_step_model.d.ts","sourceRoot":"","sources":["../../../src/AP214E3_2010/ap214_step_model.ts"],"names":[],"mappings":"AAAA,OAAO,gBAAyC,MAAM,2CAA2C,CAAA;AACjG,OAAO,aAAa,MAAM,yBAAyB,CAAA;AAEnD,OAAO,EAAC,cAAc,EAAC,MAAM,6BAA6B,CAAA;AAE1D,OAAO,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,wBAAwB,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,gBAAgB,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAKvD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,aAAa,CAAE,gBAAgB,CAAE;IAE3E,SAAgB,SAAS,EAAE,aAAa,CAAE,gBAAgB,CAAE,CAAA;IAC5D,SAAgB,mBAAmB,kCAA2B;IAC9D,SAAgB,QAAQ,qBAA2B;IACnD,SAAgB,SAAS,qBAA2B;IACpD,SAAgB,QAAQ,oBAA0B;IAClD,SAAgB,MAAM,mBAA6B;IACnD,SAAgB,aAAa,iBAAuB;IAEpD;;;;;;OAMG;gBAEC,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,cAAc,CAAE,gBAAgB,CAAE,EAAE;CAKvD"}
+{"version":3,"file":"ap214_step_model.d.ts","sourceRoot":"","sources":["../../../src/AP214E3_2010/ap214_step_model.ts"],"names":[],"mappings":"AAAA,OAAO,gBAAyC,MAAM,2CAA2C,CAAA;AACjG,OAAO,aAAa,MAAM,yBAAyB,CAAA;AAEnD,OAAO,EAAC,cAAc,EAAC,MAAM,6BAA6B,CAAA;AAC1D,OAAO,EAAC,gBAAgB,EAAC,MAAM,gCAAgC,CAAA;AAE/D,OAAO,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,wBAAwB,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,gBAAgB,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAKvD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,aAAa,CAAE,gBAAgB,CAAE;IAE3E,SAAgB,SAAS,EAAE,aAAa,CAAE,gBAAgB,CAAE,CAAA;IAC5D,SAAgB,mBAAmB,kCAA2B;IAC9D,SAAgB,QAAQ,qBAA2B;IACnD,SAAgB,SAAS,qBAA2B;IACpD,SAAgB,QAAQ,oBAA0B;IAClD,SAAgB,MAAM,mBAA6B;IACnD,SAAgB,aAAa,iBAAuB;IAEpD;;;;;;OAMG;gBAEC,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,cAAc,CAAE,gBAAgB,CAAE,EAAE,GAAG,gBAAgB,CAAE,gBAAgB,CAAE;CAK9F"}

package/compiled/src/AP214E3_2010/ap214_step_model.js

@@ -28,6 +28,6 @@ export default class AP214StepModel extends StepModelBase {
         this.profiles = new AP214ModelProfile();
         this.curves = new AP214ModelCurves(this);
         this.csgOperations = new CsgMemoization();
-        this.typeIndex = indexerInstance.create(elementIndex);
+        this.typeIndex = indexerInstance.createFor(elementIndex);
     }
 }

package/compiled/src/core/demand_residency_pump.d.ts

@@ -0,0 +1,93 @@
+import { DemandGeometryQueue } from "./demand_geometry_queue.js";
+/**
+ * The async half of demand-driven geometry (Phase B): source-byte residency.
+ *
+ * Extraction is synchronous by design (the wasm extract reads source bytes
+ * through `StepBufferProvider.acquire`), but a windowed/streamed source pages
+ * bytes in asynchronously (`ensureResident`). This pump owns that seam: it
+ * admits demand, prefetches the source ranges for the most-wanted products,
+ * and only then forwards them to the synchronous {@link DemandGeometryQueue}
+ * — so a `pump()` never hits a non-resident range mid-extract.
+ */
+export interface ResidencyPrefetcher {
+    /**
+     * Page in the source byte ranges a product's extraction will read.
+     * `StepModelBase.ensureResidentByLocalID` satisfies this shape.
+     *
+     * @param localID The product's local ID.
+     * @return {Promise<void>} Resolves when resident.
+     */
+    ensureResidentByLocalID(localID: number): Promise<void>;
+}
+/** Outcome of one pump cycle, for telemetry and tests. */
+export interface PumpResult {
+    /** Tiles extracted this cycle (from the queue's pump). */
+    extracted: number;
+    /** Products whose prefetch failed this cycle (re-queued for retry). */
+    prefetchFailures: number;
+}
+/**
+ * Admission + prefetch orchestration in front of a {@link DemandGeometryQueue}.
+ *
+ * Consumers `request()` products as demand changes (the pump owns admission —
+ * don't request on the queue directly); each async `pump()` cycle:
+ *
+ *  1. selects the top-priority pending batch,
+ *  2. awaits source residency for the batch (failures re-queue for retry
+ *     and are reported, never thrown — one bad range must not stall the
+ *     viewport),
+ *  3. forwards the resident products to the queue and runs its synchronous
+ *     pump under the same batch cap.
+ *
+ * Re-entrant calls coalesce: a `pump()` while one is in flight returns the
+ * in-flight cycle's promise rather than interleaving prefetch batches.
+ * Products already resident in the queue skip prefetch entirely (their
+ * ranking refresh is forwarded immediately).
+ */
+export declare class DemandResidencyPump {
+    private readonly queue_;
+    private readonly prefetcher_;
+    private readonly batch_;
+    /** Pending admission: product localID → highest requested priority. */
+    private readonly pending_;
+    private inFlight_;
+    /**
+     * @param queue_ The synchronous demand queue (extraction + budget).
+     * @param prefetcher_ Source-byte residency (the model / buffer provider).
+     * @param batch_ Max products prefetched + extracted per pump cycle.
+     */
+    constructor(queue_: DemandGeometryQueue, prefetcher_: ResidencyPrefetcher, batch_?: number);
+    /**
+     * Request a product at a demand priority. Resident products forward
+     * immediately (ranking refresh); others queue for the next pump cycle at
+     * the highest priority requested so far.
+     *
+     * @param productLocalID The product to materialise.
+     * @param priority The demand priority (higher = more wanted).
+     */
+    request(productLocalID: number, priority: number): void;
+    /**
+     * @return {number} Products awaiting admission (not yet prefetched).
+     */
+    get pendingCount(): number;
+    /**
+     * Run one admission cycle (see class docs). Coalesces with an in-flight
+     * cycle.
+     *
+     * @return {Promise<PumpResult>} The cycle's outcome.
+     */
+    pump(): Promise<PumpResult>;
+    /**
+     * One cycle: select top batch → prefetch → forward + queue pump.
+     *
+     * @return {Promise<PumpResult>} The cycle's outcome.
+     */
+    private pumpCycle_;
+    /**
+     * Remove and return the top-priority pending entries, up to the batch cap.
+     *
+     * @return {[number, number][]} `[productLocalID, priority]` pairs.
+     */
+    private takeTopPending_;
+}
+//# sourceMappingURL=demand_residency_pump.d.ts.map

package/compiled/src/core/demand_residency_pump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demand_residency_pump.d.ts","sourceRoot":"","sources":["../../../src/core/demand_residency_pump.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAG7D;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAElC;;;;;;OAMG;IACH,uBAAuB,CAAE,OAAO,EAAE,MAAM,GAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAGD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IAEzB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAA;IAEjB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAA;CACzB;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,mBAAmB;IAa5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbzB,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,SAAS,CAAiC;IAElD;;;;OAIG;gBAEgB,MAAM,EAAE,mBAAmB,EAC3B,WAAW,EAAE,mBAAmB,EAChC,MAAM,GAAE,MAAsB;IAOjD;;;;;;;OAOG;IACI,OAAO,CAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAI,IAAI;IAchE;;OAEG;IACH,IAAW,YAAY,IAAI,MAAM,CAEhC;IAED;;;;;OAKG;IACI,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAalC;;;;OAIG;YACW,UAAU;IAkCxB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CAkBxB"}

package/compiled/src/core/demand_residency_pump.js

@@ -0,0 +1,120 @@
+// Defaults chosen for frame-cooperative pumping: enough per cycle to fill
+// quickly, small enough that a cycle stays well under a frame budget once
+// extraction costs are real. Both are tunable per call site.
+const DEFAULT_BATCH = 32;
+/**
+ * Admission + prefetch orchestration in front of a {@link DemandGeometryQueue}.
+ *
+ * Consumers `request()` products as demand changes (the pump owns admission —
+ * don't request on the queue directly); each async `pump()` cycle:
+ *
+ *  1. selects the top-priority pending batch,
+ *  2. awaits source residency for the batch (failures re-queue for retry
+ *     and are reported, never thrown — one bad range must not stall the
+ *     viewport),
+ *  3. forwards the resident products to the queue and runs its synchronous
+ *     pump under the same batch cap.
+ *
+ * Re-entrant calls coalesce: a `pump()` while one is in flight returns the
+ * in-flight cycle's promise rather than interleaving prefetch batches.
+ * Products already resident in the queue skip prefetch entirely (their
+ * ranking refresh is forwarded immediately).
+ */
+export class DemandResidencyPump {
+    /**
+     * @param queue_ The synchronous demand queue (extraction + budget).
+     * @param prefetcher_ Source-byte residency (the model / buffer provider).
+     * @param batch_ Max products prefetched + extracted per pump cycle.
+     */
+    constructor(queue_, prefetcher_, batch_ = DEFAULT_BATCH) {
+        this.queue_ = queue_;
+        this.prefetcher_ = prefetcher_;
+        this.batch_ = batch_;
+        /** Pending admission: product localID → highest requested priority. */
+        this.pending_ = new Map();
+        if (batch_ < 1) {
+            throw new Error(`Invalid batch ${batch_}`);
+        }
+    }
+    /**
+     * Request a product at a demand priority. Resident products forward
+     * immediately (ranking refresh); others queue for the next pump cycle at
+     * the highest priority requested so far.
+     *
+     * @param productLocalID The product to materialise.
+     * @param priority The demand priority (higher = more wanted).
+     */
+    request(productLocalID, priority) {
+        if (this.queue_.isResident(productLocalID)) {
+            this.queue_.request(productLocalID, priority);
+            return;
+        }
+        const existing = this.pending_.get(productLocalID);
+        this.pending_.set(productLocalID, existing === void 0 ? priority : Math.max(existing, priority));
+    }
+    /**
+     * @return {number} Products awaiting admission (not yet prefetched).
+     */
+    get pendingCount() {
+        return this.pending_.size;
+    }
+    /**
+     * Run one admission cycle (see class docs). Coalesces with an in-flight
+     * cycle.
+     *
+     * @return {Promise<PumpResult>} The cycle's outcome.
+     */
+    pump() {
+        if (this.inFlight_ !== void 0) {
+            return this.inFlight_;
+        }
+        this.inFlight_ = this.pumpCycle_().finally(() => {
+            this.inFlight_ = void 0;
+        });
+        return this.inFlight_;
+    }
+    /**
+     * One cycle: select top batch → prefetch → forward + queue pump.
+     *
+     * @return {Promise<PumpResult>} The cycle's outcome.
+     */
+    async pumpCycle_() {
+        const batch = this.takeTopPending_();
+        if (batch.length === 0) {
+            // Nothing to admit; still give the queue a chance to fill from its own
+            // pending set (e.g. entries deferred by an earlier budget refusal).
+            return { extracted: this.queue_.pump(this.batch_), prefetchFailures: 0 };
+        }
+        const outcomes = await Promise.allSettled(batch.map(([productLocalID]) => this.prefetcher_.ensureResidentByLocalID(productLocalID)));
+        let prefetchFailures = 0;
+        for (let where = 0; where < batch.length; ++where) {
+            const [productLocalID, priority] = batch[where];
+            if (outcomes[where].status === 'fulfilled') {
+                this.queue_.request(productLocalID, priority);
+                continue;
+            }
+            // Failed prefetch: re-queue for a later cycle (transient store errors
+            // retry; persistent ones keep surfacing in the failure count).
+            ++prefetchFailures;
+            this.request(productLocalID, priority);
+        }
+        return { extracted: this.queue_.pump(this.batch_), prefetchFailures };
+    }
+    /**
+     * Remove and return the top-priority pending entries, up to the batch cap.
+     *
+     * @return {[number, number][]} `[productLocalID, priority]` pairs.
+     */
+    takeTopPending_() {
+        if (this.pending_.size === 0) {
+            return [];
+        }
+        const entries = [...this.pending_.entries()];
+        entries.sort((a, b) => b[1] - a[1]);
+        const batch = entries.slice(0, this.batch_);
+        for (const [productLocalID] of batch) {
+            this.pending_.delete(productLocalID);
+        }
+        return batch;
+    }
+}

package/compiled/src/core/demand_residency_pump.test.d.ts

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

package/compiled/src/core/demand_residency_pump.test.d.ts.map

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