@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -0,0 +1,1363 @@
+import { assert } from "../../../../../core/assert.js";
+import { ConcurrencyGate } from "../../../../../core/process/ConcurrencyGate.js";
+import { VGEO_FEEDBACK_OFFSET } from "./layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_PAGE_ROW_OFFSET } from "./layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_WANT_WORDS } from "./layout/VGEO_WANT_WORDS.js";
+import { VGeoPageFetcher } from "./VGeoPageFetcher.js";
+import { VGeoResidencyOptions } from "./VGeoResidencyOptions.js";
+
+/**
+ * @typedef {import("../format/read/VGeoContainerReader.js").VGeoContainerReader} VGeoContainerReader
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ * @typedef {import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool} GPUVirtualGeometryPool
+ */
+
+/**
+ * Where a page of a registered container is, as one word per page beside the lookup: the top two
+ * bits are the tag, the rest is the RAM slot or the VRAM row.
+ */
+const TAG_SHIFT = 30;
+const INDEX_MASK = (1 << TAG_SHIFT) - 1;
+
+const TAG_ABSENT = 0;
+const TAG_PENDING = 1;
+const TAG_RAM = 2;
+const TAG_VRAM = 3;
+
+const STATE_ABSENT = 0;
+const STATE_FETCHING = (TAG_PENDING << TAG_SHIFT) | 1;
+const STATE_QUARANTINED = (TAG_PENDING << TAG_SHIFT) | 2;
+
+const NO_SLOT = 0xFFFFFFFF;
+
+/**
+ * @param {number} state
+ * @returns {number}
+ */
+function tag_of(state) {
+    return state >>> TAG_SHIFT;
+}
+
+/**
+ * @param {number} state
+ * @returns {number}
+ */
+function index_of(state) {
+    return state & INDEX_MASK;
+}
+
+/**
+ * One registered container: its reader, its geometry row in the pool, and one word per page.
+ */
+class VGeoResidencyGeometry {
+    /**
+     * @type {VGeoContainerReader}
+     */
+    reader;
+
+    /**
+     * @type {number}
+     */
+    row;
+
+    /**
+     * Per container page index, where the page is — see the tags above.
+     * @type {Uint32Array}
+     */
+    state;
+
+    /**
+     * Per container page index, the RAM slot the page holds while it is in RAM or VRAM (VRAM is a
+     * subset of RAM), or {@link NO_SLOT}.
+     * @type {Uint32Array}
+     */
+    slot;
+
+    /**
+     * Fetches this reading dispatched for this container and how they ended, so that a container
+     * whose every fetch of a reading was quarantined is reported once.
+     * @type {{size: number, settled: number, quarantined: number}|undefined}
+     */
+    batch;
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @param {number} row
+     * @param {number} page_count
+     */
+    constructor(reader, row, page_count) {
+        this.reader = reader;
+        this.row = row;
+        this.state = new Uint32Array(page_count);
+        this.slot = new Uint32Array(page_count).fill(NO_SLOT);
+    }
+}
+
+/**
+ * Both tiers of residency for every registered container, flat, and nothing per frame that scales
+ * with what is resident.
+ *
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §6 names the tiers and the rules — RAM ⊇ VRAM, a byte budget each,
+ * LRU on last-touched under a protect window, never a page whose child is resident in the same
+ * tier, the root pinned, admission before the fetch. What this class changes is not a rule but the
+ * shape everything is kept in (RUNTIME_PLAN_2026_09_14 §4). Two owners kept the rules before it:
+ * `GPUVirtualGeometryPool` for VRAM, with a `Map` of touch stamps it walked once per install to
+ * find the coldest row, and `VGeoResidencyManager` for RAM, which built and sorted an array of
+ * every resident page of every reader whenever its budget bound. On the Zorah bdf6f961 container at
+ * 4,096 slots the first was 0.55 ms per refused install and the second the same defect in the tier
+ * above, and neither scaled with anything the host had chosen.
+ *
+ * So:
+ *
+ * - **One word per page**, beside the lookup and the same length, says where a page is — absent,
+ *   fetching, quarantined, in RAM at a slot, in VRAM at a row. A want is dropped, promoted or
+ *   fetched by one read of it, which is the whole of the cross-frame dedup.
+ * - **Struct-of-arrays per tier**, sized to a capacity the host stated: last use, bytes, the page,
+ *   the key. No `Map` is walked per frame.
+ * - **Touches arrive as bits** and are folded into `last_used` per set bit; a page in RAM and not in
+ *   VRAM cannot be touched, so its last use is the frame it left VRAM, written once.
+ * - **Eviction is CLOCK under a test budget.** A hand over each tier's array tests candidates in
+ *   order and evicts the first that may go; a reading may run at most
+ *   `max_eviction_tests_per_reading` tests across both tiers, after which it refuses what is left
+ *   and the hand carries on next reading. A full tier therefore turns over at a rate the options
+ *   chose, never at one the resident count chose. Not exact LRU, deliberately: the protect window
+ *   already coarsens the order to "not recently", and an exact order costs an update per touch.
+ * - **Admission before the fetch**, against the RAM budget and a slot, out of the `decoded_size`
+ *   the parent's child table carries (FORMAT §10) — a page that will not fit is never fetched.
+ * - **VRAM ⊆ RAM is enforced**: the RAM hand skips a page that is in VRAM, so the page a want was
+ *   discovered through is in RAM whenever the want is valid, and its child table resolves the
+ *   range. Before this nothing enforced it, and a want whose source the RAM tier had dropped was
+ *   silently skipped.
+ *
+ * A registered reader is this class's: its page map is driven through `install` and `evict` from
+ * here, and a tool or a viewer driving the same reader alongside it is unsupported rather than
+ * reconciled per frame.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoResidency {
+    /**
+     * @type {GPUVirtualGeometryPool}
+     */
+    #pool;
+
+    /**
+     * @type {VGeoResidencyOptions}
+     */
+    #options;
+
+    /**
+     * @type {ConcurrencyGate}
+     */
+    #gate;
+
+    /**
+     * @type {VGeoPageFetcher}
+     */
+    #fetcher;
+
+    /**
+     * Whether {@link destroy} terminates the fetcher's workers — it does when this made it.
+     * @type {boolean}
+     */
+    #owns_fetcher;
+
+    /**
+     * @type {Map<VGeoContainerReader, VGeoResidencyGeometry>}
+     */
+    #geometries = new Map();
+
+    /**
+     * Geometry row to its record, which is how a page row found through the pool reaches its
+     * container.
+     * @type {Map<number, VGeoResidencyGeometry>}
+     */
+    #by_row = new Map();
+
+    // ------------------------------------------------------------------ the VRAM tier
+
+    /**
+     * Per page row, the frame it was last drawn from — or installed at, so a page promoted in this
+     * reading is inside the protect window and not this reading's next victim.
+     * @type {Uint32Array}
+     */
+    #vram_last_used;
+
+    /**
+     * @type {Uint8Array}
+     */
+    #vram_pinned;
+
+    /**
+     * @type {number}
+     */
+    #vram_hand = 0;
+
+    // ------------------------------------------------------------------ the RAM tier
+
+    /**
+     * @type {(VGeoPage|undefined)[]}
+     */
+    #ram_page;
+
+    /**
+     * Geometry row per slot, or -1 for a free one.
+     * @type {Int32Array}
+     */
+    #ram_geometry;
+
+    /**
+     * @type {Uint32Array}
+     */
+    #ram_page_index;
+
+    /**
+     * Per slot, the frame the page last left VRAM, or entered RAM.
+     * @type {Uint32Array}
+     */
+    #ram_last;
+
+    /**
+     * Decoded bytes per slot; what the tier is charged and refunded.
+     * @type {Uint32Array}
+     */
+    #ram_bytes;
+
+    /**
+     * @type {number[]}
+     */
+    #ram_free = [];
+
+    /**
+     * @type {number}
+     */
+    #ram_hand = 0;
+
+    /**
+     * @type {number}
+     */
+    #ram_resident_bytes = 0;
+
+    /**
+     * Bytes admitted for fetches that have not landed, charged against the budget from the moment
+     * of admission so that a reading cannot admit more than the tier will have room for.
+     * @type {number}
+     */
+    #ram_reserved_bytes = 0;
+
+    /**
+     * @type {number}
+     */
+    #ram_count = 0;
+
+    // ------------------------------------------------------------------ per reading
+
+    /**
+     * @type {number}
+     */
+    #tests_left = 0;
+
+    /**
+     * @type {number}
+     */
+    #last_touch_count = 0;
+
+    /**
+     * @type {number}
+     */
+    #last_want_count = 0;
+
+    /**
+     * Scratch for ranking a reading's wants: record index by priority.
+     * @type {number[]}
+     */
+    #order = [];
+
+    // ------------------------------------------------------------------ counters
+
+    #evicted_vram_count = 0;
+    #evicted_ram_count = 0;
+    #refused_install_count = 0;
+    #refused_fetch_count = 0;
+    #deferred_want_count = 0;
+    #deduped_want_count = 0;
+    #stale_record_count = 0;
+    #lost_source_count = 0;
+    #moot_record_count = 0;
+    #failed_batch_count = 0;
+    #fetches_in_flight = 0;
+
+    /**
+     * @param {Object} options
+     * @param {GPUVirtualGeometryPool} options.pool
+     * @param {VGeoResidencyOptions} [options.options]
+     * @param {ConcurrencyGate} [options.gate] a fetch gate shared with other residencies
+     * @param {VGeoPageFetcher} [options.fetcher] where pages are fetched and decoded; by default
+     *     an in-process one, because only a host that can spawn a worker knows how
+     */
+    constructor({ pool, options = new VGeoResidencyOptions(), gate = undefined, fetcher = undefined }) {
+        assert.defined(pool, 'pool');
+
+        this.#pool = pool;
+        this.#options = options;
+        this.#gate = gate ?? new ConcurrencyGate(options.max_concurrent_fetches);
+        this.#fetcher = fetcher ?? new VGeoPageFetcher();
+        this.#owns_fetcher = fetcher === undefined;
+
+        const rows = pool.tables.page_capacity;
+
+        this.#vram_last_used = new Uint32Array(rows);
+        this.#vram_pinned = new Uint8Array(rows);
+
+        const slots = options.ram_slot_capacity;
+
+        assert.isPositiveInteger(slots, 'ram_slot_capacity');
+
+        this.#ram_page = new Array(slots).fill(undefined);
+        this.#ram_geometry = new Int32Array(slots).fill(-1);
+        this.#ram_page_index = new Uint32Array(slots);
+        this.#ram_last = new Uint32Array(slots);
+        this.#ram_bytes = new Uint32Array(slots);
+
+        for (let slot = slots - 1; slot >= 0; slot--) {
+            this.#ram_free.push(slot);
+        }
+    }
+
+    // ------------------------------------------------------------------ readings
+
+    /**
+     * @returns {VGeoResidencyOptions}
+     */
+    get options() {
+        return this.#options;
+    }
+
+    /**
+     * @returns {ConcurrencyGate}
+     */
+    get gate() {
+        return this.#gate;
+    }
+
+    /**
+     * @returns {VGeoPageFetcher}
+     */
+    get fetcher() {
+        return this.#fetcher;
+    }
+
+    /**
+     * @returns {GPUVirtualGeometryPool}
+     */
+    get pool() {
+        return this.#pool;
+    }
+
+    /**
+     * The clock both tiers read: the pool's frame, which the runtime advances at `begin_frame`
+     * whether or not a reading is scheduled that frame.
+     * @returns {number}
+     */
+    get frame() {
+        return this.#pool.frame;
+    }
+
+    /**
+     * Decoded bytes the VRAM tier may hold: the option, or what the pool's slots hold at its page
+     * size. Read each time, so a host may move it.
+     * @returns {number}
+     */
+    get vram_budget_bytes() {
+        return this.#options.vram_budget_bytes
+            ?? this.#pool.tables.page_capacity * this.#pool.page_size;
+    }
+
+    get ram_budget_bytes() {
+        return this.#options.ram_budget_bytes;
+    }
+
+    get ram_resident_bytes() {
+        return this.#ram_resident_bytes;
+    }
+
+    get ram_page_count() {
+        return this.#ram_count;
+    }
+
+    get reader_count() {
+        return this.#geometries.size;
+    }
+
+    get evicted_vram_count() {
+        return this.#evicted_vram_count;
+    }
+
+    get evicted_ram_count() {
+        return this.#evicted_ram_count;
+    }
+
+    /**
+     * Promotions the VRAM tier had no room for — no slot could be freed under the reading's test
+     * budget, or the page did not fit one.
+     * @returns {number}
+     */
+    get refused_install_count() {
+        return this.#refused_install_count;
+    }
+
+    /**
+     * Fetches the RAM tier had no room for.
+     * @returns {number}
+     */
+    get refused_fetch_count() {
+        return this.#refused_fetch_count;
+    }
+
+    /**
+     * Wants past a reading's promotion or fetch budget. Not a failure: the next cut asks again.
+     * @returns {number}
+     */
+    get deferred_want_count() {
+        return this.#deferred_want_count;
+    }
+
+    /**
+     * Wants for a page already in flight, or already in VRAM by the time the reading landed.
+     * @returns {number}
+     */
+    get deduped_want_count() {
+        return this.#deduped_want_count;
+    }
+
+    /**
+     * Records naming a page row that was refilled between the cut and the reading.
+     * @returns {number}
+     */
+    get stale_record_count() {
+        return this.#stale_record_count;
+    }
+
+    /**
+     * Wants whose source page was not in RAM, which the RAM tier's hand is meant to make impossible.
+     * @returns {number}
+     */
+    get lost_source_count() {
+        return this.#lost_source_count;
+    }
+
+    /**
+     * Records that named an empty row, an unregistered container, or a child reference the source
+     * page's table does not carry. The first is ordinary — a page evicted between the cut and the
+     * reading; the others a cut over a validated container does not produce.
+     * @returns {number}
+     */
+    get moot_record_count() {
+        return this.#moot_record_count;
+    }
+
+    /**
+     * Readings in which every fetch dispatched for one container was quarantined.
+     * @returns {number}
+     */
+    get failed_batch_count() {
+        return this.#failed_batch_count;
+    }
+
+    get fetches_in_flight() {
+        return this.#fetches_in_flight;
+    }
+
+    get last_touch_count() {
+        return this.#last_touch_count;
+    }
+
+    get last_want_count() {
+        return this.#last_want_count;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get quarantined_page_count() {
+        let count = 0;
+
+        for (const geometry of this.#geometries.values()) {
+            count += geometry.reader.quarantined_page_count;
+        }
+
+        return count;
+    }
+
+    // ------------------------------------------------------------------ containers
+
+    /**
+     * Take a container under both tiers: a geometry row and a lookup in the pool, its root page in
+     * RAM and VRAM, pinned in both.
+     *
+     * A refusal leaves nothing behind. Both ways this fails — a container built at another page
+     * size, and a tier with no room for another root — throw, and the pool's row is given back
+     * before they do; the message says what the tier holds.
+     *
+     * @param {VGeoContainerReader} reader open, with its root page resident
+     * @returns {number} the geometry row
+     */
+    register(reader) {
+        assert.defined(reader, 'reader');
+
+        const existing = this.#geometries.get(reader);
+
+        if (existing !== undefined) {
+            return existing.row;
+        }
+
+        assert.defined(reader.root, 'reader.root — the container must be open');
+
+        const row = this.#pool.register(reader);
+
+        const geometry = new VGeoResidencyGeometry(reader, row, reader.header.total_pages);
+
+        this.#geometries.set(reader, geometry);
+        this.#by_row.set(row, geometry);
+
+        const root = reader.root;
+
+        // a registration is a reading of its own as far as the eviction budget is concerned
+        this.#tests_left = this.#options.max_eviction_tests_per_reading;
+
+        const page_row = this.#make_ram_room(root.decoded_size)
+            ? (this.#take_ram_slot(geometry, root), this.#promote(geometry, root))
+            : -1;
+
+        if (page_row === -1) {
+            this.#drop_geometry(geometry);
+
+            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 VRAM tier holds ${this.#pool.tables.page_capacity} slots and`
+                + ` ${this.#pool.resident_page_count} are taken, of a ${this.vram_budget_bytes}-byte`
+                + ` budget with ${this.#pool.resident_bytes} spent; the RAM tier holds`
+                + ` ${this.#ram_count} pages of a ${this.#options.ram_budget_bytes}-byte budget`
+                + ` with ${this.#ram_resident_bytes} spent.`
+            );
+        }
+
+        this.#vram_pinned[page_row] = 1;
+
+        return row;
+    }
+
+    /**
+     * Give a container back: its rows, its lookup, its RAM slots, and the fetches it had on the
+     * wire. The decoded pages stay in the reader's map for the host to drop or keep.
+     *
+     * @param {VGeoContainerReader} reader
+     * @returns {boolean} whether it was registered
+     */
+    unregister(reader) {
+        const geometry = this.#geometries.get(reader);
+
+        if (geometry === undefined) {
+            return false;
+        }
+
+        // a reply that lands after this finds no geometry and is dropped
+        this.#fetcher.cancel(reader);
+        reader.cancel_all();
+
+        this.#drop_geometry(geometry);
+
+        return true;
+    }
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @returns {boolean}
+     */
+    is_registered(reader) {
+        return this.#geometries.has(reader);
+    }
+
+    /**
+     * Where one page of a registered container is, by name — for a panel or a spec.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @returns {'absent'|'fetching'|'quarantined'|'ram'|'vram'|'unregistered'}
+     */
+    where(reader, page_index) {
+        const geometry = this.#geometries.get(reader);
+
+        if (geometry === undefined || page_index >= geometry.state.length) {
+            return 'unregistered';
+        }
+
+        const state = geometry.state[page_index];
+
+        switch (tag_of(state)) {
+            case TAG_RAM:
+                return 'ram';
+            case TAG_VRAM:
+                return 'vram';
+            case TAG_PENDING:
+                return state === STATE_FETCHING ? 'fetching' : 'quarantined';
+            default:
+                return 'absent';
+        }
+    }
+
+    /**
+     * @param {VGeoResidencyGeometry} geometry
+     */
+    #drop_geometry(geometry) {
+        const state = geometry.state;
+
+        for (let page_index = 0; page_index < state.length; page_index++) {
+            const tag = tag_of(state[page_index]);
+
+            if (tag === TAG_VRAM) {
+                const row = index_of(state[page_index]);
+
+                this.#vram_pinned[row] = 0;
+                this.#vram_last_used[row] = 0;
+            }
+
+            if (tag === TAG_VRAM || tag === TAG_RAM) {
+                this.#free_ram_slot(geometry.slot[page_index]);
+            }
+
+            state[page_index] = STATE_ABSENT;
+            geometry.slot[page_index] = NO_SLOT;
+        }
+
+        this.#pool.unregister(geometry.reader);
+
+        this.#geometries.delete(geometry.reader);
+        this.#by_row.delete(geometry.row);
+    }
+
+    /**
+     * Stop every fetch every registered container has on the wire.
+     *
+     * @returns {void}
+     */
+    abort() {
+        for (const geometry of this.#geometries.values()) {
+            this.#fetcher.cancel(geometry.reader);
+            geometry.reader.cancel_all();
+        }
+    }
+
+    /**
+     * Give up on everything: every fetch, every container.
+     *
+     * @returns {void}
+     */
+    destroy() {
+        for (const reader of Array.from(this.#geometries.keys())) {
+            this.unregister(reader);
+        }
+
+        if (this.#owns_fetcher) {
+            this.#fetcher.destroy();
+        }
+    }
+
+    /**
+     * Let every quarantined page be asked for again.
+     *
+     * @returns {number} pages released
+     */
+    clear_quarantines() {
+        let released = 0;
+
+        for (const geometry of this.#geometries.values()) {
+            released += geometry.reader.clear_quarantine();
+
+            const state = geometry.state;
+
+            for (let page_index = 0; page_index < state.length; page_index++) {
+                if (state[page_index] === STATE_QUARANTINED) {
+                    state[page_index] = STATE_ABSENT;
+                }
+            }
+        }
+
+        return released;
+    }
+
+    // ------------------------------------------------------------------ a reading
+
+    /**
+     * Apply one frame's feedback: the touches to both tiers' clocks, and the wants to promotions and
+     * fetches, under the reading's budgets.
+     *
+     * @param {Uint32Array} words the feedback buffer, decoded with its own frame's layout
+     * @param {{touch_bits_base: number, touch_word_count: number, want_base: number,
+     *     word_count: number}} layout
+     * @param {number} reading_frame the frame whose cut wrote these words
+     * @returns {void}
+     */
+    apply(words, layout, reading_frame) {
+        const options = this.#options;
+
+        this.#tests_left = options.max_eviction_tests_per_reading;
+
+        for (const geometry of this.#geometries.values()) {
+            geometry.batch = undefined;
+        }
+
+        this.#fold_touches(words, layout, reading_frame);
+
+        const count = this.#rank_wants(words, layout);
+
+        let promotions = 0;
+        let fetches = 0;
+
+        for (let i = 0; i < count; i++) {
+            const base = layout.want_base + this.#order[i] * VGEO_WANT_WORDS;
+
+            const source_row = words[base];
+            const child_ref = words[base + 1];
+            const child_page_index = words[base + 2];
+            const priority = decode_float(words[base + 3]);
+
+            const entry = this.#pool.entry_of(source_row);
+
+            if (entry === undefined) {
+                // evicted between the cut and this reading, and the row is empty: moot
+                this.#moot_record_count++;
+
+                continue;
+            }
+
+            if (!this.#still_the_same_page(source_row, reading_frame)) {
+                // the row was refilled between the cut and this reading, so the page index and the
+                // byte range the child table would give come from two different pages
+                this.#stale_record_count++;
+
+                continue;
+            }
+
+            const geometry = this.#geometries.get(entry.reader);
+
+            if (geometry === undefined || child_page_index >= geometry.state.length) {
+                this.#moot_record_count++;
+
+                continue;
+            }
+
+            const state = geometry.state[child_page_index];
+            const tag = tag_of(state);
+
+            if (tag === TAG_VRAM || tag === TAG_PENDING) {
+                // promoted a reading or two ago and the cut had not seen it yet; or on the wire, or
+                // not coming back until somebody clears the quarantine
+                this.#deduped_want_count++;
+
+                continue;
+            }
+
+            if (tag === TAG_RAM) {
+                if (promotions >= options.max_promotions_per_reading) {
+                    this.#deferred_want_count++;
+
+                    continue;
+                }
+
+                const page = this.#ram_page[geometry.slot[child_page_index]];
+
+                if (this.#promote(geometry, page) !== -1) {
+                    promotions++;
+                }
+
+                continue;
+            }
+
+            // absent: a fetch, through the page the want was discovered through
+            if (fetches >= options.max_fetches_per_reading
+                || this.#fetches_in_flight >= options.max_concurrent_fetches * 2) {
+                this.#deferred_want_count++;
+
+                continue;
+            }
+
+            const source_index = this.#pool.page_index_of(source_row);
+
+            const source = entry.reader.page(source_index);
+
+            if (source === undefined) {
+                this.#lost_source_count++;
+
+                continue;
+            }
+
+            if (child_ref >= source.child_page_index.length
+                || source.child_page_index[child_ref] !== child_page_index) {
+                // a record the child table cannot resolve, which a cut over a validated container
+                // does not produce
+                this.#moot_record_count++;
+
+                continue;
+            }
+
+            if (this.#fetch(
+                geometry,
+                child_page_index,
+                source.child_frame_offset[child_ref],
+                source.child_fetch_size[child_ref],
+                source.child_decoded_size[child_ref],
+                priority
+            )) {
+                fetches++;
+            }
+        }
+
+        /*
+         And the budgets themselves, once a reading, under whatever is left of the test budget. A
+         host that lowers a budget while the tiers are full gets them back under it over the
+         following readings rather than only when the next admission happens to ask; within budget
+         this is two comparisons.
+         */
+        this.#make_vram_room(0, false);
+        this.#make_ram_room(0, false);
+    }
+
+    /**
+     * Whether a page row still holds the page it held when the cut of `reading_frame` ran.
+     *
+     * @param {number} page_row
+     * @param {number} reading_frame
+     * @returns {boolean}
+     */
+    #still_the_same_page(page_row, reading_frame) {
+        return this.#pool.visible_from(page_row) <= reading_frame;
+    }
+
+    /**
+     * @param {Uint32Array} words
+     * @param {object} layout
+     * @param {number} reading_frame
+     */
+    #fold_touches(words, layout, reading_frame) {
+        const frame = this.frame;
+
+        let count = 0;
+
+        for (let word = 0; word < layout.touch_word_count; word++) {
+            let bits = words[layout.touch_bits_base + word];
+
+            while (bits !== 0) {
+                const bit = 31 - Math.clz32(bits & -bits);
+
+                bits &= bits - 1;
+
+                const page_row = word * 32 + bit;
+
+                count++;
+
+                if (this.#pool.entry_of(page_row) === undefined) {
+                    // evicted between the cut and this reading; the stamp it would take is moot
+                    continue;
+                }
+
+                if (!this.#still_the_same_page(page_row, reading_frame)) {
+                    // evicted and refilled in between; stamping now would make a page nobody has
+                    // drawn the hottest thing in the tier
+                    this.#stale_record_count++;
+
+                    continue;
+                }
+
+                this.#vram_last_used[page_row] = frame;
+            }
+        }
+
+        this.#last_touch_count = count;
+    }
+
+    /**
+     * Order this reading's want records by priority, highest first.
+     *
+     * A sort of at most `want_capacity` indices. It is not on the GPU, deliberately: the list is
+     * capped, a sort of two thousand numbers is microseconds, and a device sort is a dozen dispatches
+     * to shave a few kilobytes off a readback (RUNTIME_PLAN_2026_09_14 §4.5).
+     *
+     * @param {Uint32Array} words
+     * @param {object} layout
+     * @returns {number} records
+     */
+    #rank_wants(words, layout) {
+        const capacity = Math.floor((layout.word_count - layout.want_base) / VGEO_WANT_WORDS);
+
+        // clamped: the count is an atomicAdd that ran past the capacity the kernel refused to write at
+        const count = Math.min(words[VGEO_FEEDBACK_OFFSET.WANT_COUNT], capacity);
+
+        this.#last_want_count = count;
+
+        const order = this.#order;
+
+        order.length = count;
+
+        for (let i = 0; i < count; i++) {
+            order[i] = i;
+        }
+
+        const priority = i => decode_float(words[layout.want_base + i * VGEO_WANT_WORDS + 3]);
+
+        order.sort((a, b) => priority(b) - priority(a));
+
+        return count;
+    }
+
+    // ------------------------------------------------------------------ VRAM
+
+    /**
+     * Whether a page row may be evicted from VRAM right now: resident, not pinned, outside the
+     * protect window, and with no child page resident in VRAM.
+     *
+     * @param {number} page_row
+     * @returns {boolean}
+     */
+    evictable_vram(page_row) {
+        if (this.#pool.entry_of(page_row) === undefined) {
+            return false;
+        }
+
+        if (this.#vram_pinned[page_row] !== 0) {
+            return false;
+        }
+
+        if (this.frame - this.#vram_last_used[page_row] < this.#options.protect_frames) {
+            return false;
+        }
+
+        return this.#pool.tables.resident_children(page_row) === 0;
+    }
+
+    /**
+     * Whether a RAM slot's page may be evicted from RAM right now: occupied, not the root, not in
+     * VRAM, outside the protect window, and with no child page resident in either tier.
+     *
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    evictable_ram(slot) {
+        const geometry_row = this.#ram_geometry[slot];
+
+        if (geometry_row === -1) {
+            return false;
+        }
+
+        const page = this.#ram_page[slot];
+
+        if (page === undefined || page.index === 0) {
+            return false;
+        }
+
+        const geometry = this.#by_row.get(geometry_row);
+
+        if (tag_of(geometry.state[page.index]) === TAG_VRAM) {
+            return false;
+        }
+
+        if (this.frame - this.#ram_last[slot] < this.#options.protect_frames) {
+            return false;
+        }
+
+        const state = geometry.state;
+
+        for (const child of page.child_page_index) {
+            const tag = tag_of(state[child]);
+
+            if (tag === TAG_RAM || tag === TAG_VRAM) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Make a page resident in VRAM out of RAM, making room under the reading's test budget.
+     *
+     * @param {VGeoResidencyGeometry} geometry
+     * @param {VGeoPage} page
+     * @returns {number} page row, or -1
+     */
+    #promote(geometry, page) {
+        if (!this.#make_vram_room(page.decoded_size)) {
+            this.#refused_install_count++;
+
+            return -1;
+        }
+
+        const page_row = this.#pool.install(geometry.reader, page.index);
+
+        if (page_row === -1) {
+            this.#refused_install_count++;
+
+            return -1;
+        }
+
+        geometry.state[page.index] = (TAG_VRAM << TAG_SHIFT) | page_row;
+
+        this.#vram_last_used[page_row] = this.frame;
+        this.#vram_pinned[page_row] = 0;
+
+        return page_row;
+    }
+
+    /**
+     * @param {number} bytes
+     * @param {boolean} [slot] whether a free page row is needed as well — it is for an install,
+     *     and not for bringing a tier back under a budget that moved
+     * @returns {boolean}
+     */
+    #make_vram_room(bytes, slot = true) {
+        const pool = this.#pool;
+
+        for (;;) {
+            if (pool.resident_bytes + bytes <= this.vram_budget_bytes
+                && (!slot || pool.tables.has_free_page_row)) {
+                return true;
+            }
+
+            const victim = this.#next_vram_victim();
+
+            if (victim === -1) {
+                return false;
+            }
+
+            this.#evict_vram(victim);
+        }
+    }
+
+    /**
+     * The CLOCK hand over the page rows, under the reading's test budget.
+     *
+     * @returns {number} page row, or -1 when the budget is spent without finding one
+     */
+    #next_vram_victim() {
+        const capacity = this.#vram_last_used.length;
+
+        while (this.#tests_left > 0) {
+            this.#tests_left--;
+
+            const page_row = this.#vram_hand;
+
+            this.#vram_hand = (page_row + 1) % capacity;
+
+            if (this.evictable_vram(page_row)) {
+                return page_row;
+            }
+        }
+
+        return -1;
+    }
+
+    /**
+     * @param {number} page_row
+     */
+    #evict_vram(page_row) {
+        const entry = this.#pool.entry_of(page_row);
+
+        const geometry = this.#geometries.get(entry.reader);
+
+        const page_index = this.#pool.page_index_of(page_row);
+
+        this.#pool.evict(page_row);
+
+        const slot = geometry.slot[page_index];
+
+        geometry.state[page_index] = (TAG_RAM << TAG_SHIFT) | slot;
+
+        // the last time it was drawn from is the last time it was in VRAM
+        this.#ram_last[slot] = this.frame;
+
+        this.#vram_pinned[page_row] = 0;
+        this.#vram_last_used[page_row] = 0;
+
+        this.#evicted_vram_count++;
+    }
+
+    // ------------------------------------------------------------------ RAM
+
+    /**
+     * @param {number} bytes
+     * @param {boolean} [slot] whether a free slot is needed as well
+     * @returns {boolean}
+     */
+    #make_ram_room(bytes, slot = true) {
+        const budget = this.#options.ram_budget_bytes;
+
+        for (;;) {
+            if (this.#ram_resident_bytes + this.#ram_reserved_bytes + bytes <= budget
+                && (!slot || this.#ram_free.length > 0)) {
+                return true;
+            }
+
+            const victim = this.#next_ram_victim();
+
+            if (victim === -1) {
+                return false;
+            }
+
+            this.#evict_ram(victim);
+        }
+    }
+
+    /**
+     * @returns {number} slot, or -1
+     */
+    #next_ram_victim() {
+        const capacity = this.#ram_geometry.length;
+
+        while (this.#tests_left > 0) {
+            this.#tests_left--;
+
+            const slot = this.#ram_hand;
+
+            this.#ram_hand = (slot + 1) % capacity;
+
+            if (this.evictable_ram(slot)) {
+                return slot;
+            }
+        }
+
+        return -1;
+    }
+
+    /**
+     * @param {number} slot
+     */
+    #evict_ram(slot) {
+        const geometry = this.#by_row.get(this.#ram_geometry[slot]);
+
+        const page_index = this.#ram_page_index[slot];
+
+        geometry.reader.evict(page_index);
+
+        geometry.state[page_index] = STATE_ABSENT;
+        geometry.slot[page_index] = NO_SLOT;
+
+        this.#free_ram_slot(slot);
+
+        this.#evicted_ram_count++;
+    }
+
+    /**
+     * Put a page the reader already holds into a slot. Room is the caller's business.
+     *
+     * @param {VGeoResidencyGeometry} geometry
+     * @param {VGeoPage} page
+     * @returns {number} slot
+     */
+    #take_ram_slot(geometry, page) {
+        const slot = this.#reserve_ram_slot(geometry, page.index, page.decoded_size);
+
+        this.#land(slot, page);
+
+        return slot;
+    }
+
+    /**
+     * Take a slot and charge the bytes, for a page that is here or on its way.
+     *
+     * @param {VGeoResidencyGeometry} geometry
+     * @param {number} page_index
+     * @param {number} bytes
+     * @returns {number} slot
+     */
+    #reserve_ram_slot(geometry, page_index, bytes) {
+        const slot = this.#ram_free.pop();
+
+        this.#ram_geometry[slot] = geometry.row;
+        this.#ram_page_index[slot] = page_index;
+        this.#ram_page[slot] = undefined;
+        this.#ram_bytes[slot] = bytes;
+        this.#ram_last[slot] = this.frame;
+
+        this.#ram_reserved_bytes += bytes;
+
+        geometry.slot[page_index] = slot;
+
+        return slot;
+    }
+
+    /**
+     * A reserved slot's page has arrived.
+     *
+     * @param {number} slot
+     * @param {VGeoPage} page
+     */
+    #land(slot, page) {
+        const geometry = this.#by_row.get(this.#ram_geometry[slot]);
+
+        this.#ram_reserved_bytes -= this.#ram_bytes[slot];
+
+        // what it actually decoded to, which is what the tier holds and refunds
+        this.#ram_bytes[slot] = page.decoded_size;
+        this.#ram_page[slot] = page;
+        this.#ram_last[slot] = this.frame;
+
+        this.#ram_resident_bytes += page.decoded_size;
+        this.#ram_count++;
+
+        geometry.state[page.index] = (TAG_RAM << TAG_SHIFT) | slot;
+    }
+
+    /**
+     * @param {number} slot
+     */
+    #free_ram_slot(slot) {
+        if (slot === NO_SLOT || this.#ram_geometry[slot] === -1) {
+            return;
+        }
+
+        if (this.#ram_page[slot] !== undefined) {
+            this.#ram_resident_bytes -= this.#ram_bytes[slot];
+            this.#ram_count--;
+        } else {
+            this.#ram_reserved_bytes -= this.#ram_bytes[slot];
+        }
+
+        this.#ram_page[slot] = undefined;
+        this.#ram_geometry[slot] = -1;
+        this.#ram_bytes[slot] = 0;
+
+        this.#ram_free.push(slot);
+    }
+
+    // ------------------------------------------------------------------ fetching
+
+    /**
+     * Admit a page against the RAM tier and start its fetch.
+     *
+     * @param {VGeoResidencyGeometry} geometry
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {number} decoded_size
+     * @param {number} priority
+     * @returns {boolean} whether a fetch was started
+     */
+    #fetch(geometry, page_index, frame_offset, fetch_size, decoded_size, priority) {
+        if (!this.#make_ram_room(decoded_size)) {
+            this.#refused_fetch_count++;
+
+            return false;
+        }
+
+        const reader = geometry.reader;
+
+        const slot = this.#reserve_ram_slot(geometry, page_index, decoded_size);
+
+        geometry.state[page_index] = STATE_FETCHING;
+
+        if (geometry.batch === undefined) {
+            geometry.batch = { size: 0, settled: 0, quarantined: 0 };
+        }
+
+        const batch = geometry.batch;
+
+        batch.size++;
+
+        this.#fetches_in_flight++;
+
+        this.#gate.submit(
+            priority,
+            () => this.#fetcher.fetch(reader, page_index, frame_offset, fetch_size)
+        )
+            .then(
+                page => {
+                    this.#fetches_in_flight--;
+
+                    if (this.#geometries.get(reader) !== geometry) {
+                        // unregistered while on the wire; the slot went with the geometry
+                        return;
+                    }
+
+                    if (geometry.state[page_index] !== STATE_FETCHING) {
+                        return;
+                    }
+
+                    // the reader's page map is the RAM tier's store, and this is its one door
+                    this.#land(slot, reader.adopt(page));
+
+                    this.#settle(reader, geometry, batch, false);
+                },
+                error => {
+                    this.#fetches_in_flight--;
+
+                    if (this.#geometries.get(reader) !== geometry) {
+                        return;
+                    }
+
+                    if (geometry.state[page_index] !== STATE_FETCHING) {
+                        return;
+                    }
+
+                    // a quarantine is the fetch's verdict and the reader's fact; a cancellation is
+                    // nobody's fault, and the next cut asks again
+                    const quarantined = error?.quarantine === true;
+
+                    if (quarantined) {
+                        reader.quarantine_page(page_index, error.reason ?? error.message);
+                    }
+
+                    geometry.state[page_index] = quarantined ? STATE_QUARANTINED : STATE_ABSENT;
+                    geometry.slot[page_index] = NO_SLOT;
+
+                    this.#free_ram_slot(slot);
+
+                    this.#settle(reader, geometry, batch, quarantined);
+                }
+            );
+
+        return true;
+    }
+
+    /**
+     * One fetch of a reading's batch has ended; a batch every page of which was quarantined is a
+     * container that cannot be streamed, which is worth one line and a counter.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {VGeoResidencyGeometry} geometry
+     * @param {{size: number, settled: number, quarantined: number}} batch
+     * @param {boolean} quarantined
+     */
+    #settle(reader, geometry, batch, quarantined) {
+        batch.settled++;
+
+        if (quarantined) {
+            batch.quarantined++;
+        }
+
+        if (batch.settled < batch.size || batch.quarantined < batch.size) {
+            return;
+        }
+
+        this.#failed_batch_count++;
+
+        console.warn(
+            `vgeo: every one of ${batch.size} page fetches was quarantined`
+            + ` by ${reader.name ?? 'a reader'}`
+        );
+    }
+}
+
+const FLOAT_SCRATCH = new Float32Array(1);
+const WORD_SCRATCH = new Uint32Array(FLOAT_SCRATCH.buffer);
+
+/**
+ * @param {number} word
+ * @returns {number}
+ */
+function decode_float(word) {
+    WORD_SCRATCH[0] = word;
+
+    return FLOAT_SCRATCH[0];
+}