@woosh/meep-engine 3.28.0 → 3.30.0

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/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":"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"}
+{"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;IA6CD;;;;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;kCAl2CY,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

@@ -645,7 +645,20 @@ export class VGeoResidency {
                 this.#vram_last_used[row] = 0;
             }
 
-            if (tag === TAG_VRAM || tag === TAG_RAM) {
+            /**
+             * TAG_PENDING too. `#fetch` reserves the slot and charges its bytes before the read goes
+             * out, and a fetching page is TAG_PENDING — so leaving it out here meant the slot and
+             * its reserved bytes were never given back: both settle handlers return on
+             * `#geometries.get(reader) !== geometry` before they would free it, and `unregister`
+             * drops the geometry synchronously right after cancelling, so that is the branch that
+             * always runs. A scene that swaps assets leaked a slot per fetch on the wire until
+             * `#make_ram_room` refused everything, while `ram_resident_bytes` and `ram_page_count`
+             * both went on reporting the tier as empty.
+             *
+             * `#free_ram_slot` is a no-op for NO_SLOT and for a slot already given back, so the
+             * quarantined half of TAG_PENDING costs nothing here.
+             */
+            if (tag === TAG_VRAM || tag === TAG_RAM || tag === TAG_PENDING) {
                 this.#free_ram_slot(geometry.slot[page_index]);
             }
 

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":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CA+EQ;0BAjGD,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"}

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

@@ -95,4 +95,38 @@ fn vg_sphere_outside_frustum(instance_base: u32, sphere: vec4<f32>) -> bool {
 
     return false;
 }
+
+/**
+ * Whether a box is entirely outside the instance's object-space frustum.
+ *
+ * The same five planes, and one corner per plane rather than eight: the corner furthest along the
+ * plane's normal is the last of the box to leave the half-space, so if *it* is behind the plane the
+ * whole box is. Picking it per axis by the normal's sign is three selects and no branch.
+ *
+ * Unlike the sphere test this one does not care whether the planes are normalized — it compares a
+ * signed distance against zero rather than against a radius — which matters because the planes are
+ * the instance's own, pulled into object space through a transform that may not be a rotation.
+ *
+ * It is conservative in the direction that costs a visit rather than a hole: a box that lies past a
+ * frustum edge without crossing any single plane's half-space passes, and is descended into.
+ */
+fn vg_box_outside_frustum(instance_base: u32, lower: vec3<f32>, upper: vec3<f32>) -> bool {
+    for (var plane = 0u; plane < 5u; plane = plane + 1u) {
+        let word = instance_base + ${VGEO_INSTANCE_OFFSET.FRUSTUM}u + plane * 4u;
+
+        let normal = vec3<f32>(
+            bitcast<f32>(instances[word]),
+            bitcast<f32>(instances[word + 1u]),
+            bitcast<f32>(instances[word + 2u])
+        );
+
+        let far_corner = select(lower, upper, normal >= vec3<f32>(0.0));
+
+        if (dot(normal, far_corner) + bitcast<f32>(instances[word + 3u]) < 0.0) {
+            return true;
+        }
+    }
+
+    return false;
+}
 `, [chunk_vgeo_cut_arena]);

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

@@ -1 +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"}
+{"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,CA0FZ;0BAnHmB,0CAA0C"}

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

@@ -95,4 +95,22 @@ fn vg_sphere_at(word: u32) -> vec4<f32> {
         bitcast<f32>(vg_arena[word + 3u])
     );
 }
+
+/**
+ * Six consecutive words as an axis-aligned box: the lower corner, then the upper.
+ */
+fn vg_box_at(word: u32) -> array<vec3<f32>, 2> {
+    return array<vec3<f32>, 2>(
+        vec3<f32>(
+            bitcast<f32>(vg_arena[word]),
+            bitcast<f32>(vg_arena[word + 1u]),
+            bitcast<f32>(vg_arena[word + 2u])
+        ),
+        vec3<f32>(
+            bitcast<f32>(vg_arena[word + 3u]),
+            bitcast<f32>(vg_arena[word + 4u]),
+            bitcast<f32>(vg_arena[word + 5u])
+        )
+    );
+}
 `, []);

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AAu2BA,qDAIG;8BAx2B2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AAm4BA,qDAIG;8BAp4B2B,qCAAqC"}

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

@@ -123,8 +123,14 @@ import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
  *   induction its page is visited. `P` fails `project(self) <= tau`, so it either enqueues `C`'s
  *   page or clamps, and it clamps only when `C`'s group is not selectable, in which case `C` must
  *   not be drawn. Neither cull intervenes: a node's sphere contains `P.parent_sphere` and its
- *   `max_parent_error` is at least `P.parent_error`, so the LOD cull cannot fire, and the frustum
- *   cull fires only where `C` is off-screen anyway.
+ *   `max_parent_error` is at least `P.parent_error`, so the LOD cull cannot fire, and both frustum
+ *   culls are on bounds of `P`'s whole subtree, which contains `C` — so they fire only where `C`
+ *   is off-screen anyway.
+ *
+ * Note that the per-cluster frustum tests do **not** have to agree across a group's several
+ * parents, and nothing here asks them to. A group is claimed and descended once, by whichever
+ * parent reaches it first; a parent that culls itself out simply is not that one. What each test
+ * promises is about its own subtree and nothing else.
  *
  * Descent crosses a page boundary by producing the child page's **node 0**: uniform items, one
  * kernel, no special case for "entering a page". `SAME_PAGE` needs no special case either, because
@@ -472,23 +478,6 @@ fn vg_visit_cluster(
 
     vg_stat(${VGEO_CUT_STAT.CLUSTERS_TESTED}u, 1u);
 
-    /*
-     Before the cluster can refine, and the reason is residency rather than the draw: refining
-     claims the child page, and a claim is a touch — the LRU's whole input — so an off-screen
-     cluster that refined anyway would keep pages nobody can see hot and the tier full of them.
-     self_sphere contains the cluster's own vertices (FORMAT §7), so this rejects nothing on
-     screen; and every parent of a group shares one self_sphere, so a group's parents decide this
-     uniformly and the cut's proofs stand (RUNTIME_PLAN §4.4).
-     */
-    if ((params.flags & ${VGEO_CUT_FLAG_CULL}u) != 0u
-        && vg_sphere_outside_frustum(
-            instance_base, vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u)
-        )) {
-        vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER}u, 1u);
-
-        return vg_expand_none();
-    }
-
     let parent_projected = vg_project(
         vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_ERROR}u),
         vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_SPHERE}u),
@@ -525,6 +514,45 @@ fn vg_visit_cluster(
         );
     }
 
+    /*
+     The frustum, on two bounds of this cluster's whole subtree, and **below the election above**.
+
+     Why here and not at the top of the function. The reason to cull is residency rather than the
+     draw: refining claims the child page, and a claim is a touch — the LRU's whole input — so an
+     off-screen cluster that refined anyway would keep pages nobody can see hot and the tier full of
+     them. A cluster that took the branch above is below the cut: it refines into nothing, claims
+     nothing and draws nothing, so culling it buys residency exactly nothing, while skipping its
+     election costs a coarsen its walk up. The parent that election reaches can protrude on screen
+     past everything under it — that is what a coarser surface covering the same region looks like —
+     and with the test above the election it was never reached, so it was neither drawn nor stood in
+     for. A hole, and the tighter the bound the more often.
+
+     Why two bounds. Both contain every vertex reachable below this cluster, which is what makes
+     either safe to cull a subtree on: self_sphere by the builder's construction and FORMAT §11.7,
+     CULL_BOX by §11.17. The box is much the tighter of the two on real geometry — a subtree is a
+     patch of surface and its box is thin where a sphere is round — and the sphere stays because a
+     container written before the box existed has its cube there instead, and a cube culls less than
+     the sphere inside it.
+    */
+    if ((params.flags & ${VGEO_CUT_FLAG_CULL}u) != 0u) {
+        if (vg_sphere_outside_frustum(
+            instance_base, vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u)
+        )) {
+            vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER}u, 1u);
+
+            return vg_expand_none();
+        }
+
+        let cull_box = vg_box_at(row + ${VGEO_CLUSTER_ROW_OFFSET.CULL_BOX}u);
+
+        if (vg_box_outside_frustum(instance_base, cull_box[0], cull_box[1])) {
+            vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER}u, 1u);
+            vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER_BOX}u, 1u);
+
+            return vg_expand_none();
+        }
+    }
+
     let self_projected = vg_project(
         vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_ERROR}u),
         vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u),

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_OFFSET.d.ts

@@ -6,5 +6,6 @@ export namespace VGEO_CLUSTER_ROW_OFFSET {
     let CHILD_PAGE_INDEX: number;
     let CHILD_GROUP: number;
     let CHILD_REF: number;
+    let CULL_BOX: number;
 }
 //# sourceMappingURL=VGEO_CLUSTER_ROW_OFFSET.d.ts.map