@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -1,10 +1,15 @@
 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 } from "./layout/VGEO_CUT_STAT.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";
+
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
+ * @typedef {import("./VGeoResidency.js").VGeoResidency} VGeoResidency
+ * @typedef {import("./cut/vgeo_cut_feedback_layout.js").vgeo_cut_feedback_layout} vgeo_cut_feedback_layout
+ */
 
 /**
  * The other half of the loop: what the cut saw, coming back to the host.
@@ -14,20 +19,11 @@ import { VGEO_WANT_WORDS } from "./layout/VGEO_WANT_WORDS.js";
  * 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.
+ * This class is the transport and nothing else: it schedules the readback while the graph is still
+ * being built, closes the frame's own layout and frame number over it, keeps the counters the
+ * kernel wrote, and hands the words to {@link VGeoResidency.apply}. What a touch or a want means —
+ * which tier it lands on, what it costs, what is fetched and what is refused — is the residency's,
+ * in one place for both tiers (RUNTIME_PLAN_2026_09_14 §4.7).
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -39,7 +35,7 @@ export class VGeoFeedbackLoop {
     #runtime;
 
     /**
-     * @type {VGeoResidencyManager}
+     * @type {VGeoResidency}
      */
     #residency;
 
@@ -53,11 +49,6 @@ export class VGeoFeedbackLoop {
      */
     #max_in_flight;
 
-    /**
-     * @type {number}
-     */
-    #install_budget_bytes;
-
     /**
      * @type {number}
      */
@@ -74,121 +65,27 @@ export class VGeoFeedbackLoop {
      */
     #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
+     * @param {VGeoResidency} options.residency both tiers' owner
+     * @param {number} [options.max_in_flight] readbacks that may be outstanding at once; defaults
+     *     to the residency's option
      */
-    constructor({
-                    runtime,
-                    residency,
-                    max_in_flight = 2,
-                    install_budget_bytes = 8 * 1024 * 1024,
-                    max_wants_per_frame = 32,
-                }) {
+    constructor({ runtime, residency, max_in_flight = undefined }) {
         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;
+        this.#max_in_flight = max_in_flight ?? residency.options.max_readbacks_in_flight;
     }
 
     /**
-     * Feedback records naming a page row that had been re-used by the time the reading landed.
-     * @returns {number}
+     * @returns {VGeoResidency}
      */
-    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;
+    get residency() {
+        return this.#residency;
     }
 
     /**
@@ -221,14 +118,22 @@ export class VGeoFeedbackLoop {
      * @returns {number}
      */
     get last_want_count() {
-        return this.#last_want_count;
+        return this.#residency.last_want_count;
     }
 
     /**
      * @returns {number}
      */
     get last_touch_count() {
-        return this.#last_touch_count;
+        return this.#residency.last_touch_count;
+    }
+
+    /**
+     * Records naming a page row that was refilled between the cut and the reading.
+     * @returns {number}
+     */
+    get stale_record_count() {
+        return this.#residency.stale_record_count;
     }
 
     /**
@@ -240,20 +145,6 @@ export class VGeoFeedbackLoop {
     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) {
@@ -268,27 +159,27 @@ export class VGeoFeedbackLoop {
 
         /*
          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).
+         layout every frame out of the page-row high-water mark, which moves 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 (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).
+         And the frame this reading is about. 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 (REVIEW_LEDGER M10). The pool stamps every
+         row with the frame whose flush publishes its occupant, and the residency compares that per
+         record against this number.
          */
-        const generations = this.#snapshot_generations();
+        const reading_frame = this.#runtime.pool.frame;
 
         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);
+                    this.#apply(new Uint32Array(reference.getValue()), layout, reading_frame);
                 } finally {
                     reference.release();
                 }
@@ -306,365 +197,42 @@ export class VGeoFeedbackLoop {
         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
+     * @param {number} reading_frame the frame this reading is about
      */
-    #apply(words, layout, generations) {
-        const pool = this.#runtime.pool;
-
+    #apply(words, layout, reading_frame) {
         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);
+         One counter is not a statistic, it is an instruction. `QUEUE_REMAINING` is non-zero exactly
+         when the descent ran out of wavefronts and abandoned subtrees it had not expanded — a hole
+         in the picture rather than a coarser surface — and this is the only moment anything on the
+         host learns it. The runtime owns what to do about it; the loop's job here is the same as
+         with a want, which is to carry the reading to whoever it is about.
+        */
+        this.#runtime.note_incomplete_descent(this.#stats[VGEO_CUT_STAT.QUEUE_REMAINING]);
 
-            by_reader.set(reader, list);
-        }
-
-        for (const [reader, wants] of by_reader) {
-            this.#dispatch_wants(reader, wants);
-        }
+        this.#residency.apply(words, layout, reading_frame);
     }
 
     /**
-     * @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.
+     * Stop every fetch the residency has on the wire.
      *
      * @returns {void}
      */
     abort() {
-        for (const controller of Array.from(this.#controllers)) {
-            controller.abort();
-        }
-
-        this.#controllers.clear();
-        this.#in_flight_pages.clear();
+        this.#residency.abort();
     }
 
     /**
      * 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.
+     * outstanding *work*.
      *
      * @returns {void}
      */