@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -1,3 +1,9 @@
+/**
+ * @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.
  *
@@ -6,20 +12,11 @@
  * 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
@@ -28,45 +25,19 @@ export class VGeoFeedbackLoop {
     /**
      * @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, install_budget_bytes, max_wants_per_frame, }: {
+    constructor({ runtime, residency, max_in_flight }: {
         runtime: GPUVirtualGeometryRuntime;
-        residency: VGeoResidencyManager;
+        residency: VGeoResidency;
         max_in_flight?: number;
-        install_budget_bytes?: number;
-        max_wants_per_frame?: number;
     });
     /**
-     * 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(): number;
-    /**
-     * Wants this loop did not re-submit because the page was already being fetched.
-     * @returns {number}
-     */
-    get deduped_want_count(): number;
-    /**
-     * Wants past this frame's fetch limit. Not a failure — the next cut asks again.
-     * @returns {number}
-     */
-    get dropped_want_count(): number;
-    /**
-     * 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(): number;
+    get residency(): import("./VGeoResidency.js").VGeoResidency;
     /**
      * @returns {Uint32Array}
      */
@@ -92,6 +63,11 @@ export class VGeoFeedbackLoop {
      * @returns {number}
      */
     get last_touch_count(): number;
+    /**
+     * Records naming a page row that was refilled between the cut and the reading.
+     * @returns {number}
+     */
+    get stale_record_count(): number;
     /**
      * Schedule this frame's readback, while the graph is still being built.
      *
@@ -100,7 +76,7 @@ export class VGeoFeedbackLoop {
      */
     read(graph: FrameGraph): boolean;
     /**
-     * Stop every fetch this loop started.
+     * Stop every fetch the residency has on the wire.
      *
      * @returns {void}
      */
@@ -109,12 +85,15 @@ export class VGeoFeedbackLoop {
      * 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}
      */
     destroy(): void;
     #private;
 }
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUVirtualGeometryRuntime = import("./GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime;
+export type VGeoResidency = import("./VGeoResidency.js").VGeoResidency;
+export type vgeo_cut_feedback_layout = typeof import("./cut/vgeo_cut_feedback_layout.js").vgeo_cut_feedback_layout;
 //# sourceMappingURL=VGeoFeedbackLoop.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoFeedbackLoop.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA+FI;;;;;;;;;;OAUG;IACH;QAT8C,OAAO;QACZ,SAAS;QACtB,aAAa,GAA9B,MAAM;QACW,oBAAoB,GAArC,MAAM;QACW,mBAAmB,GAApC,MAAM;OAoBhB;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,yBAFa,OAAO,CAqEnB;IAqVD;;;;OAIG;IACH,SAFa,IAAI,CAShB;IAED;;;;;;;;OAQG;IACH,WAFa,IAAI,CAIhB;;CACJ"}
+{"version":3,"file":"VGeoFeedbackLoop.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAqCI;;;;;;OAMG;IACH;QAL8C,OAAO,EAA1C,yBAAyB;QACF,SAAS,EAAhC,aAAa;QACI,aAAa,GAA9B,MAAM;OAUhB;IAED;;OAEG;IACH,4DAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,8BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;;;OAKG;IACH,YAHW,UAAU,GACR,OAAO,CAuDnB;IAeD;;;;OAIG;IACH,SAFa,IAAI,CAIhB;IAED;;;;;;;OAOG;IACH,WAFa,IAAI,CAIhB;;CACJ;yBAjOY,OAAO,iEAAiE,EAAE,UAAU;wCACpF,OAAO,gCAAgC,EAAE,yBAAyB;4BAClE,OAAO,oBAAoB,EAAE,aAAa"}