@woosh/meep-engine 3.27.0 → 3.28.0

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/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,CA+EQ;0BAjGD,0CAA0C"}

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_access.js

@@ -1,27 +1,18 @@
 import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
-import { VGEO_CLUSTER_ROW_WORDS } from "../layout/VGEO_CLUSTER_ROW_WORDS.js";
-import { VGEO_GEOMETRY_ROW_WORDS } from "../layout/VGEO_GEOMETRY_ROW_WORDS.js";
-import { VGEO_GROUP_ROW_WORDS } from "../layout/VGEO_GROUP_ROW_WORDS.js";
 import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
-import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
-import { VGEO_NODE_ROW_LEAF_BIT } from "../layout/VGEO_NODE_ROW_LEAF_BIT.js";
-import { VGEO_NODE_ROW_OFFSET } from "../layout/VGEO_NODE_ROW_OFFSET.js";
-import { VGEO_NODE_ROW_WORDS } from "../layout/VGEO_NODE_ROW_WORDS.js";
-import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
-import { VGEO_PAGE_ROW_WORDS } from "../layout/VGEO_PAGE_ROW_WORDS.js";
-import { VGEO_PARENT_ROW_WORDS } from "../layout/VGEO_PARENT_ROW_WORDS.js";
+import { chunk_vgeo_cut_arena } from "./chunk_vgeo_cut_arena.js";
 
 /**
- * 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
@@ -30,17 +21,6 @@ import { VGEO_PARENT_ROW_WORDS } from "../layout/VGEO_PARENT_ROW_WORDS.js";
 export const chunk_vgeo_cut_access = CodeChunk.from(
     //language=WGSL
     `
-const VG_PAGE_ROW_WORDS = ${VGEO_PAGE_ROW_WORDS}u;
-const VG_NODE_ROW_WORDS = ${VGEO_NODE_ROW_WORDS}u;
-const VG_GROUP_ROW_WORDS = ${VGEO_GROUP_ROW_WORDS}u;
-const VG_CLUSTER_ROW_WORDS = ${VGEO_CLUSTER_ROW_WORDS}u;
-const VG_PARENT_ROW_WORDS = ${VGEO_PARENT_ROW_WORDS}u;
-const VG_INSTANCE_WORDS = ${VGEO_INSTANCE_WORDS}u;
-const VG_GEOMETRY_ROW_WORDS = ${VGEO_GEOMETRY_ROW_WORDS}u;
-
-const VG_NODE_LEAF_BIT = ${VGEO_NODE_ROW_LEAF_BIT}u;
-const VG_NODE_CHILD_COUNT_MASK = 0xffu;
-
 /**
  * Any error at or above this is the root's +infinity, however the file spelled it.
  *
@@ -51,63 +31,6 @@ const VG_NODE_CHILD_COUNT_MASK = 0xffu;
 const VG_ERROR_INFINITE = 3.0e38;
 const VG_PROJECTION_MAX = 3.4e38;
 
-/**
- * A page's slot: its header, then its node, group and cluster rows.
- *
- * The stride is a uniform rather than a constant because the tier derives it from the page size its
- * containers are bounded at, and it is a **multiply** rather than a table read because format
- * §11.14 made that legal — design §6 asked for fixed-size page slots from the start and the bound
- * is what it was waiting for. There is no page table, no allocator, and no second storage binding
- * to keep coherent with this one.
- */
-fn vg_slot_base(page_row: u32) -> u32 {
-    return page_row * params.page_slot_words;
-}
-
-fn vg_page_field(page_row: u32, field: u32) -> u32 {
-    return vg_arena[vg_slot_base(page_row) + field];
-}
-
-fn vg_node_base(page_row: u32) -> u32 {
-    return vg_slot_base(page_row) + VG_PAGE_ROW_WORDS;
-}
-
-fn vg_group_base(page_row: u32) -> u32 {
-    return vg_node_base(page_row)
-        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.NODE_COUNT}u) * VG_NODE_ROW_WORDS;
-}
-
-fn vg_cluster_base(page_row: u32) -> u32 {
-    return vg_group_base(page_row)
-        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GROUP_COUNT}u) * VG_GROUP_ROW_WORDS;
-}
-
-/**
- * The fourth section: this page's parent rows, which is where a walk *up* reads.
- *
- * It may be empty, and a reader has to check rather than assume: the page row's parent
- * entry count is zero for
- * every page of a container written before format 4, which has no upward edge at all. Zero is not a
- * malformed page; it is an asset that can only be re-descended.
- */
-fn vg_parent_base(page_row: u32) -> u32 {
-    return vg_cluster_base(page_row)
-        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT}u) * VG_CLUSTER_ROW_WORDS;
-}
-
-fn vg_arena_f32(word: u32) -> f32 {
-    return bitcast<f32>(vg_arena[word]);
-}
-
-fn vg_sphere_at(word: u32) -> vec4<f32> {
-    return vec4<f32>(
-        bitcast<f32>(vg_arena[word]),
-        bitcast<f32>(vg_arena[word + 1u]),
-        bitcast<f32>(vg_arena[word + 2u]),
-        bitcast<f32>(vg_arena[word + 3u])
-    );
-}
-
 fn vg_instance_f32(instance_base: u32, field: u32) -> f32 {
     return bitcast<f32>(instances[instance_base + field]);
 }
@@ -123,7 +46,7 @@ fn vg_instance_eye(instance_base: u32) -> vec3<f32> {
 /**
  * \`err_px = r_e * screen_height / (2 * tan(fov_y / 2) * d)\`, with \`d\` the distance to the
  * **closest point** of the sphere — design §4, and written in that order so that it agrees with
- * \`select_cut.js\` term for term rather than merely in the limit.
+ * \`vgeo_select_cut\` term for term rather than merely in the limit.
  *
  * Two conventions carry real weight. A zero error projects to zero **unconditionally**, so a leaf
  * — whose error is exactly zero — does not become undrawable the moment the camera enters its
@@ -172,4 +95,4 @@ fn vg_sphere_outside_frustum(instance_base: u32, sphere: vec4<f32>) -> bool {
 
     return false;
 }
-`, []);
+`, [chunk_vgeo_cut_arena]);

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

@@ -0,0 +1,19 @@
+/**
+ * Where a row is, in the arena — and nothing else.
+ *
+ * Split out of {@link chunk_vgeo_cut_access} because three passes want an address and only one of
+ * them wants a projection. Before the split, a pass that needed one field of a page header wrote
+ * its own accessor rather than take a chunk that also declares the frustum test, the instance eye
+ * and the error projection; `shader_vgeo_cut_reseed` said so where its copy was
+ * (`vg_reseed_page_field`). The answer to "the chunk declares more than this pass binds" is a
+ * smaller chunk, not a second accessor.
+ *
+ * Requires the importing shader to declare `params` and `vg_arena`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_arena: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_arena.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_arena.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_arena.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;GAeG;AACH,mCAFU,SAAS,CAwEZ;0BAjGmB,0CAA0C"}

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_arena.js

@@ -0,0 +1,98 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CLUSTER_ROW_WORDS } from "../layout/VGEO_CLUSTER_ROW_WORDS.js";
+import { VGEO_GEOMETRY_ROW_WORDS } from "../layout/VGEO_GEOMETRY_ROW_WORDS.js";
+import { VGEO_GROUP_ROW_WORDS } from "../layout/VGEO_GROUP_ROW_WORDS.js";
+import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
+import { VGEO_NODE_ROW_LEAF_BIT } from "../layout/VGEO_NODE_ROW_LEAF_BIT.js";
+import { VGEO_NODE_ROW_WORDS } from "../layout/VGEO_NODE_ROW_WORDS.js";
+import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_PAGE_ROW_WORDS } from "../layout/VGEO_PAGE_ROW_WORDS.js";
+import { VGEO_PARENT_ROW_WORDS } from "../layout/VGEO_PARENT_ROW_WORDS.js";
+
+/**
+ * Where a row is, in the arena — and nothing else.
+ *
+ * Split out of {@link chunk_vgeo_cut_access} because three passes want an address and only one of
+ * them wants a projection. Before the split, a pass that needed one field of a page header wrote
+ * its own accessor rather than take a chunk that also declares the frustum test, the instance eye
+ * and the error projection; `shader_vgeo_cut_reseed` said so where its copy was
+ * (`vg_reseed_page_field`). The answer to "the chunk declares more than this pass binds" is a
+ * smaller chunk, not a second accessor.
+ *
+ * Requires the importing shader to declare `params` and `vg_arena`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_arena = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_PAGE_ROW_WORDS = ${VGEO_PAGE_ROW_WORDS}u;
+const VG_NODE_ROW_WORDS = ${VGEO_NODE_ROW_WORDS}u;
+const VG_GROUP_ROW_WORDS = ${VGEO_GROUP_ROW_WORDS}u;
+const VG_CLUSTER_ROW_WORDS = ${VGEO_CLUSTER_ROW_WORDS}u;
+const VG_PARENT_ROW_WORDS = ${VGEO_PARENT_ROW_WORDS}u;
+const VG_INSTANCE_WORDS = ${VGEO_INSTANCE_WORDS}u;
+const VG_GEOMETRY_ROW_WORDS = ${VGEO_GEOMETRY_ROW_WORDS}u;
+
+const VG_NODE_LEAF_BIT = ${VGEO_NODE_ROW_LEAF_BIT}u;
+const VG_NODE_CHILD_COUNT_MASK = 0xffu;
+
+/**
+ * A page's slot: its header, then its node, group and cluster rows.
+ *
+ * The stride is a uniform rather than a constant because the tier derives it from the page size its
+ * containers are bounded at, and it is a **multiply** rather than a table read because format
+ * §11.14 made that legal — design §6 asked for fixed-size page slots from the start and the bound
+ * is what it was waiting for. There is no page table, no allocator, and no second storage binding
+ * to keep coherent with this one.
+ */
+fn vg_slot_base(page_row: u32) -> u32 {
+    return page_row * params.page_slot_words;
+}
+
+fn vg_page_field(page_row: u32, field: u32) -> u32 {
+    return vg_arena[vg_slot_base(page_row) + field];
+}
+
+fn vg_node_base(page_row: u32) -> u32 {
+    return vg_slot_base(page_row) + VG_PAGE_ROW_WORDS;
+}
+
+fn vg_group_base(page_row: u32) -> u32 {
+    return vg_node_base(page_row)
+        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.NODE_COUNT}u) * VG_NODE_ROW_WORDS;
+}
+
+fn vg_cluster_base(page_row: u32) -> u32 {
+    return vg_group_base(page_row)
+        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GROUP_COUNT}u) * VG_GROUP_ROW_WORDS;
+}
+
+/**
+ * The fourth section: this page's parent rows, which is where a walk *up* reads.
+ *
+ * It may be empty, and a reader has to check rather than assume: the page row's parent
+ * entry count is zero for
+ * every page of a container written before format 4, which has no upward edge at all. Zero is not a
+ * malformed page; it is an asset that can only be re-descended.
+ */
+fn vg_parent_base(page_row: u32) -> u32 {
+    return vg_cluster_base(page_row)
+        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT}u) * VG_CLUSTER_ROW_WORDS;
+}
+
+fn vg_arena_f32(word: u32) -> f32 {
+    return bitcast<f32>(vg_arena[word]);
+}
+
+fn vg_sphere_at(word: u32) -> vec4<f32> {
+    return vec4<f32>(
+        bitcast<f32>(vg_arena[word]),
+        bitcast<f32>(vg_arena[word + 1u]),
+        bitcast<f32>(vg_arena[word + 2u]),
+        bitcast<f32>(vg_arena[word + 3u])
+    );
+}
+`, []);

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

@@ -0,0 +1,31 @@
+/**
+ * One page, claimed once per instance, and touched when the claim is won.
+ *
+ * This is the invariant the whole cut rests on — "at most one draw record per (instance, cluster)" —
+ * and it was written out three times: here's-the-original in `shader_vgeo_cut_traverse`, a
+ * line-for-line copy in `shader_vgeo_cut_reseed`, and inline in `shader_vgeo_cut_seed`. The
+ * copies had already begun to differ: the seed pass omitted the `claim_word_count` bound the other
+ * two take. It was correct — the seed pass establishes that bound a few lines earlier — but a
+ * correctness invariant whose three spellings disagree about which checks it needs is one nobody
+ * can read off the source any more.
+ *
+ * The touch is the other half and travels with it, because a claim that does not stamp the page is
+ * a page that ages out of the LRU while it is on screen. LRU on last-**touched**, never on
+ * last-wanted: stamping at fetch time freezes the stamp of exactly the pages that are being drawn
+ * and evicts them, which is the fallback-chain bug the virtual texture cache already keys on touch
+ * to avoid.
+ *
+ * One bit per page row, because the feedback buffer is per frame rather than per invocation: the
+ * bit dedups across every view and bucket of the frame and is the record the host reads, so there
+ * is no list to fill and no touch a full list could lose.
+ *
+ * Requires the importing shader to declare `params`, `vg_arena`, `instances`, `claim` and
+ * `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_claim: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_claim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_claim.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_claim.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mCAFU,SAAS,CAiEQ;0BAlGD,0CAA0C"}

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_claim.js

@@ -0,0 +1,99 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { chunk_vgeo_cut_arena } from "./chunk_vgeo_cut_arena.js";
+
+/**
+ * One page, claimed once per instance, and touched when the claim is won.
+ *
+ * This is the invariant the whole cut rests on — "at most one draw record per (instance, cluster)" —
+ * and it was written out three times: here's-the-original in `shader_vgeo_cut_traverse`, a
+ * line-for-line copy in `shader_vgeo_cut_reseed`, and inline in `shader_vgeo_cut_seed`. The
+ * copies had already begun to differ: the seed pass omitted the `claim_word_count` bound the other
+ * two take. It was correct — the seed pass establishes that bound a few lines earlier — but a
+ * correctness invariant whose three spellings disagree about which checks it needs is one nobody
+ * can read off the source any more.
+ *
+ * The touch is the other half and travels with it, because a claim that does not stamp the page is
+ * a page that ages out of the LRU while it is on screen. LRU on last-**touched**, never on
+ * last-wanted: stamping at fetch time freezes the stamp of exactly the pages that are being drawn
+ * and evicts them, which is the fallback-chain bug the virtual texture cache already keys on touch
+ * to avoid.
+ *
+ * One bit per page row, because the feedback buffer is per frame rather than per invocation: the
+ * bit dedups across every view and bucket of the frame and is the record the host reads, so there
+ * is no list to fill and no touch a full list could lose.
+ *
+ * Requires the importing shader to declare `params`, `vg_arena`, `instances`, `claim` and
+ * `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_claim = CodeChunk.from(
+    //language=WGSL
+    `
+fn vg_stat(slot: u32, amount: u32) {
+    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + slot], amount);
+}
+
+/**
+ * Record that this page was selected from this frame — design §6's eviction key.
+ */
+fn vg_touch_page(page_row: u32) {
+    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
+}
+
+/**
+ * The claim itself, against a slice of the bitmask the caller already has in hand.
+ *
+ * Taken this way rather than always through the instance record because the seed pass computes the
+ * slice base in the same invocation that claims with it — it has just written it to the instance
+ * record, and reading it straight back would be a storage round trip for a value already in a
+ * register.
+ *
+ * @returns whether this invocation is the one that claimed the page
+ */
+fn vg_claim_page_at(claim_base: u32, ordinal_capacity: u32, page_row: u32) -> bool {
+    let ordinal = vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u);
+
+    if (ordinal >= ordinal_capacity) {
+        return false;
+    }
+
+    let bit = claim_base + ordinal;
+
+    let word = bit >> 5u;
+
+    if (word >= params.claim_word_count) {
+        return false;
+    }
+
+    let mask = 1u << (bit & 31u);
+
+    if ((atomicOr(&claim[word], mask) & mask) != 0u) {
+        return false;
+    }
+
+    vg_stat(${VGEO_CUT_STAT.PAGES}u, 1u);
+
+    vg_touch_page(page_row);
+
+    return true;
+}
+
+/**
+ * The same claim, for a caller holding an instance rather than its slice. An instance whose slice
+ * of the bitmask does not fit is refused upstream, in the seed pass, rather than run unclaimed.
+ */
+fn vg_claim_page(instance_base: u32, page_row: u32) -> bool {
+    return vg_claim_page_at(
+        instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u],
+        instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u],
+        page_row
+    );
+}
+`, [chunk_vgeo_cut_arena]);