@woosh/meep-engine 3.24.0 → 3.25.0

package/src/shade/renderer/geometry/GPUGeometryManager.js

@@ -250,18 +250,32 @@ export class GPUGeometryManager {
         metadata.allocated = false;
         metadata.index = this.__last_geometry_index++;
 
-        const meshlets = geometry.meshlets;
+        if (geometry.isVirtualGeometry === true) {
+            /*
+             A virtual geometry has no meshlets to allocate and no tree to trace. Everything it
+             draws comes from a cut selected per view per frame, out of pages
+             `GPUVirtualGeometryPool` installed into the *shared* meshlet pool — so its clusters are
+             in the same buffers as everything else, and only the route to them differs.
 
-        metadata.meshlets = this.#meshlets.add_batch(meshlets);
+             The row still carries the source's bounds and triangle count, which is what
+             instance-level culling reads and what makes a VG instance an ordinary instance
+             everywhere above this line.
+             */
+            metadata.vg_row = geometry.vg_row;
+        } else {
+            const meshlets = geometry.meshlets;
 
-        // watch for data migration
-        metadata.meshlets.changed.add(() => {
+            metadata.meshlets = this.#meshlets.add_batch(meshlets);
 
-            // TODO need to handle this properly
+            // watch for data migration
+            metadata.meshlets.changed.add(() => {
 
-            console.warn('Meshlet GPU address changed.')
+                // TODO need to handle this properly
 
-        });
+                console.warn('Meshlet GPU address changed.')
+
+            });
+        }
 
         this.#geometries.set(geometry, metadata);
 
@@ -634,8 +648,14 @@ export class GPUGeometryManager {
             index_count: indexCount,
             bounding_sphere: geometry.bounding_sphere,
             bounding_box: geometry.bounding_box,
-            meshlets_address: g_meta.meshlets.metadata.offset,
-            meshlets_count: g_meta.meshlets.meshlet_count,
+            /*
+             Zero and zero for a virtual geometry, and the zero count is load-bearing rather than
+             defensive: `shader_meshes_to_meshlet_counts` reads it and therefore contributes nothing
+             for a VG instance without knowing what one is.
+             */
+            meshlets_address: g_meta.meshlets?.metadata.offset ?? 0,
+            meshlets_count: g_meta.meshlets?.meshlet_count ?? 0,
+            vg_row: g_meta.vg_row,
         }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
 
     }

package/src/shade/renderer/geometry/GPUGeometryMetadata.d.ts

@@ -24,6 +24,16 @@ export class GPUGeometryMetadata {
      * @type {number}
      */
     references: number;
+    /**
+     * Row in `GPUVirtualGeometryPool`'s geometry table, or {@link VGEO_GEOMETRY_ROW_NONE}.
+     *
+     * Set for a {@link VirtualGeometry} and for nothing else. It travels into the GPU row so a pass
+     * handed a list of visible instances can tell a virtual one from a static one — which is the
+     * whole of the seam, on this side of it.
+     *
+     * @type {number}
+     */
+    vg_row: number;
     allocated: boolean;
 }
 export type MeshletGeometry = import("./MeshletGeometry.js").MeshletGeometry;

package/src/shade/renderer/geometry/GPUGeometryMetadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryMetadata.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryMetadata.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;IACI;;OAEG;IACH,UAFU,eAAe,CAEjB;IAER;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;OAEG;IACH,uCAAS;IAET;;;;;;;OAOG;IACH,YAFU,MAAM,CAED;IAEf,mBAAkB;CACrB;8BA/BY,OAAO,sBAAsB,EAAE,eAAe"}
+{"version":3,"file":"GPUGeometryMetadata.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryMetadata.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;IACI;;OAEG;IACH,UAFU,eAAe,CAEjB;IAER;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;OAEG;IACH,uCAAS;IAET;;;;;;;OAOG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;OAQG;IACH,QAFU,MAAM,CAEgB;IAEhC,mBAAkB;CACrB;8BA1CY,OAAO,sBAAsB,EAAE,eAAe"}

package/src/shade/renderer/geometry/GPUGeometryMetadata.js

@@ -1,3 +1,5 @@
+import { VGEO_GEOMETRY_ROW_NONE } from "./virtual/runtime/layout/VGEO_GEOMETRY_ROW_NONE.js";
+
 /**
  * @typedef {import("./MeshletGeometry.js").MeshletGeometry} MeshletGeometry
  */
@@ -29,5 +31,16 @@ export class GPUGeometryMetadata {
      */
     references = 0;
 
+    /**
+     * Row in `GPUVirtualGeometryPool`'s geometry table, or {@link VGEO_GEOMETRY_ROW_NONE}.
+     *
+     * Set for a {@link VirtualGeometry} and for nothing else. It travels into the GPU row so a pass
+     * handed a list of visible instances can tell a virtual one from a static one — which is the
+     * whole of the seam, on this side of it.
+     *
+     * @type {number}
+     */
+    vg_row = VGEO_GEOMETRY_ROW_NONE;
+
     allocated = false;
 }

package/src/shade/renderer/geometry/virtual/VGEO_FORMAT.md

@@ -18,9 +18,16 @@ rather than baked in.
 implements the *mechanics* of §10 — cold start, one fetch per page from the byte range its parent
 wrote down, want dedup, activation, eviction, and the mandatory reject rules of §4 and §5. It
 implements none of the *policy*: no fetch scheduler, no budgets, no touch-LRU, no quarantine, and
-the pinning rules are left to whoever manages residency. It also decodes neither the node table
-(§6.1) nor the child-table traversal metric (§5, §6.2) — `VGeoPage` records `node_count` and stops
-— because nothing consumes them yet; a GPU cut pass is the first thing that would.
+the pinning rules are left to whoever manages residency.
+
+It decodes the **node table** (§6.1) — the GPU cut pass is the consumer that was predicted here and
+it arrived; the node metric's `max_parent_error` is what lets a whole subtree be skipped without
+touching a cluster. It decodes the **child-table traversal metric** (§5, §6.2) as well, because a
+reader that decodes two thirds of a structure is worse than one that decodes all of it — but no
+consumer reads it, and `runtime/RUNTIME_PLAN.md` §4.8 says why: at the moment a want is emitted, the
+per-cluster test the cut has already passed is strictly tighter than any page-level test, so the
+page-level one can never reject anything. Its consumer is prefetch, which is a later campaign.
+
 `shade/playground/vgeo_viewer/` drives the reader end to end, and its `select_cut.js` is a CPU
 reference traversal of the cut rule this format was shaped around.
 
@@ -115,7 +122,7 @@ All u64/u128 fields are naturally 8-byte aligned.
 | 10     | u8        | hash_algo                | 0 = xxHash3; readers MUST reject unknown values |
 | 11     | u8        | reserved                 | |
 | 12     | u32       | feature_flags_required   | readers MUST reject any unknown set bit |
-| 16     | u32       | feature_flags_ignorable  | readers MUST ignore unknown set bits |
+| 16     | u32       | feature_flags_ignorable  | readers MUST ignore unknown set bits; bit 0 = every page is within `nominal_page_size` (§11.14) |
 | 20     | u32       | payload_encoding         | 1 = `SHADE_MESHLET_V1` (§8); readers MUST reject unknown values |
 | 24     | [u8; 16]  | asset_id                 | xxh3-128 of the whole file with every **derived checksum field** zeroed (see below); stored low64 LE at bytes 0–7, high64 LE at bytes 8–15 |
 | 40     | u32       | vertex_attribute_mask    | advisory attribute presence (§8 bit table) |
@@ -127,7 +134,7 @@ All u64/u128 fields are naturally 8-byte aligned.
 | 76     | u32       | root_page_decoded_size   | RAM admission for the always-resident set, known from the header alone |
 | 80     | u64       | directory_offset         | also the exact end of the frame region |
 | 88     | u64       | dir_block_checksums_offset | `ceil(total_pages / 128)` × u64 |
-| 96     | u32       | nominal_page_size        | build parameter, bytes; informational — readers MUST NOT assume (§11.5 exception) |
+| 96     | u32       | nominal_page_size        | bytes a decoded page may come to; a **hard bound** when bit 0 of `feature_flags_ignorable` is set (§11.14), advisory otherwise |
 | 100    | u16       | reserved                 | |
 | 102    | u8        | level_count              | levels `0..level_count-1` |
 | 103    | u8        | reserved                 | |
@@ -492,8 +499,8 @@ about a scene and not about a container.
   always-resident set is small: invariant §11.7 puts exactly one root cluster in the file and the
   assembler gives the root page the complete topmost level, so a measured root page is one cluster —
   1,732 B and 1,472 B on two torus builds, header and level table included coming to about 2.4 KB.
-  A prefix past that is speculation about the *next* band, and at the hundreds-of-KB pages design §5
-  targets it buys one page. `VGeoReadOptions.head_prefix_bytes` therefore defaults to 64 KiB rather
+  A prefix past that is speculation about the *next* band, and at the 64 KiB default page size it
+  buys about one page. `VGeoReadOptions.head_prefix_bytes` therefore defaults to 64 KiB rather
   than the 256 KiB it did, and the reader **releases the prefix** the first time a read falls
   outside it (`VGeoContainerReader.release_head`, and `head_bytes` to see it). Measured, at the old
   default a 256 KiB prefix over a 22 MB container covered 105 of its 4,000 pages and served nothing
@@ -537,12 +544,14 @@ about a scene and not about a container.
   child installs — known at queue time, purely local. Arrivals verify the
   identity-seeded frame checksum; activation makes any arrival order safe beyond that.
   The reader dedups in-flight fetches by page index but pins nothing.
-  Still open, and now for a nameable reason rather than for want of an owner: a `VGeoPageWant`
-  carries the page it names and not the page it was *discovered through*, so neither the reader nor
-  the manager can pin P without the cut telling them which P it was. It is an efficiency item and not
-  a correctness one — evicting P while its child is on the wire wastes the fetch, because the child
-  installs non-selectable and activation is safe at every arrival order — and closing it means adding
-  the source page to the want, which is a change to the cut as much as to the reader.
+  Still open, and the blocker named here is gone. It was that a `VGeoPageWant` carried the page it
+  named and not the page it was *discovered through*, so neither the reader nor the manager could
+  identify P — the format stores parent counts rather than parent references, deliberately, so
+  nothing below the cut can name one. The cut says it: a want record is
+  `(source_page_row, child_ref, child_page_index, priority)` and the source row is P. Nothing pins
+  anything yet, and that is the whole of what remains. It is an efficiency item and not a
+  correctness one — evicting P while its child is on the wire wastes the fetch, because the child
+  installs non-selectable and activation is safe at every arrival order.
 - **Eviction** *(mechanics shipped in the reader, policy shipped above it)*: within each residency tier, a page is
   evictable only while it has no resident child pages in that tier — checked against its own
   child table (`SAME_PAGE` references never pin). Leaves-first order emerges from the rule;
@@ -619,8 +628,12 @@ about a scene and not about a container.
   lives within bands — the within-band spatial curve (§12) is what carries fetch
   locality and must be chosen with that as a criterion. Fetching through small unwanted
   gaps is permitted under an implementation waste threshold.
-- *(shipped)* Never assume `nominal_page_size`; per-page sizes come from child tables
-  (traversal), frames (prefix scan), or the directory (special tasks).
+- *(shipped)* Take a page's *actual* size from child tables (traversal), frames (prefix scan), or
+  the directory (special tasks) — never from `nominal_page_size`, which is an upper bound and not a
+  size. The bound itself may be relied on, and only when bit 0 of `feature_flags_ignorable` is set:
+  then no page exceeds it (§11.14) and a reader may size fixed-stride page slots against it. A
+  reader that depends on that MUST check the bit and refuse a container without it — containers
+  written before the bound existed carry a `nominal_page_size` that pages ran over.
 - *(shipped)* **Nothing a runtime holds may be able to read the whole file.** The whole-file audit
   (§11, every checksum, the directory against a frame scan) and the install-every-page sweep are in
   `format/read/tool/` as `vgeo_audit_container` and `vgeo_install_all_pages`, not on the reader —
@@ -672,8 +685,7 @@ clustering and simplification dominate regardless.
    design §3 grouping is adaptive from ~4). `parent_cluster_count` equals the exact
    number of clusters (across all pages, `SAME_PAGE` included) whose
    `child_ref/child_group` name this group; it is 0 exactly for the root page's
-   topmost-level groups. A page holding one indivisible oversized group MAY exceed
-   `nominal_page_size`; the hard bound is the frame's u32 `stored_size`.
+   topmost-level groups.
 6. `1 ≤ triangle_count ≤ 128`, `3 ≤ vertex_count ≤ 128` (Shade meshlet limits);
    `total_clusters ≥ 1`; `source_vertex_count ≥ 3`, `source_face_count ≥ 1`.
 7. Error/sphere monotonicity per design §4; `self_error = 0` and `child_ref = NO_CHILD`
@@ -709,6 +721,18 @@ clustering and simplification dominate regardless.
 13. `root_page_offset = align16(256 + 32 · level_count)`; the level table's `cluster_count` and
    `group_count` columns sum to `total_clusters` and `total_groups`; every level holds at least
    one cluster and one group; `min_error ≤ max_error`, both finite and ≥ 0.
+14. **Page size is a bound.** When bit 0 of `feature_flags_ignorable` is set, every page's
+   `decoded_size` is ≤ `nominal_page_size`, and `nominal_page_size` is non-zero. The bit is what a
+   reader checks; unset, `nominal_page_size` is the advisory build parameter it used to be and
+   nothing here applies.
+
+   The bound is what makes a page slot a fixed stride in VRAM — a slot address is a multiply, with
+   no allocator, no growth path and no address migration behind it (design §6). It costs the
+   internal fragmentation of each band's last page, measured at about 9% of a page across a
+   254-page build, and it is kept by splitting a band into more pages. What it cannot be kept by is
+   splitting a **group**: §11.1 makes a group atomic to its page. So a build whose clusters group
+   into more bytes than a page holds has no layout, and the builder refuses it naming the page size
+   that would work, rather than writing a page over the size the header states.
 
 ## 12. Open
 
@@ -717,7 +741,11 @@ clustering and simplification dominate regardless.
   the tables) is a per-frame `codec` id away and costs no reader that already handles a
   mixture. The quantized-position `payload_encoding` is the other half of the same
   question, and would take most of what LZ4 currently finds.
-- Default `nominal_page_size` (design §5: order hundreds of KB, measured).
+- ~~Default `nominal_page_size`~~ — 64 KiB, `VGEO_DEFAULT_PAGE_SIZE`: one page size rather than
+  Nanite's two, set between hiding fetch latency and paying for it in response time and in VRAM per
+  resident page on a low-end device, with a floor at the largest group a build produces. Provisional
+  — reopen it on a device measurement, and when quantization lands, since that moves what a cluster
+  costs.
 - Spatial ordering curve within a level band (Morton over group centroids is the
   default candidate; chosen with fetch-coalescing locality as an explicit criterion,
   §10).

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md

@@ -1,19 +1,27 @@
 # Virtual Geometry — Design
 
-Status: **builder, container and reader implemented; the GPU runtime is not**. This document
-pins only what is certain; everything else is listed explicitly under *Open*. Runtime home is
-this directory (`shade/renderer/geometry/virtual/`, mirroring `texture/virtual/`); builder
-lives with `core/geom/3d/topology/struct/binary/` and `core/graph/metis/`.
+Status: **builder, container, reader and GPU runtime implemented; the runtime is under review and
+not shippable** — see [runtime/REVIEW_LEDGER.md](./runtime/REVIEW_LEDGER.md), which found seven
+critical defects including one that breaks §4's no-double-draw guarantee on the ordinary streaming
+path. §10's M1 is written below as closed; treat it as *built and not yet trustworthy*. This document pins only what
+is certain; everything else is listed explicitly under *Open*. Runtime home is this directory
+(`shade/renderer/geometry/virtual/`, mirroring `texture/virtual/`); builder lives with
+`core/geom/3d/topology/struct/binary/` and `core/graph/metis/`.
 
 What exists, in the order a newcomer meets it: `build/` turns a `Geometry` into a cluster DAG,
 `format/` writes and validates the `.vgeo` container ([VGEO_FORMAT.md](./VGEO_FORMAT.md)),
-`format/read/` reads one back a page at a time with residency and activation, and
-`shade/playground/vgeo_viewer/` puts a clamped CPU cut of a *streaming* container on screen.
-What does not exist is everything §7 describes: the selection buffer, the compute cut pass, the
-VRAM page pool, and the seam through which VG instances enter the meshlet pipeline. The
-playground draws through Shade's direct geometry path instead, which is exactly why it proves
-the DAG and not the pipeline. §10 says which milestone that leaves us in, and the order the work
-actually arrived in.
+`format/read/` reads one back a page at a time with residency and activation, `residency/` owns the
+RAM tier's budget, and `runtime/` is everything §7 describes — the selection buffer, the compute cut
+pass, the VRAM page pool, the feedback loop, and the seam through which VG instances enter the
+meshlet pipeline ([runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md)).
+
+Two playgrounds prove two different things and it is worth not confusing them.
+`shade/playground/vgeo_viewer/` puts a clamped **CPU** cut of a streaming container on screen
+through Shade's direct geometry path — it proves the DAG, the format and the clamp, and by
+construction it proves nothing about the engine. `shade/playground/vgeo_runtime/` puts an ordinary
+`Mesh` in an ordinary `Scene` and draws it entirely from a **GPU** cut through the meshlet
+pipeline — it proves the seam and nothing about the DAG. §10 says which milestone that leaves us
+in, and the order the work actually arrived in.
 
 ## 1. What and why
 
@@ -317,7 +325,10 @@ Pinned:
   fill in M2, never from these nominals.
 - **Immutable and content-addressed** (`hash(output bytes)` in header and filename):
   perfect HTTP caching, CDN-friendly, no invalidation protocol.
-- **Fetch unit = size-bounded page** (order hundreds of KB; measured in M2), fetched by
+- **Fetch unit = size-bounded page** (64 KiB, `VGEO_DEFAULT_PAGE_SIZE` — **one** page size, against
+  Nanite's two, traded off between hiding fetch latency and both response time and VRAM per
+  resident page on a low-end device; this section's "order hundreds of KB" was a first-principles
+  guess and is superseded, see the constant's own note), fetched by
   HTTP **single-range** requests and **independently decodable**: a group never spans
   pages; a page carries whole groups with payloads in (near-)upload-ready encoded form.
 - **Pages carry the DAG, fetchably**: each cluster record stores its two (sphere, error)
@@ -348,7 +359,7 @@ Pinned:
 - **Coarse-first layout**: pages ordered so a plain prefix read of the file yields a
   complete coarse asset — progressive load without a feedback loop.
 
-Open: page size; a denser page codec than LZ4, if quantization leaves one worth having;
+Open: a denser page codec than LZ4, if quantization leaves one worth having;
 per-attribute quantization widths (cluster-local grids); relationship to
 `MeshletGeometrySerializationAdapter` (extend vs parallel).
 
@@ -376,6 +387,13 @@ Pinned:
   intent is **fixed-size page-slot allocation** (no compaction, no CPU metadata mirror,
   no transient 2× rebuild), plus propagation of address migration to every consumer —
   the existing `GPUGeometryManager` TODO becomes load-bearing under churn.
+
+  What that rests on is the container, and it now holds: FORMAT §11.14 makes
+  `nominal_page_size` a bound no page exceeds, announced by a feature bit a pool can require.
+  Before that it was an advisory number the builder itself broke — 13 of 40 pages over it on a
+  measured build — and a fixed stride sized against it would have been a slot overrun. A pool
+  taking the guarantee is entitled to one slot size and nothing else: it refuses a container
+  built at a different page size rather than carrying a size-class table for it.
 - **Activation invariant (closure without dependency metadata)**: a group is
   *selectable* iff **all** of its parent-cluster references are live — each referencing
   cluster's page installed and that cluster's own group selectable (per-group reference
@@ -565,6 +583,14 @@ canonicalizing them is a preprocessor's job).
   and the reports behind it. `cone_reserved` stays a zeroed reserved field (format §7). This is
   the one entry here that is not a "v1" qualifier.
 - Skinned / morphing / WPO meshes through the VG path (static geometry only).
+- **Non-opaque VG instances.** The cut runs beside the mesh→meshlet expansion of the *opaque*
+  rasterization paths, and the transparent and alpha-tested bucket path
+  (`prepare_meshlet_draw_commands_by_material`) has no seam: it is handed a scene and an optional
+  camera resource rather than a view context, where a cut needs the camera's uniform buffer to put
+  each instance into object space. A VG instance with a non-opaque material therefore expands to
+  zero meshlets and draws nothing at all. `GPUSceneRows.attach_mesh` says so out loud when one is
+  attached, because this bullet is the authority for it and did not exist while the code was citing
+  it.
 - Compute/software rasterization — WebGPU lacks portable 64-bit atomics; the hardware
   raster path through the existing pipeline is the only raster path. Deferred G-buffer
   shading already bounds the overshading cost of small triangles.
@@ -597,13 +623,31 @@ is the piece still missing, and M1 is where the work now starts.
   which was M2's job; τ-sweep watertightness as a spec (`build/vgeo_cut.spec.js` counts edges
   used by one triangle instead of two, at a spread of thresholds, and wants zero); the
   group-boundary polyline guarantee, enforced by the builder rather than merely validated.
-  **Not done**: the expansion seam — the playground draws through Shade's direct geometry path
-  (a `DynamicMesh` from raw attributes, no meshlet encode), so nothing has yet entered the
-  meshlet pipeline through a VG-shaped door. Flip validation is not done either (§2, extension
-  3).
-- **M1 — GPU cut**: selection buffer + compute cut pass; wants/touches readback wired
-  (still fully resident). Acceptance: parity with M0, selection cost measured
-  (flat-vs-hierarchy decision data).
+  **Done since**: the expansion seam. `runtime/graph_vgeo_expand_instances_to_meshlets` runs beside
+  `graph_expand_meshes_to_meshlets` at each of the three opaque call sites and appends into the same
+  collection, so a VG instance enters through a VG-shaped door and everything past the expansion is
+  untouched. `shade/playground/vgeo_runtime/` is that, on screen.
+  **Still not done**: flip validation (§2, extension 3).
+- **M1 — GPU cut** — **done**: selection buffer + compute cut pass; wants/touches readback wired.
+  `runtime/` holds all of it and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) is its design.
+  Acceptance was parity with M0 and selection cost measured, and both were taken:
+
+  *Parity* is `runtime/cut/vgeo_cut_agreement.spec.js` — the kernels run under the WGSL emulator
+  against a real container and their drawn cluster **multiset** is held to exactly what
+  `vgeo_select_cut` selects, over seven cameras and four thresholds, fully resident and with pages
+  withheld, one instance and two. Multiset rather than set because a duplicate is the failure that
+  reads as corrupt geometry rather than as a missing page.
+
+  *Measured*, on an nvidia/lovelace adapter, a 13-page torus opened holding only its root page and
+  streamed entirely by the cut's own wants: 50 drawn clusters at τ=0.5 down to 8 at τ=16, monotone,
+  visiting 9 pages down to 5, clamping to zero as pages arrive, dropping nothing. Half the frames
+  skip feedback entirely under a two-deep readback cap, which is the virtual-texture contract and
+  costs streaming latency rather than pixels.
+
+  The flat-vs-hierarchy decision data is *not* what M1 produced, and §7 already says why: §4 pinned
+  the traversal and the question stopped being a measurement to take. What the cut measures instead
+  is that the hierarchy's own accelerator is sound — the node metric's `max_parent_error` cull fires
+  across the whole agreement sweep and changes not one selected cluster.
 - **M2 — format + streaming** — *the RAM tier landed early*: `.vgeo` container, pager,
   residency tiers with the §6 invariants (page-slot pool, address-migration propagation,
   occlusion-aware wants, touch-LRU, in-flight pinning), budgets, eviction. Position
@@ -613,8 +657,12 @@ is the piece still missing, and M1 is where the work now starts.
   **Done ahead of M1**: the container and its validator; the RAM-tier pager with residency,
   activation and eviction (`format/read/`); TTFP, which is header + level table + root page and
   measured to hold on a 27M-triangle asset; the page codec, chosen on measurement (§5).
-  **Still M2's**: the VRAM page-slot pool, address-migration propagation, occlusion-aware
-  wants, touch-LRU, in-flight pinning, budgets, and position quantization.
+  **Done with M1**: the VRAM page pool (`runtime/GPUVirtualGeometryPool`) with a byte budget and
+  touch-LRU under a protect window, and the want record now naming the page it was discovered
+  *through* — which is what in-flight pinning was blocked on, since the format stores parent counts
+  rather than parent references and nothing below the cut could name that page.
+  **Still M2's**: address-migration propagation, occlusion-aware wants, the in-flight pin itself,
+  and position quantization.
 - **M3 — hardening**: prefetch, disk page store decision, budget defaults, low-limit
   adapters (τ fallback), stress on CAD-class input; browser builder-harness proof
   (build a mid-size asset in-tab).

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_PLAN.md

@@ -6,10 +6,11 @@ This file holds what is *next*, and — more usefully — the reasoning and the
 ideas that are accepted but not yet scheduled, so that picking one up does not mean
 rediscovering it.
 
-Current scope is **the GPU runtime**. The builder, the container and an incremental reader are
-built — design §10 says which milestone that leaves us in and in what order the work arrived —
-so §3 no longer waits on "a runtime" as a whole. Each item there now names what is actually
-blocking it.
+The GPU runtime is **built** — `runtime/`, and
+[runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) is its design and its adversarial review. The
+cut runs on the device, the VRAM tier holds pages under a budget, wants and touches come back
+through a readback, and a VG instance enters the meshlet pipeline through a door of its own. §3's
+items are no longer blocked on "a runtime"; each names what it is actually waiting for now.
 
 Items carry their provenance. `[M §x]` is a section of
 [MICRON_COMPARISON_2026_08_20.md](./MICRON_COMPARISON_2026_08_20.md), the review of the
@@ -78,11 +79,43 @@ accepted-and-waiting one.
   meshlet pipeline — so it proves the DAG and the format, and proves nothing about the engine
   seam.
 
+- **The GPU runtime** — `runtime/`, and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) for the
+  design and the adversarial review that reshaped it. The cut is a wavefront BFS over the page DAG
+  with a per-cluster predicate at the leaves, and that combination is the whole design: the
+  hierarchy decides which clusters to *look at*, the predicate decides whether to *draw* them, and
+  because the predicate is a pure function of one row, a page visited twice costs a duplicate record
+  rather than a wrong answer — so dedup is one bit per (instance, resident page) and never per
+  cluster, which is the number design §4 is trying not to pay.
+
+  Three things the review found, in descending order of how much they cost to rediscover:
+
+  - **Design §4's per-cluster rule double-draws as written.** A group that is resident but not
+    selectable has clusters satisfying it while their coarse stand-in is drawn over the same
+    surface. The rule needs an *own group selectable* term that a traversal gets for free and an
+    evaluator does not. §6 states the fact without stating it as a term of the rule, because §4 was
+    written for a traversal.
+  - **Page size decides whether that state is even reachable.** At the 8 KB pages
+    `select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
+    a blocked page, no page is ever mixed, and no page is ever entered twice. Measured: 40 pages
+    withheld one at a time and 60 random residency subsets produced *no* mixed page. At 64 KB the
+    median page holds eight groups and it is ordinary. A spec for anything about mixed selectability
+    has to be written at a page size that produces it.
+  - **Every bound degrades in one direction.** A full meshlet collection drops records; a claim
+    allocation that does not fit drops the *instance*, because an instance run unclaimed draws its
+    whole cut once per parent page that reaches it.
+
+  Held against mutation: removing the own-group term, the claim, the child selectability check or
+  the parent projection each turns the agreement suite red. Proved on a device in
+  `playground/vgeo_runtime/` — a 13-page container opened holding only its root page, streamed to 9
+  by its own wants, 50 drawn clusters at τ=0.5 falling monotonically to 8 at τ=16, clamping to zero,
+  dropping nothing.
+
 ## 2. Next
 
 §2.1 and §2.2 both landed. They are kept because their notes are the reasoning behind decisions
-that are now only visible in code, and rediscovering them is the expensive part. **§2.3 is the
-open one**, and it is the one to read if you are about to start on the cut pass.
+that are now only visible in code, and rediscovering them is the expensive part. §2.3 **half**
+closed, and the half that did not is the more interesting one — read it before building a
+prefetch.
 
 ### 2.1 A partitioning fallback for when METIS fails `[M §3.3]`, `[V §3.2]` — LANDED
 
@@ -204,7 +237,7 @@ instance count first and from fan-out immediately after — measured out-degree
 the middle bands of the 98k sphere. It bites only for a single instance in close-up, and only
 for the first few bands, which are also the cheapest to walk.
 
-### 2.3 Nothing reads the traversal metric or the node tree
+### 2.3 The node tree has a reader; the child-table metric still does not — LANDED (half)
 
 §2.2 built both, and the format specifies both: every child-table entry carries the child page's
 LOD-metric sphere and error range (VGEO_FORMAT §5, §6.2), and every page carries a fanout-4 tree
@@ -231,13 +264,36 @@ What it buys when the pass arrives, and what to hold it to:
 Neither is measurable until there is a GPU traversal to measure, which is the honest reason it
 has waited.
 
-## 3. Waiting on a GPU runtime
+**What happened when the traversal arrived**, and it is not what this section predicted.
+
+*Below the page*, the node tree has its reader. `runtime/cut/shader_vgeo_cut_traverse` descends it,
+tests each node's sphere and `max_parent_error`, and discards a region rather than a cluster. The
+cull fires across the whole agreement sweep and changes not one selected cluster, which is what
+sound means for an accelerator. The 0.3%–1.6% of asset size is earning something now.
+
+*Before the fetch*, the child-table metric **still has no reader, and now for a reason rather than
+for want of a consumer.** Held against the cut, it buys nothing. A want is emitted from a cluster
+that has already passed `project(parent) > τ` and `project(self) > τ`; the child page's metric
+covers that cluster's child group among others, so its `max_parent_error` is at least that group's
+`parent_error` and its sphere contains that group's `parent_sphere` — and the projection is monotone
+in both. The page-level test is therefore **always** above τ at exactly the moment the question is
+asked. It cannot reject what a per-cluster test has just accepted, because the per-cluster test is
+strictly tighter. The frustum half dies the same way: the cluster's own `self_sphere` is a tighter
+test than the child page's union sphere, available locally, for free.
+
+Where the copy *is* load-bearing is **prefetch** — ranking and bounding pages nobody has asked for
+yet, which by definition has no cluster-level evidence to be tighter than. `min_self_error` is in
+the same position: it ranks a want and the cut never asks it anything. So the field is not dead, it
+is early, and the thing it is early for is §3's territory rather than the cut's. Anyone building a
+prefetch should start here.
 
-Accepted, documented here so the reasoning is not lost. "Waiting on a runtime" used to mean
-waiting on all of it; a CPU traversal and a RAM-tier pager now exist (§1), so what each item is
-actually blocked on is named individually.
+## 3. Was waiting on a GPU runtime
 
-### 3.1 Object-space refinement `[M §2.7]`
+Accepted, documented here so the reasoning is not lost. "Waiting on a runtime" used to mean waiting
+on all of it; the runtime exists now (`runtime/`), so §3.1 has landed with it and the rest name what
+they are actually waiting for.
+
+### 3.1 Object-space refinement `[M §2.7]` — LANDED
 
 `RefinementSpec.build` in `Micron/render/refinement/RefinementSpec.js`: multiply the camera's
 view-projection by the instance transform once, derive the frustum planes from the result,
@@ -245,10 +301,17 @@ and run every cull and error test in **object space** against untransformed clus
 One matrix multiply per instance instead of transforming every cluster's bounds to world
 space. With thousands of instances sharing one geometry that difference is the entire cost.
 
-**Blocked on**: instances. The CPU traversal already tests in object space — but only because
-the viewer draws one geometry at identity and never had to decide, so the rule is written the
-right way round and the multiply that makes it pay has never been exercised. This becomes real
-work at the same moment the cut pass does.
+**Landed** with the cut. `runtime/cut/shader_vgeo_cut_collect` is the one place a VG transform is
+touched: it multiplies the camera's view-projection by the instance transform, extracts the frustum
+from the result, inverts the transform once for the eye, and writes both into the instance record.
+Every cull and error test downstream runs against untransformed cluster bounds.
+
+One thing fell out that `RefinementSpec.build` never had to face, because object space is not free
+when an instance is scaled: error and distance are **both** object-space, so a *uniform* scale
+cancels out of `r_e · k / d` exactly and needs no term at all. A non-uniform one does not, and the
+correction is the ratio of the largest axis scale to the smallest — conservative, so it over-refines
+rather than under-refines, and exactly 1 for every instance that is not stretched. Worth knowing
+before anyone adds a scale term that does nothing in the common case.
 
 ### 3.2 Proxy geometry from a DAG cut `[M §2.6]`
 
@@ -282,6 +345,16 @@ choice belongs to the view, not to the geometry.
 
 ### 3.4 GPU-driven allocation `[V §4.3]`
 
+**Narrower now, and the runtime says exactly how much.** A VG page is one arena allocation holding
+its node, group and cluster rows back to back, and an eviction frees one allocation and writes one
+lookup word. Nothing inside a resident page can move, growth appends through `OffsetAllocator#grow`
+and relocates nothing, and no address migrates. What VG's churn *does* still reach is
+`GPUMeshletManager`: a page install is an `add_batch` and an eviction a `remove_batch`, so the holes
+accumulate in that pool and closing them is still a CPU-side rebuild with the unhandled
+address-migration TODO downstream of it. Pages are near-uniform in size, so a hole is usually
+re-usable by the next install — which narrows the problem without closing it, and is the reason this
+is still an item rather than an incident.
+
 Worth pursuing **beyond virtual geometry** — this is a GPU-driven engine and CPU-side
 allocation for GPU-resident data is a standing mismatch.
 
@@ -384,9 +457,14 @@ attacked:
   `MICRON_PATCH_SIZE_MAX × 3` vertices with occupancy in a BitSet: no allocator, no
   fragmentation, no address migration, at the cost of internal fragmentation proportional to
   `1 − fill`. **Declined: pages already are the compaction mechanism.** A page is fixed-size
-  by construction and carries whole groups; the lever to pull is page waste, by keeping
-  clusters full — which §1's cluster-count target and repack are for — not by giving up
-  variable-size allocation.
+  and carries whole groups; the lever to pull is page waste, by keeping clusters full — which
+  §1's cluster-count target and repack are for — not by giving up variable-size allocation.
+
+  *(2026-09-12: "by construction" was the original wording and it was not true — the builder
+  overran `nominal_page_size` whenever a group did not fit, and the format told readers not to
+  assume the number at all. It is true now, by enforcement rather than by construction:
+  FORMAT §11.14, the builder refusing a page size no group fits, and the validator behind it.
+  The conclusion this bullet reaches is unchanged; the premise had to be made real first.)*
 - **Shape-aware greedy leaf clustering** `[M §2.8]`. Micron grows leaf patches with a heap
   scored on perimeter change, added-neighbour count, and "open face freedom" — how many of a
   candidate face's neighbours are about to be stranded

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts

@@ -48,8 +48,18 @@ export class VGeoBuildOptions {
      */
     weld_ratio: number;
     /**
-     * Target decoded bytes per page. Informational in the file; the format forbids readers from
-     * assuming it.
+     * Decoded bytes per page, as a **hard cap**: no page of the asset exceeds it, and the container
+     * says so with a feature bit a runtime can require (`VGEO_FORMAT.md` §11.14). That is what makes
+     * a page slot a fixed stride on the device — a slot address is a multiply, with no allocator, no
+     * growth path and no address migration behind it.
+     *
+     * The cap is kept by splitting bands into more pages, which costs only the internal
+     * fragmentation of the last page of each band — measured at about 9% on a 254-page build. The
+     * one thing it cannot do is split a group: `VGEO_FORMAT.md` §11.1 makes a group atomic to its
+     * page and the whole activation invariant rests on that. So a build whose clusters group into
+     * more bytes than a page holds **throws**, naming the page size that would work, and the remedy
+     * is that page size rather than anything about the mesh.
+     *
      * @type {number}
      */
     nominal_page_size: number;

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,mBAFU,MAAM,CAEe;IAE/B;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCAhEgC,uBAAuB"}
+{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA1EgC,uBAAuB"}

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js

@@ -1,4 +1,5 @@
 import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
+import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
 import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
 
 /**
@@ -53,11 +54,21 @@ export class VGeoBuildOptions {
     weld_ratio = 1e-5;
 
     /**
-     * Target decoded bytes per page. Informational in the file; the format forbids readers from
-     * assuming it.
+     * Decoded bytes per page, as a **hard cap**: no page of the asset exceeds it, and the container
+     * says so with a feature bit a runtime can require (`VGEO_FORMAT.md` §11.14). That is what makes
+     * a page slot a fixed stride on the device — a slot address is a multiply, with no allocator, no
+     * growth path and no address migration behind it.
+     *
+     * The cap is kept by splitting bands into more pages, which costs only the internal
+     * fragmentation of the last page of each band — measured at about 9% on a 254-page build. The
+     * one thing it cannot do is split a group: `VGEO_FORMAT.md` §11.1 makes a group atomic to its
+     * page and the whole activation invariant rests on that. So a build whose clusters group into
+     * more bytes than a page holds **throws**, naming the page size that would work, and the remedy
+     * is that page size rather than anything about the mesh.
+     *
      * @type {number}
      */
-    nominal_page_size = 256 * 1024;
+    nominal_page_size = VGEO_DEFAULT_PAGE_SIZE;
 
     /**
      * @type {VGeoLevelOptions}