@woosh/meep-engine 3.25.0 → 3.27.0

package/src/shade/renderer/geometry/virtual/runtime/VGeoResidency.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 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 {
+    /**
+     * @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, gate, fetcher }: {
+        pool: GPUVirtualGeometryPool;
+        options?: VGeoResidencyOptions;
+        gate?: ConcurrencyGate;
+        fetcher?: VGeoPageFetcher;
+    });
+    /**
+     * @returns {VGeoResidencyOptions}
+     */
+    get options(): VGeoResidencyOptions;
+    /**
+     * @returns {ConcurrencyGate}
+     */
+    get gate(): ConcurrencyGate;
+    /**
+     * @returns {VGeoPageFetcher}
+     */
+    get fetcher(): VGeoPageFetcher;
+    /**
+     * @returns {GPUVirtualGeometryPool}
+     */
+    get pool(): import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number;
+    get ram_budget_bytes(): number;
+    get ram_resident_bytes(): number;
+    get ram_page_count(): number;
+    get reader_count(): number;
+    get evicted_vram_count(): number;
+    get evicted_ram_count(): number;
+    /**
+     * 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(): number;
+    /**
+     * Fetches the RAM tier had no room for.
+     * @returns {number}
+     */
+    get refused_fetch_count(): number;
+    /**
+     * Wants past a reading's promotion or fetch budget. Not a failure: the next cut asks again.
+     * @returns {number}
+     */
+    get deferred_want_count(): number;
+    /**
+     * Wants for a page already in flight, or already in VRAM by the time the reading landed.
+     * @returns {number}
+     */
+    get deduped_want_count(): number;
+    /**
+     * Records naming a page row that was refilled between the cut and the reading.
+     * @returns {number}
+     */
+    get stale_record_count(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number;
+    /**
+     * Readings in which every fetch dispatched for one container was quarantined.
+     * @returns {number}
+     */
+    get failed_batch_count(): number;
+    get fetches_in_flight(): number;
+    get last_touch_count(): number;
+    get last_want_count(): number;
+    /**
+     * @returns {number}
+     */
+    get quarantined_page_count(): number;
+    /**
+     * 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: VGeoContainerReader): number;
+    /**
+     * 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: VGeoContainerReader): boolean;
+    /**
+     * @param {VGeoContainerReader} reader
+     * @returns {boolean}
+     */
+    is_registered(reader: VGeoContainerReader): boolean;
+    /**
+     * 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: VGeoContainerReader, page_index: number): 'absent' | 'fetching' | 'quarantined' | 'ram' | 'vram' | 'unregistered';
+    /**
+     * Stop every fetch every registered container has on the wire.
+     *
+     * @returns {void}
+     */
+    abort(): void;
+    /**
+     * Give up on everything: every fetch, every container.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
+    /**
+     * Let every quarantined page be asked for again.
+     *
+     * @returns {number} pages released
+     */
+    clear_quarantines(): number;
+    /**
+     * 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: Uint32Array, layout: {
+        touch_bits_base: number;
+        touch_word_count: number;
+        want_base: number;
+        word_count: number;
+    }, reading_frame: number): void;
+    /**
+     * 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: number): boolean;
+    /**
+     * 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: number): boolean;
+    #private;
+}
+export type VGeoContainerReader = import("../format/read/VGeoContainerReader.js").VGeoContainerReader;
+export type VGeoPage = import("../format/read/VGeoPage.js").VGeoPage;
+export type GPUVirtualGeometryPool = import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool;
+import { VGeoResidencyOptions } from "./VGeoResidencyOptions.js";
+import { ConcurrencyGate } from "../../../../../core/process/ConcurrencyGate.js";
+import { VGeoPageFetcher } from "./VGeoPageFetcher.js";
+//# sourceMappingURL=VGeoResidency.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/VGeoResidency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoResidency.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoResidency.js"],"names":[],"mappings":"AA+FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAwJI;;;;;;;OAOG;IACH;QAN2C,IAAI,EAApC,sBAAsB;QACS,OAAO,GAAtC,oBAAoB;QACM,IAAI,GAA9B,eAAe;QACW,OAAO,GAAjC,eAAe;OA8BzB;IAID;;OAEG;IACH,oCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,oBAEC;IAED;;;;OAIG;IACH,gCAGC;IAED,+BAEC;IAED,iCAEC;IAED,6BAEC;IAED,2BAEC;IAED,iCAEC;IAED,gCAEC;IAED;;;;OAIG;IACH,oCAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;OAGG;IACH,iCAEC;IAED,gCAEC;IAED,+BAEC;IAED,8BAEC;IAED;;OAEG;IACH,qCAQC;IAID;;;;;;;;;;OAUG;IACH,iBAHW,mBAAmB,GACjB,MAAM,CA8ClB;IAED;;;;;;OAMG;IACH,mBAHW,mBAAmB,GACjB,OAAO,CAgBnB;IAED;;;OAGG;IACH,sBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;;OAMG;IACH,cAJW,mBAAmB,cACnB,MAAM,GACJ,QAAQ,GAAC,UAAU,GAAC,aAAa,GAAC,KAAK,GAAC,MAAM,GAAC,cAAc,CAqBzE;IAgCD;;;;OAIG;IACH,SAFa,IAAI,CAOhB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAUhB;IAED;;;;OAIG;IACH,qBAFa,MAAM,CAkBlB;IAID;;;;;;;;;OASG;IACH,aANW,WAAW,UACX;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAChF,UAAgB,EAAE,MAAM,CAAA;KAAC,iBACf,MAAM,GACJ,IAAI,CA6HhB;IA2FD;;;;;;OAMG;IACH,yBAHW,MAAM,GACJ,OAAO,CAgBnB;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,GACJ,OAAO,CAoCnB;;CAiXJ;kCA5zCY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ;qCAC7C,OAAO,6BAA6B,EAAE,sBAAsB;qCALpC,2BAA2B;gCALhC,gDAAgD;gCAIhD,sBAAsB"}