@bldrs-ai/conway 1.389.1221 → 1.394.1504

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/core/geometry_tile_pool.d.ts

@@ -0,0 +1,99 @@
+import { GeometryTiles } from "./demand_geometry_queue.js";
+import { ChunkedPool } from "./mem/chunked_pool.js";
+import { SharedAssetPool } from "./mem/shared_asset_pool.js";
+/**
+ * One shareable geometry payload an instance needs resident: the asset's
+ * identity and its byte size. For IFC, the asset is a representation's
+ * tessellated geometry and `byteSize` comes from the wasm-side extract.
+ */
+export interface GeometryAsset<AssetID> {
+    assetID: AssetID;
+    byteSize: number;
+}
+/**
+ * The domain half the tile pool delegates to: what assets an instance is made
+ * of, and how to materialise / discard one asset's payload. This is the seam
+ * the production conway-geom surface implements (extract → tessellate into
+ * the asset's chunks; discard on last release); tests implement it with
+ * recording mocks.
+ */
+export interface InstanceAssetSource<AssetID> {
+    /**
+     * The assets an instance requires resident, with their byte sizes. For a
+     * simple product this is one asset; mapped/instanced representations return
+     * the same assetID from many instances — that sharing is the point.
+     *
+     * @param instanceID The instance (product local ID in the geometry case).
+     * @return {GeometryAsset<AssetID>[]} The instance's assets.
+     */
+    assetsOf(instanceID: number): GeometryAsset<AssetID>[];
+    /**
+     * Materialise an asset's payload (called exactly once per residency, on
+     * the 0→1 reference). In production: run the wasm extract/tessellate and
+     * write the result into the asset's pool chunks.
+     *
+     * @param assetID The asset to materialise.
+     */
+    materialize(assetID: AssetID): void;
+    /**
+     * Discard an asset's payload (called exactly once per residency, on the
+     * 1→0 reference, after its chunks are already back in the pool).
+     *
+     * @param assetID The asset to discard.
+     */
+    discard(assetID: AssetID): void;
+}
+/**
+ * The geometry narrowing of the general memory system (`src/core/mem/`): a
+ * {@link GeometryTiles} backend where a product's "tile" is a set of
+ * refcounted, chunk-resident **assets** in a {@link SharedAssetPool}.
+ *
+ * Composed with {@link DemandGeometryQueue} this completes the M3 resident
+ * design: the queue owns demand ordering and the logical budget; this pool
+ * owns physical residency. Two accounting views, one invariant:
+ *
+ * - **Logical (queue-side):** `extract` charges an instance the full
+ *   chunk-rounded cost of *every* asset it references, shared or not. Sharing
+ *   is thus double-charged logically — deliberately conservative: summed
+ *   logical charges always cover physical use, so with the queue's budget set
+ *   to the pool's budget, an acquire can never fail mid-extract. (Heavy
+ *   sharing under-utilises the logical budget; the production wiring can
+ *   widen the queue budget once measured. The safe direction first.)
+ * - **Physical (pool-side):** `bytesInUse` counts real chunks. Shared assets
+ *   are stored once, refcounted, and freed only on the last release — so
+ *   evicting product A never discards the representation product B still
+ *   renders (the mapped-item correctness rule, held structurally).
+ */
+export declare class GeometryTilePool<AssetID> implements GeometryTiles {
+    private readonly assets_;
+    private readonly source_;
+    /** Assets each extracted instance holds references on. */
+    private readonly held_;
+    /**
+     * @param pool The chunk pool residents live in.
+     * @param source The domain half (asset composition + materialise/discard).
+     */
+    constructor(pool: ChunkedPool, source: InstanceAssetSource<AssetID>);
+    /**
+     * @return {SharedAssetPool<AssetID>} The refcounted asset layer (physical
+     * accounting lives here / on its pool).
+     */
+    get assets(): SharedAssetPool<AssetID>;
+    /**
+     * Materialise an instance's tile: take a reference on each of its assets,
+     * materialising the ones not yet resident.
+     *
+     * @param instanceID The instance (product local ID).
+     * @return {number} The instance's logical byte cost (chunk-rounded, every
+     * asset fully charged — see class docs for why sharing is double-charged).
+     */
+    extract(instanceID: number): number;
+    /**
+     * Release an instance's tile: drop the reference on each of its assets,
+     * discarding those this instance was the last holder of.
+     *
+     * @param instanceID The instance (product local ID).
+     */
+    release(instanceID: number): void;
+}
+//# sourceMappingURL=geometry_tile_pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geometry_tile_pool.d.ts","sourceRoot":"","sources":["../../../src/core/geometry_tile_pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGzD;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAGD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO;IAE1C;;;;;;;OAOG;IACH,QAAQ,CAAE,UAAU,EAAE,MAAM,GAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAA;IAExD;;;;;;OAMG;IACH,WAAW,CAAE,OAAO,EAAE,OAAO,GAAI,IAAI,CAAA;IAErC;;;;;OAKG;IACH,OAAO,CAAE,OAAO,EAAE,OAAO,GAAI,IAAI,CAAA;CAClC;AAGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB,CAAC,OAAO,CAAE,YAAW,aAAa;IAE7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IAEtD,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IAEpE;;;OAGG;gBACU,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,CAAC;IAKpE;;;OAGG;IACH,IAAW,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC,CAE5C;IAED;;;;;;;OAOG;IACI,OAAO,CAAE,UAAU,EAAE,MAAM,GAAI,MAAM;IAoD5C;;;;;OAKG;IACI,OAAO,CAAE,UAAU,EAAE,MAAM,GAAI,IAAI;CAgB3C"}

package/compiled/src/core/geometry_tile_pool.js

@@ -0,0 +1,104 @@
+import { SharedAssetPool } from "./mem/shared_asset_pool.js";
+/**
+ * The geometry narrowing of the general memory system (`src/core/mem/`): a
+ * {@link GeometryTiles} backend where a product's "tile" is a set of
+ * refcounted, chunk-resident **assets** in a {@link SharedAssetPool}.
+ *
+ * Composed with {@link DemandGeometryQueue} this completes the M3 resident
+ * design: the queue owns demand ordering and the logical budget; this pool
+ * owns physical residency. Two accounting views, one invariant:
+ *
+ * - **Logical (queue-side):** `extract` charges an instance the full
+ *   chunk-rounded cost of *every* asset it references, shared or not. Sharing
+ *   is thus double-charged logically — deliberately conservative: summed
+ *   logical charges always cover physical use, so with the queue's budget set
+ *   to the pool's budget, an acquire can never fail mid-extract. (Heavy
+ *   sharing under-utilises the logical budget; the production wiring can
+ *   widen the queue budget once measured. The safe direction first.)
+ * - **Physical (pool-side):** `bytesInUse` counts real chunks. Shared assets
+ *   are stored once, refcounted, and freed only on the last release — so
+ *   evicting product A never discards the representation product B still
+ *   renders (the mapped-item correctness rule, held structurally).
+ */
+export class GeometryTilePool {
+    /**
+     * @param pool The chunk pool residents live in.
+     * @param source The domain half (asset composition + materialise/discard).
+     */
+    constructor(pool, source) {
+        /** Assets each extracted instance holds references on. */
+        this.held_ = new Map();
+        this.assets_ = new SharedAssetPool(pool);
+        this.source_ = source;
+    }
+    /**
+     * @return {SharedAssetPool<AssetID>} The refcounted asset layer (physical
+     * accounting lives here / on its pool).
+     */
+    get assets() {
+        return this.assets_;
+    }
+    /**
+     * Materialise an instance's tile: take a reference on each of its assets,
+     * materialising the ones not yet resident.
+     *
+     * @param instanceID The instance (product local ID).
+     * @return {number} The instance's logical byte cost (chunk-rounded, every
+     * asset fully charged — see class docs for why sharing is double-charged).
+     */
+    extract(instanceID) {
+        if (this.held_.has(instanceID)) {
+            throw new Error(`Instance ${instanceID} already extracted`);
+        }
+        const assets = this.source_.assetsOf(instanceID);
+        const pool = this.assets_.pool;
+        // Validate and price every asset BEFORE taking any references, so a bad
+        // byte size (a source bug) throws at zero state instead of mid-extract
+        // with references already taken. chunkRound throws on negatives.
+        let logicalBytes = 0;
+        for (const asset of assets) {
+            logicalBytes += pool.chunkRound(asset.byteSize);
+        }
+        for (const asset of assets) {
+            const { retained, wasAbsent } = this.assets_.retain(asset.assetID, asset.byteSize);
+            if (!retained) {
+                // Unwind references already taken so a failed extract has no effect —
+                // keeping the materialize/discard pairing: an asset this unwind takes
+                // to zero references must be discarded like any other last release.
+                for (const taken of assets) {
+                    if (taken === asset) {
+                        break;
+                    }
+                    if (this.assets_.release(taken.assetID)) {
+                        this.source_.discard(taken.assetID);
+                    }
+                }
+                throw new Error(`Geometry pool exhausted materialising instance ${instanceID} — ` +
+                    "the scheduler budget must not exceed the pool budget");
+            }
+            if (wasAbsent) {
+                this.source_.materialize(asset.assetID);
+            }
+        }
+        this.held_.set(instanceID, assets);
+        return logicalBytes;
+    }
+    /**
+     * Release an instance's tile: drop the reference on each of its assets,
+     * discarding those this instance was the last holder of.
+     *
+     * @param instanceID The instance (product local ID).
+     */
+    release(instanceID) {
+        const assets = this.held_.get(instanceID);
+        if (assets === void 0) {
+            throw new Error(`Release of un-extracted instance ${instanceID}`);
+        }
+        this.held_.delete(instanceID);
+        for (const asset of assets) {
+            if (this.assets_.release(asset.assetID)) {
+                this.source_.discard(asset.assetID);
+            }
+        }
+    }
+}

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

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

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

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

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

@@ -0,0 +1,180 @@
+/* eslint-disable no-magic-numbers */
+// M3 production design: the geometry narrowing of the mem system, alone and
+// composed with DemandGeometryQueue. The load-bearing assertions: shared
+// representations are stored once and never freed while any product still
+// holds them, and the queue's logical budget always covers the pool's
+// physical use (so an extract can never blow the pool mid-flight).
+import { describe, expect, test } from "@jest/globals";
+import { DemandGeometryQueue } from "./demand_geometry_queue.js";
+import { GeometryTilePool } from "./geometry_tile_pool.js";
+import { ChunkedPool } from "./mem/chunked_pool.js";
+/**
+ * A recording mock of the domain half: instance → assets from a fixture map,
+ * with materialize/discard calls captured.
+ *
+ * @param composition Instance → assets fixture.
+ * @return {object} `{ source, materialized, discarded }`.
+ */
+function mockSource(composition) {
+    const materialized = [];
+    const discarded = [];
+    const source = {
+        assetsOf: (instanceID) => composition[instanceID] ?? [],
+        materialize: (assetID) => {
+            materialized.push(assetID);
+        },
+        discard: (assetID) => {
+            discarded.push(assetID);
+        },
+    };
+    return { source, materialized, discarded };
+}
+describe("GeometryTilePool", () => {
+    test("a shared representation is materialised once and stored once", () => {
+        // Products 1 and 2 both instance rep-X (mapped item); 2 also has its own.
+        const { source, materialized } = mockSource({
+            1: [{ assetID: "rep-X", byteSize: 100 }],
+            2: [{ assetID: "rep-X", byteSize: 100 }, { assetID: "rep-Y", byteSize: 100 }],
+        });
+        const tiles = new GeometryTilePool(new ChunkedPool(1000, 100), source);
+        tiles.extract(1);
+        tiles.extract(2);
+        expect(materialized).toEqual(["rep-X", "rep-Y"]);
+        // Physically: two assets, 200 bytes — not 300.
+        expect(tiles.assets.pool.bytesInUse).toBe(200);
+        expect(tiles.assets.refCountOf("rep-X")).toBe(2);
+    });
+    test("evicting one product never discards a representation another still renders", () => {
+        const { source, discarded } = mockSource({
+            1: [{ assetID: "rep-X", byteSize: 100 }],
+            2: [{ assetID: "rep-X", byteSize: 100 }],
+        });
+        const tiles = new GeometryTilePool(new ChunkedPool(1000, 100), source);
+        tiles.extract(1);
+        tiles.extract(2);
+        tiles.release(1);
+        expect(discarded).toEqual([]);
+        expect(tiles.assets.isResident("rep-X")).toBe(true);
+        tiles.release(2);
+        expect(discarded).toEqual(["rep-X"]);
+        expect(tiles.assets.pool.bytesInUse).toBe(0);
+    });
+    test("extract charges the logical (chunk-rounded, fully-charged) cost", () => {
+        const { source } = mockSource({
+            1: [{ assetID: "a", byteSize: 150 }, { assetID: "b", byteSize: 10 }],
+            2: [{ assetID: "a", byteSize: 150 }],
+        });
+        const tiles = new GeometryTilePool(new ChunkedPool(1000, 100), source);
+        // 150 → 200 rounded, 10 → 100 rounded.
+        expect(tiles.extract(1)).toBe(300);
+        // Sharing is deliberately double-charged logically (conservative)...
+        expect(tiles.extract(2)).toBe(200);
+        // ...while physical stays single-stored.
+        expect(tiles.assets.pool.bytesInUse).toBe(300);
+    });
+    test("a failed extract unwinds cleanly, discarding what it materialised", () => {
+        // Asset a fits; asset b cannot (pool holds 2 chunks, b needs 3). The
+        // extract must throw, and the unwind must keep the materialize/discard
+        // pairing for a (which it took to zero references) and leave the pool
+        // exactly as before — a failed extract has no effect.
+        const { source, materialized, discarded } = mockSource({
+            1: [{ assetID: "a", byteSize: 100 }, { assetID: "b", byteSize: 300 }],
+        });
+        const pool = new ChunkedPool(200, 100);
+        const tiles = new GeometryTilePool(pool, source);
+        expect(() => tiles.extract(1)).toThrow(/exhausted/);
+        expect(materialized).toEqual(["a"]);
+        expect(discarded).toEqual(["a"]);
+        expect(pool.bytesInUse).toBe(0);
+        expect(tiles.assets.isResident("a")).toBe(false);
+    });
+    test("a failed extract never discards an asset another instance still holds", () => {
+        // Instance 1 holds shared. Instance 2 wants shared + big; big fails.
+        // The unwind drops 2's reference on shared but must NOT discard it —
+        // instance 1 still renders it.
+        const { source, discarded } = mockSource({
+            1: [{ assetID: "shared", byteSize: 100 }],
+            2: [{ assetID: "shared", byteSize: 100 }, { assetID: "big", byteSize: 300 }],
+        });
+        const pool = new ChunkedPool(200, 100);
+        const tiles = new GeometryTilePool(pool, source);
+        tiles.extract(1);
+        expect(() => tiles.extract(2)).toThrow(/exhausted/);
+        expect(discarded).toEqual([]);
+        expect(tiles.assets.isResident("shared")).toBe(true);
+        expect(tiles.assets.refCountOf("shared")).toBe(1);
+        expect(pool.bytesInUse).toBe(100);
+    });
+    test("double extract and unmatched release are errors", () => {
+        const { source } = mockSource({ 1: [{ assetID: "a", byteSize: 10 }] });
+        const tiles = new GeometryTilePool(new ChunkedPool(1000, 100), source);
+        tiles.extract(1);
+        expect(() => tiles.extract(1)).toThrow(/already extracted/);
+        expect(() => tiles.release(2)).toThrow(/un-extracted/);
+    });
+    test("a malformed byte size throws before any state changes", () => {
+        // A buggy source returning a negative size must fail at zero state —
+        // no references taken, nothing materialised, pool untouched.
+        const { source, materialized } = mockSource({
+            1: [{ assetID: "ok", byteSize: 100 }, { assetID: "bad", byteSize: -5 }],
+        });
+        const pool = new ChunkedPool(1000, 100);
+        const tiles = new GeometryTilePool(pool, source);
+        expect(() => tiles.extract(1)).toThrow(/Invalid byte size/);
+        expect(materialized).toEqual([]);
+        expect(pool.bytesInUse).toBe(0);
+        expect(tiles.assets.isResident("ok")).toBe(false);
+    });
+    test("composed with the demand queue: budget holds, shared reps survive eviction", () => {
+        // 20 products all sharing one heavy rep, each with a light unique rep —
+        // the mapped-item shape (fixtures, repeated windows).
+        const composition = {};
+        for (let id = 0; id < 20; ++id) {
+            composition[id] = [
+                { assetID: "shared-heavy", byteSize: 400 },
+                { assetID: `unique-${id}`, byteSize: 100 },
+            ];
+        }
+        const { source, materialized, discarded } = mockSource(composition);
+        const pool = new ChunkedPool(4000, 100);
+        const tiles = new GeometryTilePool(pool, source);
+        // Queue budget == pool budget: the safety invariant under test.
+        const queue = new DemandGeometryQueue(tiles, 4000);
+        // Stream demand across all 20 products with rising priority.
+        for (let id = 0; id < 20; ++id) {
+            queue.request(id, id);
+            queue.pump();
+            // Physical use never exceeds the logical budget the queue enforces.
+            expect(pool.bytesInUse).toBeLessThanOrEqual(queue.stats.residentBytes);
+            expect(queue.stats.residentBytes).toBeLessThanOrEqual(4000);
+        }
+        // The shared rep was materialised exactly once across all that churn...
+        expect(materialized.filter((a) => a === "shared-heavy").length).toBe(1);
+        // ...and never discarded, because some product always held it.
+        expect(discarded).not.toContain("shared-heavy");
+        // Evicting everything finally discards it and empties the pool.
+        queue.evictAll();
+        expect(discarded).toContain("shared-heavy");
+        expect(pool.bytesInUse).toBe(0);
+    });
+    test("composed queue at exact pool budget never exhausts the pool", () => {
+        // Every product unique (worst case for the invariant: no sharing slack).
+        const composition = {};
+        for (let id = 0; id < 50; ++id) {
+            composition[id] = [{ assetID: `u-${id}`, byteSize: 190 }];
+        }
+        const { source } = mockSource(composition);
+        const pool = new ChunkedPool(1000, 100);
+        const tiles = new GeometryTilePool(pool, source);
+        const queue = new DemandGeometryQueue(tiles, 1000);
+        // 190 rounds to 200 → 5 tiles fit. Churn all 50 through; extract must
+        // never throw pool-exhausted because logical charges cover physical.
+        for (let id = 0; id < 50; ++id) {
+            queue.request(id, id);
+            queue.pump();
+        }
+        expect(queue.stats.residentCount).toBe(5);
+        expect(pool.bytesInUse).toBe(1000);
+        expect(pool.stats.failedAcquires).toBe(0);
+    });
+});