@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -29,18 +29,21 @@ export class GPUVirtualGeometryRuntime {
      * @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.max_iterations] wavefronts before the descent is abandoned, to start
+     *     with; the runtime raises it from what the cut reports
+     * @param {number} [options.max_iteration_ceiling] as far as that raising may go
      * @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, want_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, descent_steps, }: {
+    constructor({ pool, want_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, max_iteration_ceiling, descent_steps, }: {
         pool: GPUVirtualGeometryPool;
         want_capacity?: number;
         visible_instance_hint?: number;
         claim_word_capacity?: number;
         queue_capacity?: number;
         max_iterations?: number;
+        max_iteration_ceiling?: number;
         descent_steps?: number;
     });
     /**
@@ -71,9 +74,56 @@ export class GPUVirtualGeometryRuntime {
      */
     get claim_word_capacity(): number;
     /**
+     * Wavefronts the descent may run, as the runtime currently understands this scene.
+     *
+     * A **high-water mark**, not a setting: it starts where the host put it and is raised by
+     * {@link note_incomplete_descent} from what the cut reports. `graph_vgeo_expand_instances_to_meshlets`
+     * reads it while it is recording passes, so a rise lands on the next frame.
+     *
      * @returns {number}
      */
     get max_iterations(): number;
+    /**
+     * Times the bound has been raised. Zero for the whole life of almost every scene; a small
+     * number, once, for one that needed more than it was given.
+     *
+     * @returns {number}
+     */
+    get iteration_escalations(): number;
+    /**
+     * @returns {number}
+     */
+    get iteration_ceiling(): number;
+    /**
+     * A reading saying the descent stopped with work still queued — raise the bound and keep it
+     * raised.
+     *
+     * **This is the only place the engine can learn it.** How many wavefronts a cut needs is a
+     * function of the frontier's *breadth*, which is a function of the scene, the viewpoint and the
+     * render target together; the kernel cannot know it before it runs and the host cannot know it
+     * at all. So the bound is guessed low, and the one reading that says the guess was wrong —
+     * `VGEO_CUT_STAT.QUEUE_REMAINING`, non-zero exactly when items were abandoned — pays for
+     * correcting it. It is the same shape as the rasterizer's meshlet counts, which cannot be known
+     * before the expansion runs either and are grown from what the frame reported.
+     *
+     * **Doubling, because the reading does not say how much more was needed.** A remainder is a
+     * count of *items*, and what they cost in wavefronts depends on how they spill; there is no
+     * ratio to convert one into the other. So it goes up by a factor until it drains, which is at
+     * most three steps from 8 to the ceiling.
+     *
+     * **Never lowered.** A frame that drained is evidence about that frame, not that the scene got
+     * smaller — and a bound that fell back would re-learn the same lesson every time the camera
+     * turned away and back, at a hole a time. An unused wavefront is an empty indirect dispatch,
+     * which is the cheap side of that trade.
+     *
+     * What it costs when it is wrong is bounded by the readback: the cut is capped at two readings
+     * in flight and skips frames when saturated, so the scene draws with a hole for the few frames
+     * between the first truncated descent and the reading that reports it — and then never again.
+     *
+     * @param {number} remaining items the descent still held when it was abandoned
+     * @returns {boolean} whether the bound moved
+     */
+    note_incomplete_descent(remaining: number): boolean;
     /**
      * 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

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":"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"}
+{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAKA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IAkFI;;;;;;;;;;;;;;;OAeG;IACH;QAd2C,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;QAEW,qBAAqB,GAAtC,MAAM;QACW,aAAa,GAA9B,MAAM;OAkFhB;IApID;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IA6HpB;;OAEG;IACH,yEAEC;IAED;;;;OAIG;IACH,4BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;OAQG;IACH,6BAEC;IAED;;;;;OAKG;IACH,oCAEC;IAED;;OAEG;IACH,gCAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,mCAHW,MAAM,GACJ,OAAO,CAanB;IAWD;;;;;;OAMG;IACH,iCAKC;IArBD;;;;OAIG;IACH,4BAEC;IAgBD;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;QAvUA;;WAEG;;;4BAIH;;WAEG;MAiUF;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;qCAteY,OAAO,6BAA6B,EAAE,sBAAsB;yBAC5D,OAAO,iEAAiE,EAAE,UAAU"}

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

@@ -54,6 +54,16 @@ export class GPUVirtualGeometryRuntime {
      */
     #max_iterations;
 
+    /**
+     * @type {number}
+     */
+    #iteration_ceiling;
+
+    /**
+     * @type {number}
+     */
+    #iteration_escalations = 0;
+
     /**
      * @type {number}
      */
@@ -106,7 +116,9 @@ export class GPUVirtualGeometryRuntime {
      * @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.max_iterations] wavefronts before the descent is abandoned, to start
+     *     with; the runtime raises it from what the cut reports
+     * @param {number} [options.max_iteration_ceiling] as far as that raising may go
      * @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
@@ -140,7 +152,25 @@ export class GPUVirtualGeometryRuntime {
                      with work outstanding, which is the one degradation that costs a hole.
                      */
                     queue_capacity = 1 << 16,
+                    /*
+                     Where the wavefront bound *starts*. It is raised by the runtime itself when a
+                     reading says the descent could not finish — see {@link note_incomplete_descent}
+                     — so this is the cost a scene pays until it has been told otherwise rather than
+                     a limit anyone has to get right in advance.
+
+                     Eight is what almost every cut needs: one container at a modest viewport drains
+                     in six. A converted scene at 3441×1440 does not, and nothing on the host can
+                     know that before the kernel has run.
+                    */
                     max_iterations = 8,
+                    /*
+                     And where it stops. A frontier that genuinely cannot be drained inside any
+                     budget would otherwise climb until the frame graph is nothing but empty
+                     dispatches; a hole is the better failure, because it is visible and
+                     `QUEUE_REMAINING` goes on reporting it. Measured peak need on the scene that
+                     found this was 12 to 13.
+                    */
+                    max_iteration_ceiling = 64,
                     /*
                      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
@@ -167,6 +197,7 @@ export class GPUVirtualGeometryRuntime {
         this.#claim_word_capacity = claim_word_capacity;
         this.#queue_capacity = queue_capacity;
         this.#max_iterations = max_iterations;
+        this.#iteration_ceiling = Math.max(max_iterations, max_iteration_ceiling);
         this.#descent_steps = descent_steps;
 
 
@@ -203,12 +234,77 @@ export class GPUVirtualGeometryRuntime {
     }
 
     /**
+     * Wavefronts the descent may run, as the runtime currently understands this scene.
+     *
+     * A **high-water mark**, not a setting: it starts where the host put it and is raised by
+     * {@link note_incomplete_descent} from what the cut reports. `graph_vgeo_expand_instances_to_meshlets`
+     * reads it while it is recording passes, so a rise lands on the next frame.
+     *
      * @returns {number}
      */
     get max_iterations() {
         return this.#max_iterations;
     }
 
+    /**
+     * Times the bound has been raised. Zero for the whole life of almost every scene; a small
+     * number, once, for one that needed more than it was given.
+     *
+     * @returns {number}
+     */
+    get iteration_escalations() {
+        return this.#iteration_escalations;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get iteration_ceiling() {
+        return this.#iteration_ceiling;
+    }
+
+    /**
+     * A reading saying the descent stopped with work still queued — raise the bound and keep it
+     * raised.
+     *
+     * **This is the only place the engine can learn it.** How many wavefronts a cut needs is a
+     * function of the frontier's *breadth*, which is a function of the scene, the viewpoint and the
+     * render target together; the kernel cannot know it before it runs and the host cannot know it
+     * at all. So the bound is guessed low, and the one reading that says the guess was wrong —
+     * `VGEO_CUT_STAT.QUEUE_REMAINING`, non-zero exactly when items were abandoned — pays for
+     * correcting it. It is the same shape as the rasterizer's meshlet counts, which cannot be known
+     * before the expansion runs either and are grown from what the frame reported.
+     *
+     * **Doubling, because the reading does not say how much more was needed.** A remainder is a
+     * count of *items*, and what they cost in wavefronts depends on how they spill; there is no
+     * ratio to convert one into the other. So it goes up by a factor until it drains, which is at
+     * most three steps from 8 to the ceiling.
+     *
+     * **Never lowered.** A frame that drained is evidence about that frame, not that the scene got
+     * smaller — and a bound that fell back would re-learn the same lesson every time the camera
+     * turned away and back, at a hole a time. An unused wavefront is an empty indirect dispatch,
+     * which is the cheap side of that trade.
+     *
+     * What it costs when it is wrong is bounded by the readback: the cut is capped at two readings
+     * in flight and skips frames when saturated, so the scene draws with a hole for the few frames
+     * between the first truncated descent and the reading that reports it — and then never again.
+     *
+     * @param {number} remaining items the descent still held when it was abandoned
+     * @returns {boolean} whether the bound moved
+     */
+    note_incomplete_descent(remaining) {
+        assert.isNonNegativeInteger(remaining, 'remaining');
+
+        if (remaining === 0 || this.#max_iterations >= this.#iteration_ceiling) {
+            return false;
+        }
+
+        this.#max_iterations = Math.min(this.#max_iterations * 2, this.#iteration_ceiling);
+        this.#iteration_escalations++;
+
+        return true;
+    }
+
     /**
      * Steps of the descent one traversal dispatch runs.
      *

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

@@ -39,7 +39,7 @@ held to `vgeo_select_cut` exactly, and `playground/vgeo_runtime/` runs it on a d
 
 Everything below the runtime was already built when this was written. The builder produces a DAG,
 the container holds it, the reader streams it a page at a time with residency and activation,
-`VGeoResidencyManager` owns the RAM budget, and `playground/vgeo_viewer/select_cut.js` selects a
+`VGeoResidencyManager` owns the RAM budget, and `runtime/cut/__fixtures__/vgeo_select_cut.js` selects a
 correct cut on the CPU against a partially resident container. What had never run was any of it on
 the GPU, and the one piece of M0 that is engine-facing — the expansion seam — had never been built
 at all.
@@ -76,7 +76,7 @@ no cluster the flat rule would draw is missed.
 | `GPUMeshletManager` | data + metadata pools, `add_batch`/`remove_batch` | the VRAM tier's storage; format §8 makes a page payload a **copy** into the data pool |
 | `MESHLET_DEFINITION_STRUCT` | `(meshlet index, mesh index)` | the cut's output record type — unchanged, which is what makes the seam one call |
 | `graph_expand_meshes_to_meshlets` | four call sites, three of them opaque | the seam: a VG expansion runs beside each opaque one and appends into the same collection (§5) |
-| `playground/vgeo_viewer/select_cut.js` | the rule on the CPU | **the oracle**. The GPU cut is held to agreeing with it exactly |
+| `cut/__fixtures__/vgeo_select_cut.js` | the rule on the CPU | **the oracle**. The GPU cut is held to agreeing with it exactly |
 
 ## 2. Phase 1 — the page decode has holes, and they are load-bearing
 
@@ -287,7 +287,7 @@ is resident but not selectable — its clusters' parents are split across pages
 pages has not arrived. The clamp draws `C`'s parent `P`, correctly, standing in over that surface.
 But `C` itself satisfies §4's form — `project(C.parent) > τ` and `project(C.self) ≤ τ` — so a
 flat evaluation draws it as well, underneath `P`, and the depth buffer picks between two surfaces
-a few microns apart. This is exactly the failure `select_cut.spec.js` was written to catch, and
+a few microns apart. This is exactly the failure `vgeo_select_cut.spec.js` was written to catch, and
 the CPU traversal never meets it because *not entering a non-selectable group* is how it descends.
 A predicate has to say so out loud:
 
@@ -535,7 +535,7 @@ Four tiers, in the order they catch things.
    pages withheld. Multiset, not set: a duplicate is the failure mode that reads as corrupt
    geometry rather than as a missing page, and a set comparison cannot see it.
 
-   **At 64 KB pages, not the 8 KB `select_cut.spec.js` uses** (REVIEW_LEDGER D2). The 8 KB fixture
+   **At 64 KB pages, not the 8 KB `vgeo_select_cut.spec.js` uses** (REVIEW_LEDGER D2). The 8 KB fixture
    is the one that puts a group's parents on either side of a page boundary thirteen times over,
    which is what *that* spec is for — and it is the one fixture in which this spec's headline case
    cannot occur: measured, 8 KB puts exactly one group in every page of this torus, so a blocked

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":"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"}
+{"version":3,"file":"VGeoFeedbackLoop.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js"],"names":[],"mappings":"AAMA;;;;;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;IAwBD;;;;OAIG;IACH,SAFa,IAAI,CAIhB;IAED;;;;;;;OAOG;IACH,WAFa,IAAI,CAIhB;;CACJ;yBA1OY,OAAO,iEAAiE,EAAE,UAAU;wCACpF,OAAO,gCAAgC,EAAE,yBAAyB;4BAClE,OAAO,oBAAoB,EAAE,aAAa"}

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../../../core/assert.js";
 import { graph_read_buffer } from "../../../buffer/graph_read_buffer.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";
 
@@ -206,6 +207,15 @@ export class VGeoFeedbackLoop {
             this.#stats[i] = words[VGEO_FEEDBACK_OFFSET.STATS + i];
         }
 
+        /*
+         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]);
+
         this.#residency.apply(words, layout, reading_frame);
     }
 

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoPageFetcher.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IA0EI;;;;;;OAMG;IACH;QAL4B,YAAY,GAA7B,MAAM;QACuB,WAAW,SAA5B,MAAM;OAS5B;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;;;OAOG;IACH,cAPW,mBAAmB,cACnB,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CAc7B;IAED;;;;;;OAMG;IACH,eAHW,mBAAmB,GACjB,MAAM,CAuBlB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAiBhB;;CAwKJ;kCAnYY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ"}
+{"version":3,"file":"VGeoPageFetcher.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IA0EI;;;;;;OAMG;IACH;QAL4B,YAAY,GAA7B,MAAM;QACuB,WAAW,SAA5B,MAAM;OAS5B;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;;;OAOG;IACH,cAPW,mBAAmB,cACnB,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CAc7B;IAED;;;;;;OAMG;IACH,eAHW,mBAAmB,GACjB,MAAM,CAuBlB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAiBhB;;CAiLJ;kCA5YY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ"}

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

@@ -301,6 +301,14 @@ export class VGeoPageFetcher {
             id,
             source_id,
             asset_id_low64: reader.header.asset_id_low64,
+            /*
+             The worker decodes cluster records and their layout is the container's (§7), so the
+             version travels with the identity. It rides every request rather than only the one
+             carrying the descriptor: the worker builds its core from whichever request arrives
+             first for a source, and a field that is only sometimes there is a field that is
+             sometimes undefined.
+            */
+            format_version: reader.header.format_version,
             verify_frames: options.verify_frames,
             fetch_retries: options.fetch_retries,
             fetch_retry_backoff_ms: options.fetch_retry_backoff_ms,
@@ -378,6 +386,7 @@ export class VGeoPageFetcher {
             core = new VGeoPageFetcherCore({
                 read: (offset, length, abort) => source.read(offset, length, abort),
                 asset_id_low64: () => reader.header.asset_id_low64,
+                format_version: () => reader.header.format_version,
                 verify_frames: options.verify_frames,
                 fetch_retries: options.fetch_retries,
                 fetch_retry_backoff_ms: options.fetch_retry_backoff_ms,

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

@@ -1 +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"}
+{"version":3,"file":"VGeoResidency.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoResidency.js"],"names":[],"mappings":"AA2GA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;IAiKI;;;;;;;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;;CAqXJ;kCAr1CY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ;qCAC7C,OAAO,6BAA6B,EAAE,sBAAsB;qCALpC,2BAA2B;gCALhC,gDAAgD;gCAIhD,sBAAsB"}

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

@@ -34,6 +34,18 @@ const NO_SLOT = 0xFFFFFFFF;
  * @param {number} state
  * @returns {number}
  */
+/**
+ * Which of {@link VGeoResidency}'s two CLOCK hands is meant. They are an array rather than two
+ * fields so that one sweep can serve both tiers.
+ * @type {number}
+ */
+const HAND_VRAM = 0;
+
+/**
+ * @type {number}
+ */
+const HAND_RAM = 1;
+
 function tag_of(state) {
     return state >>> TAG_SHIFT;
 }
@@ -189,11 +201,6 @@ export class VGeoResidency {
      */
     #vram_pinned;
 
-    /**
-     * @type {number}
-     */
-    #vram_hand = 0;
-
     // ------------------------------------------------------------------ the RAM tier
 
     /**
@@ -229,11 +236,6 @@ export class VGeoResidency {
      */
     #ram_free = [];
 
-    /**
-     * @type {number}
-     */
-    #ram_hand = 0;
-
     /**
      * @type {number}
      */
@@ -253,6 +255,25 @@ export class VGeoResidency {
 
     // ------------------------------------------------------------------ per reading
 
+    /**
+     * The CLOCK hands, {@link HAND_VRAM} and {@link HAND_RAM}. One array rather than two fields
+     * because {@link #next_victim} sweeps either tier and has to advance the one it was given.
+     * @type {Int32Array}
+     */
+    #hands = new Int32Array(2);
+
+    /**
+     * Bound once each, rather than per sweep: {@link #next_victim} takes the test as a function and
+     * is called per eviction, which is often enough that a closure a call would be a closure a call.
+     * @type {function(number): boolean}
+     */
+    #is_evictable_vram = (page_row) => this.evictable_vram(page_row);
+
+    /**
+     * @type {function(number): boolean}
+     */
+    #is_evictable_ram = (slot) => this.evictable_ram(slot);
+
     /**
      * @type {number}
      */
@@ -1036,28 +1057,44 @@ export class VGeoResidency {
     }
 
     /**
-     * The CLOCK hand over the page rows, under the reading's test budget.
+     * One tier's CLOCK hand, advanced under the reading's shared test budget.
+     *
+     * Both tiers sweep the same way — this is the "eviction is CLOCK under a test budget" bullet
+     * above, and the only thing that differs between them is which array is being swept and what
+     * makes an entry of it evictable. The budget is deliberately *not* per tier: a reading gets
+     * `max_eviction_tests_per_reading` tests to spend across both, so a VRAM tier that is entirely
+     * hot cannot also spend the RAM tier's allowance looking.
      *
-     * @returns {number} page row, or -1 when the budget is spent without finding one
+     * @param {number} hand {@link HAND_VRAM} or {@link HAND_RAM}
+     * @param {number} capacity entries in that tier
+     * @param {function(number): boolean} evictable
+     * @returns {number} the index to evict, or -1 when the budget is spent without finding one
      */
-    #next_vram_victim() {
-        const capacity = this.#vram_last_used.length;
-
+    #next_victim(hand, capacity, evictable) {
         while (this.#tests_left > 0) {
             this.#tests_left--;
 
-            const page_row = this.#vram_hand;
+            const candidate = this.#hands[hand];
 
-            this.#vram_hand = (page_row + 1) % capacity;
+            this.#hands[hand] = (candidate + 1) % capacity;
 
-            if (this.evictable_vram(page_row)) {
-                return page_row;
+            if (evictable(candidate)) {
+                return candidate;
             }
         }
 
         return -1;
     }
 
+    /**
+     * @returns {number} page row, or -1
+     */
+    #next_vram_victim() {
+        return this.#next_victim(
+            HAND_VRAM, this.#vram_last_used.length, this.#is_evictable_vram
+        );
+    }
+
     /**
      * @param {number} page_row
      */
@@ -1113,21 +1150,9 @@ export class VGeoResidency {
      * @returns {number} slot, or -1
      */
     #next_ram_victim() {
-        const capacity = this.#ram_geometry.length;
-
-        while (this.#tests_left > 0) {
-            this.#tests_left--;
-
-            const slot = this.#ram_hand;
-
-            this.#ram_hand = (slot + 1) % capacity;
-
-            if (this.evictable_ram(slot)) {
-                return slot;
-            }
-        }
-
-        return -1;
+        return this.#next_victim(
+            HAND_RAM, this.#ram_geometry.length, this.#is_evictable_ram
+        );
     }
 
     /**

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_access.d.ts

@@ -1,14 +1,14 @@
 /**
- * Addressing and arithmetic shared by every pass of the cut — how to find a row, and how to project
- * an error.
+ * The arithmetic the cut rule is written in: where the camera is in an instance's own space, what
+ * an object-space error projects to in pixels, and whether a sphere is worth descending into at all.
  *
- * The arena is `array<u32>` with hand-written accessors rather than a marshalled struct array,
- * because it holds three different row types in one allocation per page and no struct array can say
- * that. The offsets it indexes with are the `layout/` constants, so the CPU writer and the kernel
- * are reading the same numbers rather than two copies of them.
+ * Addressing moved to {@link chunk_vgeo_cut_arena}, which this pulls in — a pass that only wants to
+ * find a row should not have to take the frustum test with it, and the passes that did not want to
+ * wrote their own accessor instead.
  *
- * Every buffer named here has to be declared by the importing shader. That is the price of sharing
- * addressing across passes, and it is the same bargain `chunk_scene_database_access` makes.
+ * Every buffer named here has to be declared by the importing shader — `instances`, plus whatever
+ * the arena chunk needs. That is the price of sharing addressing across passes, and it is the same
+ * bargain `chunk_scene_database_access` makes.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_vgeo_cut_access.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_access.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CAmJZ;0BA9KmB,0CAA0C"}
+{"version":3,"file":"chunk_vgeo_cut_access.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_access.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CAiHQ;0BAnID,0CAA0C"}