@woosh/meep-engine 3.26.0 → 3.27.0

package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.js

@@ -1,723 +0,0 @@
-import { assert } from "../../../../../core/assert.js";
-import { ConcurrencyGate } from "../../../../../core/process/ConcurrencyGate.js";
-import { VGeoResidencyOptions } from "./VGeoResidencyOptions.js";
-
-/**
- * One reader's place in the manager's books.
- */
-class VGeoResidencyEntry {
-    /**
-     * @type {VGeoContainerReader}
-     */
-    reader = undefined;
-
-    /**
-     * The frame each resident page was last touched on. A page installs touched, because installing
-     * it was somebody wanting it.
-     * @type {Map<number, number>}
-     */
-    touched = new Map();
-
-    /**
-     * What this reader's `resident_bytes` was the last time the total was reconciled with it. Kept
-     * per reader so that the total stays exact under interleaved installs: the delta is taken
-     * against the reader's own authoritative number rather than accumulated from page sizes, so two
-     * installs completing in either order come to the same total.
-     * @type {number}
-     */
-    bytes = 0;
-
-    /**
-     * @param {VGeoContainerReader} reader
-     */
-    constructor(reader) {
-        this.reader = reader;
-    }
-}
-
-/**
- * The budget owner: what may be resident, what may be in flight, and what gets dropped.
- *
- * `VGeoContainerReader` is mechanics — it fetches a page, decodes it, keeps the activation counters
- * straight, and reports what it holds. It decides none of the questions that only make sense across
- * readers, and `VGEO_FORMAT.md` §10 says so deliberately, requirement by requirement: the eviction
- * *rule* is spelled out there and the *choice* of which page to drop is left to "whatever owns the
- * budget". This is that. Nothing here reaches inside a reader; it is written entirely against the
- * reader's public surface, which is the test that the split is real.
- *
- * Three things live here because none of them can live below:
- *
- * - **A byte budget across every reader.** A reader reports `resident_bytes` and enforces nothing;
- *   at a thousand assets of several gigabytes each, the resident set has to be a small fraction of
- *   *one* asset and no reader can know that. {@link install_wants} admits a want against the budget
- *   before it is fetched, using the `decoded_size` the child table already told the traversal, and
- *   {@link evict_to_budget} is what makes room.
- * - **A shared fetch cap and a global priority order.** Per-reader caps do not compose: eight
- *   readers at `max_concurrent_fetches = 6` were measured issuing 48 concurrent range requests.
- *   One {@link ConcurrencyGate} holds the total, and holds it as one priority queue so that the
- *   most visibly coarse page wins wherever it came from. That is meaningful only because a want's
- *   priority is pixels of projected error past the threshold, which is comparable across assets by
- *   construction; a per-reader queue could not say it however truthfully the numbers compared.
- * - **Eviction, on §10's rule and design §6's order.** A page is evictable only while it has no
- *   resident child pages (leaves-first falls out of that), the root page is never evictable, and
- *   among the rest the oldest **last-touched** stamp goes first with a protect window no shorter
- *   than feedback latency. LRU on last-*wanted* would freeze stamps at fetch time and evict what is
- *   on screen.
- *
- * **Two of those three are the third implementation in this engine, and that is the honest way to
- * read them.** `VTPhysicalCache` is the near-identical precedent for eviction: a `#last_touch`
- * `Uint32Array` per slot, `touch(slot, frame)` and `last_touch(slot)`, a per-slot lock flag for
- * slots that must never be evicted — the analogue of pinning the root page here — and
- * `find_eviction_candidate(current_frame, protect_window)`, whose own doc justifies the window the
- * same way this class does: feedback readback runs a couple of frames behind, so recently touched
- * really means probably on screen. That convergence is neither coincidence nor independent
- * invention — design §6 pinned the rule and wrote "the VT system already keys on touch for this
- * reason" while doing it. The one thing that cache does differently is worth copying if this ever
- * gets hot: it picks by linear scan, on the argument that at ≤ ~1k slots a scan beats maintaining
- * a heap. For the fetch cap, `AssetManager.load_concurrency` and
- * `VirtualTextureManager.max_concurrent_loads` both predate it — being the third place to want it
- * is why the gate is now {@link ConcurrencyGate}, in `core/process/`, whose own doc says where it
- * repeats those two and why neither of them adopted it.
- *
- * **The first bullet is what has no precedent here.** Neither of those budgets *bytes* across
- * *several* readers. `VTPhysicalCache` budgets a count of fixed-size slots, which is the whole
- * reason its eviction can be a scan over a flat array; `AssetManager` budgets nothing at all —
- * `remove` and `clear` are manual and there is no eviction policy to compare against. Admitting a
- * page against a byte budget *before* the fetch, out of the `decoded_size` its parent's child
- * table already carries, is the part of this that had nothing to borrow from. So are the two
- * failure behaviours below: bounded retry with backoff into per-page quarantine, where
- * `AssetManager` only records a failure and lets a *new* `get` retry it, and per-fetch
- * `AbortSignal` cancellation, which neither precedent has.
- *
- * **Why these pages are not simply `AssetManager`'s problem**, given how much of this it already
- * does: an `AssetDescription` is a path and a type, two strings, one entry per thing loaded. A VG
- * page is a byte range inside a container that the format gives no global identifier at all — a
- * cluster is a page plus an index within it — and containers here run to 4,000 and 20,000 pages
- * apiece against a thousand open assets. The unit is wrong by orders of magnitude before anything
- * about the cache itself is considered.
- *
- * **What it does not do.** It does not decide what to want — that is the cut's job, and the wants
- * arrive here already ranked. It does not know about VRAM: design §6's third tier is a separate
- * budget over a separate pool, and this is the RAM tier. And it does not make a dropped page
- * incorrect: everything it evicts, the clamped cut covers with a coarser ancestor that is still
- * selectable, which is why a budget can be enforced at all.
- *
- * A runtime registering a reader should also set `VGeoReadOptions.verify_frames` on it. §10 requires
- * frame verification of a runtime reader and the reader defaults it off, because a tool reading a
- * file it just built is not defending against a network — but a manager holding a thousand streamed
- * assets is exactly the case the requirement is about, and verification is what lets the retries and
- * the quarantine below see corruption rather than only outages.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class VGeoResidencyManager {
-    /**
-     * @type {VGeoResidencyOptions}
-     */
-    #options;
-
-    /**
-     * @type {ConcurrencyGate}
-     */
-    #scheduler;
-
-    /**
-     * @type {Map<VGeoContainerReader, VGeoResidencyEntry>}
-     */
-    #readers = new Map();
-
-    /**
-     * @type {number}
-     */
-    #frame = 0;
-
-    /**
-     * Decoded bytes across every registered reader. Kept incrementally — see
-     * {@link VGeoResidencyEntry.bytes} — and reconciled outright by {@link resync}.
-     * @type {number}
-     */
-    #resident_bytes = 0;
-
-    /**
-     * @type {number}
-     */
-    #evicted_page_count = 0;
-
-    /**
-     * @type {number}
-     */
-    #refused_want_count = 0;
-
-    /**
-     * @param {VGeoResidencyOptions} [options]
-     * @param {ConcurrencyGate} [scheduler] one is built from {@link options} when it is left out;
-     *     pass one to share a cap with something else that fetches
-     */
-    constructor(options = new VGeoResidencyOptions(), scheduler = undefined) {
-        this.#options = options;
-        this.#scheduler = scheduler ?? new ConcurrencyGate(options.max_concurrent_fetches);
-    }
-
-    /**
-     * @returns {VGeoResidencyOptions}
-     */
-    get options() {
-        return this.#options;
-    }
-
-    /**
-     * @returns {ConcurrencyGate}
-     */
-    get scheduler() {
-        return this.#scheduler;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get reader_count() {
-        return this.#readers.size;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get frame() {
-        return this.#frame;
-    }
-
-    /**
-     * Decoded page bytes held by every registered reader together — the number the budget is spent
-     * against.
-     * @returns {number}
-     */
-    get resident_bytes() {
-        return this.#resident_bytes;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get budget_bytes() {
-        return this.#options.budget_bytes;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get resident_page_count() {
-        let count = 0;
-
-        for (const entry of this.#readers.values()) {
-            count += entry.reader.resident_page_count;
-        }
-
-        return count;
-    }
-
-    /**
-     * How many pages this manager has dropped. Telemetry, and the thing to watch when a scene is
-     * thrashing: a page count that climbs faster than the frame count is a budget too small for the
-     * cut being asked for.
-     * @returns {number}
-     */
-    get evicted_page_count() {
-        return this.#evicted_page_count;
-    }
-
-    /**
-     * How many wants were refused because nothing could be evicted to make room for them.
-     *
-     * Not an error: a refused want is a page the next traversal will want again, from a cut that is
-     * correct without it. A number that stays high is the budget saying it cannot hold the cut being
-     * asked for, which is a τ or a budget decision and not a streaming one.
-     *
-     * @returns {number}
-     */
-    get refused_want_count() {
-        return this.#refused_want_count;
-    }
-
-    /**
-     * Take a reader under the budget.
-     *
-     * @param {VGeoContainerReader} reader
-     * @returns {VGeoContainerReader} the same reader, so this can wrap an `open`
-     */
-    register(reader) {
-        assert.defined(reader, 'reader');
-
-        if (this.#readers.has(reader)) {
-            return reader;
-        }
-
-        const entry = new VGeoResidencyEntry(reader);
-
-        entry.bytes = reader.resident_bytes;
-
-        for (const page of reader.resident_pages()) {
-            entry.touched.set(page.index, this.#frame);
-        }
-
-        this.#readers.set(reader, entry);
-        this.#resident_bytes += entry.bytes;
-
-        return reader;
-    }
-
-    /**
-     * Stop counting a reader's pages against the budget.
-     *
-     * The reader keeps whatever it holds — dropping it is the caller's business, and a reader being
-     * unregistered is usually one about to be discarded whole.
-     *
-     * @param {VGeoContainerReader} reader
-     * @returns {boolean} whether it was registered
-     */
-    unregister(reader) {
-        const entry = this.#readers.get(reader);
-
-        if (entry === undefined) {
-            return false;
-        }
-
-        this.#resident_bytes -= entry.bytes;
-
-        this.#readers.delete(reader);
-
-        return true;
-    }
-
-    /**
-     * @param {VGeoContainerReader} reader
-     * @returns {boolean}
-     */
-    is_registered(reader) {
-        return this.#readers.has(reader);
-    }
-
-    /**
-     * Advance the frame counter, and reconcile the byte total with what the readers actually hold.
-     *
-     * Call it once a frame. The reconciliation is what keeps the budget honest when something
-     * installed or evicted without going through here — which a tool, a test, or a playground
-     * button all legitimately do.
-     *
-     * @returns {number} the new frame number
-     */
-    advance_frame() {
-        this.#frame++;
-
-        this.resync();
-
-        return this.#frame;
-    }
-
-    /**
-     * Re-read every registered reader's `resident_bytes`, and forget touch stamps for pages that are
-     * no longer resident.
-     *
-     * @returns {number} the reconciled total
-     */
-    resync() {
-        let total = 0;
-
-        for (const entry of this.#readers.values()) {
-            entry.bytes = entry.reader.resident_bytes;
-
-            total += entry.bytes;
-
-            if (entry.touched.size > entry.reader.resident_page_count) {
-                for (const page_index of Array.from(entry.touched.keys())) {
-                    if (!entry.reader.is_resident(page_index)) {
-                        entry.touched.delete(page_index);
-                    }
-                }
-            }
-        }
-
-        this.#resident_bytes = total;
-
-        return total;
-    }
-
-    /**
-     * Record that a page was selected from this frame — design §6's touch, which is what eviction
-     * orders on.
-     *
-     * @param {VGeoContainerReader} reader
-     * @param {number} page_index
-     */
-    touch(reader, page_index) {
-        const entry = this.#readers.get(reader);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        entry.touched.set(page_index, this.#frame);
-    }
-
-    /**
-     * Record every page of a cut as touched.
-     *
-     * @param {VGeoContainerReader} reader
-     * @param {Iterable<number>} page_indices
-     */
-    touch_all(reader, page_indices) {
-        const entry = this.#readers.get(reader);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        for (const page_index of page_indices) {
-            entry.touched.set(page_index, this.#frame);
-        }
-    }
-
-    /**
-     * The frame a page was last touched on, or `-1` for one nothing has reported.
-     *
-     * @param {VGeoContainerReader} reader
-     * @param {number} page_index
-     * @returns {number}
-     */
-    last_touched(reader, page_index) {
-        return this.#readers.get(reader)?.touched.get(page_index) ?? -1;
-    }
-
-    /**
-     * Whether a page may be dropped right now — §10's eviction rule, plus design §6's protect
-     * window.
-     *
-     * @param {VGeoContainerReader} reader
-     * @param {number} page_index
-     * @returns {boolean}
-     */
-    evictable(reader, page_index) {
-        const entry = this.#readers.get(reader);
-
-        if (entry === undefined || !reader.is_resident(page_index)) {
-            return false;
-        }
-
-        // §10: the root page is pinned, because every traversal starts by walking its parentless
-        // groups and a cut with no entry point is not a coarser cut, it is no cut
-        if (page_index === 0) {
-            return false;
-        }
-
-        // §10: within a tier, a page is evictable only while it has no resident child pages —
-        // checked against its own child table. Leaves-first order is a consequence, not a rule.
-        if (reader.resident_child_count(page_index) > 0) {
-            return false;
-        }
-
-        const touched = entry.touched.get(page_index);
-
-        if (touched !== undefined && this.#frame - touched < this.#options.protect_frames) {
-            return false;
-        }
-
-        return true;
-    }
-
-    /**
-     * Drop pages until the budget has room for `headroom` more bytes.
-     *
-     * Oldest touch first, and only pages the rule allows — so the first pass finds leaves, dropping
-     * them makes their parents evictable, and the next pass finds those. Dropping a page can only
-     * ever make another page *more* evictable, never less, which is what lets each pass reuse the
-     * ordering it built.
-     *
-     * @param {number} [headroom] bytes to leave room for on top of the budget's own limit
-     * @returns {number} pages dropped
-     */
-    evict_to_budget(headroom = 0) {
-        const budget = this.#options.budget_bytes;
-
-        let dropped = 0;
-
-        for (;;) {
-            if (this.#resident_bytes + headroom <= budget) {
-                return dropped;
-            }
-
-            const candidates = this.#candidates();
-
-            if (candidates.length === 0) {
-                return dropped;
-            }
-
-            candidates.sort((a, b) => a.touched - b.touched);
-
-            let this_pass = 0;
-
-            for (const candidate of candidates) {
-                if (this.#resident_bytes + headroom <= budget) {
-                    break;
-                }
-
-                if (!this.evictable(candidate.entry.reader, candidate.page_index)) {
-                    continue;
-                }
-
-                this.#drop(candidate.entry, candidate.page_index);
-
-                dropped++;
-                this_pass++;
-            }
-
-            if (this_pass === 0) {
-                return dropped;
-            }
-        }
-    }
-
-    /**
-     * Every page that could be dropped right now, with its touch stamp.
-     *
-     * @returns {{entry: VGeoResidencyEntry, page_index: number, touched: number}[]}
-     */
-    #candidates() {
-        const out = [];
-
-        for (const entry of this.#readers.values()) {
-            const reader = entry.reader;
-
-            for (const page of reader.resident_pages()) {
-                if (!this.evictable(reader, page.index)) {
-                    continue;
-                }
-
-                out.push({
-                    entry,
-                    page_index: page.index,
-                    // a page nothing has reported is as cold as it gets, and is the right first
-                    // victim: it arrived, and no cut has selected from it since
-                    touched: entry.touched.get(page.index) ?? -1,
-                });
-            }
-        }
-
-        return out;
-    }
-
-    /**
-     * @param {VGeoResidencyEntry} entry
-     * @param {number} page_index
-     */
-    #drop(entry, page_index) {
-        if (!entry.reader.evict(page_index)) {
-            return;
-        }
-
-        entry.touched.delete(page_index);
-
-        this.#reconcile(entry);
-
-        this.#evicted_page_count++;
-    }
-
-    /**
-     * Pull the total back onto what one reader now says it holds.
-     *
-     * @param {VGeoResidencyEntry} entry
-     */
-    #reconcile(entry) {
-        const now = entry.reader.resident_bytes;
-
-        this.#resident_bytes += now - entry.bytes;
-
-        entry.bytes = now;
-    }
-
-    /**
-     * Install a reader's wants, under the shared fetch cap and the shared byte budget.
-     *
-     * This is the runtime's entry point, and what it does that `VGeoContainerReader.install_wants`
-     * cannot: every fetch queues on one scheduler shared with every other reader, so priority is
-     * compared across assets and the in-flight total is bounded; and every page is admitted against
-     * the budget *before* it is fetched, out of the `decoded_size` its parent's child table already
-     * carries — so a page that will not fit is never paid for.
-     *
-     * A want that cannot be admitted is dropped, not queued. It is not a failure: the cut that
-     * produced it is correct without the page, and the next traversal will want it again — by which
-     * time something may have gone cold enough to evict. {@link refused_want_count} counts them.
-     *
-     * A want with no `decoded_size` is admitted blind and the budget is enforced after the fact, at
-     * the end of this call. Wants that came from a cut always carry it.
-     *
-     * @param {VGeoContainerReader} reader must be registered
-     * @param {VGeoPageWant[]} wants
-     * @param {number} [limit] most pages to install this call
-     * @param {AbortSignal} [signal] stops admitting, and abandons what this reader has in flight
-     * @returns {Promise<VGeoPage[]>} the pages installed, in completion order
-     */
-    async install_wants(reader, wants, limit = wants.length, signal = undefined) {
-        const entry = this.#readers.get(reader);
-
-        assert.defined(entry, 'the reader must be registered before its wants can be installed');
-
-        // Ranked before it is cut, so a limit takes the most visibly coarse pages rather than an
-        // arbitrary prefix — and deduplicated on page index, because two clusters wanting one page
-        // is one fetch (§10) and two admissions would double-charge the budget for it.
-        const queue = [];
-        const seen = new Set();
-
-        for (const want of wants.slice().sort((a, b) => b.priority - a.priority)) {
-            if (seen.has(want.page_index)) {
-                continue;
-            }
-
-            seen.add(want.page_index);
-
-            queue.push(want);
-
-            if (queue.length >= limit) {
-                break;
-            }
-        }
-
-        const installed = [];
-
-        /**
-         * Pages this call has on the wire, so that aborting it abandons those and not whatever
-         * another view of another asset started through the same reader.
-         * @type {Set<number>}
-         */
-        const mine = new Set();
-
-        const abandon = () => {
-            for (const page_index of mine) {
-                reader.cancel(page_index);
-            }
-        };
-
-        signal?.addEventListener('abort', abandon, { once: true });
-
-        try {
-            await Promise.all(queue.map((want) => this.#scheduler.submit(
-                want.priority, () => this.#install_one(entry, want, signal, installed, mine)
-            )));
-        } finally {
-            signal?.removeEventListener('abort', abandon);
-        }
-
-        // The backstop for wants that carried no `decoded_size`, and for anything that installed
-        // outside this call while it was running.
-        this.evict_to_budget();
-
-        return installed;
-    }
-
-    /**
-     * @param {VGeoResidencyEntry} entry
-     * @param {VGeoPageWant} want
-     * @param {AbortSignal|undefined} signal
-     * @param {VGeoPage[]} installed
-     * @param {Set<number>} in_flight the calling batch's own, for a scoped abort
-     * @returns {Promise<void>}
-     */
-    async #install_one(entry, want, signal, installed, in_flight) {
-        if (signal !== undefined && signal.aborted) {
-            return;
-        }
-
-        const reader = entry.reader;
-
-        const resident = reader.page(want.page_index);
-
-        if (resident !== undefined) {
-            // §10: a want whose target page is already installed resolves as an activation recheck,
-            // never a fetch — and the reader has already done that recheck. What is left is the
-            // touch, which is what keeps the page from being the next thing evicted.
-            entry.touched.set(want.page_index, this.#frame);
-
-            return;
-        }
-
-        if (reader.is_quarantined(want.page_index)) {
-            return;
-        }
-
-        if (!this.#admit(want.decoded_size)) {
-            this.#refused_want_count++;
-
-            return;
-        }
-
-        in_flight.add(want.page_index);
-
-        try {
-            const page = await reader.install_want(want);
-
-            entry.touched.set(page.index, this.#frame);
-
-            this.#reconcile(entry);
-
-            installed.push(page);
-        } catch {
-            // quarantined, or cancelled. Either way the cut stands without it, and the reason is on
-            // the reader's quarantine for whoever is watching telemetry.
-            this.#reconcile(entry);
-        } finally {
-            in_flight.delete(want.page_index);
-        }
-    }
-
-    /**
-     * Whether the budget can take `bytes` more, after evicting what it can.
-     *
-     * @param {number} bytes
-     * @returns {boolean}
-     */
-    #admit(bytes) {
-        const budget = this.#options.budget_bytes;
-
-        if (this.#resident_bytes + bytes <= budget) {
-            return true;
-        }
-
-        this.evict_to_budget(bytes);
-
-        return this.#resident_bytes + bytes <= budget;
-    }
-
-    /**
-     * Let every quarantined page of every registered reader be asked for again.
-     *
-     * The policy half of §10's quarantine, and the reason it is here rather than on the reader: a
-     * reader that failed three fetches of one page cannot tell an unreachable CDN from a corrupt
-     * frame, and a manager that has watched other pages of other assets arrive since can. A caller
-     * that has just come back online, or that is retrying a whole scene, calls this; nothing calls it
-     * on a timer, because a checksum that failed once will fail again and the retry costs a fetch.
-     *
-     * @returns {number} how many pages were released, across every reader
-     */
-    clear_quarantines() {
-        let released = 0;
-
-        for (const entry of this.#readers.values()) {
-            released += entry.reader.clear_quarantine();
-        }
-
-        return released;
-    }
-
-    /**
-     * How many pages are quarantined across every registered reader.
-     * @returns {number}
-     */
-    get quarantined_page_count() {
-        let count = 0;
-
-        for (const entry of this.#readers.values()) {
-            count += entry.reader.quarantined_page_count;
-        }
-
-        return count;
-    }
-}