@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.d.ts

@@ -4,9 +4,9 @@
  * @param {VirtualGeometryPage[]} pages in file order, root first; every group's `page` must point
  *     back at the page holding it
  * @param {VGeoWriteOptions} options
- * @returns {BinaryBuffer} the whole file; its capacity is exactly the file's length, so
+ * @returns {Promise<BinaryBuffer>} the whole file; its capacity is exactly the file's length, so
  *     `raw_bytes` is the file
  */
-export function vgeo_write_container(pages: VirtualGeometryPage[], options: VGeoWriteOptions): BinaryBuffer;
+export function vgeo_write_container(pages: VirtualGeometryPage[], options: VGeoWriteOptions): Promise<BinaryBuffer>;
 import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=vgeo_write_container.d.ts.map

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AA4bA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BAppB4B,4CAA4C"}
+{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAkdA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,QAAQ,YAAY,CAAC,CAmOjC;6BA1rB4B,4CAA4C"}

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.js

@@ -17,6 +17,7 @@ import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
 import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "./frame/VGEO_FRAME_OFFSET.js";
+import { VGEO_GROUP_OFFSET } from "./page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_HASH_ALGO_XXH3 } from "./header/VGEO_HASH_ALGO_XXH3.js";
 import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
@@ -24,6 +25,7 @@ import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
 import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
 import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
 import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
+import { VGEO_MAX_LEVEL_COUNT } from "./header/VGEO_MAX_LEVEL_COUNT.js";
 import { VGEO_MAX_PARENT_ENTRY_COUNT } from "./page/VGEO_MAX_PARENT_ENTRY_COUNT.js";
 import { VGEO_MAX_PARENT_REF } from "./page/VGEO_MAX_PARENT_REF.js";
 import { VGEO_MIN_READER_VERSION } from "./header/VGEO_MIN_READER_VERSION.js";
@@ -240,15 +242,21 @@ function build_page_blob(page, child_pages, parents) {
         'page parent-page table must stay within what parent_ref can index'
     );
 
+    /*
+     Derived here and derived again by the reader, rather than written down: from `format_version`
+     6 the page header has no field for it, and the four bytes it used to occupy carry `node_count`
+     and the widened band instead. Nothing is lost by the move — the group table follows the header
+     and the node table follows the group table, so this was never free to be anything else.
+    */
     const node_table_offset = VGEO_PAGE_HEADER_SIZE + page.groups.length * VGEO_GROUP_RECORD_SIZE;
     const cluster_table_offset = node_table_offset + page.nodes.length * VGEO_NODE_RECORD_SIZE;
 
     /*
      The parent section sits between the cluster records and the payload rather than beside the
-     group table, which keeps `node_table_offset`'s "= 56 + 8·group_count" true and leaves every
-     offset a reader before format 4 computed exactly where it was. Both tables hold 4-byte entries
-     and the sections above them are all multiples of four, so the payload stays word-aligned —
-     format §11.8's promise, which the meshlet batch divides by four without rounding.
+     group table, which keeps the node table's "= 56 + 8·group_count" true and leaves every offset a
+     reader before format 4 computed exactly where it was. Both tables hold 4-byte entries and the
+     sections above them are all multiples of four, so the payload stays word-aligned — format
+     §11.8's promise, which the meshlet batch divides by four without rounding.
     */
     const parent_table_offset = cluster_table_offset + clusters.length * VGEO_CLUSTER_RECORD_SIZE;
 
@@ -272,13 +280,16 @@ function build_page_blob(page, child_pages, parents) {
 
     buffer.writeUint16(page.groups.length);
     buffer.writeUint16(clusters.length);
-    buffer.writeUint8(page.min_level);
-    buffer.writeUint8(page.max_level);
-    buffer.writeUint16(page.nodes.length);
+    buffer.writeUint16(page.min_level);
+    buffer.writeUint16(page.max_level);
     buffer.writeUint32(cluster_table_offset);
     buffer.writeUint32(payload_offset);
     buffer.writeUint32(payload_size);
-    buffer.writeUint32(node_table_offset);
+    buffer.writeUint16(page.nodes.length);
+
+    // The two bytes version 6 did not need out of `node_table_offset`, and §11 requires them zero.
+    buffer.writeUint16(0);
+
     buffer.writeUint32(parent_table_offset);
     buffer.writeUint16(parent_entry_count);
     buffer.writeUint16(parent_pages.length);
@@ -355,11 +366,18 @@ function build_page_blob(page, child_pages, parents) {
             buffer.writeUint16(parent.cluster);
         });
 
-        buffer.position = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
+        const group_record = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
 
+        buffer.position = group_record + VGEO_GROUP_OFFSET.CLUSTER_FIRST;
         buffer.writeUint16(cluster_index);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.CLUSTER_COUNT;
         buffer.writeUint16(group.clusters.length);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT;
         buffer.writeUint16(group.parent_cluster_count);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.PARENT_FIRST;
         buffer.writeUint16(parent_first);
 
         parent_first += group_parents.length;
@@ -372,7 +390,14 @@ function build_page_blob(page, child_pages, parents) {
             buffer.writeFloat32(cluster.self_error);
             buffer.writeFloat32(cluster.parent_error);
             buffer.writeFloat32Array(cluster.parent_sphere, 0, 4);
-            buffer.writeFloat32Array(cluster.bounds_sphere, 0, 4);
+
+            /*
+             Where `bounds_sphere` and `cone_reserved` were before `format_version` 5: the cut culls
+             a cluster and its whole subtree on this box, and the sphere it replaced was read by
+             nothing at runtime. The record is the same 112 bytes.
+            */
+            buffer.writeFloat32Array(cluster.subtree_aabb, 0, 6);
+
             buffer.writeFloat32Array(cluster.aabb, 0, 6);
 
             if (cluster.child_group === undefined) {
@@ -383,9 +408,6 @@ function build_page_blob(page, child_pages, parents) {
                 buffer.writeUint16(cluster.child_group.index_in_page);
             }
 
-            // cone_reserved
-            buffer.writeUint32(0);
-
             buffer.writeUint32(cluster.encoding_flags);
             buffer.writeUint32(cursor);
             buffer.writeUint32(cluster.payload.byteLength);
@@ -448,10 +470,10 @@ function page_size_guarantee(blobs, nominal_page_size) {
  * @param {VirtualGeometryPage[]} pages in file order, root first; every group's `page` must point
  *     back at the page holding it
  * @param {VGeoWriteOptions} options
- * @returns {BinaryBuffer} the whole file; its capacity is exactly the file's length, so
+ * @returns {Promise<BinaryBuffer>} the whole file; its capacity is exactly the file's length, so
  *     `raw_bytes` is the file
  */
-export function vgeo_write_container(pages, options) {
+export async function vgeo_write_container(pages, options) {
     assert.isArray(pages, 'pages');
     assert.greaterThan(pages.length, 0, 'pages.length');
 
@@ -459,9 +481,25 @@ export function vgeo_write_container(pages, options) {
         assert.equal(page.index, index, `page ${index} carries index ${page.index}`);
     });
 
+    assert.lessThanOrEqual(
+        options.levels.length, VGEO_MAX_LEVEL_COUNT,
+        'level_count must stay within what the header and the page bands can name (format §4)'
+    );
+
     const parents = resolve_group_references(pages);
 
-    const blobs = pages.map((page) => {
+    /**
+     * @type {PageBlob[]}
+     */
+    const blobs = [];
+
+    /*
+     One page at a time rather than a `Promise.all` over the list. Under a stream codec that would
+     be one live `CompressionStream` per page of the container — thousands of zlib instances for a
+     conversion that is builder-bound anyway — and under the synchronous codecs it would be the
+     same loop with a promise around each step.
+     */
+    for (const page of pages) {
         const blob = new PageBlob();
 
         blob.child_pages = collect_child_pages(page);
@@ -471,7 +509,7 @@ export function vgeo_write_container(pages, options) {
         // Compression happens here, before a single offset is known, and that is what keeps the
         // layout non-circular: a frame's extent follows from its *stored* size and its child count,
         // and neither depends on any offset value, because the child table is plaintext.
-        const encoded = vgeo_encode_frame_blob(decoded, options.codec, options.codec_level);
+        const encoded = await vgeo_encode_frame_blob(decoded, options.codec, options.codec_level);
 
         blob.codec = encoded.codec;
         blob.stored = encoded.bytes;
@@ -483,8 +521,8 @@ export function vgeo_write_container(pages, options) {
 
         blob.fetch_size = round_up(blob.extent, VGEO_FRAME_ALIGNMENT);
 
-        return blob;
-    });
+        blobs.push(blob);
+    }
 
     const feature_flags_ignorable = page_size_guarantee(blobs, options.nominal_page_size);
 
@@ -548,7 +586,7 @@ export function vgeo_write_container(pages, options) {
     buffer.writeUint32(options.nominal_page_size);
 
     buffer.position = VGEO_HEADER_OFFSET.LEVEL_COUNT;
-    buffer.writeUint8(options.levels.length);
+    buffer.writeUint16(options.levels.length);
 
     buffer.position = VGEO_HEADER_OFFSET.SOURCE_VERTEX_COUNT;
     buffer.writeUint64(BigInt(options.source_vertex_count));
@@ -617,8 +655,8 @@ export function vgeo_write_container(pages, options) {
         buffer.writeUint64(BigInt(blob.frame_offset));
         buffer.writeUint32(blob.fetch_size);
         buffer.writeUint32(blob.decoded_size);
-        buffer.writeUint8(pages[page_index].min_level);
-        buffer.writeUint8(pages[page_index].max_level);
+        buffer.writeUint16(pages[page_index].min_level);
+        buffer.writeUint16(pages[page_index].max_level);
         buffer.writeUint16(page_index === 0 ? VGEO_DIRECTORY_FLAG_ROOT_PAGE : 0);
         buffer.writeUint16(pages[page_index].groups.length);
         buffer.writeUint16(page_cluster_count);

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

@@ -0,0 +1,385 @@
+# Virtual Geometry cut — the per-cluster frustum test, measured and tightened
+
+**2026-09-16.** Follows `RUNTIME_PLAN_2026_09_14.md` §2.1 and §7, which left `pages visited` at half
+to three quarters of the resident tier when zoomed in and named the LOD sphere's looseness as the
+cause. This document measures that claim before acting on it, and the measurement changes what is
+worth building. Everything measured here was measured on the real asset in node
+(`measure_spheres*.mjs`, `measure3_breakdown.mjs`, `measure4_extents.mjs`, `measure5_reach.mjs`,
+`measure6_error_bound.mjs`, `measure7_containment.mjs`, `measure8_lod_vertices.mjs` of the
+building session).
+
+## 0. What the symptom is made of
+
+The container is the Zorah rosette panel, mesh 2023 primitive 0, as rebuilt on 2026-09-14
+(`5d4baf9e9ab4a0ea2bb6b3bcf48829f2.vgeo`, `format_version` 4, 942 MB): 17,213 pages, 590,858
+clusters, 160,441 groups, 34.3 clusters a page. Its DAG is 42 levels deep counted as the longest
+chain from a cluster down to a leaf, with 277,659 leaves. The tour of §7 saw, zoomed in at rest,
+3,220 pages visited of 4,096 resident against 4,060 clusters drawn.
+
+A CPU cut over the whole container — every page resident, camera on the panel's normal at the
+tour's poses, 50° fov, 1258×646, τ = 1 — reproduces that: 3,091 pages visited at rest with the
+cluster test on the LOD sphere, 4,537 with no frustum test at all. Where those pages are is the
+finding. At rest, of the 3,091:
+
+| | pages | of which drew a cluster | transit only |
+|---|---:|---:|---:|
+| levels 0–3 (the surface on screen and one step above) | 1,326 | 661 | 665 |
+| levels 4–19 | 1,665 | 7 | 1,658 |
+| levels 20–41 | 100 | 0 | 100 |
+
+A page is placed at the lowest level of any cluster it holds; 8,166 pages hold more than one level.
+Levels 4 and up hold 1,836 pages of the file. **1,765 of them are entered at rest with the LOD
+sphere and 1,650 with the exact subtree box** (levels 4–9: 415/466, 319/333, 247/251, 165/167,
+121/121, 80/80 visited with the sphere; 353, 293, 229, 160, 120, 78 with the box). Seven of them draw
+anything. They are the way down.
+
+## 1. Why the coarse pages cannot be culled, by any bound
+
+The cluster test decides whether a cluster refines into its child group. Culling it has to be
+conservative for **everything reachable below it**, because the child group is reached through it
+and a parent culled with an on-screen descendant is a hole. What is reachable below a cluster is
+not "the geometry this cluster approximates". Every simplification step consumes one group and
+produces two or more parents; every parent's `child_group` is the **whole** consumed group, so a
+parent's subtree carries its sibling's half of the surface too, and each child's subtree carries
+*its* sibling's, and so on down. The region below a cluster doubles per level. Measured, as the
+median diagonal of the exact subtree AABB against the object's diagonal, with the cluster's own AABB
+beside it:
+
+| level | clusters | own AABB diagonal | subtree AABB diagonal |
+|---:|---:|---:|---:|
+| 0 | 277,659 | 0.3% | 0.3% |
+| 4 | 18,783 | 0.7% | 1.1% |
+| 7 | 5,405 | 1.1% | 9.2% |
+| 10 | 2,919 | 1.2% | 23% |
+| 14 | 1,531 | 1.6% | 43% |
+| 20 | 948 | 1.9% | 64% |
+| 28 | 574 | 3.5% | 97% |
+
+A zoomed view covers one to two percent of the panel. From level 7 up the median cluster's subtree
+is bigger than the view, and from level 12 up it is a third of the object. No sphere and no box
+around that region is outside any zoomed frustum, and the coarse pages get visited because they
+hold clusters like that. The LOD sphere's looseness is real — below — but it is not what fills the
+tier.
+
+**The DAG's shape makes it worse than it need be.** Below level 4 each level halves the cluster
+count; above it the ratio decays to 0.6, 0.8 and by level 10 about 0.9 a level, so 58,000 clusters
+and 1,800 pages sit in a long thin tail above the surface anyone draws. That tail is the transit set.
+Pages also mix levels — 8,166 of 17,213 span more than one — so a coarse page's groups are
+spatially wherever the assembler found room.
+
+## 2. What was measured, against the four questions asked
+
+### 2.1 Where a subtree sphere could come from, and how tight it gets
+
+Install-derived is out by construction, not by measurement: `self_sphere` **is** a subtree bound.
+The builder's step sphere contains the consumed clusters' own step spheres and the produced
+clusters' vertices, so by induction it contains every vertex under it; a sample of 1,160 clusters
+across levels 0–28 found no subtree vertex outside its `self_sphere` (worst excess −3·10⁻⁹ of the
+radius, a leaf touching its own miniball). Nothing else a page carries is tighter for the subtree:
+node spheres and child-table metrics are unions of these same spheres.
+
+So the question is how much tighter a builder-computed bound is. Volume of the candidate over the
+volume of the LOD sphere, medians per level:
+
+| level | exact subtree AABB, as a box | its circumsphere | miniball over children's subtree boxes | miniball over every subtree AABB corner | miniball over every subtree vertex |
+|---:|---:|---:|---:|---:|---:|
+| 0 | — | 1.39 | 1.39 | 1.47 | 1.00 |
+| 2 | — | 0.82 | 0.79 | 0.70 | 0.49 |
+| 4 | — | 0.51 | 0.49 | 0.52 | 0.30 |
+| 8 | — | 0.31 | 0.30 | 0.28 | 0.22 |
+| 12 | — | 0.22 | 0.22 | 0.15 | 0.17 |
+| 16 | — | 0.18 | 0.18 | 0.15 | 0.14 |
+| 20 | — | 0.12 | 0.12 | 0.10 | — |
+
+The last two columns are medians over samples of 300 and 40 clusters a level drawn with different
+seeds, which is why the vertex miniball can read larger than the corner miniball at one level; the
+first three are exhaustive. The LOD sphere compounds: 1.5× the exact volume at level 1, 3–5× from
+level 4, 7× at level 20. A tight sphere is 0.55–0.6 of its radius at the levels that matter. The composable
+children's-boxes miniball is within 5–15% of the exhaustive reference at every level and is O(N)
+to build; the exact vertex miniball is the tightest and costs O(N·depth) points through a miniball,
+which on this container is ten billion points.
+
+### 2.2 What the tighter bound buys the cut
+
+Pages visited by the CPU cut, full residency, the tour's poses. `none` has the frustum test off
+entirely; `lod` is today's kernel; the exact AABB is tested as a box (p-vertex against each plane):
+
+| pose | none | LOD sphere | subtree-box circumsphere | children's-boxes miniball | exact subtree AABB |
+|---|---:|---:|---:|---:|---:|
+| rest (0.12 r) | 4,537 | 3,091 | 2,924 | 2,916 | **2,521** |
+| stop 0 | 4,583 | 3,051 | 2,856 | 2,847 | 2,478 |
+| stop 3 | 4,204 | 2,495 | 2,185 | 2,179 | **1,639** |
+| stop 4 | 4,261 | 2,599 | 2,190 | 2,183 | **1,649** |
+| stop 5 | 3,609 | 1,748 | 1,312 | 1,306 | **1,052** |
+| stop 7 | 4,000 | 2,245 | 1,890 | 1,887 | 1,452 |
+| framing (2.8 r) | 1,441 | 1,441 | 1,441 | 1,441 | 1,441 |
+
+A tight **sphere** takes 5–6% off at rest and up to 25% at a stop. The exact **box** takes 18% off at
+rest and 35–40% at stops 3, 4 and 5, and draws fewer clusters too (2,115 against 2,734 at rest: those
+were on-screen by the sphere and off-screen in fact). The CPU cut's camera is not the tour's — its
+orientation is the panel's normal and the tour's is the orbit controller's, and it drew 2,734 where the
+tour drew 4,060 — so the tables compare candidates against each other, and §5's tour is what compares
+before with after. The box wins because a subtree here is a flat
+patch of a flat panel — its AABB is thin along the normal and its circumsphere is not.
+
+### 2.3 The one test that would have hit the target, and why it is not sound
+
+A cluster's **own** bounds inflated by the error accumulated down its chain — `reach(P) =
+P.self_error + max over the child group of reach(c)`, leaves 0 — is the Nanite-shaped argument: an
+on-screen point of the fine surface is within the step's error of some parent's surface, so some
+chain of parents each passing that test exists. It visits 1,444 pages at rest and 358–1,300 at the
+stops, the two-to-fourfold cut the task hoped for. And it leaves **14 to 37 in-frustum clusters of
+the open cut undrawn at every pose**, some with their box six diagonals inside the frustum — holes
+in the middle of the screen, not slivers at its edge. Scaling the reach by 6 still leaves 10–20.
+
+The reason is measurable and is a finding on its own: **the stored error is not a distance bound.**
+Per step, the farthest any consumed vertex lies from the produced parents' triangles, over the step's
+`self_error`:
+
+| group level | steps sampled | ratio median | p90 | max | steps over 1 |
+|---:|---:|---:|---:|---:|---:|
+| 0 | 60 | 1.30 | 2.50 | 4.9 | 97% |
+| 3 | 60 | 1.29 | 2.07 | 5.6 | 75% |
+| 5 | 60 | 1.08 | 2.79 | 1,696 | 55% |
+| 10 | 60 | 0.77 | 2.39 | 10.5 | 33% |
+| 20 | 60 | 0.51 | 4.20 | 35.0 | 27% |
+| 32 | 46 | 5.60 | 16.8 | 33.0 | 85% |
+
+`self_error` is the quadric's conformance to the source, normalised by its weight (`vgeo_build_levels`
+§"Error is conformance to the source") — a plane-distance statistic, which is the right thing for a
+screen-space LOD threshold and the wrong thing to build a cull on. A cull that is right for most
+steps is a hole for the rest. Rejected; the number is recorded so nobody measures it again.
+
+### 2.4 Row cost and slot fit
+
+The exact subtree AABB is six words a cluster row: 13 → 19. `SELF_SPHERE` stays — the projection
+reads it — and the existing sphere test stays in front of the box test (§3.4). On this container the
+widest page is 52 clusters, 5 nodes, 15 groups, 25 parent entries: 851 words today, 1,163 at 19 words,
+56.8% of the 2,048-word slot a 64 KB page gets. `slot_words_for` and the install refusal are
+unchanged in form. At the million resident clusters design §4 targets the arena is 76 MB rather than
+52.
+
+## 3. What is built
+
+### 3.1 Format — `subtree_aabb` in the cluster record, as `format_version` 5
+
+The record stays 112 bytes. `bounds_sphere` goes: nothing at runtime read it (the row's doc said
+so), the AABB already serves the meshlet metadata and every downstream cull, and its 16 bytes plus
+`cone_reserved`'s 4 and the 6 that shift down make room for a 24-byte box in one place. Everything
+from offset 40 moves, so `min_reader_version` moves to 5 with it — a version-4 reader would read a
+version-5 record's `child_ref` out of its box.
+
+| offset | type | field | |
+|---:|---|---|---|
+| 0 | [f32; 4] | self_sphere | unchanged |
+| 16 | f32 | self_error | unchanged |
+| 20 | f32 | parent_error | unchanged |
+| 24 | [f32; 4] | parent_sphere | unchanged |
+| 40 | [f32; 6] | **subtree_aabb** | object-space AABB of this cluster's vertices and of every cluster reachable below it through child groups; leaves: equals `aabb` |
+| 64 | [f32; 6] | aabb | was 56 |
+| 88 | u16 | child_ref | was 80 |
+| 90 | u16 | child_group | was 82 |
+| 92 | u32 | encoding_flags | was 88; `cone_reserved` (was 84) is gone |
+| 96 | u32 | payload_offset | was 92 |
+| 100 | u32 | payload_size | was 96 |
+| 104 | u8 | vertex_count | was 100 |
+| 105 | u8 | triangle_count | was 101 |
+| 106 | [u8; 6] | reserved | was ten bytes at 102; the validator's zero check follows |
+
+The writer and the validator read and write the record **positionally** (`vgeo_write_container` after
+`SELF_SPHERE`, `read_clusters` in the validator), so both are re-sequenced, not just the offset table.
+`VirtualGeometryCluster.bounds_sphere` stays as a **builder-only** field — the object sphere, the
+group centroids and the leaf `self_sphere` are built from it — and its doc says it is no longer
+written. `VIRTUAL_GEOMETRY_DESIGN.md` and `VIRTUAL_GEOMETRY_PLAN.md` mention `cone_reserved` as a
+zeroed column and are corrected.
+
+**Build invariant §11.17.** `subtree_aabb` contains the cluster's `aabb` and, for every cluster of its
+child group, that cluster's `subtree_aabb`. Exact on stored values, no tolerance: the builder computes
+the union of float32 extremes, which is exactly representable. By induction it contains every vertex
+below the cluster, which is the whole of what the cull needs, and it needs no sphere nesting — the
+containment that made §7's LOD pair compound is not asked of it.
+
+**§11.7 gains what dropping `bounds_sphere` would have lost.** The validator checked
+`bounds_sphere ∋ vertices` and never `self_sphere ∋ vertices`; the latter is what the sphere test and
+the version-4 cube in §3.4 rest on, and it was only ever true by construction (`vgeo_build_levels`
+sets a leaf's `self_sphere` to its miniball and inflates every step sphere to contain the produced
+vertices). It is now stated in §11.7 and checked per cluster against the payload.
+
+**Builder.** A memoised walk over `child_group` after `vgeo_build_levels`: a leaf's box is its `aabb`;
+a parent's is its `aabb` unioned with each child-group member's `subtree_aabb`. Not a pass by level:
+a round leaves unmerged clusters in the frontier, so a group formed at round L holds members created
+at any lower level, and `group.level` says where the group was formed, not where its members were.
+The walk is O(N) either way.
+
+**Reader.** `VGeoPage.subtree_aabb` (`6 · cluster_count`) replaces `bounds_sphere`. The page decoder
+is handed the container's `format_version` — through `VGeoPageFetcherCore`, whose three construction
+sites (reader, in-process fetcher, worker) all have the header — and reads a version-4 record by the
+old offsets, synthesising `subtree_aabb` as the cube around `self_sphere`: a conservative subtree
+bound, so a container nobody has rebuilt still culls correctly. §3.4 says why it also culls no worse.
+The validator accepts only the current version, as it always has.
+
+### 3.2 Runtime — `CULL_BOX` in the row, tested after the sphere and after the election
+
+`VGEO_CLUSTER_ROW_OFFSET.CULL_BOX = 13`, six words, `VGEO_CLUSTER_ROW_WORDS = 19`;
+`vgeo_runtime_write_page_block` copies `page.subtree_aabb`. `vg_visit_cluster` keeps its
+`SELF_SPHERE` test and adds `vg_box_outside_frustum` on the row's box: a p-vertex per plane, five
+planes, the same `VGEO_CUT_FLAG_CULL` bit. Clusters the sphere rejects count in `CULLED_CLUSTER` as
+before; clusters the sphere passed and the box rejected count in a new `CULLED_CLUSTER_BOX`, so a
+version-4 container reading zero there is §3.4's promise made visible. Two conservative bounds on the
+same subtree; a cluster outside either is outside.
+
+**The frustum tests move below the walk-up election.** Today the cull runs before the
+`parent_projected <= tau` branch, so with the coarsen flag on a frontier cluster the frustum rejects
+never elects the walk to its parents — and the parent's own `aabb` can protrude on screen beyond the
+children's union, which is exactly why §3.1 adds it. A tighter bound fires that more often. A cluster
+below the cut refines into nothing and claims nothing, so culling it buys residency nothing; the
+election is evaluated first, unconditionally, and the frustum tests gate only what follows: drawing,
+clamping and refining. The production caller never sets coarsen today; the spec does.
+
+### 3.3 The CPU reference cut
+
+`vgeo_select_cut` culls on `page.subtree_aabb` with the same box test, so the fixture and the kernel
+answer the same question, and its spec's claims ("never a hole while a page is missing", "a fully
+resident cut is a whole-file reader's cut") run against the new bound.
+
+### 3.4 Why the sphere test stays
+
+For a version-5 page the box is inside the sphere's cube and usually inside the sphere; the sphere
+test culls almost nothing the box would not. For a version-4 page the synthesised box **is** the
+sphere's cube, and a cube culls less than its inscribed sphere: the CPU cut visits 6–10% more pages
+on the cube alone (3,292 against 3,091 at rest). With both tests a version-4 container culls exactly
+what it culls today and a version-5 container culls what the box allows. No version reaches the
+kernel.
+
+## 4. The proof, and where it lives
+
+**Claim.** With culling on, the cut draws every cluster the open cut draws that has a vertex inside
+the frustum, and no cluster the open cut does not draw — descending from the root, and walking up
+from a kept frontier with the coarsen flag on. Parents of one group may decide differently —
+a group is claimed and drawn once by whichever parent reaches it first — so no group-uniformity is
+needed and none is argued; §2.1 of the 2026-09-14 plan leaned on it and did not need to.
+
+**Argument.** A culled cluster's `CULL_BOX` (or `SELF_SPHERE`) is outside a frustum plane. Both
+contain every vertex of every cluster reachable below it (§3.1's invariant for the box; §7's
+construction for the sphere), so every such cluster is outside the same plane, and so is every
+triangle they carry. Nothing on screen was under it. The LOD half of the rule is untouched, so
+RUNTIME_PLAN §4.4's second proof — every cluster the flat rule draws is reached — holds for every
+on-screen cluster: each ancestor along its chain contains it and so passes both tests.
+
+**Where it is checked.** `vgeo_cut_agreement.spec.js`, `frustum culling removes only what is outside
+the frustum`, rewritten to hold the kernel against the **reader's pages** and not against any bound
+the row carries. For each cluster the open cut drew and the culled cut did not, it walks the child
+groups through the reader and asserts every **vertex** of every cluster it reaches — decoded from the
+payload, the same witness `vgeo_read_page.spec` uses for the `aabb` — is outside the frustum. Not the
+descendants' boxes: a sphere that contains every vertex need not contain a box corner, so a
+sphere-culled cluster with a straddling box would fail a box oracle on a correct kernel. For every
+touched page but the root it asserts some cluster refining into it passes the kernel's own predicate
+on bounds the spec computes itself — `self_sphere` not rejected and the union box of its subtree
+not rejected — because a union box the frustum cuts through the gap between two members passes the
+kernel's test with no member inside, and a p-vertex test admits a box just past an edge, so no
+assertion about member boxes is implied by the design. The same test runs with the coarsen flag on
+over a frontier seeded below the cut, against the open coarsen cut. That the **stored**
+`subtree_aabb` equals the union the spec computes is `vgeo_read_page.spec.js`'s to check, and it does,
+exactly. A child group whose page the reader does not hold is a leaf to the walk: nothing below a
+missing page can be drawn, and the parent's own vertices are already in the check.
+
+## 5. What it reads after — measured 2026-09-16
+
+The rosette panel rebuilt at version 5 (`5a01cc81…`, 17,213 pages, 590,858 clusters and 160,441
+groups — identical to the version-4 build, and 940,215,784 bytes against 941,905,000), validated
+clean including §11.17 and the new §11.7 check. The tour of RUNTIME_PLAN §7, same driver, same eight
+stops twice round, 4,096 slots, 1258×646, then the rosette at rest. Both containers were driven
+through **this** runtime, so the version-4 column is the §3.4 promise rather than an old reading.
+
+| | version 4 (cube from the LOD sphere) | version 5 (subtree box) |
+|---|---:|---:|
+| pages visited, rosette at rest | 3,231 | **2,854** |
+| pages visited, stops 3, 4, 5, 7 | 2,908 / 2,502 / 2,005 / 2,322 | **2,169 / 1,763 / 1,341 / 1,633** |
+| pages visited, framing distance | 1,445 | 1,445 |
+| pages visited, summed over the tour | 48,563 | **39,075** |
+| clusters drawn at rest | 4,055 | 3,471 |
+| clusters the box culled and the sphere did not, at rest | 0 | 5,520 |
+| `clamped`, every stop | 0 | 0 |
+| pages evicted over the run | 3,040 | **1,908** |
+| installs refused over the run | 1,640 | **483** |
+| pages fetched | 4,895 | 4,653 |
+
+Against the same stop the box takes 12% off at rest, 14–18% at the three stops facing the panel
+squarely, and 25–33% at the four oblique ones — where §2.2's node measurement said 35–40%, and the
+difference is the sphere test still running in front of it. At the framing distance, where nothing
+is off screen, it costs and saves nothing and the box culls zero. `culled (box)` is zero at every
+stop of the version-4 run, which is §3.4 measured rather than argued.
+
+**Drawn falls with visited**, 4,055 to 3,471 at rest, and that is the other half of the same fact:
+those clusters passed a sphere that reaches well outside the geometry it stands for, and they were
+off screen. The rest-pose screenshot is the same picture — same ornament, same shading, same depth
+of detail; only the panel's own counters differ.
+
+**What it is worth is residency, not the cut's own cost.** Evictions over the run fall by 37% and
+refused installs by 71%, which is the LRU being handed a working set closer to what the view needs.
+`clamped` stays zero throughout, so nothing is drawn coarse to pay for it.
+
+## 6. What this does not do, and what would
+
+- **It does not get visited pages to a few hundred, and nothing conservative on a DAG edge can.** §1
+  is the floor: ~1,550 transit pages at every zoomed pose. That floor is the traversal's, not the
+  bound's. A descent that reaches groups through a **spatial** hierarchy — a BVH whose leaves are
+  groups at every level placed by their own bounds, the LOD range of what is beneath a node deciding
+  whether to enter it, the flat rule of §4.4 evaluated at each group reached — needs no subtree
+  bound at all, because nothing is reached *through* a coarse cluster; and it enumerates each group
+  once, which retires the claim. That is Nanite's shape and a different document: it replaces the
+  child-table descent, the claim, the frontier and the coarsen path of CUT_PLAN_2026_09_14.
+- **It does not fix the builder's tail.** Convergence decaying from 0.5 to 0.9 a level above level
+  4 is where the 1,700 transit pages come from, and the assembler mixing levels in a page is why a
+  zoomed view touches most of them. Both are the builder's, measured here and left open.
+- **It does not make the error a bound.** §2.3's table is a property of the LOD metric, not of this
+  cull; whether the LOD switch should carry a geometric bound beside the quadric is its own question.
+- **It does not touch the node test**, which culls inside an already-claimed page and does not move
+  residency.
+
+## 7. Order, and what each step leaves green
+
+Each change carries a spec that fails before it and passes after; no spies, no mocks.
+
+1. **Format.** `VGEO_CLUSTER_OFFSET` v5 layout and a v4 table kept for the reader;
+   `VGEO_FORMAT_VERSION`/`VGEO_MIN_READER_VERSION` 5; writer re-sequenced and writing `subtree_aabb`;
+   builder computes it; reader reads it through `format_version` handed to `VGeoPageFetcherCore` at
+   its four construction sites (and synthesises the cube for v4); validator re-sequenced, checks §11.17
+   and `self_sphere ∋ vertices`, stops after a version defect. Pins: `vgeo_read_page.spec` — every
+   cluster's `subtree_aabb` is exactly the union of its `aabb` and its child group's boxes, and a
+   leaf's equals its `aabb`; `vgeo_validate_container.spec` — a shrunk `subtree_aabb` is caught, and so
+   is a `self_sphere` that leaves a vertex out; `VGeoContainerReader.spec` — a version-4 record layout
+   reads through the legacy offsets with the cube synthesised. `VGEO_FORMAT.md` §4, §7, §11 follow.
+2. **Rebuild the container** with the new builder, in the background, while the runtime lands.
+3. **Runtime.** Row layout, page block, kernel (box test, the new counter, the election ahead of the
+   culls), fixture cut. Pins: `VGeoRuntimeTables.spec` — the row carries the page's box;
+   `vgeo_cut_agreement.spec` — §4's rewritten test, descending and coarsening; the compile spec stays
+   at ten storage buffers.
+4. **Tour** on the rebuilt container and on its version-4 form; §5's table filled in; screenshot
+   compared. Done 2026-09-16.
+
+## 8. Review — folded in
+
+One adversarial pass over the draft against the code, fifteen findings, the ones that changed the
+document:
+
+- **The spec's oracle was wrong for the sphere test (finding 1)** and its claim assertion was not
+  implied by the design (2). §4 now tests vertices and the kernel's own predicate on spec-computed
+  bounds.
+- **"One level below" is false (3):** unmerged clusters ride the frontier upward. §3.1 memoises.
+- **The coarsen path was unproven and the tighter bound widens its hole (4).** §3.2 moves the
+  frustum tests below the election and §4's claim now covers walking up.
+- **`self_sphere ∋ vertices` was never a stated invariant (5)** and dropping `bounds_sphere` deleted
+  the only vertex-in-sphere check. §3.1 adds it to §11.7 and the validator.
+- **`payload_offset`/`payload_size` move (6)** and both the writer and the validator are positional.
+  §3.1's table and step 1 say so.
+- **Two tables disagreed (7):** §0's per-level split and §1's totals now use one classification, the
+  §2.1 caption names its samples, and §5 no longer transfers a CPU delta onto the GPU's count.
+- **Four construction sites, not three (8)**, and the version rides the worker's first request with
+  the descriptor. The validator stops after a version defect (10) rather than misreading v4 records
+  positionally. `bounds_sphere` is scoped to the record (11). The slot-words doc is rewritten for 76
+  bytes a cluster (12). A separate counter tells box culls from sphere culls (15).
+
+Confirmed by the pass and left as written: the object-space frustum makes the p-vertex test and the
+version-4 cube conservative under instance scale (14); §2.4's arithmetic (12); `vgeo_read_header`'s
+check admits both versions (9).

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

@@ -435,7 +435,7 @@ the view-dependent half, with the same eviction hooks.
    another site already moved.
 
    **There are not two sites — and that is a defect, not a shape to design around.** The
-   phase-one seam call sits *inside* the `ShadeDrawMode × ShadeDrawSide` loop of
+   phase-one seam call sits *inside* the per-opaque-bucket loop of
    `graph_rasterize_partial_opaque`, so a standard view records one cut per **active opaque bucket**
    plus one for phase two. The engine already says so where rev 2 did not read it —
    `GPUVirtualGeometryRuntime`: "once per bucket per HZB pass per view".
@@ -518,7 +518,26 @@ the view-dependent half, with the same eviction hooks.
    checks instead of asking an asset its version — and `GENERATION`. `slot_range` learned the
    section, or the parent rows would never have been uploaded. Still nothing consumes them.
 
-   **A verification surface went away mid-session, and §7.5 needs it.** The `vgeo_runtime`
+   **A verification surface went away mid-session and came back — steps 1–6 are confirmed in a
+   real browser.** Chrome's regression was worked around on master (`b3919f9c3`, `34c836d4d`:
+   the four indirectly dispatched culls, and then particles and SHARC, off immediates and onto a
+   uniform), and with that in place the `vgeo_runtime` playground draws again. Re-measured
+   against it afterwards:
+
+   - the in-page container, now written at `format_version` 4 with parent tables, builds, loads
+     and draws, and the cut shaders — the coarsen path and the tenth binding included — compile
+     under Tint with no console error;
+   - the deepest converted Zorah container, which is **`format_version` 3 and carries no parent
+     tables at all**, loads and draws under the format-4 reader at every camera tried. That is
+     §2.1's back-compatibility claim tested rather than argued, on 27.9M faces;
+   - §7.1's table reproduces exactly: `descent_steps` 32 takes 5 dispatches and 16 takes 6, both
+     with `QUEUE_REMAINING` 0, while 8 takes all 8 and leaves 12–124 items queued. The default
+     of 24 sits inside the clean band.
+
+   What follows is the note written while it was broken, kept because the diagnosis is what
+   makes the gap in the record legible:
+
+   **A verification surface went away mid-session, and §7.5 needed it.** The `vgeo_runtime`
    playground draws nothing in headless Chrome: `begin_frame` runs, the feedback resource is open,
    the adapter is an NVIDIA Lovelace with subgroups, the container builds and its root page installs
    with a selectable group — and `VGEO_CUT_STAT.PAGES` stays 0, so the seed never reaches its first