@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -1,258 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}