@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,674 @@
+import { assert } from "../../../../../core/assert.js";
+import { graph_read_buffer } from "../../../buffer/graph_read_buffer.js";
+import { VGeoPageWant } from "../format/read/VGeoPageWant.js";
+import { VGEO_CUT_STAT_COUNT } from "./layout/VGEO_CUT_STAT_COUNT.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";
+
+/**
+ * The other half of the loop: what the cut saw, coming back to the host.
+ *
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §6 sets the contract and the virtual-texture system is the shipped
+ * precedent for it — a small in-flight cap, multi-frame `mapAsync` latency, and **frames where
+ * feedback is skipped entirely** when saturated. A loop that insisted on a reading every frame
+ * would stall the frame it was reading, which is the failure the cap exists to prevent.
+ *
+ * What comes back is two lists and a counter block:
+ *
+ * - **touches** — page rows the cut drew from. They go to the VRAM pool's LRU and to
+ *   `VGeoResidencyManager`'s, which is design §6's touch-LRU at both tiers. Not last-*wanted*:
+ *   stamping at fetch time freezes the stamp of exactly what is on screen and evicts it.
+ * - **wants** — pages a clamped cluster could not reach, each naming the page it was discovered
+ *   *through*. That second half is what resolves the byte range without a directory, and it is
+ *   also the page format §10 asks to be pinned while its child is in flight.
+ *
+ * A want resolves to one of two very different things, and telling them apart is this class's real
+ * work. A page already in RAM is a **VRAM install** and no fetch at all — the bytes are here and
+ * the cut simply has not been given them. A page not in RAM is a fetch, handed to the residency
+ * manager with its priority so that it competes globally against every other asset's wants rather
+ * than within whichever reader asked first.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoFeedbackLoop {
+    /**
+     * @type {GPUVirtualGeometryRuntime}
+     */
+    #runtime;
+
+    /**
+     * @type {VGeoResidencyManager}
+     */
+    #residency;
+
+    /**
+     * @type {number}
+     */
+    #in_flight = 0;
+
+    /**
+     * @type {number}
+     */
+    #max_in_flight;
+
+    /**
+     * @type {number}
+     */
+    #install_budget_bytes;
+
+    /**
+     * @type {number}
+     */
+    #skipped_frames = 0;
+
+    /**
+     * @type {number}
+     */
+    #read_count = 0;
+
+    /**
+     * The counters of the last frame that came back — what M1's "selection cost measured" reads.
+     * @type {Uint32Array}
+     */
+    #stats = new Uint32Array(VGEO_CUT_STAT_COUNT);
+
+    /**
+     * @type {number}
+     */
+    #last_want_count = 0;
+
+    /**
+     * @type {number}
+     */
+    #last_touch_count = 0;
+
+    /**
+     * Page indices this loop has asked for and not yet heard back about, per reader.
+     *
+     * A page stays wanted for as long as it is missing, so the same want arrives every frame until
+     * the fetch lands. Without this the shared `ConcurrencyGate` accumulates one closure per frame
+     * per wanted page and the RAM budget is charged once per frame for the same bytes.
+     *
+     * @type {Map<VGeoContainerReader, Set<number>>}
+     */
+    #in_flight_pages = new Map();
+
+    /**
+     * One per batch of fetches still running, so {@link abort} can stop all of them.
+     * @type {Set<AbortController>}
+     */
+    #controllers = new Set();
+
+    /**
+     * @type {number}
+     */
+    #max_wants_per_frame;
+
+    /**
+     * @type {number}
+     */
+    #deduped_wants = 0;
+
+    /**
+     * @type {number}
+     */
+    #dropped_wants = 0;
+
+    /**
+     * @type {number}
+     */
+    #failed_batches = 0;
+
+    /**
+     * Touches and wants naming a page row that was re-used between the cut and this reading.
+     * @type {number}
+     */
+    #stale_records = 0;
+
+    /**
+     * @param {Object} options
+     * @param {GPUVirtualGeometryRuntime} options.runtime
+     * @param {VGeoResidencyManager} options.residency the RAM tier's budget owner
+     * @param {number} [options.max_in_flight] readbacks that may be outstanding at once
+     * @param {number} [options.install_budget_bytes] decoded page bytes promoted to VRAM per frame
+     * @param {number} [options.max_wants_per_frame] pages one frame may newly ask to fetch, across
+     *     every reader — see {@link #dispatch_frame}, which is where the "across every reader" is
+     *     enforced; the rest are dropped and asked for again next frame, which is what a want is
+     *     for
+     */
+    constructor({
+                    runtime,
+                    residency,
+                    max_in_flight = 2,
+                    install_budget_bytes = 8 * 1024 * 1024,
+                    max_wants_per_frame = 32,
+                }) {
+        assert.defined(runtime, 'runtime');
+        assert.defined(residency, 'residency');
+
+        this.#runtime = runtime;
+        this.#residency = residency;
+        this.#max_in_flight = max_in_flight;
+        this.#install_budget_bytes = install_budget_bytes;
+        this.#max_wants_per_frame = max_wants_per_frame;
+    }
+
+    /**
+     * Feedback records naming a page row that had been re-used by the time the reading landed.
+     * @returns {number}
+     */
+    get stale_record_count() {
+        return this.#stale_records;
+    }
+
+    /**
+     * Wants this loop did not re-submit because the page was already being fetched.
+     * @returns {number}
+     */
+    get deduped_want_count() {
+        return this.#deduped_wants;
+    }
+
+    /**
+     * Wants past this frame's fetch limit. Not a failure — the next cut asks again.
+     * @returns {number}
+     */
+    get dropped_want_count() {
+        return this.#dropped_wants;
+    }
+
+    /**
+     * Batches every page of which the reader quarantined, plus any that rejected outright.
+     *
+     * A reader that has stopped answering is the one streaming failure a host can do something
+     * about, and it is the one thing a per-page quarantine cannot say on its own.
+     *
+     * @returns {number}
+     */
+    get failed_batch_count() {
+        return this.#failed_batches;
+    }
+
+    /**
+     * @returns {Uint32Array}
+     */
+    get stats() {
+        return this.#stats;
+    }
+
+    /**
+     * Frames whose feedback was dropped because the loop was saturated.
+     *
+     * Not an error and not a leak: the clamped cut keeps a coarse stand-in correct indefinitely, so
+     * a skipped frame costs latency in the streaming and nothing in what is on screen.
+     *
+     * @returns {number}
+     */
+    get skipped_frames() {
+        return this.#skipped_frames;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get read_count() {
+        return this.#read_count;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get last_want_count() {
+        return this.#last_want_count;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get last_touch_count() {
+        return this.#last_touch_count;
+    }
+
+    /**
+     * Schedule this frame's readback, while the graph is still being built.
+     *
+     * @param {FrameGraph} graph
+     * @returns {boolean} whether a reading was scheduled
+     */
+    read(graph) {
+        assert.defined(graph, 'graph');
+
+        /*
+         The RAM tier's clock, moved here rather than left to the host. `advance_frame` is what
+         carries the protect window forward, and without it `evict_to_budget` protects everything
+         and never drops a page — so the RAM tier is unbounded. Its only non-spec caller was the
+         playground (REVIEW_LEDGER M12), which is to say that in any real host the second tier of a
+         three-tier design was doing nothing at all.
+
+         Before the early returns below on purpose: a frame whose feedback is skipped is still a
+         frame, and a clock that only advanced on the frames the readback kept up with would make
+         the protect window a function of readback latency.
+         */
+        this.#residency.advance_frame();
+        this.#residency.evict_to_budget();
+
+        const feedback = this.#runtime.feedback;
+
+        if (feedback === -1) {
+            return false;
+        }
+
+        if (this.#in_flight >= this.#max_in_flight) {
+            this.#skipped_frames++;
+
+            return false;
+        }
+
+        /*
+         Closed over, not looked up again when the reading lands. `begin_frame` recomputes the
+         layout every frame out of the page-row high-water mark and the lookup word count, both of
+         which move as pages install — so a readback that lands a frame or two later and asked the
+         runtime for "the" layout would decode this frame's bytes with a later frame's bases, and
+         read wants and touches out of the middle of the stamp region (REVIEW_LEDGER C5).
+         */
+        const layout = this.#runtime.feedback_layout;
+
+        /*
+         And the generation of every page row that exists right now. A row is reused the moment it
+         is freed and this reading is at least a frame behind the cut that produced it, so a touch
+         or a want naming row 7 may be naming the page that *was* in row 7. Comparing the generation
+         is what tells the two apart (REVIEW_LEDGER M10).
+         */
+        const generations = this.#snapshot_generations();
+
+        this.#in_flight++;
+
+        graph_read_buffer({ graph, buffer: feedback, offset: 0, size: layout.word_count * 4 })
+            .then(reference => {
+                try {
+                    this.#apply(new Uint32Array(reference.getValue()), layout, generations);
+                } finally {
+                    reference.release();
+                }
+            })
+            .catch(error => {
+                // a timed-out or failed mapping costs a frame of feedback, not a frame of rendering
+                console.warn('vgeo: feedback readback failed', error);
+            })
+            .finally(() => {
+                this.#in_flight--;
+            });
+
+        this.#read_count++;
+
+        return true;
+    }
+
+    /**
+     * @returns {Uint32Array} one generation per page row that could appear in this frame's feedback
+     */
+    #snapshot_generations() {
+        const tables = this.#runtime.pool.tables;
+
+        const count = this.#runtime.pool.page_row_capacity;
+
+        const generations = new Uint32Array(count);
+
+        for (let row = 0; row < count; row++) {
+            generations[row] = tables.generation_of(row);
+        }
+
+        return generations;
+    }
+
+    /**
+     * Whether a page row still holds the page it held when the cut ran.
+     *
+     * @param {number} page_row
+     * @param {Uint32Array} generations
+     * @returns {boolean}
+     */
+    #still_the_same_page(page_row, generations) {
+        if (page_row >= generations.length) {
+            // a row that did not exist when the graph was built cannot be one this cut named
+            return false;
+        }
+
+        return this.#runtime.pool.tables.generation_of(page_row) === generations[page_row];
+    }
+
+    /**
+     * @param {Uint32Array} words
+     * @param {ReturnType<vgeo_cut_feedback_layout>} layout the frame's own, not the current one
+     * @param {Uint32Array} generations per page row, as of the frame this reading is about
+     */
+    #apply(words, layout, generations) {
+        const pool = this.#runtime.pool;
+
+        for (let i = 0; i < VGEO_CUT_STAT_COUNT; i++) {
+            this.#stats[i] = words[VGEO_FEEDBACK_OFFSET.STATS + i];
+        }
+
+        /*
+         Clamped, because the count is an `atomicAdd` that ran past the capacity the kernel then
+         refused to write at. Reading it unclamped would read the words after the list, which are
+         whatever the pool's transient buffer held before this frame.
+         */
+        const touch_count = Math.min(
+            words[VGEO_FEEDBACK_OFFSET.TOUCH_COUNT], layout.word_count - layout.touch_base
+        );
+
+        this.#last_touch_count = touch_count;
+        this.#last_want_count = Math.min(
+            words[VGEO_FEEDBACK_OFFSET.WANT_COUNT],
+            Math.floor((layout.touch_base - layout.want_base) / VGEO_WANT_WORDS)
+        );
+
+        for (let i = 0; i < touch_count; i++) {
+            const page_row = words[layout.touch_base + i];
+
+            const entry = pool.entry_of(page_row);
+
+            if (entry === undefined) {
+                // evicted between the cut and the reading; the stamp it would have taken is moot
+                continue;
+            }
+
+            if (!this.#still_the_same_page(page_row, generations)) {
+                /*
+                 Evicted *and refilled* in between. Stamping now would tell both tiers' LRU that a
+                 page nobody has drawn is the hottest thing in the cache, and it would do it at
+                 exactly the moment a page was streaming in.
+                 */
+                this.#stale_records++;
+
+                continue;
+            }
+
+            pool.touch(page_row);
+
+            this.#residency.touch(
+                entry.reader, pool.tables.page_field(page_row, VGEO_PAGE_ROW_OFFSET.PAGE_INDEX)
+            );
+        }
+
+        /**
+         * Wants that need bytes, per reader — the residency manager takes them a reader at a time
+         * because a reader is what owns a fetch, and orders them globally because a priority in
+         * pixels of error is comparable across assets by construction.
+         * @type {Map<VGeoContainerReader, VGeoPageWant[]>}
+         */
+        const fetches = new Map();
+
+        let promoted = 0;
+
+        for (let i = 0; i < this.#last_want_count; i++) {
+            const base = layout.want_base + i * VGEO_WANT_WORDS;
+
+            const source_row = words[base];
+            const child_ref = words[base + 1];
+            const child_page_index = words[base + 2];
+            const priority = new Float32Array(new Uint32Array([words[base + 3]]).buffer)[0];
+
+            const entry = pool.entry_of(source_row);
+
+            if (entry === undefined) {
+                continue;
+            }
+
+            if (!this.#still_the_same_page(source_row, generations)) {
+                /*
+                 The row was reused between the cut and this reading, so the page index below and
+                 the byte range the child table would give come from two different pages — a fetch
+                 aimed at a page nobody asked for, charged to the RAM budget, at the priority of a
+                 cluster in an unrelated part of the asset.
+                 */
+                this.#stale_records++;
+
+                continue;
+            }
+
+            const reader = entry.reader;
+
+            const source_index = pool.tables.page_field(source_row, VGEO_PAGE_ROW_OFFSET.PAGE_INDEX);
+
+            const source = reader.page(source_index);
+
+            if (source === undefined || child_ref >= source.child_page_index.length) {
+                continue;
+            }
+
+            if (reader.is_resident(child_page_index)) {
+                /*
+                 The bytes are already in RAM, so this is not a fetch at all — the cut is clamping
+                 because the page has not been promoted to VRAM yet. Budgeted per frame, because a
+                 camera that suddenly wants a hundred pages should get them over several frames
+                 rather than in one hitch.
+                 */
+                if (promoted < this.#install_budget_bytes) {
+                    if (pool.install(reader, child_page_index) !== -1) {
+                        promoted += source.child_decoded_size[child_ref];
+                    }
+                }
+
+                continue;
+            }
+
+            const want = new VGeoPageWant();
+
+            want.page_index = child_page_index;
+            want.frame_offset = source.child_frame_offset[child_ref];
+            want.fetch_size = source.child_fetch_size[child_ref];
+            want.decoded_size = source.child_decoded_size[child_ref];
+            want.priority = priority;
+            want.reference_count = 1;
+
+            const list = fetches.get(reader) ?? [];
+
+            list.push(want);
+
+            fetches.set(reader, list);
+        }
+
+        this.#dispatch_frame(fetches);
+    }
+
+    /**
+     * One frame's fetches: deduped against what is in flight, ranked across every reader, and cut
+     * to the frame's limit.
+     *
+     * **Across every reader, which is what the option has always said and not what it did.**
+     * `max_wants_per_frame` was applied inside {@link #dispatch_wants}, once per reader, so a frame
+     * seeing eight streaming assets issued eight times the limit — the shape
+     * `VGeoResidencyManager`'s own doc records being measured at 48 concurrent range requests
+     * against a cap of 6, and the reason its gate is shared. One frame, one budget.
+     *
+     * Ranked across readers for the same reason the gate is shared: a want's priority is pixels of
+     * projected error past the threshold, which is comparable across assets by construction. So the
+     * frame's budget goes to the worst coarseness on screen wherever it came from, rather than to
+     * whichever reader this frame's touch list happened to name first.
+     *
+     * @param {Map<VGeoContainerReader, VGeoPageWant[]>} fetches
+     */
+    #dispatch_frame(fetches) {
+        /**
+         * @type {{reader: VGeoContainerReader, want: VGeoPageWant}[]}
+         */
+        const fresh = [];
+
+        for (const [reader, wants] of fetches) {
+            const in_flight = this.#in_flight_of(reader);
+
+            for (const want of wants) {
+                if (in_flight.has(want.page_index)) {
+                    this.#deduped_wants++;
+
+                    continue;
+                }
+
+                fresh.push({ reader, want });
+            }
+        }
+
+        if (fresh.length === 0) {
+            return;
+        }
+
+        fresh.sort((a, b) => b.want.priority - a.want.priority);
+
+        const batch = fresh.slice(0, this.#max_wants_per_frame);
+
+        this.#dropped_wants += fresh.length - batch.length;
+
+        /**
+         * Back into per-reader lists, because a reader is what owns a fetch.
+         * @type {Map<VGeoContainerReader, VGeoPageWant[]>}
+         */
+        const by_reader = new Map();
+
+        for (const { reader, want } of batch) {
+            const list = by_reader.get(reader) ?? [];
+
+            list.push(want);
+
+            by_reader.set(reader, list);
+        }
+
+        for (const [reader, wants] of by_reader) {
+            this.#dispatch_wants(reader, wants);
+        }
+    }
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @returns {Set<number>} page indices this loop has asked that reader for and not heard back
+     */
+    #in_flight_of(reader) {
+        let in_flight = this.#in_flight_pages.get(reader);
+
+        if (in_flight === undefined) {
+            in_flight = new Set();
+
+            this.#in_flight_pages.set(reader, in_flight);
+        }
+
+        return in_flight;
+    }
+
+    /**
+     * Hand one reader's share of this frame's batch to the residency manager.
+     *
+     * This was `install_wants(...).catch(() => {})` and nothing else, which costs three things that
+     * compound rather than three separate ones. A page still wanted while its fetch is in flight is
+     * re-submitted **every frame**, so the shared `ConcurrencyGate` accumulates one stale closure
+     * per frame per wanted page and the RAM budget is charged for the same page over and over. A
+     * batch that is still running when the next arrives has no way to be told to stop. And an empty
+     * catch turns a reader that has quarantined every page it was asked for into silence
+     * (REVIEW_LEDGER M11).
+     *
+     * So: a page already in flight is not asked for again, the whole batch carries one
+     * `AbortSignal` that {@link abort} can pull, and a failure is counted and reported once rather
+     * than swallowed once per frame. The dedup and the frame's limit are {@link #dispatch_frame}'s,
+     * one level up, because both are properties of the frame rather than of a reader.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {VGeoPageWant[]} batch already deduped and inside this frame's limit
+     */
+    #dispatch_wants(reader, batch) {
+        const in_flight = this.#in_flight_of(reader);
+
+        for (const want of batch) {
+            in_flight.add(want.page_index);
+        }
+
+        const controller = new AbortController();
+
+        this.#controllers.add(controller);
+
+        this.#residency.install_wants(reader, batch, batch.length, controller.signal)
+            .then(() => {
+                if (controller.signal.aborted) {
+                    return;
+                }
+
+                /*
+                 A failed fetch does not come back as a rejection. `VGeoResidencyManager` catches it
+                 per page — the cut stands without any one page, which is the whole point of a
+                 clamped cut — so a `.catch` here sees only a programming error, and the campaign
+                 closed M11 with the reporting on exactly that branch. A reader that has quarantined
+                 every page asked of it was therefore still silent (re-review 2026-09-12).
+
+                 The reader's quarantine is where the fact lives, so that is what is read. Every
+                 page of the batch quarantined is an asset that cannot be streamed at all, which is
+                 the condition worth one line in the console; a page or two is ordinary attrition
+                 and is on `VGeoResidencyManager.quarantined_page_count` for whoever is watching.
+                 */
+                let quarantined = 0;
+
+                for (const want of batch) {
+                    if (reader.is_quarantined(want.page_index)) {
+                        quarantined++;
+                    }
+                }
+
+                if (quarantined < batch.length) {
+                    return;
+                }
+
+                this.#failed_batches++;
+
+                // once per batch, not once per frame per page: the dedup one level up is what makes
+                // that difference, and a reader that has quarantined everything asked of it is a
+                // fact somebody has to be able to see
+                console.warn(
+                    `vgeo: every one of ${batch.length} page fetches was quarantined`
+                    + ` by ${reader.name ?? 'a reader'}`
+                );
+            })
+            .catch(error => {
+                if (controller.signal.aborted) {
+                    return;
+                }
+
+                this.#failed_batches++;
+
+                console.warn('vgeo: a batch of page fetches failed', error);
+            })
+            .finally(() => {
+                this.#controllers.delete(controller);
+
+                for (const want of batch) {
+                    in_flight.delete(want.page_index);
+                }
+            });
+    }
+
+    /**
+     * Stop every fetch this loop started.
+     *
+     * @returns {void}
+     */
+    abort() {
+        for (const controller of Array.from(this.#controllers)) {
+            controller.abort();
+        }
+
+        this.#controllers.clear();
+        this.#in_flight_pages.clear();
+    }
+
+    /**
+     * Give up on this loop: the same as {@link abort}, under the name a host tears things down by.
+     *
+     * The loop owns no device resource, so there is nothing else to release — what it owns is
+     * outstanding *work*, and the reason to have this verb at all is that `abort` reads like a
+     * transient control ("stop what is in flight, carry on") while a teardown is final.
+     *
+     * @returns {void}
+     */
+    destroy() {
+        this.abort();
+    }
+}