@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryPool.js

@@ -0,0 +1,932 @@
+import { assert } from "../../../../../core/assert.js";
+import { VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES } from "../format/header/VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES.js";
+import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
+import { VGEO_GEOMETRY_ROW_OFFSET } from "./layout/VGEO_GEOMETRY_ROW_OFFSET.js";
+import { VGEO_GEOMETRY_ROW_WORDS } from "./layout/VGEO_GEOMETRY_ROW_WORDS.js";
+import { VGEO_PAGE_ROW_OFFSET } from "./layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_PAGE_ROW_WORDS } from "./layout/VGEO_PAGE_ROW_WORDS.js";
+import { VGeoRuntimeTables } from "./VGeoRuntimeTables.js";
+import { vgeo_runtime_meshlet_batch } from "./vgeo_runtime_meshlet_batch.js";
+
+/**
+ * One resident geometry's bookkeeping above the tables.
+ */
+class VGeoPoolGeometry {
+    /**
+     * @type {VGeoContainerReader}
+     */
+    reader;
+
+    /**
+     * @type {number}
+     */
+    row = 0;
+
+    /**
+     * Container page index to the meshlet-pool allocation holding that page's clusters.
+     * @type {Map<number, object>}
+     */
+    batches = new Map();
+
+    /**
+     * Container page index to page-table row.
+     * @type {Map<number, number>}
+     */
+    rows = new Map();
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @param {number} row
+     */
+    constructor(reader, row) {
+        this.reader = reader;
+        this.row = row;
+    }
+}
+
+/**
+ * The VRAM tier: which pages are on the device, what they cost, and what goes when the budget says
+ * so.
+ *
+ * `VGeoRuntimeTables` is the layout and `VGeoResidencyManager` is the RAM tier's budget; this is
+ * the one in between, and it is the only object in the runtime that holds a `GPUDevice`. The split
+ * is the same one the format made between `format/read/` and `residency/`: a page's *shape* is a
+ * fact about the container, and what may be resident is a question about a scene.
+ *
+ * **Two tiers, two budgets, and the inner one is a subset.** A page is in VRAM only if it is in
+ * RAM, and every question this tier asks about its own residency it answers out of its own tables —
+ * eviction's child rule, the bytes an eviction refunds, and above all *selectability*, which was
+ * being taken from the RAM tier and is what REVIEW_LEDGER C1 is. The reader is consulted for
+ * exactly one thing: the decoded bytes of a page being installed.
+ *
+ * Eviction is design §6's rule: LRU on **last-touched**, under a protect window no shorter than
+ * feedback latency. Not last-*wanted* — that freezes a stamp at fetch time and evicts exactly what
+ * is on screen, which is the fallback-chain bug `VTPhysicalCache` already keys on touch to avoid.
+ *
+ * **Two budgets, and both of them bind.** Slots are fixed and finite, so a full table is as real a
+ * reason to evict as a full byte budget; `#make_room` loops on whichever of the two is short.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUVirtualGeometryPool {
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GPUMeshletManager}
+     */
+    #meshlets;
+
+    /**
+     * @type {VGeoRuntimeTables}
+     */
+    #tables;
+
+    /**
+     * @type {Map<VGeoContainerReader, VGeoPoolGeometry>}
+     */
+    #geometries = new Map();
+
+    /**
+     * Page row to the geometry that owns it, so an eviction chosen by budget can find its reader.
+     * @type {Map<number, VGeoPoolGeometry>}
+     */
+    #owner = new Map();
+
+    /**
+     * Page row to the frame it was last selected from.
+     * @type {Map<number, number>}
+     */
+    #touched = new Map();
+
+    /**
+     * Page rows that may never go: the root page of every registered geometry, which is where every
+     * traversal starts and without which a geometry draws nothing at all.
+     * @type {Set<number>}
+     */
+    #pinned = new Set();
+
+    /**
+     * Per page row, the unsubscribe for that page's meshlet batch relocation signal.
+     * @type {Map<number, function>}
+     */
+    #batch_listeners = new Map();
+
+    /**
+     * @type {number}
+     */
+    #frame = 0;
+
+    /**
+     * @type {number}
+     */
+    #resident_bytes = 0;
+
+    /**
+     * @type {number}
+     */
+    #budget_bytes;
+
+    /**
+     * @type {number}
+     */
+    #protect_window;
+
+    /**
+     * @type {number}
+     */
+    #page_size;
+
+    /**
+     * Word ranges of each shadow that have changed since the last flush, as `[start, end)` pairs.
+     * @type {{lookup: number[], arena: number[], geometries: number[]}}
+     */
+    #dirty = { lookup: [], arena: [], geometries: [] };
+
+    /**
+     * @type {{lookup: GPUBuffer, arena: GPUBuffer, geometries: GPUBuffer}}
+     */
+    #buffers;
+
+    /**
+     * @type {number}
+     */
+    #evicted_page_count = 0;
+
+    /**
+     * @type {number}
+     */
+    #refused_install_count = 0;
+
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUMeshletManager} options.meshlets the pool VG shares with static geometry, so a VG
+     *     draw record is read downstream by the same shader that reads a static one
+     * @param {number} [options.budget_bytes] decoded page bytes this tier may hold; defaults to
+     *     what its slots hold at the page size it was built for, so the two agree by construction
+     * @param {number} [options.protect_window] frames a touched page is safe for; no shorter than
+     *     feedback latency, which is at least one frame of `mapAsync` and in practice several
+     * @param {Object} [options.table_options] passed to {@link VGeoRuntimeTables}
+     * @param {number} [options.page_size] the page size every container registered here must have
+     *     been built at, and the one this tier's slots are sized from
+     */
+    constructor({
+                    device,
+                    meshlets,
+                    budget_bytes = undefined,
+                    protect_window = 4,
+                    table_options = undefined,
+                    page_size = VGEO_DEFAULT_PAGE_SIZE,
+                }) {
+        assert.defined(device, 'device');
+        assert.defined(meshlets, 'meshlets');
+        assert.isNonNegativeInteger(protect_window, 'protect_window');
+        assert.isPositiveInteger(page_size, 'page_size');
+
+        this.#device = device;
+        this.#meshlets = meshlets;
+        this.#protect_window = protect_window;
+        this.#page_size = page_size;
+
+        this.#tables = new VGeoRuntimeTables({ page_size, ...table_options });
+
+        this.#budget_bytes = budget_bytes ?? this.#tables.page_capacity * page_size;
+
+        assert.isNonNegativeInteger(this.#budget_bytes, 'budget_bytes');
+
+        this.#buffers = {
+            lookup: this.#create('lookup', this.#tables.lookup_words.byteLength),
+            arena: this.#create('arena', this.#tables.arena_words.byteLength),
+            geometries: this.#create('geometries', this.#tables.geometry_words.byteLength),
+        };
+
+        // everything starts absent, and "absent" is a sentinel rather than a zero — the lookup has
+        // to reach the device before any cut reads it
+        this.#dirty.lookup = [0, this.#tables.lookup_words.length];
+        this.#dirty.arena = [0, this.#tables.arena_words.length];
+        this.#dirty.geometries = [0, this.#tables.geometry_words.length];
+    }
+
+    /**
+     * @param {string} name
+     * @param {number} size bytes
+     * @returns {GPUBuffer}
+     */
+    #create(name, size) {
+        /*
+         The ceiling is `maxStorageBufferBindingSize`, not `maxBufferSize`. Design §6 names this and
+         names `GPUMeshletManager` clamping against the wrong one: the spec defaults are 256 MiB and
+         128 MiB, so a buffer between them is creatable and not bindable — and `createBuffer`
+         answers an over-limit size with an *invalid buffer* rather than an exception, which makes
+         the failure silent where it happens and loud several frames later.
+
+         Checked once, at construction, because nothing here is ever recreated: the arena is
+         `page_capacity` slots from the first frame to the last.
+         */
+        const limit = this.#device.limits?.maxStorageBufferBindingSize ?? size;
+
+        if (size > limit) {
+            throw new Error(
+                `virtual geometry ${name} wants ${size} bytes,`
+                + ` past this adapter's ${limit}-byte storage binding limit`
+            );
+        }
+
+        return this.#device.createBuffer({
+            label: `GPUVirtualGeometryPool/${name}`,
+            size: Math.max(4, size),
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_lookup() {
+        return this.#buffers.lookup;
+    }
+
+    /**
+     * The arena, which is also the page table: a page's header is the first words of its slot.
+     * @returns {GPUBuffer}
+     */
+    get buffer_arena() {
+        return this.#buffers.arena;
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_geometries() {
+        return this.#buffers.geometries;
+    }
+
+    /**
+     * @returns {VGeoRuntimeTables}
+     */
+    get tables() {
+        return this.#tables;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get resident_bytes() {
+        return this.#resident_bytes;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get budget_bytes() {
+        return this.#budget_bytes;
+    }
+
+    /**
+     * The page size every container registered here is required to have been built at.
+     * @returns {number}
+     */
+    get page_size() {
+        return this.#page_size;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get page_slot_words() {
+        return this.#tables.slot_words;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get resident_page_count() {
+        return this.#tables.resident_page_count;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get evicted_page_count() {
+        return this.#evicted_page_count;
+    }
+
+    /**
+     * Installs that could not be made — no slot could be freed, or the page did not fit one.
+     * @returns {number}
+     */
+    get refused_install_count() {
+        return this.#refused_install_count;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get frame() {
+        return this.#frame;
+    }
+
+    /**
+     * One past the highest page row handed out — what sizes the feedback buffer's touch stamps.
+     * @returns {number}
+     */
+    get page_row_capacity() {
+        return Math.max(1, this.#tables.page_row_high_water);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get lookup_word_count() {
+        return this.#tables.lookup_words.length;
+    }
+
+    /**
+     * Give a container a geometry row, and make its root page resident and pinned.
+     *
+     * The root is not an optimization: every traversal is seeded with it, invariant §11.7 puts
+     * exactly one root cluster in the file, and a measured root page is one cluster of under two
+     * kilobytes. A geometry whose root is not here draws nothing.
+     *
+     * This is also the door the page-size guarantee is checked at, because it is the last moment a
+     * refusal is still cheap: past it, this container's pages are laid into the tier's storage on
+     * the strength of the size it was built at. The two ways that can be wrong are refused rather
+     * than reconciled — deliberately, and naming both numbers, because reconciling them means a
+     * table of slot-size classes and that is a later change than this one.
+     *
+     * @param {VGeoContainerReader} reader with its root page installed
+     * @returns {number} geometry row
+     * @throws {Error} when the container does not guarantee its page size, guarantees a different
+     *     one than this pool holds, or cannot get its root page onto the device
+     */
+    register(reader) {
+        assert.defined(reader, 'reader');
+        assert.defined(reader.root, 'reader.root — the container must be open');
+
+        this.#require_page_size(reader);
+
+        if (this.#geometries.has(reader)) {
+            return this.#geometries.get(reader).row;
+        }
+
+        const row = this.#tables.register_geometry(reader.header.total_pages);
+
+        const geometry = new VGeoPoolGeometry(reader, row);
+
+        this.#geometries.set(reader, geometry);
+
+        this.#mark('geometries', row * VGEO_GEOMETRY_ROW_WORDS, VGEO_GEOMETRY_ROW_WORDS);
+
+        const page_row = this.install(reader, 0);
+
+        if (page_row === -1) {
+            /*
+             A thrown error rather than a stripped assert. `assert.*` is removed from the shipped
+             build by the consumer, so the check that used to stand here was a development-only
+             one — and what it was guarding is the seed kernel reading VGEO_PAGE_ROW_NONE out of the
+             geometry row as a u32 index and multiplying it into a live stat word (REVIEW_LEDGER
+             C7). The geometry is rolled back rather than left half-registered.
+             */
+            this.#geometries.delete(reader);
+
+            this.#tables.unregister_geometry(row);
+
+            this.#mark('geometries', row * VGEO_GEOMETRY_ROW_WORDS, VGEO_GEOMETRY_ROW_WORDS);
+
+            throw new Error(
+                `virtual geometry: the root page of this container could not be made resident, so`
+                + ` it would draw nothing and every cut seeded from it would read an absent row.`
+                + ` The tier holds ${this.#tables.page_capacity} slots and`
+                + ` ${this.#tables.resident_page_count} are taken, of a ${this.#budget_bytes}-byte`
+                + ` budget with ${this.#resident_bytes} spent.`
+            );
+        }
+
+        this.#pinned.add(page_row);
+
+        return row;
+    }
+
+    /**
+     * Drop a container: its pages, its meshlet batches, its lookup and its row.
+     *
+     * A registered geometry pins a root page, holds a meshlet batch per resident page and a block
+     * of the page lookup, and none of it used to have a way out (REVIEW_LEDGER M15). A scene that
+     * swaps assets leaks every one of those.
+     *
+     * @param {VGeoContainerReader} reader
+     * @returns {boolean} whether it was registered
+     */
+    unregister(reader) {
+        const geometry = this.#geometries.get(reader);
+
+        if (geometry === undefined) {
+            return false;
+        }
+
+        for (const page_row of geometry.rows.values()) {
+            this.#pinned.delete(page_row);
+            this.#unwatch_batch(page_row);
+
+            // before the eviction, which zeroes the slot header this number lives in
+            this.#resident_bytes -= this.#decoded_bytes_of(page_row);
+        }
+
+        for (const batch of geometry.batches.values()) {
+            this.#meshlets.remove_batch(batch);
+        }
+
+        geometry.batches.clear();
+        geometry.rows.clear();
+
+        for (const page_row of this.#tables.unregister_geometry(geometry.row)) {
+            this.#owner.delete(page_row);
+            this.#touched.delete(page_row);
+
+            this.#mark('arena', page_row * this.#tables.slot_words, VGEO_PAGE_ROW_WORDS);
+        }
+
+        this.#geometries.delete(reader);
+
+        this.#mark('lookup', 0, this.#tables.lookup_words.length);
+        this.#mark(
+            'geometries', geometry.row * VGEO_GEOMETRY_ROW_WORDS, VGEO_GEOMETRY_ROW_WORDS
+        );
+
+        return true;
+    }
+
+    /**
+     * Refuse a container this tier cannot hold at one page size.
+     *
+     * The bit is checked as well as the number, and it is the more important of the two. A container
+     * built before FORMAT §11.14 carries a `nominal_page_size` that reads exactly like a promise and
+     * is not one — the builder ran past it whenever a group did not fit a page, by up to 146% of it
+     * on a measured build — so taking the number on its own would size this tier against a figure
+     * some of its own pages exceed.
+     *
+     * @param {VGeoContainerReader} reader
+     */
+    #require_page_size(reader) {
+        const header = reader.header;
+
+        if ((header.feature_flags_ignorable & VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES) === 0) {
+            throw new Error(
+                `virtual geometry: this pool holds pages of ${this.#page_size} bytes, and this`
+                + ` container makes no promise about its own. Its header names`
+                + ` ${header.nominal_page_size} but the bounded-pages bit is clear, which means it`
+                + ` was built before that size was a bound and its pages may be over it`
+                + ` (VGEO_FORMAT §11.14). Rebuild the asset.`
+            );
+        }
+
+        if (header.nominal_page_size !== this.#page_size) {
+            throw new Error(
+                `virtual geometry: this container's pages are bounded at`
+                + ` ${header.nominal_page_size} bytes and this pool holds pages of`
+                + ` ${this.#page_size}. There is no slot-size class table yet, so the two have to`
+                + ` agree — build the asset at ${this.#page_size}, or give the pool a page_size of`
+                + ` ${header.nominal_page_size}.`
+            );
+        }
+    }
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @returns {number} geometry row, or -1
+     */
+    geometry_row_of(reader) {
+        return this.#geometries.get(reader)?.row ?? -1;
+    }
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {boolean}
+     */
+    is_resident(reader, page_index) {
+        return this.#geometries.get(reader)?.rows.has(page_index) ?? false;
+    }
+
+    /**
+     * Where this page's clusters actually are in the shared metadata pool, asked of the pool rather
+     * than of the page row — so a caller can check that the row agrees.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {number} metadata row, or -1
+     */
+    meshlet_base_of(reader, page_index) {
+        return this.#geometries.get(reader)?.batches.get(page_index)?.metadata.offset ?? -1;
+    }
+
+    /**
+     * Make a RAM-resident page VRAM-resident.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {number} page row, or -1 when the tier could not make room
+     */
+    install(reader, page_index) {
+        const geometry = this.#geometries.get(reader);
+
+        assert.defined(geometry, 'the reader must be registered first');
+
+        const existing = geometry.rows.get(page_index);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const page = reader.page(page_index);
+
+        if (page === undefined) {
+            // not in RAM; a want that outran its fetch, which is ordinary and not an error
+            return -1;
+        }
+
+        if (this.#tables.slot_words_for(page) > this.#tables.slot_words) {
+            // nothing to evict for: no slot in this tier is ever bigger than another
+            this.#refused_install_count++;
+
+            return -1;
+        }
+
+        if (!this.#make_room(page.decoded_size)) {
+            this.#refused_install_count++;
+
+            return -1;
+        }
+
+        const batch = this.#meshlets.add_batch(vgeo_runtime_meshlet_batch(page));
+
+        let page_row;
+
+        try {
+            page_row = this.#tables.install(geometry.row, page, batch.metadata.offset);
+        } catch (error) {
+            this.#meshlets.remove_batch(batch);
+
+            this.#refused_install_count++;
+
+            return -1;
+        }
+
+        geometry.batches.set(page_index, batch);
+        geometry.rows.set(page_index, page_row);
+
+        this.#owner.set(page_row, geometry);
+        this.#touched.set(page_row, this.#frame);
+        this.#watch_batch(page_row, batch);
+
+        this.#resident_bytes += page.decoded_size;
+
+        this.#mark_slot(page_row);
+        this.#mark('lookup', this.#tables.geometry_field(
+            geometry.row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        ) + page_index, 1);
+        this.#mark('geometries', geometry.row * VGEO_GEOMETRY_ROW_WORDS, VGEO_GEOMETRY_ROW_WORDS);
+
+        /*
+         Activation reaches further than the page that arrived: a group becomes selectable when the
+         last of its parents' pages installs, and those parents can be anywhere already resident. So
+         the whole geometry's answer is recomputed rather than just this page's.
+         */
+        this.#refresh_selectable(geometry);
+
+        return page_row;
+    }
+
+    /**
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    evict(page_row) {
+        if (this.#pinned.has(page_row)) {
+            return false;
+        }
+
+        const geometry = this.#owner.get(page_row);
+
+        if (geometry === undefined) {
+            return false;
+        }
+
+        const page_index = this.#tables.page_field(page_row, VGEO_PAGE_ROW_OFFSET.PAGE_INDEX);
+
+        const lookup_word = this.#tables.geometry_field(
+            geometry.row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        ) + page_index;
+
+        /*
+         The tier's own number, out of the slot. Re-deriving it from the RAM reader gave zero for
+         every page the RAM tier had already dropped, so `resident_bytes` only ever went up and the
+         budget eventually refused every install (REVIEW_LEDGER C4).
+         */
+        this.#resident_bytes -= this.#decoded_bytes_of(page_row);
+
+        this.#unwatch_batch(page_row);
+
+        this.#tables.evict(page_row);
+
+        this.#meshlets.remove_batch(geometry.batches.get(page_index));
+
+        geometry.batches.delete(page_index);
+        geometry.rows.delete(page_index);
+
+        this.#owner.delete(page_row);
+        this.#touched.delete(page_row);
+
+        this.#evicted_page_count++;
+
+        this.#mark_slot(page_row);
+        this.#mark('lookup', lookup_word, 1);
+
+        this.#refresh_selectable(geometry);
+
+        return true;
+    }
+
+    /**
+     * Which geometry owns a page row, and therefore which reader answers questions about it.
+     *
+     * A page row is the only handle the feedback loop gets back from the device — a touch is a row
+     * and a want names the row it was discovered through — so this is how a readback lands back on
+     * a container. It returns `undefined` for a row that has been evicted since the cut ran, which
+     * is ordinary rather than exceptional: feedback is at least a frame behind by construction.
+     *
+     * A row that has been evicted *and re-used* is the harder case, and it is not this method's:
+     * the caller compares {@link VGeoRuntimeTables.generation_of} against the generation it
+     * snapshotted when it built the graph.
+     *
+     * @param {number} page_row
+     * @returns {{reader: VGeoContainerReader, row: number}|undefined}
+     */
+    entry_of(page_row) {
+        return this.#owner.get(page_row);
+    }
+
+    /**
+     * A page the cut reported drawing from, this frame.
+     *
+     * @param {number} page_row
+     * @returns {void}
+     */
+    touch(page_row) {
+        if (this.#owner.has(page_row)) {
+            this.#touched.set(page_row, this.#frame);
+        }
+    }
+
+    /**
+     * @returns {void}
+     */
+    advance_frame() {
+        this.#frame++;
+    }
+
+    /**
+     * Whether a page may go: not pinned, not touched inside the protect window, and with no VRAM
+     * child.
+     *
+     * The child rule is this tier's own, out of this tier's tables. Dropping a parent while its
+     * children stay leaves those children unreachable — nothing refines into them any more — so
+     * they would sit in VRAM, selectable, and never drawn.
+     *
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    evictable(page_row) {
+        if (this.#pinned.has(page_row)) {
+            return false;
+        }
+
+        if (!this.#owner.has(page_row)) {
+            return false;
+        }
+
+        if (this.#frame - (this.#touched.get(page_row) ?? 0) < this.#protect_window) {
+            return false;
+        }
+
+        return !this.#tables.has_resident_child(page_row);
+    }
+
+    /**
+     * Drop coldest-first until a slot is free and `bytes` fit.
+     *
+     * Both budgets bind. Slots are fixed and finite now, so a full table is a reason to evict in its
+     * own right — where it used to be a permanent cliff independent of the byte budget
+     * (REVIEW_LEDGER M17).
+     *
+     * @param {number} bytes
+     * @returns {boolean}
+     */
+    #make_room(bytes) {
+        let guard = this.#tables.resident_page_count + 1;
+
+        while (guard-- > 0) {
+            const short = this.#resident_bytes + bytes > this.#budget_bytes
+                || !this.#tables.has_free_page_row;
+
+            if (!short) {
+                return true;
+            }
+
+            const coldest = this.#coldest();
+
+            if (coldest === -1) {
+                // nothing may go — every page is pinned, hot, or a parent. Refusing the install is
+                // the right answer: the cut clamps and draws coarser, which is what it is for.
+                return false;
+            }
+
+            this.evict(coldest);
+        }
+
+        return this.#resident_bytes + bytes <= this.#budget_bytes
+            && this.#tables.has_free_page_row;
+    }
+
+    /**
+     * @returns {number} page row, or -1
+     */
+    #coldest() {
+        let best = -1;
+        let best_stamp = Number.POSITIVE_INFINITY;
+
+        for (const [page_row, stamp] of this.#touched) {
+            if (stamp >= best_stamp || !this.evictable(page_row)) {
+                continue;
+            }
+
+            best = page_row;
+            best_stamp = stamp;
+        }
+
+        return best;
+    }
+
+    /**
+     * @param {number} page_row
+     * @returns {number}
+     */
+    #decoded_bytes_of(page_row) {
+        return this.#tables.page_field(page_row, VGEO_PAGE_ROW_OFFSET.DECODED_SIZE);
+    }
+
+    /**
+     * Follow a page's meshlet batch when the shared pool moves it.
+     *
+     * `MESHLET_BASE` is the metadata row a draw record is offset from, and `GPUMeshletManager`
+     * relocates every batch when it compacts — after which a page row that cached its base points
+     * at another page's clusters, silently (REVIEW_LEDGER C2). The manager announces the move and
+     * nothing here was listening.
+     *
+     * @param {number} page_row
+     * @param {object} batch
+     */
+    #watch_batch(page_row, batch) {
+        const listener = () => {
+            if (this.#tables.set_meshlet_base(page_row, batch.metadata.offset)) {
+                this.#mark(
+                    'arena',
+                    page_row * this.#tables.slot_words + VGEO_PAGE_ROW_OFFSET.MESHLET_BASE,
+                    1
+                );
+            }
+        };
+
+        batch.changed.add(listener);
+
+        this.#batch_listeners.set(page_row, () => batch.changed.remove(listener));
+    }
+
+    /**
+     * @param {number} page_row
+     */
+    #unwatch_batch(page_row) {
+        this.#batch_listeners.get(page_row)?.();
+
+        this.#batch_listeners.delete(page_row);
+    }
+
+    /**
+     * @param {VGeoPoolGeometry} geometry
+     */
+    #refresh_selectable(geometry) {
+        for (const page_row of this.#tables.refresh_selectable(geometry.row)) {
+            const [start, count] = this.#tables.group_range(page_row);
+
+            this.#mark('arena', start, count);
+        }
+    }
+
+    /**
+     * @param {number} page_row
+     */
+    #mark_slot(page_row) {
+        const [start, count] = this.#tables.slot_range(page_row);
+
+        this.#mark('arena', start, Math.max(count, VGEO_PAGE_ROW_OFFSET.DECODED_SIZE + 1));
+    }
+
+    /**
+     * @param {'lookup'|'arena'|'geometries'} which
+     * @param {number} start word
+     * @param {number} count words
+     */
+    #mark(which, start, count) {
+        this.#dirty[which].push(start, start + count);
+    }
+
+    /**
+     * Push everything that changed since the last call to the device.
+     *
+     * Ranges rather than whole buffers, because the arena is the size of the resident set and a
+     * frame changes a page or two of it. Coalesced by sorting rather than by an interval tree: a
+     * frame's worth of installs is tens of ranges, and a structure that beat a sort at that size
+     * would be a structure to maintain.
+     *
+     * @returns {void}
+     */
+    flush() {
+        this.#write('lookup', this.#tables.lookup_words, this.#buffers.lookup);
+        this.#write('arena', this.#tables.arena_words, this.#buffers.arena);
+        this.#write('geometries', this.#tables.geometry_words, this.#buffers.geometries);
+    }
+
+    /**
+     * @param {'lookup'|'arena'|'geometries'} which
+     * @param {Uint32Array} shadow
+     * @param {GPUBuffer} buffer
+     */
+    #write(which, shadow, buffer) {
+        const ranges = this.#dirty[which];
+
+        if (ranges.length === 0) {
+            return;
+        }
+
+        /**
+         * @type {number[][]}
+         */
+        const pairs = [];
+
+        for (let i = 0; i < ranges.length; i += 2) {
+            pairs.push([ranges[i], ranges[i + 1]]);
+        }
+
+        pairs.sort((a, b) => a[0] - b[0]);
+
+        let start = pairs[0][0];
+        let end = pairs[0][1];
+
+        for (let i = 1; i <= pairs.length; i++) {
+            if (i < pairs.length && pairs[i][0] <= end) {
+                end = Math.max(end, pairs[i][1]);
+
+                continue;
+            }
+
+            const clamped = Math.min(end, shadow.length);
+
+            if (clamped > start) {
+                this.#device.queue.writeBuffer(
+                    buffer,
+                    start * 4,
+                    shadow.buffer,
+                    shadow.byteOffset + start * 4,
+                    (clamped - start) * 4
+                );
+            }
+
+            if (i < pairs.length) {
+                start = pairs[i][0];
+                end = pairs[i][1];
+            }
+        }
+
+        ranges.length = 0;
+    }
+
+    destroy() {
+        for (const unwatch of this.#batch_listeners.values()) {
+            unwatch();
+        }
+
+        this.#batch_listeners.clear();
+
+        for (const reader of Array.from(this.#geometries.keys())) {
+            this.unregister(reader);
+        }
+
+        for (const buffer of Object.values(this.#buffers)) {
+            buffer.destroy();
+        }
+    }
+}