@bldrs-ai/conway 1.408.1248 → 1.413.1255

package/compiled/src/core/demand_residency_pump.test.js

@@ -0,0 +1,148 @@
+/* eslint-disable no-magic-numbers */
+// Phase B: the pump must guarantee source residency BEFORE the synchronous
+// extract runs, admit strictly by priority under the batch cap, coalesce
+// re-entrant cycles, and survive prefetch failures without stalling.
+import { describe, expect, test } from "@jest/globals";
+import { DemandGeometryQueue } from "./demand_geometry_queue.js";
+import { DemandResidencyPump } from "./demand_residency_pump.js";
+/**
+ * A mock tiles backend that records extraction order and asserts every
+ * extracted product was made resident first.
+ *
+ * @param residentSource Set the prefetcher fills.
+ * @return {object} `{ tiles, extracted }`.
+ */
+function residencyCheckedTiles(residentSource) {
+    const extracted = [];
+    const tiles = {
+        extract(id) {
+            if (!residentSource.has(id)) {
+                throw new Error(`extract(${id}) before source residency`);
+            }
+            extracted.push(id);
+            return 10;
+        },
+        release() { },
+    };
+    return { tiles, extracted };
+}
+/**
+ * A controllable prefetcher: records call order; optionally fails given ids.
+ *
+ * @param residentSource The set fulfilled prefetches add to.
+ * @param failIDs IDs whose prefetch rejects.
+ * @return {object} `{ prefetcher, calls }`.
+ */
+function mockPrefetcher(residentSource, failIDs = new Set()) {
+    const calls = [];
+    const prefetcher = {
+        ensureResidentByLocalID: async (localID) => {
+            calls.push(localID);
+            if (failIDs.has(localID)) {
+                throw new Error(`range fetch failed for ${localID}`);
+            }
+            residentSource.add(localID);
+        },
+    };
+    return { prefetcher, calls };
+}
+describe("DemandResidencyPump", () => {
+    test("prefetches source bytes before any synchronous extract", async () => {
+        const residentSource = new Set();
+        const { tiles, extracted } = residencyCheckedTiles(residentSource);
+        const { prefetcher, calls } = mockPrefetcher(residentSource);
+        const pump = new DemandResidencyPump(new DemandGeometryQueue(tiles, 1000), prefetcher);
+        pump.request(1, 10);
+        pump.request(2, 20);
+        const result = await pump.pump();
+        // The residency-checked tiles throw if this ordering ever breaks.
+        expect(result.extracted).toBe(2);
+        expect(new Set(calls)).toEqual(new Set([1, 2]));
+        expect(extracted).toEqual([2, 1]); // still priority-ordered
+    });
+    test("admits strictly by priority under the batch cap", async () => {
+        const residentSource = new Set();
+        const { tiles, extracted } = residencyCheckedTiles(residentSource);
+        const { prefetcher, calls } = mockPrefetcher(residentSource);
+        const queue = new DemandGeometryQueue(tiles, 1000000);
+        const pump = new DemandResidencyPump(queue, prefetcher, 3);
+        for (let id = 0; id < 10; ++id) {
+            pump.request(id, id); // rising priority: 7, 8, 9 are most wanted
+        }
+        await pump.pump();
+        expect(new Set(calls)).toEqual(new Set([7, 8, 9]));
+        expect(extracted).toEqual([9, 8, 7]);
+        expect(pump.pendingCount).toBe(7);
+        await pump.pump();
+        expect(extracted).toEqual([9, 8, 7, 6, 5, 4]);
+    });
+    test("requesting a resident product refreshes ranking without prefetch", async () => {
+        const residentSource = new Set();
+        const { tiles } = residencyCheckedTiles(residentSource);
+        const { prefetcher, calls } = mockPrefetcher(residentSource);
+        const queue = new DemandGeometryQueue(tiles, 1000);
+        const pump = new DemandResidencyPump(queue, prefetcher);
+        pump.request(1, 10);
+        await pump.pump();
+        expect(calls).toEqual([1]);
+        // Re-request while resident: no new prefetch, no new pending entry.
+        pump.request(1, 99);
+        expect(pump.pendingCount).toBe(0);
+        await pump.pump();
+        expect(calls).toEqual([1]);
+    });
+    test("a failed prefetch re-queues and later retries; others proceed", async () => {
+        const residentSource = new Set();
+        const { tiles, extracted } = residencyCheckedTiles(residentSource);
+        const failIDs = new Set([2]);
+        const { prefetcher } = mockPrefetcher(residentSource, failIDs);
+        const pump = new DemandResidencyPump(new DemandGeometryQueue(tiles, 1000), prefetcher);
+        pump.request(1, 10);
+        pump.request(2, 20);
+        const first = await pump.pump();
+        expect(first.prefetchFailures).toBe(1);
+        expect(extracted).toEqual([1]);
+        expect(pump.pendingCount).toBe(1); // 2 re-queued
+        // The transient failure clears; the retry succeeds.
+        failIDs.clear();
+        const second = await pump.pump();
+        expect(second.prefetchFailures).toBe(0);
+        expect(extracted).toEqual([1, 2]);
+    });
+    test("re-entrant pump calls coalesce onto the in-flight cycle", async () => {
+        const residentSource = new Set();
+        const { tiles } = residencyCheckedTiles(residentSource);
+        const { prefetcher, calls } = mockPrefetcher(residentSource);
+        const pump = new DemandResidencyPump(new DemandGeometryQueue(tiles, 1000), prefetcher);
+        pump.request(1, 10);
+        const a = pump.pump();
+        const b = pump.pump();
+        expect(b).toBe(a); // same promise, no interleaved second cycle
+        await a;
+        expect(calls).toEqual([1]);
+        // After settling, pump() starts a fresh cycle.
+        pump.request(2, 5);
+        await pump.pump();
+        expect(calls).toEqual([1, 2]);
+    });
+    test("an empty admission cycle still drains the queue-side pending set", async () => {
+        const residentSource = new Set([1, 2]);
+        const { tiles, extracted } = residencyCheckedTiles(residentSource);
+        const { prefetcher } = mockPrefetcher(residentSource);
+        // Tiny budget: only one of the two fits per pump; the loser stays
+        // pending inside the QUEUE (deferred by budget), not the pump.
+        const queue = new DemandGeometryQueue(tiles, 10);
+        const pump = new DemandResidencyPump(queue, prefetcher);
+        pump.request(1, 10);
+        pump.request(2, 20);
+        await pump.pump();
+        expect(extracted).toEqual([2]);
+        expect(queue.stats.pendingCount).toBe(1);
+        // No new admissions; the cycle still gives the queue its pump call.
+        // (1 cannot displace 2 at this budget, so it stays pending — the point
+        // is the queue got the chance.)
+        const result = await pump.pump();
+        expect(result.extracted).toBe(0);
+        expect(queue.stats.pendingCount).toBe(1);
+    });
+});

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

@@ -0,0 +1,110 @@
+import { ChunkedPool } from "./mem/chunked_pool.js";
+import { GeometryAsset, GeometryTilePool } from "./geometry_tile_pool.js";
+/**
+ * The wasm module's geometry tile pool surface (conway-geom
+ * `tile_pool_api.h` via the embind bindings in conway-api.cpp) — Phase B of
+ * the demand-geometry track. Typed narrowly here rather than through the
+ * vendored module d.ts; asset ids and sizes cross the boundary as JS numbers
+ * (< 2^53 by construction).
+ *
+ * Division of labour (see "Resident memory: two regimes" in the design doc):
+ * the TS side (`ChunkedPool` + `SharedAssetPool` + `GeometryTilePool`) is the
+ * accounting/policy layer — it holds no payload bytes — while the wasm
+ * `TilePool` owns the physical chunks. In this composition the TS layer calls
+ * `materialize`/`discard` exactly once per residency, so the wasm-side
+ * refcount stays at 1 for TS-managed tiles; the wasm refcounting exists for
+ * future direct-C++ holders, not for this path.
+ */
+export interface GeometryTilePoolBindings {
+    initGeometryTilePool(budgetBytes: number, chunkBytes: number): boolean;
+    geometryTilePoolInitialized(): boolean;
+    commitGeometryTileBytes(assetID: number, sourceAddress: number, byteLength: number): boolean;
+    retainGeometryTile(assetID: number): boolean;
+    releaseGeometryTile(assetID: number): boolean;
+    geometryTileResident(assetID: number): boolean;
+    geometryTileRefCount(assetID: number): number;
+    geometryTileByteSize(assetID: number): number;
+    geometryTileSegmentCount(assetID: number): number;
+    geometryTileSegmentAddress(assetID: number, segment: number): number;
+    geometryTileSegmentByteLength(assetID: number, segment: number): number;
+    geometryTileVertexByteLength(assetID: number): number;
+    geometryTileIndexByteLength(assetID: number): number;
+    geometryTilePoolBytesInUse(): number;
+    geometryTilePoolTotalBytes(): number;
+    geometryTilePoolFreeChunks(): number;
+    geometryTilePoolFailedCommits(): number;
+}
+/**
+ * The domain extractor the wasm-backed source delegates to: which assets a
+ * product is made of, and how to run the wasm extract → tessellate →
+ * `commitGeometryTile` for one asset. Implemented over the real extraction
+ * pipeline in the Phase B wiring of `IfcModelGeometry`; tests use recording
+ * fakes.
+ */
+export interface TileAssetExtractor {
+    /**
+     * The assets (representation geometries) a product requires resident,
+     * with their reified byte sizes. Mapped items return the same assetID from
+     * many products — the sharing the pools are built around.
+     *
+     * @param productLocalID The product's local ID.
+     * @return {GeometryAsset<number>[]} The product's assets.
+     */
+    assetsOf(productLocalID: number): GeometryAsset<number>[];
+    /**
+     * Extract + tessellate one asset and commit its reified payload into the
+     * wasm tile pool (`commitGeometryTile`). Called exactly once per residency.
+     * Must throw if the commit fails — under the budget invariant it cannot,
+     * so a failure is a contract violation, not a recoverable state.
+     *
+     * @param assetID The asset to materialise.
+     */
+    extractIntoTile(assetID: number): void;
+}
+/**
+ * The Phase B backend composition: the TS accounting stack
+ * (`ChunkedPool` → `GeometryTilePool`) wired over the wasm tile pool, ready
+ * to hand to `DemandGeometryQueue`.
+ */
+export interface WasmTileBackend {
+    /** The TS accounting pool (mirrors the wasm pool's budget and chunking). */
+    pool: ChunkedPool;
+    /** The `GeometryTiles` backend for the demand queue. */
+    tiles: GeometryTilePool<number>;
+}
+/**
+ * Initialise the wasm tile pool and build the TS accounting stack over it,
+ * with identical budget and chunking on both sides so the TS all-or-nothing
+ * admission mirrors the wasm pool's exactly (the queue-budget ≤ pool-budget
+ * invariant then guarantees a wasm commit can never fail mid-extract).
+ *
+ * @param bindings The wasm module's tile pool surface.
+ * @param extractor The domain extract/commit implementation.
+ * @param budgetBytes The resident geometry budget (both sides).
+ * @param chunkBytes The chunk size (both sides; ≥ the wasm 16-byte floor).
+ * @return {WasmTileBackend} The composed backend.
+ */
+export declare function createWasmTileBackend(bindings: GeometryTilePoolBindings, extractor: TileAssetExtractor, budgetBytes: number, chunkBytes: number): WasmTileBackend;
+/**
+ * A resident tile's reified payload, gathered from the wasm pool's segments
+ * into typed arrays ready for GPU upload (three.js BufferAttributes). The
+ * arrays are standalone copies — valid after the tile is evicted.
+ */
+export interface GeometryTilePayload {
+    vertexData: Float32Array;
+    indexData: Uint32Array;
+}
+/**
+ * Gather a resident tile's payload out of the wasm heap by walking its
+ * (generally non-contiguous) segments. This is the copying consumption path;
+ * a zero-copy per-segment upload can walk the same segment accessors
+ * directly.
+ *
+ * @param bindings The wasm module's tile pool surface.
+ * @param heap The module's HEAPU8 view (re-read after any wasm memory
+ * growth; pass the module's current view, do not cache across calls).
+ * @param assetID The resident tile to read.
+ * @return {GeometryTilePayload} The gathered payload.
+ */
+export declare function readGeometryTilePayload(bindings: GeometryTilePoolBindings, heap: Uint8Array, assetID: number): GeometryTilePayload;
+//# sourceMappingURL=geometry_tile_bindings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geometry_tile_bindings.d.ts","sourceRoot":"","sources":["../../../src/core/geometry_tile_bindings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EACL,aAAa,EACb,gBAAgB,EAEjB,MAAM,sBAAsB,CAAA;AAG7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,wBAAwB;IAEvC,oBAAoB,CAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAI,OAAO,CAAA;IACxE,2BAA2B,IAAI,OAAO,CAAA;IAEtC,uBAAuB,CACrB,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAI,OAAO,CAAA;IAEvE,kBAAkB,CAAE,OAAO,EAAE,MAAM,GAAI,OAAO,CAAA;IAC9C,mBAAmB,CAAE,OAAO,EAAE,MAAM,GAAI,OAAO,CAAA;IAC/C,oBAAoB,CAAE,OAAO,EAAE,MAAM,GAAI,OAAO,CAAA;IAChD,oBAAoB,CAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IAC/C,oBAAoB,CAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IAE/C,wBAAwB,CAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IACnD,0BAA0B,CAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IACtE,6BAA6B,CAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IACzE,4BAA4B,CAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IACvD,2BAA2B,CAAE,OAAO,EAAE,MAAM,GAAI,MAAM,CAAA;IAEtD,0BAA0B,IAAI,MAAM,CAAA;IACpC,0BAA0B,IAAI,MAAM,CAAA;IACpC,0BAA0B,IAAI,MAAM,CAAA;IACpC,6BAA6B,IAAI,MAAM,CAAA;CACxC;AAGD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAE,cAAc,EAAE,MAAM,GAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAA;IAE3D;;;;;;;OAOG;IACH,eAAe,CAAE,OAAO,EAAE,MAAM,GAAI,IAAI,CAAA;CACzC;AAGD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAE9B,4EAA4E;IAC5E,IAAI,EAAE,WAAW,CAAA;IAEjB,wDAAwD;IACxD,KAAK,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAA;CAChC;AAGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACjC,QAAQ,EAAE,wBAAwB,EAClC,SAAS,EAAE,kBAAkB,EAC7B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GAAI,eAAe,CAwBxC;AAGD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,YAAY,CAAA;IACxB,SAAS,EAAE,WAAW,CAAA;CACvB;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,wBAAwB,EAClC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,GAAI,mBAAmB,CAyCzC"}

package/compiled/src/core/geometry_tile_bindings.js

@@ -0,0 +1,76 @@
+import { ChunkedPool } from "./mem/chunked_pool.js";
+import { GeometryTilePool, } from "./geometry_tile_pool.js";
+/**
+ * Initialise the wasm tile pool and build the TS accounting stack over it,
+ * with identical budget and chunking on both sides so the TS all-or-nothing
+ * admission mirrors the wasm pool's exactly (the queue-budget ≤ pool-budget
+ * invariant then guarantees a wasm commit can never fail mid-extract).
+ *
+ * @param bindings The wasm module's tile pool surface.
+ * @param extractor The domain extract/commit implementation.
+ * @param budgetBytes The resident geometry budget (both sides).
+ * @param chunkBytes The chunk size (both sides; ≥ the wasm 16-byte floor).
+ * @return {WasmTileBackend} The composed backend.
+ */
+export function createWasmTileBackend(bindings, extractor, budgetBytes, chunkBytes) {
+    // TS pool first: if the config is invalid on the TS side (non-integer or
+    // degenerate chunking), fail before touching the wasm pool so no
+    // initialized-but-unowned wasm region is left behind.
+    const pool = new ChunkedPool(budgetBytes, chunkBytes);
+    if (!bindings.initGeometryTilePool(budgetBytes, chunkBytes)) {
+        throw new Error(`Wasm tile pool rejected init (budget ${budgetBytes}, ` +
+            `chunk ${chunkBytes})`);
+    }
+    const source = {
+        assetsOf: (productLocalID) => extractor.assetsOf(productLocalID),
+        materialize: (assetID) => {
+            extractor.extractIntoTile(assetID);
+        },
+        discard: (assetID) => {
+            bindings.releaseGeometryTile(assetID);
+        },
+    };
+    return { pool, tiles: new GeometryTilePool(pool, source) };
+}
+// Geometry tile payload layout (tile_pool_api.h): 8-byte header of two u32
+// byte lengths, then float vertex data, then u32 index data.
+const TILE_HEADER_BYTES = 8;
+/**
+ * Gather a resident tile's payload out of the wasm heap by walking its
+ * (generally non-contiguous) segments. This is the copying consumption path;
+ * a zero-copy per-segment upload can walk the same segment accessors
+ * directly.
+ *
+ * @param bindings The wasm module's tile pool surface.
+ * @param heap The module's HEAPU8 view (re-read after any wasm memory
+ * growth; pass the module's current view, do not cache across calls).
+ * @param assetID The resident tile to read.
+ * @return {GeometryTilePayload} The gathered payload.
+ */
+export function readGeometryTilePayload(bindings, heap, assetID) {
+    const byteSize = bindings.geometryTileByteSize(assetID);
+    if (byteSize < TILE_HEADER_BYTES) {
+        throw new Error(`Tile ${assetID} is not resident or has no header`);
+    }
+    const gathered = new Uint8Array(byteSize);
+    let copied = 0;
+    const segments = bindings.geometryTileSegmentCount(assetID);
+    for (let segment = 0; segment < segments; ++segment) {
+        const address = bindings.geometryTileSegmentAddress(assetID, segment);
+        const length = bindings.geometryTileSegmentByteLength(assetID, segment);
+        gathered.set(heap.subarray(address, address + length), copied);
+        copied += length;
+    }
+    const view = new DataView(gathered.buffer);
+    const vertexBytes = view.getUint32(0, true);
+    const indexBytes = view.getUint32(4, true);
+    if (TILE_HEADER_BYTES + vertexBytes + indexBytes !== byteSize) {
+        throw new Error(`Tile ${assetID} header inconsistent with payload size ` +
+            `(${vertexBytes} + ${indexBytes} + ${TILE_HEADER_BYTES} !== ${byteSize})`);
+    }
+    // Slice to aligned standalone buffers (gathered's offsets are 8/`+vertex`,
+    // which may misalign Float32Array/Uint32Array views over the same buffer).
+    const vertexData = new Float32Array(gathered.buffer.slice(TILE_HEADER_BYTES, TILE_HEADER_BYTES + vertexBytes));
+    const indexData = new Uint32Array(gathered.buffer.slice(TILE_HEADER_BYTES + vertexBytes, TILE_HEADER_BYTES + vertexBytes + indexBytes));
+    return { vertexData, indexData };
+}

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

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

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

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

package/compiled/src/core/geometry_tile_bindings.test.js

@@ -0,0 +1,211 @@
+/* eslint-disable no-magic-numbers */
+// Phase B: the wasm-backed tile composition — TS accounting over the module's
+// physical pool — and the segment-walk payload reader, verified against a
+// faithful in-memory fake of the embind surface (same layout, same chunking,
+// same non-contiguous segments a fragmented pool produces).
+import { describe, expect, test } from "@jest/globals";
+import { DemandGeometryQueue } from "./demand_geometry_queue.js";
+import { createWasmTileBackend, readGeometryTilePayload, } from "./geometry_tile_bindings.js";
+const HEADER_BYTES = 8;
+/**
+ * A faithful in-memory fake of the wasm tile pool bindings: a byte "heap"
+ * carved into chunks with a LIFO freelist, tiles committed as (possibly
+ * non-contiguous) chunk lists — the same observable behaviour as the C++
+ * TilePool through the embind surface.
+ *
+ * @return {object} `{ bindings, heap, commitPayload }` where commitPayload
+ * scatter-commits a payload built from header+floats+indices.
+ */
+function fakeWasmPool() {
+    const HEAP_BYTES = 64 * 1024;
+    const heap = new Uint8Array(HEAP_BYTES);
+    let chunkBytes = 0;
+    let regionBase = 0;
+    let freeList = [];
+    const tiles = new Map();
+    let failedCommits = 0;
+    let totalChunks = 0;
+    const bindings = {
+        initGeometryTilePool: (budget, chunk) => {
+            if (chunk < 16 || budget < chunk) {
+                return false;
+            }
+            chunkBytes = chunk;
+            totalChunks = Math.floor(budget / chunk);
+            regionBase = 1024; // nonzero base, like a real heap allocation
+            freeList = [];
+            for (let c = totalChunks - 1; c >= 0; --c) {
+                freeList.push(c);
+            }
+            tiles.clear();
+            return true;
+        },
+        geometryTilePoolInitialized: () => chunkBytes > 0,
+        commitGeometryTileBytes: (assetID, sourceAddress, byteLength) => {
+            const needed = Math.ceil(byteLength / chunkBytes);
+            if (tiles.has(assetID) || needed > freeList.length) {
+                ++failedCommits;
+                return false;
+            }
+            const chunks = [];
+            let copied = 0;
+            for (let where = 0; where < needed; ++where) {
+                const chunk = freeList.pop();
+                chunks.push(chunk);
+                const span = Math.min(byteLength - copied, chunkBytes);
+                heap.set(heap.subarray(sourceAddress + copied, sourceAddress + copied + span), regionBase + chunk * chunkBytes);
+                copied += span;
+            }
+            tiles.set(assetID, { chunks, byteSize: byteLength, refCount: 1 });
+            return true;
+        },
+        retainGeometryTile: (assetID) => {
+            const tile = tiles.get(assetID);
+            if (tile === void 0) {
+                return false;
+            }
+            ++tile.refCount;
+            return true;
+        },
+        releaseGeometryTile: (assetID) => {
+            const tile = tiles.get(assetID);
+            if (tile === void 0) {
+                return false;
+            }
+            if (--tile.refCount > 0) {
+                return false;
+            }
+            freeList.push(...tile.chunks);
+            tiles.delete(assetID);
+            return true;
+        },
+        geometryTileResident: (assetID) => tiles.has(assetID),
+        geometryTileRefCount: (assetID) => tiles.get(assetID)?.refCount ?? 0,
+        geometryTileByteSize: (assetID) => tiles.get(assetID)?.byteSize ?? 0,
+        geometryTileSegmentCount: (assetID) => tiles.get(assetID)?.chunks.length ?? 0,
+        geometryTileSegmentAddress: (assetID, segment) => {
+            const tile = tiles.get(assetID);
+            if (tile === void 0 || segment >= tile.chunks.length) {
+                return 0;
+            }
+            return regionBase + tile.chunks[segment] * chunkBytes;
+        },
+        geometryTileSegmentByteLength: (assetID, segment) => {
+            const tile = tiles.get(assetID);
+            if (tile === void 0 || segment >= tile.chunks.length) {
+                return 0;
+            }
+            return Math.min(tile.byteSize - segment * chunkBytes, chunkBytes);
+        },
+        geometryTileVertexByteLength: (assetID) => {
+            const address = bindings.geometryTileSegmentAddress(assetID, 0);
+            return address === 0 ?
+                0 : new DataView(heap.buffer).getUint32(address, true);
+        },
+        geometryTileIndexByteLength: (assetID) => {
+            const address = bindings.geometryTileSegmentAddress(assetID, 0);
+            return address === 0 ?
+                0 : new DataView(heap.buffer).getUint32(address + 4, true);
+        },
+        geometryTilePoolBytesInUse: () => (totalChunks - freeList.length) * chunkBytes,
+        geometryTilePoolTotalBytes: () => totalChunks * chunkBytes,
+        geometryTilePoolFreeChunks: () => freeList.length,
+        geometryTilePoolFailedCommits: () => failedCommits,
+    };
+    // Stage a payload high in the fake heap and scatter-commit it.
+    const commitPayload = (assetID, floats, indices) => {
+        const staging = HEAP_BYTES - 8192;
+        const view = new DataView(heap.buffer, staging);
+        view.setUint32(0, floats.length * 4, true);
+        view.setUint32(4, indices.length * 4, true);
+        floats.forEach((value, i) => view.setFloat32(HEADER_BYTES + i * 4, value, true));
+        indices.forEach((value, i) => view.setUint32(HEADER_BYTES + floats.length * 4 + i * 4, value, true));
+        return bindings.commitGeometryTileBytes(assetID, staging, HEADER_BYTES + floats.length * 4 + indices.length * 4);
+    };
+    return { bindings, heap, commitPayload };
+}
+describe("createWasmTileBackend", () => {
+    test("composes TS accounting over the wasm pool end to end with the queue", () => {
+        const { bindings, commitPayload } = fakeWasmPool();
+        // Two products share one representation; extraction commits real bytes.
+        const composition = {
+            1: [{ assetID: 100, byteSize: 200 }],
+            2: [{ assetID: 100, byteSize: 200 }, { assetID: 200, byteSize: 100 }],
+        };
+        const extracted = [];
+        const extractor = {
+            assetsOf: (id) => composition[id] ?? [],
+            extractIntoTile: (assetID) => {
+                extracted.push(assetID);
+                if (!commitPayload(assetID, [1, 2, 3], [0, 1, 2])) {
+                    throw new Error("commit failed");
+                }
+            },
+        };
+        const backend = createWasmTileBackend(bindings, extractor, 4096, 64);
+        const queue = new DemandGeometryQueue(backend.tiles, 4096);
+        queue.request(1, 10);
+        queue.request(2, 20);
+        queue.pump();
+        // Shared asset extracted once; both tiles resident wasm-side.
+        expect(extracted).toEqual([100, 200]);
+        expect(bindings.geometryTileResident(100)).toBe(true);
+        expect(bindings.geometryTileResident(200)).toBe(true);
+        // Evicting product 2 releases only its unique asset (100 is shared).
+        queue.evictAll();
+        expect(bindings.geometryTileResident(100)).toBe(false);
+        expect(bindings.geometryTileResident(200)).toBe(false);
+        expect(bindings.geometryTilePoolBytesInUse()).toBe(0);
+    });
+    test("rejects a config the wasm pool refuses", () => {
+        const { bindings } = fakeWasmPool();
+        const extractor = {
+            assetsOf: () => [],
+            extractIntoTile: () => { },
+        };
+        expect(() => createWasmTileBackend(bindings, extractor, 4096, 8))
+            .toThrow(/rejected init/);
+    });
+});
+describe("readGeometryTilePayload", () => {
+    test("gathers a multi-segment payload back to exact typed arrays", () => {
+        const { bindings, heap, commitPayload } = fakeWasmPool();
+        bindings.initGeometryTilePool(4096, 64);
+        // 40 floats + 20 indices + header = 248 bytes over 64-byte chunks →
+        // 4 non-contiguous segments with a partial tail.
+        const floats = Array.from({ length: 40 }, (_v, i) => i * 0.5);
+        const indices = Array.from({ length: 20 }, (_v, i) => i * 3);
+        expect(commitPayload(7, floats, indices)).toBe(true);
+        expect(bindings.geometryTileSegmentCount(7)).toBe(4);
+        const payload = readGeometryTilePayload(bindings, heap, 7);
+        expect(Array.from(payload.vertexData)).toEqual(floats);
+        expect(Array.from(payload.indexData)).toEqual(indices);
+        expect(bindings.geometryTileVertexByteLength(7)).toBe(160);
+        expect(bindings.geometryTileIndexByteLength(7)).toBe(80);
+    });
+    test("survives freelist fragmentation (interleaved tiles)", () => {
+        const { bindings, heap, commitPayload } = fakeWasmPool();
+        bindings.initGeometryTilePool(4096, 64);
+        commitPayload(1, [1, 1, 1, 1], [1]);
+        commitPayload(2, Array(30).fill(2), [2, 2]);
+        bindings.releaseGeometryTile(1);
+        // Tile 3's chunks interleave with tile 2's.
+        const floats = Array.from({ length: 25 }, (_v, i) => i + 0.25);
+        commitPayload(3, floats, [9, 8, 7]);
+        const payload = readGeometryTilePayload(bindings, heap, 3);
+        expect(Array.from(payload.vertexData)).toEqual(floats);
+        expect(Array.from(payload.indexData)).toEqual([9, 8, 7]);
+    });
+    test("rejects a non-resident tile and a corrupt header", () => {
+        const { bindings, heap, commitPayload } = fakeWasmPool();
+        bindings.initGeometryTilePool(4096, 64);
+        expect(() => readGeometryTilePayload(bindings, heap, 42))
+            .toThrow(/not resident/);
+        commitPayload(5, [1], [2]);
+        // Corrupt the header's vertex byte length in place.
+        const address = bindings.geometryTileSegmentAddress(5, 0);
+        new DataView(heap.buffer).setUint32(address, 9999, true);
+        expect(() => readGeometryTilePayload(bindings, heap, 5))
+            .toThrow(/inconsistent/);
+    });
+});

package/compiled/src/ifc/ifc_step_model.d.ts

@@ -1,6 +1,7 @@
 import EntityTypesIfc from "./ifc4_gen/entity_types_ifc.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 { IfcModelGeometry } from "./ifc_model_geometry.js";
 import { IfcModelProfile } from "./ifc_model_profile.js";
@@ -32,6 +33,6 @@ export default class IfcStepModel extends StepModelBase<EntityTypesIfc> {
      * @param elementIndex The parsed index to elements in the STEP.
      * @param provider Optional pre-built buffer provider (windowed source).
      */
-    constructor(buffer: Uint8Array | undefined, elementIndex: StepIndexEntry<EntityTypesIfc>[], provider?: StepBufferProvider);
+    constructor(buffer: Uint8Array | undefined, elementIndex: StepIndexEntry<EntityTypesIfc>[] | StepIndexColumns<EntityTypesIfc>, provider?: StepBufferProvider);
 }
 //# sourceMappingURL=ifc_step_model.d.ts.map

package/compiled/src/ifc/ifc_step_model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ifc_step_model.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_step_model.ts"],"names":[],"mappings":"AAAA,OAAO,cAAqC,MAAM,iCAAiC,CAAA;AACnF,OAAO,aAAa,MAAM,yBAAyB,CAAA;AAEnD,OAAO,EAAC,cAAc,EAAC,MAAM,6BAA6B,CAAA;AAE1D,OAAO,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,sBAAsB,MAAM,6BAA6B,CAAA;AAChE,OAAO,cAAc,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AAKjE;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,aAAa,CAAE,cAAc,CAAE;IAEvE,SAAgB,SAAS,EAAE,aAAa,CAAE,cAAc,CAAE,CAAA;IAC1D,SAAgB,mBAAmB,gCAAyB;IAC5D,SAAgB,QAAQ,mBAA+B;IACvD,SAAgB,YAAY,mBAAqC;IACjE,SAAgB,QAAQ,kBAA4B;IACpD,SAAgB,MAAM,iBAA2B;IACjD,SAAgB,aAAa,iBAAuB;IACpD,SAAgB,SAAS,mBAA+B;IACxD,SAAgB,aAAa,mBAAqC;IAClE,SAAgB,cAAc,wBAAiB;IAE/C;;;;;;;;OAQG;gBAEC,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,YAAY,EAAE,cAAc,CAAE,cAAc,CAAE,EAAE,EAChD,QAAQ,CAAC,EAAE,kBAAkB;CAKlC"}
+{"version":3,"file":"ifc_step_model.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_step_model.ts"],"names":[],"mappings":"AAAA,OAAO,cAAqC,MAAM,iCAAiC,CAAA;AACnF,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,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,sBAAsB,MAAM,6BAA6B,CAAA;AAChE,OAAO,cAAc,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AAKjE;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,aAAa,CAAE,cAAc,CAAE;IAEvE,SAAgB,SAAS,EAAE,aAAa,CAAE,cAAc,CAAE,CAAA;IAC1D,SAAgB,mBAAmB,gCAAyB;IAC5D,SAAgB,QAAQ,mBAA+B;IACvD,SAAgB,YAAY,mBAAqC;IACjE,SAAgB,QAAQ,kBAA4B;IACpD,SAAgB,MAAM,iBAA2B;IACjD,SAAgB,aAAa,iBAAuB;IACpD,SAAgB,SAAS,mBAA+B;IACxD,SAAgB,aAAa,mBAAqC;IAClE,SAAgB,cAAc,wBAAiB;IAE/C;;;;;;;;OAQG;gBAEC,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,YAAY,EAAE,cAAc,CAAE,cAAc,CAAE,EAAE,GAAG,gBAAgB,CAAE,cAAc,CAAE,EACrF,QAAQ,CAAC,EAAE,kBAAkB;CAKlC"}

package/compiled/src/ifc/ifc_step_model.js

@@ -33,6 +33,6 @@ export default class IfcStepModel extends StepModelBase {
         this.materials = new IfcMaterialCache(this);
         this.voidMaterials = new IfcMaterialCache(this, true);
         this.elementTypeIDs = EntityTypesIfc;
-        this.typeIndex = indexerInstance.create(elementIndex);
+        this.typeIndex = indexerInstance.createFor(elementIndex);
     }
 }

package/compiled/src/ifc/ifc_step_parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ifc_step_parser.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_step_parser.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,2BAA2B,CAAA;AACrD,OAAO,UAAU,EAAE,EAAC,qBAAqB,EAAE,WAAW,EAAC,MAAM,6BAA6B,CAAA;AAC1F,OAAO,cAAc,MAAM,iCAAiC,CAAA;AAE5D,OAAO,YAAY,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAExD,OAAO,EACL,qBAAqB,EAEtB,MAAM,8BAA8B,CAAA;AAOrC;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,UAAU,CAAE,cAAc,CAAE;IACrE;;OAEG;;IAKH;;;;;OAKG;IACH,gBAAuB,QAAQ,gBAAsB;IAErD;;;;;;;OAOG;IACI,gBAAgB,CACnB,KAAK,EAAE,aAAa,EACpB,UAAU,CAAC,EAAE,qBAAqB,GAAI,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC;IAMjF;;;;;;;;OAQG;IACU,qBAAqB,CAC9B,KAAK,EAAE,aAAa,EACpB,UAAU,CAAC,EAAE,qBAAqB,GAClC,OAAO,CAAC,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;IAMpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,kBAAkB,CACrB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,qBAAqB,EAC5B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE,GACzE;QAAC,WAAW;QAAE,YAAY,GAAG,SAAS;KAAC;CAgB5C"}
+{"version":3,"file":"ifc_step_parser.d.ts","sourceRoot":"","sources":["../../../src/ifc/ifc_step_parser.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,2BAA2B,CAAA;AACrD,OAAO,UAAU,EAAE,EAAC,qBAAqB,EAAE,WAAW,EAAC,MAAM,6BAA6B,CAAA;AAC1F,OAAO,cAAc,MAAM,iCAAiC,CAAA;AAE5D,OAAO,YAAY,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAExD,OAAO,EACL,qBAAqB,EAEtB,MAAM,8BAA8B,CAAA;AAOrC;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,UAAU,CAAE,cAAc,CAAE;IACrE;;OAEG;;IAKH;;;;;OAKG;IACH,gBAAuB,QAAQ,gBAAsB;IAErD;;;;;;;OAOG;IACI,gBAAgB,CACnB,KAAK,EAAE,aAAa,EACpB,UAAU,CAAC,EAAE,qBAAqB,GAAI,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC;IAMjF;;;;;;;;OAQG;IACU,qBAAqB,CAC9B,KAAK,EAAE,aAAa,EACpB,UAAU,CAAC,EAAE,qBAAqB,GAClC,OAAO,CAAC,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;IAMpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,kBAAkB,CACrB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,qBAAqB,EAC5B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE,GACzE;QAAC,WAAW;QAAE,YAAY,GAAG,SAAS;KAAC;CAkB5C"}

package/compiled/src/ifc/ifc_step_parser.js

@@ -1,7 +1,7 @@
 import StepParser from "../step/parsing/step_parser.js";
 import EntitTypesIfcSearch from "./ifc4_gen/entity_types_search.gen.js";
 import IfcStepModel from "./ifc_step_model.js";
-import { buildIndexStreaming } from "../step/parsing/streaming_index_builder.js";
+import { buildColumnarIndexStreaming } from "../step/parsing/streaming_index_builder.js";
 import { WindowedStepBufferProvider, } from "../step/step_buffer_provider.js";
 /** Default moving-window size for the streaming index build (1 MiB). */
 // eslint-disable-next-line no-magic-numbers
@@ -72,9 +72,11 @@ class IfcStepParser extends StepParser {
             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);
+        // Columnar build (M7): the index goes straight into SoA columns — the
+        // per-record object phase never exists, so peak heap is window + columns.
+        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)];
     }
 }
 /**

package/compiled/src/step/indexing/step_type_indexer.d.ts

@@ -1,4 +1,5 @@
 import { MultiIndexSet } from "../../indexing/multi_index_set.js";
+import { StepIndexColumns } from "../parsing/columnar_index.js";
 import { StepIndexEntry } from "../parsing/step_parser.js";
 /**
  * Indexes STEP by type so that it can be searched by type.
@@ -11,6 +12,25 @@ export declare class StepTypeIndexer<TypeIDType extends number> {
      * @param typeCount The number of types that will be indexed.
      */
     constructor(typeCount: number);
+    /**
+     * 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: StepIndexEntry<TypeIDType>[] | StepIndexColumns<TypeIDType>): MultiIndexSet<TypeIDType>;
+    /**
+     * 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: StepIndexColumns<TypeIDType>): MultiIndexSet<TypeIDType>;
     /**
      * Create a type index from a set of parsed STEP elements.
      *