@woosh/meep-engine 3.24.0 → 3.25.0

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

@@ -0,0 +1,976 @@
+import { assert } from "../../../../../core/assert.js";
+import { ALLOCATOR_NO_SPACE, OffsetAllocator } from "../../../../../core/binary/allocator/OffsetAllocator.js";
+import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
+import { VGEO_CLUSTER_ROW_OFFSET } from "./layout/VGEO_CLUSTER_ROW_OFFSET.js";
+import { VGEO_CLUSTER_ROW_WORDS } from "./layout/VGEO_CLUSTER_ROW_WORDS.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_GROUP_FLAG_SELECTABLE } from "./layout/VGEO_GROUP_FLAG_SELECTABLE.js";
+import { VGEO_GROUP_ROW_OFFSET } from "./layout/VGEO_GROUP_ROW_OFFSET.js";
+import { VGEO_GROUP_ROW_WORDS } from "./layout/VGEO_GROUP_ROW_WORDS.js";
+import { VGEO_NODE_ROW_WORDS } from "./layout/VGEO_NODE_ROW_WORDS.js";
+import { VGEO_NO_CHILD_PAGE } from "./layout/VGEO_NO_CHILD_PAGE.js";
+import { VGEO_PAGE_ROW_NONE } from "./layout/VGEO_PAGE_ROW_NONE.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 { vgeo_runtime_page_block_words } from "./vgeo_runtime_page_block_words.js";
+import { vgeo_runtime_page_slot_words } from "./vgeo_runtime_page_slot_words.js";
+import { vgeo_runtime_write_page_block } from "./vgeo_runtime_write_page_block.js";
+
+/**
+ * What a VRAM-resident page **is**, with no device anywhere near it.
+ *
+ * Two word arrays: the arena of fixed-stride page slots, and the per-geometry page lookup.
+ * {@link GPUVirtualGeometryPool} owns the buffers, the budget and the meshlet-pool allocation; this
+ * owns the layout, and the split is the same one `format/read/` and `residency/` already make —
+ * mechanics below, policy and devices above.
+ *
+ * It is worth having as its own object for a reason beyond tidiness: the cut kernel's agreement
+ * against `vgeo_select_cut` is the single most important test in this campaign, and it can run in
+ * node against these arrays. A mirror written for the spec would prove the mirror.
+ *
+ * ## Slots, not allocations
+ *
+ * A page's rows live at `page_row × slot_words`, and everything that used to make that address a
+ * question is gone with the question: no `OffsetAllocator`, no growth, no ceiling, no shadow that
+ * can grow before the buffer it mirrors. `VIRTUAL_GEOMETRY_DESIGN.md` §6 asked for this from the
+ * start and format §11.14 is what finally permits it — `nominal_page_size` is a bound every page is
+ * within, `GPUVirtualGeometryPool.register` refuses a container that does not promise it, and
+ * {@link vgeo_runtime_page_slot_words} turns that promise into a stride. A page whose rows do not
+ * fit the stride is refused; see that function for why the stride is a choice and what it was
+ * measured against.
+ *
+ * The page's own header is the first {@link VGEO_PAGE_ROW_WORDS} words of its slot rather than a
+ * row of a second table, which saves the traversal a storage binding it does not have to spare
+ * (RUNTIME_PLAN §4.9) and makes an install one contiguous range.
+ *
+ * ## This tier answers its own activation question
+ *
+ * {@link refresh_selectable} computes selectability from the arena and the lookup — this tier's
+ * residency — and consults no reader. It used to publish `VGeoContainerReader.is_selectable`, which
+ * is a fact about the **RAM** tier, into the flag the kernel reads while the descent was gated on
+ * the **VRAM** lookup. VRAM is a strict subset, so a group could be flagged selectable while a page
+ * holding one of its parents had no row here, and the parent's own ancestor then drew a coarse
+ * stand-in over the surface the group was drawing. That is REVIEW_LEDGER C1, and what closes it is
+ * the group row carrying its parent count (VGEO_GROUP_ROW_OFFSET.PARENT_COUNT) so that the rule
+ * can be evaluated where the residency it is about lives.
+ *
+ * **Nothing here decides anything.** What to install, what to evict — all of that is the pool's.
+ * What this refuses is only what it cannot represent.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoRuntimeTables {
+    /**
+     * Fixed-stride page slots: `[page header][node rows][group rows][cluster rows]`, one per row.
+     * @type {Uint32Array}
+     */
+    #arena;
+
+    /**
+     * The same memory as {@link #arena}, for the halves of a row that are distances rather than
+     * indices.
+     * @type {Float32Array}
+     */
+    #arena_floats;
+
+    /**
+     * Container page index to page row, or {@link VGEO_PAGE_ROW_NONE}, one block per geometry.
+     *
+     * Its own buffer and its own allocator, so a block's offset is a small dense number. That is
+     * what lets the cut index its per-want dedup stamps by `lookup offset + child page index`
+     * without a second per-geometry field or a stamp array the size of the arena.
+     *
+     * The allocator here is not the one the review took out: it hands out one block per *geometry*,
+     * at registration, and a scene registers a handful of assets where it installs and evicts
+     * thousands of pages.
+     *
+     * @type {Uint32Array}
+     */
+    #lookup;
+
+    /**
+     * `geometry row * VGEO_GEOMETRY_ROW_WORDS + field`. Read by the instance-collect pass and
+     * folded into instance records, never bound by the traversal.
+     * @type {Uint32Array}
+     */
+    #geometries;
+
+    /**
+     * @type {OffsetAllocator}
+     */
+    #lookup_allocator;
+
+    /**
+     * @type {number}
+     */
+    #slot_words;
+
+    /**
+     * @type {number}
+     */
+    #page_capacity;
+
+    /**
+     * Page rows in use, so an eviction can tell a resident row from a free one without a second
+     * structure and {@link resident_page_count} is a size rather than a scan.
+     * @type {Set<number>}
+     */
+    #resident_rows = new Set();
+
+    /**
+     * Resident page rows per geometry row — what {@link refresh_selectable} runs over, and what an
+     * eviction has to look at to find a page's VRAM children.
+     * @type {Map<number, Set<number>>}
+     */
+    #geometry_rows = new Map();
+
+    /**
+     * Lookup allocation per geometry row, so an unregistered geometry gives its lookup back.
+     * @type {Map<number, Allocation>}
+     */
+    #geometry_allocations = new Map();
+
+    /**
+     * Page rows that are free, newest first. A row is a slot and carries no identity, so re-using
+     * the most recently freed one keeps the live rows dense and the table's high-water mark — which
+     * is what sizes the touch-stamp region every frame — from creeping.
+     * @type {number[]}
+     */
+    #free_page_rows = [];
+
+    /**
+     * Per page row, how many times it has been freed.
+     *
+     * A row is reused the moment it is freed, and feedback is at least a frame behind the cut that
+     * produced it, so a want or a touch naming row 7 may be naming the page that was in row 7 when
+     * the cut ran rather than the one there now. The host snapshots a row's generation while it
+     * builds the graph and compares when the readback lands; a mismatch is a record about a page
+     * that no longer exists, and dropping it is the whole of the fix (REVIEW_LEDGER M10).
+     *
+     * CPU-side deliberately. Nothing on the device ever needs this — the kernel reads rows that are
+     * resident *now*, which is by construction the state it was dispatched against.
+     *
+     * @type {Uint32Array}
+     */
+    #generations;
+
+    /**
+     * @type {number}
+     */
+    #page_row_high_water = 0;
+
+    /**
+     * @type {number}
+     */
+    #geometry_row_high_water = 0;
+
+    /**
+     * Geometry rows an unregister gave back. A scene that swaps assets would otherwise walk the
+     * geometry table's high-water mark up until registration refused, with the table mostly empty.
+     * @type {number[]}
+     */
+    #free_geometry_rows = [];
+
+    /**
+     * Per geometry row: ordinals that are free, and the high-water mark of ordinals handed out.
+     *
+     * An ordinal is a page's dense index *within its geometry*, and it exists only to index the
+     * per-instance claim bitmask. Its capacity is therefore what one instance's slice of that
+     * bitmask costs, which is why the mark matters and why ordinals are recycled rather than
+     * counted upward.
+     *
+     * @type {Map<number, {free: number[], high_water: number}>}
+     */
+    #ordinals = new Map();
+
+    /**
+     * Clusters installed here whose `child_ref` named an entry outside their page's child table.
+     *
+     * Impossible in a container the validator accepts, reachable because validation is off by
+     * default, and worth counting rather than asserting on: the cluster is written as a leaf and
+     * drawn, which is what `vgeo_select_cut` does with the same input.
+     *
+     * @type {number}
+     */
+    #broken_child_refs = 0;
+
+    /**
+     * Scratch for {@link refresh_selectable}: live parent references per resident group, indexed by
+     * the group's word offset in the arena. One map reused across calls rather than one allocated
+     * per call, because activation runs on every install and every eviction.
+     * @type {Map<number, number>}
+     */
+    #live_refs = new Map();
+
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.page_capacity] slots
+     * @param {number} [options.page_size] bytes a page of every container held here is bounded by;
+     *     what the slot stride is derived from
+     * @param {number} [options.slot_words] the stride itself, overriding the derivation
+     * @param {number} [options.lookup_words]
+     * @param {number} [options.geometry_capacity] rows
+     */
+    constructor({
+                    page_capacity = 1024,
+                    page_size = VGEO_DEFAULT_PAGE_SIZE,
+                    slot_words = vgeo_runtime_page_slot_words(page_size),
+                    lookup_words = 1 << 16,
+                    geometry_capacity = 256,
+                } = {}) {
+        assert.isPositiveInteger(page_capacity, 'page_capacity');
+        assert.isPositiveInteger(slot_words, 'slot_words');
+        assert.isNonNegativeInteger(lookup_words, 'lookup_words');
+        assert.isNonNegativeInteger(geometry_capacity, 'geometry_capacity');
+        assert.greaterThan(slot_words, VGEO_PAGE_ROW_WORDS, 'slot_words');
+
+        this.#slot_words = slot_words;
+        this.#page_capacity = page_capacity;
+
+        this.#lookup = new Uint32Array(lookup_words);
+        this.#geometries = new Uint32Array(geometry_capacity * VGEO_GEOMETRY_ROW_WORDS);
+        this.#generations = new Uint32Array(page_capacity);
+
+        const words = new Uint32Array(page_capacity * slot_words);
+
+        this.#arena = words;
+        this.#arena_floats = new Float32Array(words.buffer, words.byteOffset, words.length);
+
+        this.#lookup_allocator = new OffsetAllocator(lookup_words);
+    }
+
+    /**
+     * @returns {Uint32Array}
+     */
+    get lookup_words() {
+        return this.#lookup;
+    }
+
+    /**
+     * @returns {Uint32Array}
+     */
+    get arena_words() {
+        return this.#arena;
+    }
+
+    /**
+     * @returns {Uint32Array}
+     */
+    get geometry_words() {
+        return this.#geometries;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get broken_child_refs() {
+        return this.#broken_child_refs;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get slot_words() {
+        return this.#slot_words;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get page_capacity() {
+        return this.#page_capacity;
+    }
+
+    /**
+     * One past the highest page row ever handed out — what sizes a per-page-row stamp region.
+     * @returns {number}
+     */
+    get page_row_high_water() {
+        return this.#page_row_high_water;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get resident_page_count() {
+        return this.#resident_rows.size;
+    }
+
+    /**
+     * Whether a row could take a page without anything being evicted first.
+     * @returns {boolean}
+     */
+    get has_free_page_row() {
+        return this.#free_page_rows.length > 0 || this.#page_row_high_water < this.#page_capacity;
+    }
+
+    /**
+     * How many times this row has been freed — the token that tells a feedback record about the
+     * page that *was* here from one about the page that is.
+     *
+     * @param {number} page_row
+     * @returns {number}
+     */
+    generation_of(page_row) {
+        return this.#generations[page_row];
+    }
+
+    /**
+     * Give a container a geometry row and a page lookup of its own.
+     *
+     * The lookup is `total_pages` words and starts entirely absent, which is the correct state for
+     * a container nothing has been installed from: every cluster that refers into it clamps, draws
+     * coarse, and wants.
+     *
+     * @param {number} page_count the container's `total_pages`
+     * @param {number} [ordinal_capacity] initial claim width; grown by installs
+     * @returns {number} geometry row
+     * @throws {Error} when the lookup does not fit
+     */
+    register_geometry(page_count, ordinal_capacity = 0) {
+        assert.isNonNegativeInteger(page_count, 'page_count');
+        assert.greaterThan(page_count, 0, 'page_count');
+
+        const recycled = this.#free_geometry_rows.pop();
+
+        const row = recycled ?? this.#geometry_row_high_water;
+
+        if (recycled === undefined
+            && (row + 1) * VGEO_GEOMETRY_ROW_WORDS > this.#geometries.length) {
+            throw new Error(
+                `no room for a ${row + 1}th virtual geometry`
+                + ` in a table of ${this.#geometries.length / VGEO_GEOMETRY_ROW_WORDS}`
+            );
+        }
+
+        const allocation = this.#lookup_allocator.allocate(page_count);
+
+        if (allocation.offset === ALLOCATOR_NO_SPACE) {
+            throw new Error(
+                `no room for a ${page_count}-page lookup in ${this.#lookup.length} words`
+            );
+        }
+
+        if (recycled === undefined) {
+            this.#geometry_row_high_water = row + 1;
+        }
+
+        this.#geometry_allocations.set(row, allocation);
+
+        this.#lookup.fill(
+            VGEO_PAGE_ROW_NONE, allocation.offset, allocation.offset + page_count
+        );
+
+        const base = row * VGEO_GEOMETRY_ROW_WORDS;
+
+        this.#geometries[base + VGEO_GEOMETRY_ROW_OFFSET.ROOT_PAGE_ROW] = VGEO_PAGE_ROW_NONE;
+        this.#geometries[base + VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET] = allocation.offset;
+        this.#geometries[base + VGEO_GEOMETRY_ROW_OFFSET.PAGE_COUNT] = page_count;
+        this.#geometries[base + VGEO_GEOMETRY_ROW_OFFSET.ORDINAL_CAPACITY] = ordinal_capacity;
+
+        this.#ordinals.set(row, { free: [], high_water: ordinal_capacity });
+        this.#geometry_rows.set(row, new Set());
+
+        return row;
+    }
+
+    /**
+     * Drop a geometry: every page it has here, then its lookup and its row.
+     *
+     * @param {number} geometry_row
+     * @returns {number[]} the page rows that were evicted, so a caller holding per-row state can
+     *     drop it too
+     */
+    unregister_geometry(geometry_row) {
+        const rows = this.#geometry_rows.get(geometry_row);
+
+        if (rows === undefined) {
+            return [];
+        }
+
+        const evicted = Array.from(rows);
+
+        for (const page_row of evicted) {
+            this.evict(page_row);
+        }
+
+        const allocation = this.#geometry_allocations.get(geometry_row);
+
+        if (allocation !== undefined) {
+            this.#lookup.fill(
+                0,
+                allocation.offset,
+                allocation.offset + this.geometry_field(
+                    geometry_row, VGEO_GEOMETRY_ROW_OFFSET.PAGE_COUNT
+                )
+            );
+
+            this.#lookup_allocator.free(allocation);
+            this.#geometry_allocations.delete(geometry_row);
+        }
+
+        this.#geometries.fill(
+            0,
+            geometry_row * VGEO_GEOMETRY_ROW_WORDS,
+            (geometry_row + 1) * VGEO_GEOMETRY_ROW_WORDS
+        );
+
+        this.#geometries[
+            geometry_row * VGEO_GEOMETRY_ROW_WORDS + VGEO_GEOMETRY_ROW_OFFSET.ROOT_PAGE_ROW
+        ] = VGEO_PAGE_ROW_NONE;
+
+        this.#geometry_rows.delete(geometry_row);
+        this.#ordinals.delete(geometry_row);
+        this.#free_geometry_rows.push(geometry_row);
+
+        return evicted;
+    }
+
+    /**
+     * @param {number} geometry_row
+     * @param {number} field one of {@link VGEO_GEOMETRY_ROW_OFFSET}
+     * @returns {number}
+     */
+    geometry_field(geometry_row, field) {
+        return this.#geometries[geometry_row * VGEO_GEOMETRY_ROW_WORDS + field];
+    }
+
+    /**
+     * @param {number} geometry_row
+     * @param {number} page_index container page index
+     * @returns {number} page row, or {@link VGEO_PAGE_ROW_NONE}
+     */
+    page_row_of(geometry_row, page_index) {
+        const base = this.geometry_field(
+            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        );
+
+        return this.#lookup[base + page_index];
+    }
+
+    /**
+     * @param {number} page_row
+     * @param {number} field one of {@link VGEO_PAGE_ROW_OFFSET}
+     * @returns {number}
+     */
+    page_field(page_row, field) {
+        return this.#arena[page_row * this.#slot_words + field];
+    }
+
+    /**
+     * Word offset of a page's node rows — the slot, past its header.
+     *
+     * @param {number} page_row
+     * @returns {number}
+     */
+    node_base(page_row) {
+        return page_row * this.#slot_words + VGEO_PAGE_ROW_WORDS;
+    }
+
+    /**
+     * @param {number} page_row
+     * @returns {number}
+     */
+    group_base(page_row) {
+        return this.node_base(page_row)
+            + this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.NODE_COUNT) * VGEO_NODE_ROW_WORDS;
+    }
+
+    /**
+     * @param {number} page_row
+     * @returns {number}
+     */
+    cluster_base(page_row) {
+        return this.group_base(page_row)
+            + this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT) * VGEO_GROUP_ROW_WORDS;
+    }
+
+    /**
+     * Make a decoded page resident: one slot, one lookup word.
+     *
+     * The page installs **not selectable** — every group's flag is clear — because a page that
+     * arrives drawing is a page that draws before the ancestors it hangs off have. Activation is
+     * {@link refresh_selectable}.
+     *
+     * @param {number} geometry_row
+     * @param {VGeoPage} page as `vgeo_read_page` decoded it
+     * @param {number} meshlet_base row of this page's cluster 0 in the meshlet metadata pool
+     * @returns {number} page row
+     * @throws {Error} when no slot is free — the caller's cue to evict, since what to drop is a
+     *     budget question and this object holds no budget — or when the page's rows do not fit one
+     * @see broken_child_refs for what the last install reported about the page it wrote
+     */
+    install(geometry_row, page, meshlet_base) {
+        assert.defined(page, 'page');
+        assert.isNonNegativeInteger(meshlet_base, 'meshlet_base');
+
+        const node_count = page.node_count;
+        const group_count = page.group_cluster_first.length;
+        const cluster_count = page.cluster_count;
+
+        const words = VGEO_PAGE_ROW_WORDS
+            + vgeo_runtime_page_block_words(node_count, group_count, cluster_count);
+
+        if (words > this.#slot_words) {
+            throw new Error(
+                `virtual geometry page ${page.index} needs ${words} words and this tier's slots`
+                + ` hold ${this.#slot_words}. Its ${node_count} nodes, ${group_count} groups and`
+                + ` ${cluster_count} clusters are legal and unusually dense for their page size;`
+                + ` construct the pool with slot_words of at least ${words}.`
+            );
+        }
+
+        const page_row = this.#take_page_row();
+
+        if (page_row === -1) {
+            throw new Error(
+                `virtual geometry page table is full at ${this.#page_capacity} slots`
+            );
+        }
+
+        const ordinal = this.#take_ordinal(geometry_row);
+
+        const base = page_row * this.#slot_words;
+
+        this.#broken_child_refs += vgeo_runtime_write_page_block(
+            this.#arena, this.#arena_floats, base + VGEO_PAGE_ROW_WORDS, page
+        );
+
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.NODE_COUNT] = node_count;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.GROUP_COUNT] = group_count;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT] = cluster_count;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.MESHLET_BASE] = meshlet_base;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.PAGE_INDEX] = page.index;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.ORDINAL] = ordinal;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW] = geometry_row;
+        this.#arena[base + VGEO_PAGE_ROW_OFFSET.DECODED_SIZE] = page.decoded_size;
+
+        this.#resident_rows.add(page_row);
+        this.#geometry_rows.get(geometry_row).add(page_row);
+
+        const lookup_base = this.geometry_field(
+            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        );
+
+        this.#lookup[lookup_base + page.index] = page_row;
+
+        if (page.index === 0) {
+            this.#geometries[
+                geometry_row * VGEO_GEOMETRY_ROW_WORDS + VGEO_GEOMETRY_ROW_OFFSET.ROOT_PAGE_ROW
+            ] = page_row;
+        }
+
+        return page_row;
+    }
+
+    /**
+     * How many words of a slot an install of this page would take, header included.
+     *
+     * @param {VGeoPage} page
+     * @returns {number}
+     */
+    slot_words_for(page) {
+        return VGEO_PAGE_ROW_WORDS + vgeo_runtime_page_block_words(
+            page.node_count, page.group_cluster_first.length, page.cluster_count
+        );
+    }
+
+    /**
+     * Drop a resident page.
+     *
+     * The lookup word goes back to {@link VGEO_PAGE_ROW_NONE} first, and that single word is the
+     * whole of what makes the eviction safe: every cluster anywhere that refines into this page
+     * reads it, finds nothing, and clamps — drawing the coarser surface it was already drawing
+     * before the page arrived. Nothing is patched and nothing is scanned.
+     *
+     * The slot's **header** is zeroed and its rows are not. A row nothing points at is unreachable
+     * — the lookup is the only way in and no queue item survives a frame — and leaving the rows
+     * costs nothing while zeroing them would dirty a slot's worth of words per eviction.
+     *
+     * @param {number} page_row
+     * @returns {boolean} whether the row was resident
+     */
+    evict(page_row) {
+        if (!this.#resident_rows.has(page_row)) {
+            return false;
+        }
+
+        const geometry_row = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW);
+        const page_index = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.PAGE_INDEX);
+
+        const lookup_base = this.geometry_field(
+            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        );
+
+        this.#lookup[lookup_base + page_index] = VGEO_PAGE_ROW_NONE;
+
+        if (page_index === 0) {
+            this.#geometries[
+                geometry_row * VGEO_GEOMETRY_ROW_WORDS + VGEO_GEOMETRY_ROW_OFFSET.ROOT_PAGE_ROW
+            ] = VGEO_PAGE_ROW_NONE;
+        }
+
+        this.#give_ordinal(geometry_row, this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.ORDINAL));
+
+        const base = page_row * this.#slot_words;
+
+        this.#arena.fill(0, base, base + VGEO_PAGE_ROW_WORDS);
+
+        this.#resident_rows.delete(page_row);
+        this.#geometry_rows.get(geometry_row)?.delete(page_row);
+
+        this.#free_page_rows.push(page_row);
+        this.#generations[page_row]++;
+
+        return true;
+    }
+
+    /**
+     * The page rows this geometry holds, which is also what an eviction candidate's children are
+     * looked for among.
+     *
+     * @param {number} geometry_row
+     * @returns {Set<number>}
+     */
+    pages_of(geometry_row) {
+        return this.#geometry_rows.get(geometry_row) ?? EMPTY_ROWS;
+    }
+
+    /**
+     * Whether any page resident **in this tier** refines out of this one.
+     *
+     * Design §6's eviction rule reads "no child page resident in this tier", and this answers it out
+     * of the arena rather than out of the RAM reader's child table — which returned "no children"
+     * the moment the RAM tier dropped the page, orphaning every VRAM-resident child under it
+     * (REVIEW_LEDGER M9).
+     *
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    has_resident_child(page_row) {
+        const geometry_row = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW);
+
+        const lookup_base = this.geometry_field(
+            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        );
+
+        const cluster_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT);
+        const cluster_base = this.cluster_base(page_row);
+
+        for (let cluster = 0; cluster < cluster_count; cluster++) {
+            const child_page_index = this.#arena[
+                cluster_base + cluster * VGEO_CLUSTER_ROW_WORDS
+                    + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX
+            ];
+
+            if (child_page_index === VGEO_NO_CHILD_PAGE) {
+                continue;
+            }
+
+            const child_row = this.#lookup[lookup_base + child_page_index];
+
+            if (child_row !== VGEO_PAGE_ROW_NONE && child_row !== page_row) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Recompute one geometry's group selectability over **this tier's** residency.
+     *
+     * `VIRTUAL_GEOMETRY_DESIGN.md` §6: a group is selectable iff every one of its parent-cluster
+     * references is live — the referencing cluster's page resident here, and that cluster's own
+     * group selectable here. Groups with no parents at all are the top of the DAG and are selectable
+     * the moment their page is. That is a closure over the resident set, so it is computed as one:
+     * seed the parentless groups and cascade down, counting a reference only when the group making
+     * it is already selectable.
+     *
+     * Recomputed whole rather than propagated incrementally, because an install can turn groups on
+     * several pages away and an eviction can turn them off again, and because the cost is the same
+     * order as the install that provoked it — one pass over the geometry's resident clusters. The
+     * incremental form is a later optimization with a counter to keep correct; the one thing it
+     * must not be is a *second* implementation of the rule.
+     *
+     * @param {number} geometry_row
+     * @returns {number[]} page rows whose group flags changed, for the caller to upload
+     */
+    refresh_selectable(geometry_row) {
+        const rows = this.#geometry_rows.get(geometry_row);
+
+        if (rows === undefined || rows.size === 0) {
+            return [];
+        }
+
+        const arena = this.#arena;
+        const live = this.#live_refs;
+
+        live.clear();
+
+        const lookup_base = this.geometry_field(
+            geometry_row, VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET
+        );
+
+        /**
+         * Word offsets of group rows to turn on, as a stack.
+         * @type {number[]}
+         */
+        const queue = [];
+
+        for (const page_row of rows) {
+            const group_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT);
+            const group_base = this.group_base(page_row);
+
+            for (let group = 0; group < group_count; group++) {
+                const row = group_base + group * VGEO_GROUP_ROW_WORDS;
+
+                live.set(row, 0);
+
+                if (arena[row + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT] === 0) {
+                    queue.push(row);
+                }
+            }
+        }
+
+        /**
+         * @type {Set<number>}
+         */
+        const selectable = new Set();
+
+        while (queue.length > 0) {
+            const group_row = queue.pop();
+
+            if (selectable.has(group_row)) {
+                continue;
+            }
+
+            selectable.add(group_row);
+
+            const page_row = Math.floor(group_row / this.#slot_words);
+
+            const cluster_base = this.cluster_base(page_row);
+
+            const first = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST];
+            const count = arena[group_row + VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT];
+
+            for (let i = 0; i < count; i++) {
+                const cluster = cluster_base + (first + i) * VGEO_CLUSTER_ROW_WORDS;
+
+                const child_page_index = arena[
+                    cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX
+                ];
+
+                if (child_page_index === VGEO_NO_CHILD_PAGE) {
+                    continue;
+                }
+
+                const child_row = this.#lookup[lookup_base + child_page_index];
+
+                if (child_row === VGEO_PAGE_ROW_NONE) {
+                    // the child page is not in this tier; its groups stay blocked, which is exactly
+                    // what makes the cluster above clamp and draw
+                    continue;
+                }
+
+                const child_group = arena[cluster + VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP];
+
+                if (child_group >= this.page_field(child_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT)) {
+                    // a child_group outside the child page's table; counting it would corrupt a
+                    // neighbour's counter, and the traversal draws the referring cluster instead
+                    continue;
+                }
+
+                const child = this.group_base(child_row) + child_group * VGEO_GROUP_ROW_WORDS;
+
+                const counted = live.get(child) + 1;
+
+                live.set(child, counted);
+
+                if (counted === arena[child + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT]) {
+                    queue.push(child);
+                }
+            }
+        }
+
+        /**
+         * @type {number[]}
+         */
+        const changed = [];
+
+        for (const page_row of rows) {
+            const group_count = this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT);
+            const group_base = this.group_base(page_row);
+
+            let dirty = false;
+
+            for (let group = 0; group < group_count; group++) {
+                const row = group_base + group * VGEO_GROUP_ROW_WORDS;
+
+                const flags = selectable.has(row) ? VGEO_GROUP_FLAG_SELECTABLE : 0;
+
+                if (arena[row + VGEO_GROUP_ROW_OFFSET.FLAGS] !== flags) {
+                    arena[row + VGEO_GROUP_ROW_OFFSET.FLAGS] = flags;
+
+                    dirty = true;
+                }
+            }
+
+            if (dirty) {
+                changed.push(page_row);
+            }
+        }
+
+        return changed;
+    }
+
+    /**
+     * Publish one group's selectability directly.
+     *
+     * {@link refresh_selectable} is what a runtime calls; this is for a spec that needs a state the
+     * rule happens not to produce on the assets measured so far — the cut's own-group term is
+     * correctness for exactly such a state, and a guard nothing can construct is a guard nothing can
+     * test. The next {@link refresh_selectable} overwrites it.
+     *
+     * @param {number} page_row
+     * @param {number} group
+     * @param {boolean} selectable
+     * @returns {void}
+     */
+    set_group_selectable(page_row, group, selectable) {
+        const word = this.group_base(page_row)
+            + group * VGEO_GROUP_ROW_WORDS
+            + VGEO_GROUP_ROW_OFFSET.FLAGS;
+
+        this.#arena[word] = selectable ? VGEO_GROUP_FLAG_SELECTABLE : 0;
+    }
+
+    /**
+     * @param {number} page_row
+     * @param {number} group
+     * @returns {boolean}
+     */
+    is_group_selectable(page_row, group) {
+        const word = this.group_base(page_row)
+            + group * VGEO_GROUP_ROW_WORDS
+            + VGEO_GROUP_ROW_OFFSET.FLAGS;
+
+        return (this.#arena[word] & VGEO_GROUP_FLAG_SELECTABLE) !== 0;
+    }
+
+    /**
+     * Word range of one page's slot, as `[start, count]` — what an install dirties.
+     *
+     * @param {number} page_row
+     * @returns {number[]}
+     */
+    slot_range(page_row) {
+        const base = page_row * this.#slot_words;
+
+        const words = VGEO_PAGE_ROW_WORDS + vgeo_runtime_page_block_words(
+            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.NODE_COUNT),
+            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT),
+            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT)
+        );
+
+        return [base, words];
+    }
+
+    /**
+     * Word range of one page's group rows — what an activation pass dirties.
+     *
+     * @param {number} page_row
+     * @returns {number[]}
+     */
+    group_range(page_row) {
+        return [
+            this.group_base(page_row),
+            this.page_field(page_row, VGEO_PAGE_ROW_OFFSET.GROUP_COUNT) * VGEO_GROUP_ROW_WORDS,
+        ];
+    }
+
+    /**
+     * Republish one page's meshlet base, after the shared meshlet pool relocated its batch.
+     *
+     * @param {number} page_row
+     * @param {number} meshlet_base
+     * @returns {boolean} whether it moved
+     */
+    set_meshlet_base(page_row, meshlet_base) {
+        const word = page_row * this.#slot_words + VGEO_PAGE_ROW_OFFSET.MESHLET_BASE;
+
+        if (this.#arena[word] === meshlet_base) {
+            return false;
+        }
+
+        this.#arena[word] = meshlet_base;
+
+        return true;
+    }
+
+    /**
+     * @returns {number} row, or -1 when every slot is taken
+     */
+    #take_page_row() {
+        const recycled = this.#free_page_rows.pop();
+
+        if (recycled !== undefined) {
+            return recycled;
+        }
+
+        const row = this.#page_row_high_water;
+
+        if (row >= this.#page_capacity) {
+            return -1;
+        }
+
+        this.#page_row_high_water = row + 1;
+
+        return row;
+    }
+
+    /**
+     * @param {number} geometry_row
+     * @returns {number}
+     */
+    #take_ordinal(geometry_row) {
+        const state = this.#ordinals.get(geometry_row);
+
+        const recycled = state.free.pop();
+
+        if (recycled !== undefined) {
+            return recycled;
+        }
+
+        const ordinal = state.high_water;
+
+        state.high_water = ordinal + 1;
+
+        this.#geometries[
+            geometry_row * VGEO_GEOMETRY_ROW_WORDS + VGEO_GEOMETRY_ROW_OFFSET.ORDINAL_CAPACITY
+        ] = state.high_water;
+
+        return ordinal;
+    }
+
+    /**
+     * An ordinal goes back to the free list and the capacity does **not** come down with it.
+     *
+     * The capacity is what one instance's slice of the claim bitmask costs, so lowering it would
+     * make the bitmask's layout a function of eviction order — and the layout is fixed for the
+     * frame by a prefix scan taken before any of this runs.
+     *
+     * @param {number} geometry_row
+     * @param {number} ordinal
+     */
+    #give_ordinal(geometry_row, ordinal) {
+        this.#ordinals.get(geometry_row)?.free.push(ordinal);
+    }
+}
+
+/**
+ * @type {Set<number>}
+ */
+const EMPTY_ROWS = new Set();