@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool} GPUVirtualGeometryPool
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
 /**
  * What one frame of virtual geometry needs that is not a page: the threshold, the feedback buffer
  * every view writes into, and the parameters every pass reads.
@@ -19,27 +23,25 @@ export class GPUVirtualGeometryRuntime {
     /**
      * @param {Object} options
      * @param {GPUVirtualGeometryPool} options.pool
-     * @param {GPUDevice} options.device
      * @param {number} [options.want_capacity] pages one frame may ask for, across every view
-     * @param {number} [options.touch_capacity] page rows one frame may report drawing from
      * @param {number} [options.visible_instance_hint] VG instances one expansion site is expected
      *     to see; what {@link claim_word_capacity} is sized from, and nothing else
      * @param {number} [options.claim_word_capacity] words of the per-invocation claim bitmask,
      *     overriding the derivation below
      * @param {number} [options.queue_capacity] traversal items one wavefront may hold
      * @param {number} [options.max_iterations] wavefronts before the descent is abandoned
-     * @param {number} [options.cluster_chunk] clusters one group-chunk item covers
+     * @param {number} [options.descent_steps] steps of the descent one traversal dispatch runs
+     *     before handing back what it still holds; see the traversal kernel for why it cannot
+     *     simply stop when the wave runs dry
      */
-    constructor({ pool, device, want_capacity, touch_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, cluster_chunk, }: {
+    constructor({ pool, want_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, descent_steps, }: {
         pool: GPUVirtualGeometryPool;
-        device: GPUDevice;
         want_capacity?: number;
-        touch_capacity?: number;
         visible_instance_hint?: number;
         claim_word_capacity?: number;
         queue_capacity?: number;
         max_iterations?: number;
-        cluster_chunk?: number;
+        descent_steps?: number;
     });
     /**
      * Pixels of permitted error — the single quality/perf lever, and a runtime dial by design §4.
@@ -53,11 +55,13 @@ export class GPUVirtualGeometryRuntime {
     /**
      * @returns {GPUVirtualGeometryPool}
      */
-    get pool(): GPUVirtualGeometryPool;
+    get pool(): import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool;
     /**
-     * @returns {GPUBuffer}
+     * Pages one frame may ask for, across every view.
+     *
+     * @returns {number}
      */
-    get params_buffer(): GPUBuffer;
+    get want_capacity(): number;
     /**
      * @returns {number}
      */
@@ -70,6 +74,20 @@ export class GPUVirtualGeometryRuntime {
      * @returns {number}
      */
     get max_iterations(): number;
+    /**
+     * Settable, like tau, and for the same reason: it is a quality-of-schedule dial whose right
+     * value is a property of the asset's depth and the scene's breadth together rather than of the
+     * engine. `begin_frame` re-writes the params every frame, so a change lands on the next one.
+     *
+     * @param {number} value
+     */
+    set descent_steps(value: number);
+    /**
+     * Steps of the descent one traversal dispatch runs.
+     *
+     * @returns {number}
+     */
+    get descent_steps(): number;
     /**
      * This frame's feedback resource. Every expansion site writes into it and one readback reads it.
      * @returns {number}
@@ -95,31 +113,42 @@ export class GPUVirtualGeometryRuntime {
      * @returns {ReturnType<vgeo_cut_feedback_layout>}
      */
     get feedback_layout(): {
-        touch_stamp_base: number;
-        want_stamp_base: number;
+        touch_bits_base: number;
+        /**
+         * @type {number}
+         */
+        touch_word_count: number;
         want_base: number;
-        touch_base: number;
-        word_count: number;
+        word_count: number; /**
+         * @type {number}
+         */
     };
     /**
      * Open a frame: publish the page tables, size the feedback buffer against what is resident, and
      * write the parameters every pass of every view will read.
      *
-     * The sizing happens here rather than at construction because two of its terms move with
-     * residency — one touch stamp per page-table row, one want stamp per lookup word — and a frame
-     * is the coarsest granularity at which they hold still.
+     * The sizing happens here rather than at construction because one of its terms moves with
+     * residency — one touch bit per page-table row — and a frame is the coarsest granularity at
+     * which it holds still.
      *
-     * @param {FrameGraph} graph
-     * @param {Object} view
-     * @param {number} view.screen_height pixels of the render target
-     * @param {number} view.fov_y radians
-     * @param {number} [view.meshlet_capacity] records the shared meshlet collection holds
+     * **The pool's frame advances here, before the flush**, and not at `end_frame`. The frame
+     * number is what stamps a page row's `visible_from` — the frame whose flush publishes the
+     * row's occupant — and what a reading compares it against. With the advance here, an install
+     * landing anywhere after this frame's flush is stamped for the next one and rejected by this
+     * frame's reading, exactly (RUNTIME_PLAN_2026_09_14 §2.4). It is also the clock both tiers'
+     * protect windows read, and it moves whether or not a readback is scheduled this frame.
+     *
+     * **A frame has no projection.** It used to take one, and wrote it into a params buffer
+     * every view then shared — so a shadow cascade cut against whichever view opened the
+     * frame. `projection_k` is a property of a render target and a camera, which is to say of
+     * a view, and it lives on {@link VGeoViewCut} with the rest of what a view owns alone.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
      * @returns {number} the feedback resource
      */
-    begin_frame(graph: FrameGraph, { screen_height, fov_y }: {
-        screen_height: number;
-        fov_y: number;
-        meshlet_capacity?: number;
+    begin_frame({ graph }: {
+        graph: FrameGraph;
     }): number;
     /**
      * What one expansion site was handed, folded into the parameters every pass of the frame reads.
@@ -162,7 +191,7 @@ export class GPUVirtualGeometryRuntime {
      *
      * @returns {FrameGraph|undefined}
      */
-    get frame_graph(): any;
+    get frame_graph(): import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     /**
      * Close a frame. The feedback resource stops being valid; reading it is
      * {@link VGeoFeedbackLoop}'s, which schedules the readback while the graph is still being built.
@@ -170,7 +199,8 @@ export class GPUVirtualGeometryRuntime {
      * @returns {void}
      */
     end_frame(): void;
-    destroy(): void;
     #private;
 }
+export type GPUVirtualGeometryPool = import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
 //# sourceMappingURL=GPUVirtualGeometryRuntime.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH;IAwFI;;;;;;;;;;;;;OAaG;IACH;QAZ2C,IAAI;QACjB,MAAM;QACR,aAAa,GAA9B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,aAAa,GAA9B,MAAM;OAqDhB;IA3GD;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IAoGpB;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;;;;;MAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QALwB,aAAa,EAA1B,MAAM;QACO,KAAK,EAAlB,MAAM;QACQ,gBAAgB,GAA9B,MAAM;QACJ,MAAM,CAqClB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAehB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,uBAEC;IAyBD;;;;;OAKG;IACH,aAFa,IAAI,CAOhB;IAED,gBAEC;;CACJ"}
+{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAwEI;;;;;;;;;;;;;OAaG;IACH;QAZ2C,IAAI,EAApC,sBAAsB;QACL,aAAa,GAA9B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,aAAa,GAA9B,MAAM;OA+DhB;IA/GD;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IAwGpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,6BAEC;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;QAvOA;;WAEG;;;4BAIH;;WAEG;MAiOF;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH;QAH+B,KAAK,EAAzB,UAAU;QACR,MAAM,CA+BlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAahB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,wGAEC;IAGD;;;;;OAKG;IACH,aAFa,IAAI,CAKhB;;CACJ;qCAtYY,OAAO,6BAA6B,EAAE,sBAAsB;yBAC5D,OAAO,iEAAiE,EAAE,UAAU"}

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

@@ -1,11 +1,13 @@
 import { assert } from "../../../../../core/assert.js";
 import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
 import { noop } from "../../../../../core/function/noop.js";
-import { write_gpu_typed_buffer } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
-import { VGEO_CUT_FLAG_CULL } from "./cut/VGEO_CUT_FLAG_CULL.js";
-import { VGEO_CUT_PARAMS_STRUCT } from "./cut/VGEO_CUT_PARAMS_STRUCT.js";
 import { vgeo_cut_feedback_layout } from "./cut/vgeo_cut_feedback_layout.js";
 
+/**
+ * @typedef {import("./GPUVirtualGeometryPool.js").GPUVirtualGeometryPool} GPUVirtualGeometryPool
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
 /**
  * What one frame of virtual geometry needs that is not a page: the threshold, the feedback buffer
  * every view writes into, and the parameters every pass reads.
@@ -29,25 +31,13 @@ export class GPUVirtualGeometryRuntime {
      */
     #pool;
 
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
 
-    /**
-     * @type {GPUBuffer}
-     */
-    #params;
 
     /**
      * @type {number}
      */
     #want_capacity;
 
-    /**
-     * @type {number}
-     */
-    #touch_capacity;
 
     /**
      * @type {number}
@@ -67,7 +57,7 @@ export class GPUVirtualGeometryRuntime {
     /**
      * @type {number}
      */
-    #cluster_chunk;
+    #descent_steps;
 
     /**
      * Pixels of permitted error — the single quality/perf lever, and a runtime dial by design §4.
@@ -96,10 +86,6 @@ export class GPUVirtualGeometryRuntime {
      */
     #graph;
 
-    /**
-     * @type {number}
-     */
-    #projection_k = 1;
 
     /**
      * @type {number}
@@ -114,22 +100,20 @@ export class GPUVirtualGeometryRuntime {
     /**
      * @param {Object} options
      * @param {GPUVirtualGeometryPool} options.pool
-     * @param {GPUDevice} options.device
      * @param {number} [options.want_capacity] pages one frame may ask for, across every view
-     * @param {number} [options.touch_capacity] page rows one frame may report drawing from
      * @param {number} [options.visible_instance_hint] VG instances one expansion site is expected
      *     to see; what {@link claim_word_capacity} is sized from, and nothing else
      * @param {number} [options.claim_word_capacity] words of the per-invocation claim bitmask,
      *     overriding the derivation below
      * @param {number} [options.queue_capacity] traversal items one wavefront may hold
      * @param {number} [options.max_iterations] wavefronts before the descent is abandoned
-     * @param {number} [options.cluster_chunk] clusters one group-chunk item covers
+     * @param {number} [options.descent_steps] steps of the descent one traversal dispatch runs
+     *     before handing back what it still holds; see the traversal kernel for why it cannot
+     *     simply stop when the wave runs dry
      */
     constructor({
                     pool,
-                    device,
                     want_capacity = 2048,
-                    touch_capacity = 8192,
                     visible_instance_hint = 1024,
                     /*
                      One bit per (instance, page ordinal), and the two terms are the *pool's* page
@@ -156,26 +140,36 @@ export class GPUVirtualGeometryRuntime {
                      with work outstanding, which is the one degradation that costs a hole.
                      */
                     queue_capacity = 1 << 16,
-                    max_iterations = 64,
-                    cluster_chunk = 8,
+                    max_iterations = 8,
+                    /*
+                     Steps of the in-kernel descent one dispatch runs, and the knob that is *not*
+                     the safety bound — `max_iterations` is, and lowering this spends it. A wave
+                     keeps one child per lane and spills the rest, so a dispatch advances what it
+                     held by `descent_steps` levels and hands the rest to the next one: the
+                     dispatches a cut needs are `ceil(depth / descent_steps)` plus its spill
+                     generations, not `depth / descent_steps`. Running out of dispatches is
+                     `VGEO_CUT_STAT.QUEUE_REMAINING`, and that is a hole rather than coarseness.
+
+                     Measured over a full orbit of the deepest converted Zorah container — 27.9M
+                     faces, 17,172 pages, 39 levels — at tau 1, the dispatches it needs are 6 at 32
+                     and at 24, 7 at 20, all 8 at 16 and at 12, and more than 8 below that. So 24 is
+                     the most this can be lowered for nothing: the same six dispatches 32 needs,
+                     with a quarter fewer idle steps inside each. `DRAWN` is bit-identical at every
+                     value that drains, which is what makes this a schedule knob and not a quality
+                     one.
+                    */
+                    descent_steps = 24,
                 }) {
         assert.defined(pool, 'pool');
-        assert.defined(device, 'device');
 
         this.#pool = pool;
-        this.#device = device;
         this.#want_capacity = want_capacity;
-        this.#touch_capacity = touch_capacity;
         this.#claim_word_capacity = claim_word_capacity;
         this.#queue_capacity = queue_capacity;
         this.#max_iterations = max_iterations;
-        this.#cluster_chunk = cluster_chunk;
+        this.#descent_steps = descent_steps;
+
 
-        this.#params = device.createBuffer({
-            label: 'GPUVirtualGeometryRuntime/params',
-            size: VGEO_CUT_PARAMS_STRUCT.aligned_size,
-            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-        });
     }
 
     /**
@@ -186,10 +180,12 @@ export class GPUVirtualGeometryRuntime {
     }
 
     /**
-     * @returns {GPUBuffer}
+     * Pages one frame may ask for, across every view.
+     *
+     * @returns {number}
      */
-    get params_buffer() {
-        return this.#params;
+    get want_capacity() {
+        return this.#want_capacity;
     }
 
     /**
@@ -213,6 +209,29 @@ export class GPUVirtualGeometryRuntime {
         return this.#max_iterations;
     }
 
+    /**
+     * Steps of the descent one traversal dispatch runs.
+     *
+     * @returns {number}
+     */
+    get descent_steps() {
+        return this.#descent_steps;
+    }
+
+    /**
+     * Settable, like tau, and for the same reason: it is a quality-of-schedule dial whose right
+     * value is a property of the asset's depth and the scene's breadth together rather than of the
+     * engine. `begin_frame` re-writes the params every frame, so a change lands on the next one.
+     *
+     * @param {number} value
+     */
+    set descent_steps(value) {
+        assert.isNonNegativeInteger(value, 'descent_steps');
+        assert.greaterThan(value, 0, 'descent_steps');
+
+        this.#descent_steps = value;
+    }
+
     /**
      * This frame's feedback resource. Every expansion site writes into it and one readback reads it.
      * @returns {number}
@@ -253,28 +272,35 @@ export class GPUVirtualGeometryRuntime {
      * Open a frame: publish the page tables, size the feedback buffer against what is resident, and
      * write the parameters every pass of every view will read.
      *
-     * The sizing happens here rather than at construction because two of its terms move with
-     * residency — one touch stamp per page-table row, one want stamp per lookup word — and a frame
-     * is the coarsest granularity at which they hold still.
+     * The sizing happens here rather than at construction because one of its terms moves with
+     * residency — one touch bit per page-table row — and a frame is the coarsest granularity at
+     * which it holds still.
+     *
+     * **The pool's frame advances here, before the flush**, and not at `end_frame`. The frame
+     * number is what stamps a page row's `visible_from` — the frame whose flush publishes the
+     * row's occupant — and what a reading compares it against. With the advance here, an install
+     * landing anywhere after this frame's flush is stamped for the next one and rejected by this
+     * frame's reading, exactly (RUNTIME_PLAN_2026_09_14 §2.4). It is also the clock both tiers'
+     * protect windows read, and it moves whether or not a readback is scheduled this frame.
+     *
+     * **A frame has no projection.** It used to take one, and wrote it into a params buffer
+     * every view then shared — so a shadow cascade cut against whichever view opened the
+     * frame. `projection_k` is a property of a render target and a camera, which is to say of
+     * a view, and it lives on {@link VGeoViewCut} with the rest of what a view owns alone.
      *
-     * @param {FrameGraph} graph
-     * @param {Object} view
-     * @param {number} view.screen_height pixels of the render target
-     * @param {number} view.fov_y radians
-     * @param {number} [view.meshlet_capacity] records the shared meshlet collection holds
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
      * @returns {number} the feedback resource
      */
-    begin_frame(graph, { screen_height, fov_y }) {
+    begin_frame({ graph }) {
         assert.defined(graph, 'graph');
-        assert.greaterThan(screen_height, 0, 'screen_height');
 
+        this.#pool.advance_frame();
         this.#pool.flush();
 
         this.#layout = vgeo_cut_feedback_layout({
             page_row_capacity: this.#pool.page_row_capacity,
-            lookup_word_count: this.#pool.lookup_word_count,
             want_capacity: this.#want_capacity,
-            touch_capacity: this.#touch_capacity,
         });
 
         const spawn = graph.add('vgeo/frame', {}, noop);
@@ -294,10 +320,6 @@ export class GPUVirtualGeometryRuntime {
         this.#instance_capacity = 0;
         this.#meshlet_capacity = 0;
 
-        this.#projection_k = screen_height / (2 * Math.tan(fov_y * 0.5));
-
-        this.#write_params();
-
         return this.#feedback;
     }
 
@@ -330,8 +352,6 @@ export class GPUVirtualGeometryRuntime {
         this.#meshlet_capacity = this.#meshlet_capacity === 0
             ? meshlet_capacity
             : Math.min(this.#meshlet_capacity, meshlet_capacity);
-
-        this.#write_params();
     }
 
     /**
@@ -363,28 +383,6 @@ export class GPUVirtualGeometryRuntime {
         return this.#graph;
     }
 
-    /**
-     * @returns {void}
-     */
-    #write_params() {
-        write_gpu_typed_buffer_to_device(this.#device, this.#params, {
-            tau: this.tau,
-            projection_k: this.#projection_k,
-            queue_capacity: this.#queue_capacity,
-            claim_word_count: this.#claim_word_capacity,
-            cluster_chunk: this.#cluster_chunk,
-            page_slot_words: this.#pool.page_slot_words,
-            touch_stamp_base: this.#layout.touch_stamp_base,
-            want_stamp_base: this.#layout.want_stamp_base,
-            want_base: this.#layout.want_base,
-            want_capacity: this.#want_capacity,
-            touch_base: this.#layout.touch_base,
-            touch_capacity: this.#touch_capacity,
-            instance_capacity: this.#instance_capacity,
-            meshlet_capacity: this.#meshlet_capacity,
-            flags: this.cull_enabled ? VGEO_CUT_FLAG_CULL : 0,
-        });
-    }
 
     /**
      * Close a frame. The feedback resource stops being valid; reading it is
@@ -395,31 +393,5 @@ export class GPUVirtualGeometryRuntime {
     end_frame() {
         this.#feedback = -1;
         this.#graph = undefined;
-
-        this.#pool.advance_frame();
     }
-
-    destroy() {
-        this.#params.destroy();
-    }
-}
-
-/**
- * `write_gpu_typed_buffer` writes into an `ArrayBuffer`; a uniform wants bytes on a device. One
- * scratch buffer rather than one per frame, because the params block is forty-odd bytes written
- * once a frame and allocating for it would be the expensive half.
- *
- * @type {ArrayBuffer}
- */
-const PARAMS_SCRATCH = new ArrayBuffer(VGEO_CUT_PARAMS_STRUCT.aligned_size);
-
-/**
- * @param {GPUDevice} device
- * @param {GPUBuffer} buffer
- * @param {Object} value
- */
-function write_gpu_typed_buffer_to_device(device, buffer, value) {
-    write_gpu_typed_buffer(value, VGEO_CUT_PARAMS_STRUCT, PARAMS_SCRATCH, 0);
-
-    device.queue.writeBuffer(buffer, 0, PARAMS_SCRATCH, 0, VGEO_CUT_PARAMS_STRUCT.aligned_size);
 }

package/src/shade/renderer/geometry/virtual/runtime/REVIEW_LEDGER.md

@@ -239,3 +239,40 @@ Two things this pass could not prove below the drive, written down rather than c
   implemented as a per-reader one.** `VGeoResidencyManager`'s own doc records the first being
   measured at 48 concurrent range requests against a cap of six, and that is why its gate is shared.
   Worth a grep the next time a limit is added: the reader-shaped one is the easy one to write.
+
+## 2026-09-14 — the remainder counter never worked
+
+`QUEUE_REMAINING` read zero at every iteration budget, including the ones where the descent drew
+nothing at all. M8 added the counter and a spec for it, and both were right about a frame with one
+cut in it; the engine has never recorded a frame with one cut in it.
+
+Measured on `zorah-2026-13-09/bdf6f9615ae672d54bfb70cde904f5c2.vgeo` (28M faces, 17,172 pages)
+through the playground on a 4090, sweeping `max_iterations` at tau = 1:
+
+| `max_iterations` | pages | drawn | remaining, before | after |
+| --- | --- | --- | --- | --- |
+| 40 | 1593 | 10177 | 0 | 0 |
+| 39 | 1593 | 10177 | 0 | 0 |
+| 38 | 1593 | 10170 | 0 | 7 |
+| 32 | 1315 | 2115 | 0 | 4556 |
+| 20 | 25 | 0 | 0 | 75 |
+
+Two causes, and they cancelled into a plausible number:
+
+- **The prepare pass wrote it, and the prepare pass runs between wavefronts.** What it could report
+  is the frontier of an iteration, not a remainder, and the next iteration overwrote it. Only a pass
+  after the last wavefront is looking at the right thing.
+- **It was a plain store, and a frame has more than one cut.** The two-way HZB filter gives every
+  view two expansion sites and a scene routinely has all of its virtual geometry in one of them, so
+  the *empty* bucket ran last and stored its own zero over the other's truncation. Every other stat
+  in `VGEO_CUT_STAT` is an add across the frame's cuts; this one was not.
+
+`shader_vgeo_cut_queue_remainder` is the tail now — three bindings, one workgroup, an `atomicAdd` —
+and the prepare pass no longer binds the feedback buffer at all. The spec that missed it ran one
+cut against one feedback buffer, which is the only arrangement in which a last-writer-wins race has
+no second writer; the new one runs a truncated cut and an empty cut against the buffer
+`begin_frame` would have given them both.
+
+**What this unblocks.** `max_iterations` defaults to 64 and the descent on this asset converges at
+39, so 89 of the 128 traverse dispatches a frame records are empty — and until now nothing could
+say whether a smaller budget was safe. It can now: 39 is exact and 40 is free.