@bldrs-ai/conway 1.389.1221 → 1.394.1504

package/compiled/src/core/composed_model_skeleton.js

@@ -0,0 +1,66 @@
+/**
+ * A composed view over every model in a {@link ModelRegistry} (M5 / design S3).
+ *
+ * Federation's read side: a site plan that references per-building files, or a
+ * project split across disciplines, is browsed as **one** model whose entities
+ * carry universal {@link EntityAddress}es (`modelURI#expressID`). A type query
+ * here fans out across all registered members and yields addresses, not bare
+ * express IDs — so "every `IfcWall` in the project" spans files, and each
+ * result round-trips back through {@link ModelRegistry.resolve} to the right
+ * model.
+ *
+ * This is the composition scaffold: it unions the members' type skeletons
+ * under the shared address space. The spatial-containment merge (a site's
+ * `IfcRelAggregates` linking to building files) layers on top by resolving the
+ * cross-file references the {@link CrossReferenceRegistry} discovers — the next
+ * increment, gated on the loader registering streamed models here.
+ */
+export class ComposedModelSkeleton {
+    /**
+     * @param registry_ The registry whose models this composes over.
+     */
+    constructor(registry_) {
+        this.registry_ = registry_;
+    }
+    /**
+     * @return {ModelRegistry<H>} The registry backing this composed view.
+     */
+    get registry() {
+        return this.registry_;
+    }
+    /**
+     * Yield the universal address of every entity of the given types across all
+     * registered models.
+     *
+     * @param types The entity constructors to query (subtype closures unioned).
+     * @return {IterableIterator<EntityAddress>} Addresses of matching entities.
+     * @yields {EntityAddress} Each matching entity's universal address.
+     */
+    *entitiesOfType(...types) {
+        for (const modelURI of this.registry_.uris()) {
+            const model = this.registry_.get(modelURI);
+            if (model === void 0) {
+                continue;
+            }
+            for (const expressID of model.expressIDsOfTypes(...types)) {
+                yield { modelURI, expressID };
+            }
+        }
+    }
+    /**
+     * Count entities of the given types across all registered models.
+     *
+     * @param types The entity constructors to count.
+     * @return {number} The total across the federation.
+     */
+    countOfType(...types) {
+        let total = 0;
+        for (const model of this.registry_.models()) {
+            for (const expressID of model.expressIDsOfTypes(...types)) {
+                void expressID;
+                ++total;
+            }
+        }
+        return total;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,69 @@
+/* eslint-disable no-magic-numbers */
+// M5: the composed view fans a type query across every registered model and
+// yields universal addresses, so "every wall in the project" spans files and
+// each result round-trips back through the registry to its model.
+import { describe, expect, test } from "@jest/globals";
+import { ComposedModelSkeleton } from "./composed_model_skeleton.js";
+import { ModelRegistry } from "./model_registry.js";
+import { SharedByteBudget } from "./shared_byte_budget.js";
+/**
+ * A fake type-queryable model returning a fixed express-ID set regardless of
+ * the queried types (the query-closure matching itself is covered by the
+ * incremental-type-index tests; here we exercise cross-model composition).
+ */
+class FakeModel {
+    /**
+     * @param ids The express IDs this model reports for any query.
+     */
+    constructor(ids) {
+        this.ids = ids;
+    }
+    /**
+     * @return {IterableIterator<number>} The fixed express IDs.
+     */
+    *expressIDsOfTypes() {
+        yield* this.ids;
+    }
+}
+// A dummy constructor to satisfy the query signature (unused by FakeModel).
+const ANY_TYPE = { query: [1] };
+describe("ComposedModelSkeleton", () => {
+    /**
+     * A composed view over two fake models.
+     *
+     * @return {ComposedModelSkeleton} The composed view.
+     */
+    function composed() {
+        const registry = new ModelRegistry(new SharedByteBudget(1000));
+        registry.register("site/a.ifc", new FakeModel([1, 2]));
+        registry.register("site/b.ifc", new FakeModel([10, 11, 12]));
+        return new ComposedModelSkeleton(registry);
+    }
+    test("yields universal addresses across every registered model", () => {
+        const view = composed();
+        const addresses = [...view.entitiesOfType(ANY_TYPE)];
+        expect(addresses).toEqual([
+            { modelURI: "site/a.ifc", expressID: 1 },
+            { modelURI: "site/a.ifc", expressID: 2 },
+            { modelURI: "site/b.ifc", expressID: 10 },
+            { modelURI: "site/b.ifc", expressID: 11 },
+            { modelURI: "site/b.ifc", expressID: 12 },
+        ]);
+    });
+    test("counts across the federation", () => {
+        expect(composed().countOfType(ANY_TYPE)).toBe(5);
+    });
+    test("each composed address resolves back to its own model", () => {
+        const view = composed();
+        for (const address of view.entitiesOfType(ANY_TYPE)) {
+            const resolved = view.registry.resolve(address);
+            expect(resolved).toBeDefined();
+            expect(resolved?.expressID).toBe(address.expressID);
+        }
+    });
+    test("an empty registry composes to nothing", () => {
+        const view = new ComposedModelSkeleton(new ModelRegistry(new SharedByteBudget(10)));
+        expect([...view.entitiesOfType(ANY_TYPE)]).toEqual([]);
+        expect(view.countOfType(ANY_TYPE)).toBe(0);
+    });
+});

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

@@ -0,0 +1,147 @@
+/**
+ * Demand-driven, budgeted geometry materialisation (M3).
+ *
+ * The streaming loader inverts geometry: instead of extracting every product
+ * up front, extraction becomes a **cache fill keyed by product**, ordered by
+ * demand (viewport frustum + distance, explicit selection, prefetch hints)
+ * and bounded by an explicit byte budget. This module is the scheduler: a
+ * priority queue over product local IDs plus an evictable resident set, with
+ * the actual extract / release delegated to a pluggable {@link GeometryTiles}.
+ *
+ * The heavy half — the wasm-side extract → tessellate → upload and the
+ * per-product native reclaim — lives behind {@link GeometryTiles}. Its
+ * production implementation needs a **conway-geom API to free one product's
+ * native geometry** (today the wasm heap has no per-product reclaim); scoping
+ * that C++ surface is the M3 blocker tracked in the design doc. This scheduler
+ * is engine-side, fully deterministic, and tested against a mock tiles impl,
+ * so the queue/budget/eviction policy is settled independently of the wasm
+ * work.
+ */
+/**
+ * The per-product geometry work behind the queue. Implementations do the
+ * expensive materialisation; the queue owns only ordering and the budget.
+ */
+export interface GeometryTiles {
+    /**
+     * Materialise a product's geometry tile and return its resident cost in
+     * bytes (GPU/scene + any retained wasm working set the budget should count).
+     * Called at most once per product between evictions.
+     *
+     * @param productLocalID The product's local ID.
+     * @return {number} The tile's resident byte cost (≥ 0).
+     */
+    extract(productLocalID: number): number;
+    /**
+     * Release a product's materialised tile, freeing its resident bytes — the
+     * scene mesh and, crucially, the product's native (wasm) geometry. This is
+     * the per-product reclaim the production conway-geom surface must provide.
+     *
+     * @param productLocalID The product's local ID.
+     */
+    release(productLocalID: number): void;
+}
+/**
+ * Runtime counters for a queue, for tests and telemetry.
+ */
+export interface DemandQueueStats {
+    extractions: number;
+    evictions: number;
+    residentBytes: number;
+    residentCount: number;
+    pendingCount: number;
+}
+/**
+ * A budgeted, demand-ordered geometry materialisation queue.
+ *
+ * Usage: `request(productLocalID, priority)` as demand changes (higher
+ * priority = more wanted); `pump()` to materialise the most-wanted pending
+ * products until the queue drains or the byte budget forces eviction of
+ * lower-priority resident tiles. Re-requesting an evicted product re-fills it.
+ * A steady stream of `request` + `pump` keeps a bounded working set of the
+ * highest-priority products resident — the "full model navigable under a
+ * fixed budget" behaviour.
+ */
+export declare class DemandGeometryQueue {
+    private readonly tiles_;
+    private readonly budgetBytes_;
+    /** Highest priority a product currently wants materialising at. */
+    private readonly pending_;
+    /** Resident tiles by product local ID. */
+    private readonly resident_;
+    private residentBytes_;
+    private extractions_;
+    private evictions_;
+    /**
+     * @param tiles The extract/release backend.
+     * @param budgetBytes Maximum resident tile bytes before eviction kicks in.
+     */
+    constructor(tiles: GeometryTiles, budgetBytes: number);
+    /**
+     * Request a product be materialised at the given demand priority. Updates
+     * the priority if already pending (keeping the higher of the two) or already
+     * resident (so eviction ranks it correctly). Requesting a resident product
+     * does not re-extract it.
+     *
+     * @param productLocalID The product to materialise.
+     * @param priority The demand priority (higher = more wanted).
+     */
+    request(productLocalID: number, priority: number): void;
+    /**
+     * Materialise pending products in descending priority order, evicting the
+     * lowest-priority resident tiles whenever the budget is exceeded. A pending
+     * product whose priority is below every resident tile AND that can't fit is
+     * left pending (it will fill once demand raises it or resident tiles drop).
+     *
+     * @param maxExtractions Optional cap on how many tiles to extract this pump
+     * (e.g. a per-frame budget); unbounded when omitted.
+     * @return {number} The number of tiles extracted this pump.
+     */
+    pump(maxExtractions?: number): number;
+    /**
+     * Evict every resident tile (e.g. on model close), releasing all bytes.
+     */
+    evictAll(): void;
+    /**
+     * @return {boolean} True if the product's tile is resident.
+     * @param productLocalID The product to check.
+     */
+    isResident(productLocalID: number): boolean;
+    /**
+     * @return {DemandQueueStats} A snapshot of runtime counters.
+     */
+    get stats(): DemandQueueStats;
+    /**
+     * Pop the highest-priority pending request. Linear scan — swap for a heap
+     * if a real workload shows the pending set growing large per pump.
+     *
+     * @return {PendingRequest | undefined} The request, or undefined if none.
+     */
+    private popHighestPending_;
+    /**
+     * Ensure there is conceptual room for a tile requested at `priority` by
+     * evicting resident tiles strictly lower in priority while over budget.
+     * Returns false if the budget is full of tiles at least as wanted as this
+     * request (so it shouldn't displace them).
+     *
+     * @param priority The incoming request's priority.
+     * @return {boolean} True if extraction should proceed.
+     */
+    private ensureRoomFor_;
+    /**
+     * Evict lowest-priority resident tiles until within budget (used after an
+     * extraction that pushed us over — e.g. a large tile).
+     */
+    private evictToBudget_;
+    /**
+     * @return {{ productLocalID: number, priority: number } | undefined} The
+     * lowest-priority resident tile, or undefined if none.
+     */
+    private lowestPriorityResident_;
+    /**
+     * Release one resident tile.
+     *
+     * @param productLocalID The tile to evict.
+     */
+    private evictOne_;
+}
+//# sourceMappingURL=demand_geometry_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demand_geometry_queue.d.ts","sourceRoot":"","sources":["../../../src/core/demand_geometry_queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAE5B;;;;;;;OAOG;IACH,OAAO,CAAE,cAAc,EAAE,MAAM,GAAI,MAAM,CAAA;IAEzC;;;;;;OAMG;IACH,OAAO,CAAE,cAAc,EAAE,MAAM,GAAI,IAAI,CAAA;CACxC;AAiBD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;CACrB;AAGD;;;;;;;;;;GAUG;AACH,qBAAa,mBAAmB;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IAErC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAE5D,OAAO,CAAC,cAAc,CAAI;IAE1B,OAAO,CAAC,YAAY,CAAI;IAExB,OAAO,CAAC,UAAU,CAAI;IAEtB;;;OAGG;gBACU,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM;IAUtD;;;;;;;;OAQG;IACI,OAAO,CAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAI,IAAI;IAiBhE;;;;;;;;;OASG;IACI,IAAI,CAAE,cAAc,GAAE,MAAiC,GAAI,MAAM;IAoCxE;;OAEG;IACI,QAAQ,IAAI,IAAI;IASvB;;;OAGG;IACI,UAAU,CAAE,cAAc,EAAE,MAAM,GAAI,OAAO;IAIpD;;OAEG;IACH,IAAW,KAAK,IAAI,gBAAgB,CAQnC;IAED;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAYtB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;OAIG;IACH,OAAO,CAAC,SAAS;CAYlB"}

package/compiled/src/core/demand_geometry_queue.js

@@ -0,0 +1,223 @@
+/**
+ * Demand-driven, budgeted geometry materialisation (M3).
+ *
+ * The streaming loader inverts geometry: instead of extracting every product
+ * up front, extraction becomes a **cache fill keyed by product**, ordered by
+ * demand (viewport frustum + distance, explicit selection, prefetch hints)
+ * and bounded by an explicit byte budget. This module is the scheduler: a
+ * priority queue over product local IDs plus an evictable resident set, with
+ * the actual extract / release delegated to a pluggable {@link GeometryTiles}.
+ *
+ * The heavy half — the wasm-side extract → tessellate → upload and the
+ * per-product native reclaim — lives behind {@link GeometryTiles}. Its
+ * production implementation needs a **conway-geom API to free one product's
+ * native geometry** (today the wasm heap has no per-product reclaim); scoping
+ * that C++ surface is the M3 blocker tracked in the design doc. This scheduler
+ * is engine-side, fully deterministic, and tested against a mock tiles impl,
+ * so the queue/budget/eviction policy is settled independently of the wasm
+ * work.
+ */
+/**
+ * A budgeted, demand-ordered geometry materialisation queue.
+ *
+ * Usage: `request(productLocalID, priority)` as demand changes (higher
+ * priority = more wanted); `pump()` to materialise the most-wanted pending
+ * products until the queue drains or the byte budget forces eviction of
+ * lower-priority resident tiles. Re-requesting an evicted product re-fills it.
+ * A steady stream of `request` + `pump` keeps a bounded working set of the
+ * highest-priority products resident — the "full model navigable under a
+ * fixed budget" behaviour.
+ */
+export class DemandGeometryQueue {
+    /**
+     * @param tiles The extract/release backend.
+     * @param budgetBytes Maximum resident tile bytes before eviction kicks in.
+     */
+    constructor(tiles, budgetBytes) {
+        /** Highest priority a product currently wants materialising at. */
+        this.pending_ = new Map();
+        /** Resident tiles by product local ID. */
+        this.resident_ = new Map();
+        this.residentBytes_ = 0;
+        this.extractions_ = 0;
+        this.evictions_ = 0;
+        if (budgetBytes <= 0) {
+            throw new Error(`Invalid budgetBytes ${budgetBytes}`);
+        }
+        this.tiles_ = tiles;
+        this.budgetBytes_ = budgetBytes;
+    }
+    /**
+     * Request a product be materialised at the given demand priority. Updates
+     * the priority if already pending (keeping the higher of the two) or already
+     * resident (so eviction ranks it correctly). Requesting a resident product
+     * does not re-extract it.
+     *
+     * @param productLocalID The product to materialise.
+     * @param priority The demand priority (higher = more wanted).
+     */
+    request(productLocalID, priority) {
+        const tile = this.resident_.get(productLocalID);
+        if (tile !== void 0) {
+            // Already resident — just refresh its eviction ranking.
+            tile.priority = Math.max(tile.priority, priority);
+            return;
+        }
+        const existing = this.pending_.get(productLocalID);
+        this.pending_.set(productLocalID, existing === void 0 ? priority : Math.max(existing, priority));
+    }
+    /**
+     * Materialise pending products in descending priority order, evicting the
+     * lowest-priority resident tiles whenever the budget is exceeded. A pending
+     * product whose priority is below every resident tile AND that can't fit is
+     * left pending (it will fill once demand raises it or resident tiles drop).
+     *
+     * @param maxExtractions Optional cap on how many tiles to extract this pump
+     * (e.g. a per-frame budget); unbounded when omitted.
+     * @return {number} The number of tiles extracted this pump.
+     */
+    pump(maxExtractions = Number.POSITIVE_INFINITY) {
+        let extractedThisPump = 0;
+        while (extractedThisPump < maxExtractions && this.pending_.size > 0) {
+            const next = this.popHighestPending_();
+            if (next === void 0) {
+                break;
+            }
+            // If the working set is full and this request can't beat the cheapest
+            // evictable (lower-priority) resident tile, stop — nothing more fits.
+            if (!this.ensureRoomFor_(next.priority)) {
+                // Put it back; it stays pending for a future pump.
+                this.pending_.set(next.productLocalID, next.priority);
+                break;
+            }
+            const bytes = this.tiles_.extract(next.productLocalID);
+            this.resident_.set(next.productLocalID, { bytes, priority: next.priority });
+            this.residentBytes_ += bytes;
+            ++this.extractions_;
+            ++extractedThisPump;
+            // A single oversized tile can still exceed budget; evict what we can.
+            this.evictToBudget_();
+        }
+        return extractedThisPump;
+    }
+    /**
+     * Evict every resident tile (e.g. on model close), releasing all bytes.
+     */
+    evictAll() {
+        for (const productLocalID of this.resident_.keys()) {
+            this.tiles_.release(productLocalID);
+            ++this.evictions_;
+        }
+        this.resident_.clear();
+        this.residentBytes_ = 0;
+    }
+    /**
+     * @return {boolean} True if the product's tile is resident.
+     * @param productLocalID The product to check.
+     */
+    isResident(productLocalID) {
+        return this.resident_.has(productLocalID);
+    }
+    /**
+     * @return {DemandQueueStats} A snapshot of runtime counters.
+     */
+    get stats() {
+        return {
+            extractions: this.extractions_,
+            evictions: this.evictions_,
+            residentBytes: this.residentBytes_,
+            residentCount: this.resident_.size,
+            pendingCount: this.pending_.size,
+        };
+    }
+    /**
+     * Pop the highest-priority pending request. Linear scan — swap for a heap
+     * if a real workload shows the pending set growing large per pump.
+     *
+     * @return {PendingRequest | undefined} The request, or undefined if none.
+     */
+    popHighestPending_() {
+        let bestID;
+        let bestPriority = Number.NEGATIVE_INFINITY;
+        for (const [productLocalID, priority] of this.pending_) {
+            if (priority > bestPriority) {
+                bestPriority = priority;
+                bestID = productLocalID;
+            }
+        }
+        if (bestID === void 0) {
+            return void 0;
+        }
+        this.pending_.delete(bestID);
+        return { productLocalID: bestID, priority: bestPriority };
+    }
+    /**
+     * Ensure there is conceptual room for a tile requested at `priority` by
+     * evicting resident tiles strictly lower in priority while over budget.
+     * Returns false if the budget is full of tiles at least as wanted as this
+     * request (so it shouldn't displace them).
+     *
+     * @param priority The incoming request's priority.
+     * @return {boolean} True if extraction should proceed.
+     */
+    ensureRoomFor_(priority) {
+        if (this.residentBytes_ < this.budgetBytes_) {
+            return true;
+        }
+        // Over/at budget: only proceed if there's a lower-priority tile to evict.
+        let evictedAny = false;
+        while (this.residentBytes_ >= this.budgetBytes_) {
+            const victim = this.lowestPriorityResident_();
+            if (victim === void 0 || victim.priority >= priority) {
+                break;
+            }
+            this.evictOne_(victim.productLocalID);
+            evictedAny = true;
+        }
+        return this.residentBytes_ < this.budgetBytes_ || evictedAny;
+    }
+    /**
+     * Evict lowest-priority resident tiles until within budget (used after an
+     * extraction that pushed us over — e.g. a large tile).
+     */
+    evictToBudget_() {
+        while (this.residentBytes_ > this.budgetBytes_) {
+            const victim = this.lowestPriorityResident_();
+            if (victim === void 0) {
+                break;
+            }
+            this.evictOne_(victim.productLocalID);
+        }
+    }
+    /**
+     * @return {{ productLocalID: number, priority: number } | undefined} The
+     * lowest-priority resident tile, or undefined if none.
+     */
+    lowestPriorityResident_() {
+        let worstID;
+        let worstPriority = Number.POSITIVE_INFINITY;
+        for (const [productLocalID, tile] of this.resident_) {
+            if (tile.priority < worstPriority) {
+                worstPriority = tile.priority;
+                worstID = productLocalID;
+            }
+        }
+        return worstID === void 0 ?
+            void 0 : { productLocalID: worstID, priority: worstPriority };
+    }
+    /**
+     * Release one resident tile.
+     *
+     * @param productLocalID The tile to evict.
+     */
+    evictOne_(productLocalID) {
+        const tile = this.resident_.get(productLocalID);
+        if (tile === void 0) {
+            return;
+        }
+        this.tiles_.release(productLocalID);
+        this.resident_.delete(productLocalID);
+        this.residentBytes_ -= tile.bytes;
+        ++this.evictions_;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,133 @@
+/* eslint-disable no-magic-numbers */
+// M3: the demand-geometry scheduler — priority ordering, byte budget, and
+// eviction — tested against a mock tiles backend so the policy is settled
+// independently of the wasm extract/reclaim work.
+import { describe, expect, test } from "@jest/globals";
+import { DemandGeometryQueue } from "./demand_geometry_queue.js";
+/**
+ * A mock tiles backend: every product costs a fixed number of bytes and
+ * records the extract/release calls so tests can assert on them.
+ *
+ * @param costBytes Per-tile resident cost.
+ * @return {object} `{ tiles, extracted, released }`.
+ */
+function mockTiles(costBytes) {
+    const extracted = [];
+    const released = [];
+    const tiles = {
+        extract(id) {
+            extracted.push(id);
+            return costBytes;
+        },
+        release(id) {
+            released.push(id);
+        },
+    };
+    return { tiles, extracted, released };
+}
+describe("DemandGeometryQueue", () => {
+    test("materialises highest-priority requests first", () => {
+        const { tiles, extracted } = mockTiles(10);
+        const q = new DemandGeometryQueue(tiles, 1000);
+        q.request(1, 5);
+        q.request(2, 50);
+        q.request(3, 20);
+        q.pump();
+        // Extracted in descending priority: 2 (50), 3 (20), 1 (5).
+        expect(extracted).toEqual([2, 3, 1]);
+        expect(q.stats.residentCount).toBe(3);
+        expect(q.stats.residentBytes).toBe(30);
+    });
+    test("evicts the lowest-priority tile when the budget is exceeded", () => {
+        const { tiles, released } = mockTiles(100);
+        // Budget holds 3 tiles (300).
+        const q = new DemandGeometryQueue(tiles, 300);
+        for (const [id, pri] of [[1, 10], [2, 20], [3, 30]]) {
+            q.request(id, pri);
+        }
+        q.pump();
+        expect(q.stats.residentCount).toBe(3);
+        // A 4th, higher-priority request must evict the lowest (id 1, pri 10).
+        q.request(4, 40);
+        q.pump();
+        expect(q.isResident(4)).toBe(true);
+        expect(q.isResident(1)).toBe(false);
+        expect(released).toContain(1);
+        expect(q.stats.residentBytes).toBeLessThanOrEqual(300);
+    });
+    test("a request below every resident tile does not displace them", () => {
+        const { tiles, extracted } = mockTiles(100);
+        const q = new DemandGeometryQueue(tiles, 200); // holds 2
+        q.request(1, 50);
+        q.request(2, 40);
+        q.pump();
+        expect(q.stats.residentCount).toBe(2);
+        // Low-priority newcomer can't beat either resident tile → stays pending.
+        q.request(3, 5);
+        const n = q.pump();
+        expect(n).toBe(0);
+        expect(q.isResident(3)).toBe(false);
+        expect(extracted).toEqual([1, 2]);
+        expect(q.stats.pendingCount).toBe(1);
+    });
+    test("re-requesting an evicted product re-extracts it", () => {
+        const { tiles, extracted } = mockTiles(100);
+        const q = new DemandGeometryQueue(tiles, 100); // holds 1
+        q.request(1, 10);
+        q.pump();
+        q.request(2, 20); // evicts 1
+        q.pump();
+        expect(q.isResident(1)).toBe(false);
+        q.request(1, 30); // evicts 2, re-extracts 1
+        q.pump();
+        expect(q.isResident(1)).toBe(true);
+        // 1 extracted twice (first fill, then re-fill after eviction).
+        expect(extracted.filter((id) => id === 1).length).toBe(2);
+    });
+    test("requesting an already-resident product does not re-extract", () => {
+        const { tiles, extracted } = mockTiles(10);
+        const q = new DemandGeometryQueue(tiles, 1000);
+        q.request(1, 10);
+        q.pump();
+        q.request(1, 99); // already resident — just bumps ranking
+        q.pump();
+        expect(extracted).toEqual([1]);
+    });
+    test("a per-pump extraction cap bounds work per call", () => {
+        const { tiles } = mockTiles(1);
+        const q = new DemandGeometryQueue(tiles, 1000000);
+        for (let id = 0; id < 100; ++id) {
+            q.request(id, id);
+        }
+        expect(q.pump(10)).toBe(10);
+        expect(q.stats.residentCount).toBe(10);
+        expect(q.stats.pendingCount).toBe(90);
+    });
+    test("evictAll releases everything", () => {
+        const { tiles, released } = mockTiles(10);
+        const q = new DemandGeometryQueue(tiles, 1000);
+        for (let id = 0; id < 5; ++id) {
+            q.request(id, id);
+        }
+        q.pump();
+        q.evictAll();
+        expect(q.stats.residentCount).toBe(0);
+        expect(q.stats.residentBytes).toBe(0);
+        expect(released.sort()).toEqual([0, 1, 2, 3, 4]);
+    });
+    test("keeps the resident set bounded by the budget across a demand stream", () => {
+        const { tiles } = mockTiles(100);
+        const q = new DemandGeometryQueue(tiles, 500); // holds 5
+        // A moving "viewport": 200 products stream past with rising priority.
+        for (let id = 0; id < 200; ++id) {
+            q.request(id, id);
+            q.pump();
+            expect(q.stats.residentBytes).toBeLessThanOrEqual(500);
+        }
+        // The 5 most-wanted (highest ids) remain.
+        expect(q.stats.residentCount).toBe(5);
+        for (const id of [195, 196, 197, 198, 199]) {
+            expect(q.isResident(id)).toBe(true);
+        }
+    });
+});