@woosh/meep-engine 3.21.0 → 3.23.0

package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.d.ts

@@ -0,0 +1,258 @@
+/**
+ * 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 {
+    /**
+     * @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?: VGeoResidencyOptions, scheduler?: ConcurrencyGate);
+    /**
+     * @returns {VGeoResidencyOptions}
+     */
+    get options(): VGeoResidencyOptions;
+    /**
+     * @returns {ConcurrencyGate}
+     */
+    get scheduler(): ConcurrencyGate;
+    /**
+     * @returns {number}
+     */
+    get reader_count(): number;
+    /**
+     * @returns {number}
+     */
+    get frame(): number;
+    /**
+     * Decoded page bytes held by every registered reader together — the number the budget is spent
+     * against.
+     * @returns {number}
+     */
+    get resident_bytes(): number;
+    /**
+     * @returns {number}
+     */
+    get budget_bytes(): number;
+    /**
+     * @returns {number}
+     */
+    get resident_page_count(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number;
+    /**
+     * Take a reader under the budget.
+     *
+     * @param {VGeoContainerReader} reader
+     * @returns {VGeoContainerReader} the same reader, so this can wrap an `open`
+     */
+    register(reader: VGeoContainerReader): VGeoContainerReader;
+    /**
+     * 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: VGeoContainerReader): boolean;
+    /**
+     * @param {VGeoContainerReader} reader
+     * @returns {boolean}
+     */
+    is_registered(reader: VGeoContainerReader): boolean;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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: VGeoContainerReader, page_index: number): void;
+    /**
+     * Record every page of a cut as touched.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {Iterable<number>} page_indices
+     */
+    touch_all(reader: VGeoContainerReader, page_indices: Iterable<number>): void;
+    /**
+     * 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: VGeoContainerReader, page_index: number): number;
+    /**
+     * 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: VGeoContainerReader, page_index: number): boolean;
+    /**
+     * 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?: number): number;
+    /**
+     * 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
+     */
+    install_wants(reader: VGeoContainerReader, wants: VGeoPageWant[], limit?: number, signal?: AbortSignal): Promise<VGeoPage[]>;
+    /**
+     * 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(): number;
+    /**
+     * How many pages are quarantined across every registered reader.
+     * @returns {number}
+     */
+    get quarantined_page_count(): number;
+    #private;
+}
+import { VGeoResidencyOptions } from "./VGeoResidencyOptions.js";
+import { ConcurrencyGate } from "../../../../../core/process/ConcurrencyGate.js";
+//# sourceMappingURL=VGeoResidencyManager.d.ts.map

package/src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoResidencyManager.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/residency/VGeoResidencyManager.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH;IAsCI;;;;OAIG;IACH,sBAJW,oBAAoB,cACpB,eAAe,EAMzB;IAED;;OAEG;IACH,oCAEC;IAED;;OAEG;IACH,iCAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;;OAIG;IACH,6BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,kCAQC;IAED;;;;;OAKG;IACH,iCAEC;IAED;;;;;;;;OAQG;IACH,iCAEC;IAED;;;;;OAKG;IACH,2DAmBC;IAED;;;;;;;;OAQG;IACH,yCAFa,OAAO,CAcnB;IAED;;;OAGG;IACH,4CAFa,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,iBAFa,MAAM,CAQlB;IAED;;;;;OAKG;IACH,UAFa,MAAM,CAsBlB;IAED;;;;;;OAMG;IACH,+CAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,qDAFW,SAAS,MAAM,CAAC,QAY1B;IAED;;;;;;OAMG;IACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,mDAHW,MAAM,GACJ,OAAO,CA4BnB;IAED;;;;;;;;;;OAUG;IACH,2BAHW,MAAM,GACJ,MAAM,CAyClB;IA4DD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,kDALW,cAAc,UACd,MAAM,WACN,WAAW,GACT,QAAQ,UAAU,CAAC,CAyD/B;IA2ED;;;;;;;;;;OAUG;IACH,qBAFa,MAAM,CAUlB;IAED;;;OAGG;IACH,qCAQC;;CACJ;qCAhtBoC,2BAA2B;gCADhC,gDAAgD"}