@woosh/meep-engine 3.60.4 → 3.60.5

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

@@ -1,913 +0,0 @@
-# `.vgeo` — Virtual Geometry Container Format
-
-Status: **writer, validator and reader implemented; no GPU runtime.** Companion to
-[VIRTUAL_GEOMETRY_DESIGN.md](./VIRTUAL_GEOMETRY_DESIGN.md); every requirement pinned in
-its §5/§6 is realized here as a concrete field or invariant. Pinned structure below;
-open details are listed at the end. One `.vgeo` file = one unique geometry's complete
-cluster DAG; instances share the file.
-
-The implementation lives beside this document: `format/` is the container — what a file is,
-how one is written, and `vgeo_validate_container.js`, which audits every §11 invariant in
-one; `format/read/` reads one a page at a time; and `build/` is the pipeline that produces
-it from a `Geometry`, glTF front end included. The node command line over the writer and the
-validator is at `meep-engine/tools/geometry/virtual/`. One glTF yields **one file per
-primitive**, in object space, with the scene's placements written to a sidecar manifest
-rather than baked in.
-
-**Where the reader stops**, because it is the first thing a runtime needs to know. `format/read/`
-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 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_runtime/` and `shade/playground/vgeo_scene/` drive the reader end to end
-against a device, and `runtime/cut/__fixtures__/vgeo_select_cut.js` is a CPU reference traversal of the
-cut rule this format was shaped around — the oracle the GPU cut is held to, and the only traversal
-of it that is not a kernel.
-
-## 1. Design constraints (inherited, binding)
-
-- **Geometry only.** `.vgeo` carries geometry and its vertex attributes — nothing else.
-  Materials are orthogonal, engine-side concerns; a multi-material source splits into
-  one geometry per material before it reaches the DAG builder — for glTF that split is
-  free, since a primitive already carries exactly one material, and the converter's
-  front-end emits one file per primitive. The format has no material fields.
-- Billions of source triangles per asset: 64-bit file offsets, 32-bit page indices.
-- Immutable, content-addressed; perfect HTTP/CDN caching; fetched by single-range
-  requests.
-- Fetch unit = size-bounded **page**, independently decodable; a group never spans pages.
-- No separate global hierarchy: cluster metadata travels **in** pages, so the hierarchy
-  streams with the geometry it describes.
-- **Traversal-first**: a page carries everything needed to fetch the pages it refines
-  into. Standard runtime operation is header → root page → page-to-page traversal; the
-  directory is auxiliary (tooling, validation, arbitrary-page access), never a hot-path
-  dependency.
-- Time-to-first-pixel = header + root page, O(1) in asset size.
-- Prefix-readable: a plain byte-prefix of the file is a complete coarse asset.
-- Per-page compression inside the container only; transparent HTTP compression is
-  assumed absent (it does not compose with range requests).
-- The page DAG is acyclic by construction: child references point strictly forward in
-  the file.
-
-## 2. Conventions
-
-- Little-endian throughout. Types: `u8 u16 u32 u64 f32`; `[T; N]` = N-element array.
-- All file offsets are absolute byte offsets from file start. All in-page offsets are
-  byte offsets from the start of the **decoded** page.
-- **Frames** (stored pages) start at 16-byte-aligned file offsets; `directory_offset`
-  is 16-aligned; alignment padding is real bytes in the file. Inside a decoded page,
-  all tables and payload sections are 4-byte aligned (Shade's pools are u32-word
-  addressed).
-- Levels are numbered `0 = leaves`, increasing toward the root. "Coarser" = higher
-  level. A page's **band** is a contiguous level range `min_level..max_level`.
-  A level is a **group** ordinal, not a per-cluster depth: it says which band a group
-  sits in, and a group's clusters may sit at several different depths in the DAG,
-  because a cluster the builder had no use for is carried forward untouched rather than
-  coarsened for the sake of symmetry. Cluster records carry no level, and nothing needs
-  one. What the ordinal guarantees is the property file order depends on: **every group
-  is in a strictly lower band than the group holding its parents**, so pages laid out by
-  descending band make every child reference point forward.
-- Sentinels for cluster `child_ref`: `NO_CHILD = 0xFFFF` (leaves),
-  `SAME_PAGE = 0xFFFE` (child group lives in this page — legal only in multi-level
-  pages, the root page included); valid child-table indices are `≤ 0xFFFD`. Cluster
-  `child_group`: `NO_GROUP = 0xFFFF`, exactly for leaves. All `f32` fields are NaN-free.
-  Error values are finite `≥ 0`, except the root's parent error which is `+∞` (f32
-  infinity).
-- Reserved fields: writers MUST write 0; readers MUST ignore their contents.
-- Hashing is xxHash3; a `hash_algo` id is reserved for future change. **Integrity
-  model**: identity-seeded per-frame checksums are the *operative client-side*
-  mechanism — and because all DAG edges (child tables, cluster records) live inside
-  frames, the traversal path is covered by them end to end; the header and the
-  directory carry their own checksums; `asset_id` is whole-file and
-  *publisher/pipeline/cache-side* — a range-fetching client never reads the whole file
-  and can never verify it. None of these are a security boundary — they defend against
-  truncation, corruption, version skew, and cache mixups, not attackers.
-
-## 3. Top-level layout
-
-```
-[ Header (256 B) ]
-[ Level table ]                              ← level_count × 32 B, §4.1
-[ Root page frame ]                          ← always-resident set = header + table + this
-[ Page frames, coarse-first band order ]     ← prefix of the file = coarse asset
-[ Page directory ]                           ← flat 32 B records, range-fetchable
-[ Directory block checksums ]                ← u64 per 128 records (4 KB block)
-```
-
-The frame region is **exactly** `[root_page_offset, directory_offset)` — that is the
-normative end-of-frames rule (see §5). Its start is a header field rather than a constant
-because the level table (§4.1) precedes it and its size depends on the build. The directory is **derived data**: every field in it is
-reconstructible by scanning frames and decoding page headers. It exists for special
-tasks — tooling, validation, RAM budgeting before fetch, resuming from a disk cache,
-jumping to an arbitrary page without walking the DAG — and standard runtime traversal
-never touches it. Random-access readers fetch directory slices on demand: record `i`
-lives at exactly `directory_offset + 32·i`.
-
-## 4. Header (256 bytes, fixed)
-
-All u64/u128 fields are naturally 8-byte aligned.
-
-| offset | type      | field                    | notes |
-|-------:|-----------|--------------------------|-------|
-| 0      | u32       | magic                    | `'VGEO'` = 0x4F454756 |
-| 4      | u16       | format_version           | 6 today; breaking layout changes only |
-| 6      | u16       | min_reader_version       | 6 today; reader MUST reject if its version is lower |
-| 8      | u16       | header_size              | = 256 |
-| 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; 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) |
-| 44     | u32       | total_pages              | = directory record count |
-| 48     | u64       | total_clusters           | ≥ 1 |
-| 56     | u64       | total_groups             | ≥ 1 |
-| 64     | u64       | root_page_offset         | = `align16(256 + 32 · level_count)` — the level table (§4.1) sits between |
-| 72     | u32       | root_page_fetch_size     | same definition as child-table/directory `fetch_size`, for page 0 |
-| 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        | 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    | u16       | level_count              | levels `0..level_count-1`; ≤ 65,535. A `u8` through version 5, and the byte above it was reserved and written as zero — so little-endian makes this field read identically through either width for any container of 255 levels or fewer |
-| 104    | u64       | source_vertex_count      | vertices of the normalized source mesh (post-weld) the leaves represent |
-| 112    | u64       | source_face_count        | triangles of the normalized source mesh |
-| 120    | [f32; 4]  | object_sphere            | object-space minimal bounding sphere (center xyz, radius) of the whole geometry |
-| 136    | [f32; 6]  | object_bounds            | object-space AABB (min xyz, max xyz); instances transform at runtime |
-| 160    | [u8; 88]  | reserved                 | |
-| 248    | u64       | header_checksum          | xxh3-64 of bytes 0–255 with this field zeroed (`asset_id` already final) |
-
-**`format_version` 4 moved and `min_reader_version` did not**, which is the pair working as
-intended rather than an oversight. 4 added the parent tables (§6.3, §6.4): they occupy bytes that
-were reserved and written as zero, and they sit between the cluster records and the payload, so
-every offset a version-3 reader computes lands exactly where it did and such a reader reads a
-version-4 file correctly by ignoring them. In the other direction a version-4 reader meets
-`parent_table_offset = 0` on an older file and takes it as "this container has no upward edge",
-which is true — so neither direction needs a version test, and nothing has to be rebuilt to stay
-readable.
-
-**5 moved both**, which is the pair working the other way. It put `subtree_aabb` in the cluster
-record (§7) over the bytes `bounds_sphere` and `cone_reserved` held, so every field from offset 40
-on shifted: a version-4 reader would take a version-5 `child_ref` out of the middle of a bounding
-box and descend into whatever group that named. There is no ignoring it and no partial reading of
-it, so `min_reader_version` moved with the version, which is what that field is for. A version-5
-reader still reads version-4 records — it branches on the version it is holding — so nothing has to
-be rebuilt to stay readable, only to be culled tightly.
-
-**6 widened the level ordinal to `u16`** in all three places it is written down: `level_count`
-here, the page band in the page header (§6.1), and the page band in the directory record (§9). 255
-was a ceiling a real asset reached — the 2026-09-14 Zorah conversion refused a three-million-triangle
-bush at exactly 255 levels with 39 clusters still unmerged, while the other 2,974 geometries of that
-scene, one of them 27 million triangles, converged by 149 — and a ceiling an asset can touch is a
-ceiling in the wrong place. Two of the three cost nothing: this header and the directory record both
-had reserved bytes lying beside the field. The page header had none, and rather than grow the page
-this spends `node_table_offset`, which only ever restated `56 + 8·group_count`. So **a page header
-is still 56 bytes and every other field of every page ever written is still at its old offset** —
-but bytes 4..8 and 20..24 of it now mean different things, and there is no partial reading of that,
-so `min_reader_version` moved. A version-6 reader keeps the older page layout as it keeps the older
-cluster layout, so again nothing has to be rebuilt to stay readable.
-
-### 4.1 Level table (`level_count` × 32 B, immediately after the header)
-
-Statistics per level, at `256 + 32·i`, ending where the root page frame begins. Small —
-a hundred levels is 3.2 KB, and the deepest container yet converted is 149 — so a single
-fetch of the file's head brings the header, the whole table, and the always-resident root
-page together, and the table is available before any page has been decoded. That is a
-statement about what builds produce and not a bound: `level_count` is a `u16`, and a
-reader sizing a head fetch must take the number it finds rather than assume this one.
-
-| offset | type | field             | notes |
-|-------:|------|-------------------|-------|
-| 0      | f32  | min_error         | smallest object-space `r_e` any cluster of this level carries |
-| 4      | f32  | max_error         | largest |
-| 8      | f32  | max_sphere_radius | largest LOD-metric sphere radius at this level |
-| 12     | u32  | cluster_count     | ≥ 1 |
-| 16     | u32  | group_count       | groups sitting in this band; ≥ 1 |
-| 20     | u32  | triangle_count    | |
-| 24     | u64  | reserved          | |
-
-What it is for: an instance's level range can be **bracketed** from the errors and radii
-alone — the coarsest level that still passes the threshold at the instance's near point,
-the finest that could be wanted at its far one — without reading a cluster record or
-fetching a page. That is what lets a scene of ten thousand identical parts resolve to a
-handful of distinct cuts instead of ten thousand of them, and what lets a prefetch name
-exactly the bands a bracket spans.
-
-These are facts about the build, not a policy. In particular **`max_error` is not monotonic
-in the level**: a round merges an error band, and a later round can produce a cluster finer
-than an earlier one did, by finally reaching geometry that had been waiting for a partner.
-A reader that wants a monotonic bound takes a running maximum from the coarsest end; that
-is the reader's choice and not the file's.
-
-`cluster_count` and `group_count` sum to the header's `total_clusters` and `total_groups`,
-which is the cross-check that keeps the table from drifting from the pages.
-
-**What `asset_id` covers.** The whole file, with these fields treated as zero: `asset_id` itself,
-`header_checksum`, every frame's `checksum` (§5), and the entire `dir_block_checksums` region (§9).
-Excluding the last two is what breaks the circle — the frame checksums are seeded from
-`asset_id_low64` and the directory block checksums from `asset_id_high64`, so covering them would
-make the identity a function of itself. Nothing is lost by the exclusion: every one of those fields
-is a function of content the hash still covers, so any change to the asset still moves `asset_id`.
-
-Build order, and the order a verifier repeats: zero those fields → hash → write `asset_id` →
-compute and write the frame and directory-block checksums it seeds → compute and write
-`header_checksum` over bytes 0–255 with only that field zeroed.
-
-The asset filename MUST be derived from `asset_id` in streamed deployments (content
-addressing is what makes same-URL version skew impossible; every client-side integrity
-property leans on it). The field is authoritative, the name is the enforcement.
-
-A new `payload_encoding` (e.g. quantized positions) is a **per-asset capability gate,
-not a format break**: old readers cleanly reject the asset instead of misreading it;
-`format_version` moves only when the container layout itself changes.
-
-## 5. Page frame (stored page)
-
-Every page — root included — is stored as a self-delimiting frame:
-
-```
-[ FrameHeader (24 B) ] [ Child table (plaintext) ] [ blob (codec-encoded) ]
-```
-
-| offset | type | field            | notes |
-|-------:|------|------------------|-------|
-| 0      | u32  | magic            | `'VGPG'` = 0x47504756 |
-| 4      | u8   | codec            | 0 = raw, 1 = one LZ4 block, 2 = one raw DEFLATE stream; applies to the blob only; readers MUST reject unknown values |
-| 5      | u8   | flags            | 0 |
-| 6      | u16  | child_page_count | entries in the child table; 0 for all-leaf pages |
-| 8      | u32  | stored_size      | bytes of blob (after the child table) |
-| 12     | u32  | decoded_size     | decoded-page bytes (== stored_size when raw); MUST equal the referencing child-table entry's (and the directory record's), else reject |
-| 16     | u64  | checksum         | xxh3-64, **seed = asset_id_low64 XOR page_index**, over frame bytes `[0, 16)` followed by `[24, 24 + 48·child_page_count + stored_size)` — everything but this field |
-
-**Child table** — `child_page_count` × 48 B, plaintext (never compressed), deduplicated:
-one entry per distinct child page this page's clusters refine into. This is what makes
-traversal self-sufficient — an installed page needs nothing but itself to fetch every
-page one level down — and it is plaintext for two load-bearing reasons: fetch ranges
-are readable before (or without) blob decode, and stored sizes stay independent of
-offset values, which keeps the build's layout computation non-circular (§10).
-
-| offset | type | field         | notes |
-|-------:|------|---------------|-------|
-| 0      | u64  | frame_offset  | absolute; strictly greater than this page's own frame offset (§11.3) |
-| 8      | u32  | page_index    | the child page's global index (frame ordinal) — checksum seed, want dedup |
-| 12     | u32  | fetch_size    | `24 + 48·child.child_page_count + child.stored_size`, rounded up to 16 — the exact range to fetch |
-| 16     | u32  | decoded_size  | RAM budgeting before fetch; MUST equal the child frame's |
-| 20     | u32  | reserved      | |
-| 24     | metric | metric      | the child page's own metric (§6.2), copied — this is what makes a page testable *before* it is fetched; MUST equal that page's header metric (§11.11) |
-
-The identity-seeded checksum binds the frame to *this page of this asset* and covers
-the frame header fields, the child table, and the blob — a well-formed frame of the
-wrong page, wrong asset, or wrong version fails verification instead of installing
-silently. It also guards the traversal path itself: a corrupt child-table entry fetches
-a range whose frame cannot checksum as the expected page index.
-
-The next frame starts at `round_up(frame_offset + 24 + 48·child_page_count +
-stored_size, 16)`. **Prefix scanning**: page indices are frame ordinals (file order ==
-index order); scan sequentially and stop when the next aligned offset + 24 exceeds
-`min(bytes_available, directory_offset)` — never rely on magic mismatch as a
-terminator.
-
-**Codecs.** `codec` is a property of one frame, not of the file: a writer picks per page
-and an asset may carry a mixture, so a reader that handles the defined codecs handles
-any file without asking what it was written with. That is what makes "compress unless it
-would not shrink" expressible — the LZ4 worst case is about one byte in 255 plus a
-token, deflate's is a stored block that is never smaller than its input, and paying
-either to store bytes verbatim is a straight loss, so a page that does not compress is
-written raw and says so.
-
-A new codec id is a **per-asset capability gate, not a format break**, exactly as a new
-`payload_encoding` is: an older reader meets a codec it has no decoder for and refuses
-the asset instead of misreading it. `format_version` moves only when the container
-layout itself changes, and adding a codec does not change it — `2` went in without
-touching `format_version` or `min_reader_version`.
-
-`1` is a **bare LZ4 block**, not an LZ4 frame, and `2` is a **bare DEFLATE stream**
-(RFC 1951), not a zlib or gzip member. Both wrappers carry a magic, a checksum and a
-content size that this frame already carries better, and `decoded_size` is what the blob
-is decoded against. Both codecs are independent per blob — no match reaches outside the
-page — so a page decodes from its own bytes with no other page involved, which is the
-same property residency already needs.
-
-`decoded_size` is untrusted input, and readers allocate against it before anything can
-contradict it. It MUST therefore be checked against what `stored_size` bytes could
-physically produce under `codec` — exactly `stored_size` for raw, at most
-`255·stored_size + 19` for LZ4, at most `1032·stored_size` for deflate — *before* the
-allocation. A blob that then decodes to anything other than `decoded_size` MUST be
-rejected: a page truncated to a plausible prefix is the one corruption that reads as a
-valid page with geometry missing.
-
-Those ceilings are what the *format* permits, and neither compressing one is anything
-like what a page looks like, so a length check alone is a weak guard — deflate's 1032:1 admits a 256 KB blob claiming 264
-MB. A decoder MUST therefore bound its own output as it produces it rather than
-comparing lengths once it is done: the LZ4 decoder is given the end of the page as its
-write limit, and the deflate decoder stops at the first chunk that would pass it. A blob
-that expands further than its header admits then costs one chunk rather than the whole
-expansion.
-
-**Which codec, and why deflate is the default.** Measured over the 44 pages of a
-240×120 torus: LZ4 stores them at **1.295x** and deflate at **1.369x**, and decoding
-every page costs **3.8 ms** under LZ4 against **16.9 ms** under deflate — 562 MB/s of
-decoded output against 126. Deflate buys about seven points of ratio for four and a half
-times the decode.
-
-**The builder and the converter write deflate**, because the two sides of that trade are
-not paid the same number of times: an asset is built once and fetched forever, and the
-bytes deflate saves are saved on every fetch of every page by every client. LZ4 is the
-deliberate setting for a container whose pages arrive while someone is looking at it —
-there the decode is a page's *arrival* cost on the residency path, and 126 MB/s is what
-that costs. Neither is a property of the file format: `codec` is a frame field and a
-reader that handles the defined codecs reads either without being told.
-
-A *default* codec is a statement about readers rather than about bytes. Under the gate
-above, a container written with deflate opens only in a reader that carries the deflate
-decoder, so the default is what decides which builds of this engine can open a freshly
-converted asset. `format_version` still does not move, and an older reader still refuses
-rather than misreads.
-
-Deflate is also the *hosted* codec: `CompressionStream`/`DecompressionStream` are the
-platform's own zlib, so it costs no bytes of library — and the platform offers it only
-as a stream, which is why everything in this reader from the blob decode upwards is
-asynchronous. Nothing in the format requires that; a synchronous inflate would read the
-same files.
-
-**What it is worth, measured.** LZ4 over the pages of the Stanford models comes to
-**1.12x on the bunny, 1.18x on the dragon and 1.14x on the 27M-triangle lucy** — pages
-are >99% of a file, so that is very nearly the file ratio. That is modest, and the reason
-is worth writing down because it says where the next win is rather than here:
-
-| section | share of page bytes | lz4 |
-|---|---:|---:|
-| page header, group, node and cluster tables | 7% | 1.6x |
-| payload | 93% | 1.09–1.15x |
-
-The tables compress, and there are not enough of them to matter. The payload does not,
-because under `SHADE_MESHLET_V1` it is float32 positions and packed attribute words —
-high-entropy at the byte level, with no repetition for an LZ matcher to find. For
-reference, on the same bytes `gzip -9` reaches 1.22x — codec `2`'s algorithm, at a level
-the platform API does not expose — and `xz -9` 1.63x, so this is the data resisting
-rather than the codec failing; an entropy coder buys a little more for a lot more time. **The lever is `payload_encoding`, not
-`codec`** — quantized positions (§12) shrink those bytes directly and leave the residue
-far more compressible.
-
-What the reader pays is one block decode per page installed, into the buffer the page was
-going to be copied into anyway: ~350–500 MB/s of decoded output from the JS decoder, so
-about 0.6 ms for a 256 KB page.
-
-## 6. Decoded page
-
-```
-[ PageHeader (56 B) ] [ Group table ] [ Node table ] [ Cluster records ]
-[ Parent-page table ] [ Group-parent table ] [ Payload ]
-```
-
-The two parent tables sit between the cluster records and the payload, and that placement is the
-reason `min_reader_version` did not move when version 4 added them (§4): the node table's `= 56 +
-8·group_count` stays true, every earlier offset is where it was, and both tables hold 4-byte entries
-over sections that are already multiples of four, so §11.8's word-aligned payload survives.
-
-PageHeader:
-
-| offset | type | field                 | notes |
-|-------:|------|-----------------------|-------|
-| 0      | u16  | group_count           | ≥ 1; group table immediately follows the header |
-| 2      | u16  | cluster_count         | ≥ 1 |
-| 4      | u16  | min_level             | page band; non-root pages span one contiguous band. A `u8` at 4 and another at 5 through version 5 |
-| 6      | u16  | max_level             | |
-| 8      | u32  | cluster_table_offset  | |
-| 12     | u32  | payload_offset        | |
-| 16     | u32  | payload_size          | |
-| 20     | u16  | node_count            | ≥ 1; ≤ 2·`group_count` (§6.1). At 6 through version 5 |
-| 22     | u16  | reserved              | what version 5 spent on `node_table_offset`, which said only `56 + 8·group_count` — the group table follows the header and the node table follows the group table, so a reader derives it. MUST be zero |
-| 24     | u32  | parent_table_offset   | start of the parent section — the parent-page table, then the group-parent table. **0 means the page carries neither**, which is what every container written before `format_version` 4 says about itself |
-| 28     | u16  | parent_entry_count    | entries in the group-parent table (§6.3) = Σ `parent_cluster_count` over this page's groups |
-| 30     | u16  | parent_page_count     | entries in the parent-page table (§6.4) |
-| 32     | metric | metric             | this page's own traversal metric (§6.2) — the root node's, repeated here so an installed page can be tested from itself |
-
-Group table — `group_count` × 8 B. Groups are the atomic LOD/residency unit; because a
-group never spans pages, installing/evicting a page carries whole groups by
-construction — no global group index exists or is needed:
-
-| offset | type | field                | notes |
-|-------:|------|----------------------|-------|
-| 0      | u16  | cluster_first        | index into this page's cluster records |
-| 2      | u16  | cluster_count        | ≥ 1; ≤ 4096 (format cap, §11.5) |
-| 4      | u16  | parent_cluster_count | number of parent clusters referencing this group, `SAME_PAGE` references included; 0 exactly for the root page's topmost-level groups — drives activation (§10). Also the length of this group's run in the group-parent table |
-| 6      | u16  | parent_first         | index of that run's first entry (§6.3). Groups tile the table in order, exactly as `cluster_first` tiles the cluster records |
-
-### 6.3 Group-parent table (`parent_entry_count` × 4 B)
-
-The format's **only upward edge**, and the mirror of the child table with everything a parent does
-not need taken out. Every entry here is the reverse of exactly one cluster's
-`child_ref`/`child_group` pair, and §11.16 holds the two to each other.
-
-| offset | type | field          | notes |
-|-------:|------|----------------|-------|
-| 0      | u16  | parent_ref     | index into the parent-page table (§6.4), or `SAME_PAGE` |
-| 2      | u16  | parent_cluster | cluster index within that page |
-
-**Four bytes an entry, against the child table's 48**, because the two directions are not
-symmetric. A child reference carries a fetch range and a metric copy because the child may be
-absent and the decision to fetch it is taken before it arrives. A parent of a group in the cut is
-resident already — `VGEO_GROUP_FLAG_SELECTABLE` is exactly "every parent reference is live" — so a
-parent reference has nothing to decide and only has to say where.
-
-Measured across 8,899 pages of 30 converted containers: 17.4 entries a page on average and 26 at
-the worst, so the table runs to about 70 bytes against pages of 56–256 KB, and compresses with the
-rest of them (§5: tables are 7% of page bytes at 1.6×).
-
-What it is *for* is a cut that is kept between frames. A cut that has descended to a group and then
-sees the camera pull back has to draw the clusters that consumed that group instead, and without
-this it could only find them by descending from the root again — which is the cost keeping a cut is
-meant to remove, paid on the common case.
-
-### 6.4 Parent-page table (`parent_page_count` × 4 B)
-
-One `page_index u32` per **distinct other** page holding a parent of one of this page's groups,
-deduplicated and ascending. A parent inside this page spends `SAME_PAGE` in §6.3 instead and has no
-entry here, so a page never appears in its own table.
-
-It lives in the decoded page rather than beside the plaintext child table because nothing needs it
-before decode: no fetch range is computed from it, and in the blob it compresses with the other
-tables. Measured: 4.9 entries a page on average, 18 at the worst.
-
-### 6.1 Node table (`node_count` × 32 B)
-
-A tree over **this page's groups**, and nothing else. It is the part of the hierarchy below page
-granularity, and it has no paging question of its own: it arrives with the page it describes,
-leaves with it, and can never name anything that is not there.
-
-| offset | type   | field       | notes |
-|-------:|--------|-------------|-------|
-| 0      | metric | metric      | bounds everything under this node (§6.2) |
-| 24     | u16    | child_first | first child — a node index when interior, a group index when a leaf |
-| 26     | u16    | child_count | 1..4 |
-| 28     | u16    | flags       | bit 0: leaf (children are groups) |
-| 30     | u16    | reserved    | |
-
-Node 0 is the root, always. Children occupy a **contiguous run**, and the tree is laid out
-breadth-first, so an interior node's `child_first` is strictly greater than its own index — which
-bounds any walk without a reader having to track one. Leaves **partition** the group table: every
-group is reached through exactly one leaf, no group twice and none not at all. A page with a single
-group still has a tree: one leaf node covering it, so a reader always starts at node 0 and never
-special-cases.
-
-Cost, measured across sphere assets from 3k to 98k triangles at page sizes from 8 KB to 256 KB: the
-node table plus every metric copy runs **0.3%–1.6% of asset size**, and trees come out one to three
-deep.
-
-### 6.2 Traversal metric (24 B)
-
-The same three fields wherever they appear — a child-table entry (§5), a page header (§6), a node
-(§6.1):
-
-| offset | type     | field            | notes |
-|-------:|----------|------------------|-------|
-| 0      | [f32; 4] | sphere           | contains every bound anything covered carries |
-| 16     | f32      | min_self_error   | finest error covered |
-| 20     | f32      | max_parent_error | coarsest parent error covered; `+∞` where the root is covered |
-
-One sphere serves both the spatial test and the projection. It is the union of the covered clusters'
-`parent_sphere`s, and monotonicity does the rest: `parent_sphere` contains `self_sphere`, which
-contains the cluster's own vertices, so nothing under the node escapes it.
-
-`max_parent_error` is the load-bearing number. A cluster is drawn only while `project(parent) > τ`,
-so if the *largest* parent error under a node still projects to no more than τ, nothing under it can
-be drawn and the entire subtree is skippable. `min_self_error` answers the other question — whether
-anything here is drawable at all, or whether this is only a waypoint on the way to something finer —
-which is what a prefetch ranks its wants by.
-
-A group is the natural unit for all of this and needs no new geometry: every cluster of a group is
-consumed by one step and therefore shares that step's `parent_sphere` and `parent_error`, which is
-the same fact that makes the group the atomic LOD decision.
-
-**The copy in a child-table entry is the point of the whole thing.** It is what a traversal reads
-*before* fetching a page, and without it the only way to learn a page was not wanted is to fetch and
-decode it. Being a copy, it can drift; §11.11 requires it to match the page's own.
-
-## 7. Cluster record (112 bytes)
-
-Everything the runtime cut rule, culling, wants, and upload need — denormalized per
-cluster so selection reads one record. Three kinds of bounds, deliberately distinct: the
-**LOD-metric pair** (`self_sphere`/`parent_sphere` — shared per group step so all
-siblings project identical values, monotonically inflated, never a tight fit), the
-**cluster's own box** (`aabb` — its tight fit, the meshlet metadata's `bounds_box`, culled
-downstream by the HZB), and the **subtree box** (`subtree_aabb` — this cluster's geometry and
-everything reachable below it, and the only one of the three the cut's per-cluster frustum test
-can use, because culling a cluster takes its whole child group out of the descent):
-
-| offset | type     | field           | notes |
-|-------:|----------|-----------------|-------|
-| 0      | [f32; 4] | self_sphere     | LOD-metric sphere (center xyz + radius) of the group step that created this cluster; leaves: equals `bounds_sphere` |
-| 16     | f32      | self_error      | object-space `r_e`; leaves: 0 |
-| 20     | f32      | parent_error    | error of the step that consumed it; roots: +∞ |
-| 24     | [f32; 4] | parent_sphere   | LOD-metric sphere of the consuming step; roots: duplicate of self_sphere |
-| 40     | [f32; 6] | subtree_aabb    | object-space AABB of this cluster's vertices **and of every cluster reachable below it** through child groups (§11.17); leaves: equals `aabb`. What the runtime's per-cluster frustum cull reads |
-| 64     | [f32; 6] | aabb            | this cluster's own object-space AABB — GPU metadata `bounds_box`, the downstream culls, and the (future) dequantization grid |
-| 88     | u16      | child_ref       | index into this frame's child table; `SAME_PAGE` when the child group is in this page; `NO_CHILD` for leaves |
-| 90     | u16      | child_group     | group index within the child page (or this page, for `SAME_PAGE`); `NO_GROUP` for leaves |
-| 92     | u32      | encoding_flags  | frozen bit table in §8 |
-| 96     | u32      | payload_offset  | into this page's payload section; ≡ 0 (mod 4) |
-| 100    | u32      | payload_size    | bytes; ≡ 0 (mod 4) |
-| 104    | u8       | vertex_count    | 3 ≤ n ≤ 128 |
-| 105    | u8       | triangle_count  | 1 ≤ n ≤ 128 |
-| 106    | [u8; 6]  | reserved        | **write 0** |
-
-**What version 5 spent to fit `subtree_aabb` in the same 112 bytes.** `bounds_sphere`, the cluster's
-own miniball, which no runtime ever read — the cut tests the LOD sphere, the HZB and the small-primitive
-cull test `bounds_box`, and the builder keeps its own copy of the sphere for the object bounds and the
-group centroids. And `cone_reserved`, four bytes held for a backface-cone cull that is **declined
-outright** (design §9, plan §5): the earlier note kept it because reclaiming four bytes was not worth
-moving `format_version`, and moving it for twenty-four was.
-
-Monotonicity (`parent_error ≥ self_error`, `parent_sphere ⊇ self_sphere`) is a build
-invariant, not a reader concern. A single-cluster asset is valid: one root page, one
-group with `parent_cluster_count = 0`, one cluster with `parent_error = +∞`,
-`child_ref = NO_CHILD`, `child_page_count = 0`.
-
-## 8. Payload encoding
-
-`payload_encoding = 1` (`SHADE_MESHLET_V1`). **Byte-compat scope**: the payload block is
-byte-compatible with `GPUMeshletManager`'s **data pool** — uploading it is a copy. The
-40-byte GPU metadata rows (`MESHLET_METADATA_STRUCT`: bounds_box, address,
-primitive_count, vertex_count, flags) are **synthesized at install** from the cluster
-record (aabb → bounds_box, counts widened to u32, `address = slot_base_word +
-payload_offset/4`, flags = encoding_flags) — a small pack step that is part of the
-design's "VRAM paging mechanism is new work", not an existing patch path.
-
-Payload block layout:
-
-1. Index section: `triangle_count × 3` local u8 indices, zero-padded to a 4-byte word
-   boundary.
-2. Attribute sections, in the frozen order below, each `words × vertex_count` u32
-   words — unless its `encoding_flags` bit marks it constant-compressed, in which case
-   exactly `words` u32s are stored once.
-
-Frozen tables (byte-identical to Shade's `ENCODED_ORDERED_ATTRIBUTES`,
-`ENCODED_ATTRIBUTE_SIZES`, `MESHLET_METADATA_FLAGS` as of this writing — the spec, not
-the source, is now the authority for `.vgeo` files):
-
-| # | attribute | words/vertex | encoding                  | flags bit (constant-compressed) | mask bit |
-|---|-----------|-------------:|----------------------------|-------------------------------:|---------:|
-| 0 | position  | 3            | raw f32×3                  | — (never compressed)            | 0 |
-| 1 | normal    | 1            | octahedral u32             | 1 (0x01)                        | 1 |
-| 2 | tangent   | 1            | packed u32                 | 2 (0x02)                        | 2 |
-| 3 | color     | 1            | RGBA8 u32                  | 4 (0x04)                        | 3 |
-| 4 | uv0       | 2            | raw f32×2                  | 8 (0x08)                        | 4 |
-| 5 | uv1       | 1            | 2×unorm16 u32              | 16 (0x10)                       | 5 |
-
-- `encoding_flags` bits 5 (0x20, skinning joints) and 6 (0x40, skinning weights) MUST
-  be clear, and **no skinning sections are stored** — `SHADE_MESHLET_V1` payloads end
-  at uv1. (Load-bearing note: skinning attributes are last in Shade's attribute order
-  and the static decode path never addresses them, which is exactly what makes their
-  omission safe. VG is static-only, design §9.)
-- All other `encoding_flags` bits are reserved, MUST be 0.
-- An attribute the source lacks still ships its section, constant-compressed to the
-  engine default — **sections are never omitted**; `vertex_attribute_mask` is advisory
-  (which attributes carry real data). True section omission would shift every following
-  offset and is only expressible as a new `payload_encoding` id.
-
-Quantized positions land as a **new `payload_encoding` id** (plus a page codec if
-entropy coding pays). The cluster record already carries the dequantization grid
-(`aabb`).
-
-## 9. Page directory (auxiliary)
-
-Flat array of `total_pages` 32 B records at `directory_offset`; record `i` describes
-page index `i` (page index order == file order == coarse-first). Auxiliary and fully
-derivable from the frames (§3) — standard runtime traversal never reads it.
-
-| offset | type | field          | notes |
-|-------:|------|----------------|-------|
-| 0      | u64  | frame_offset   | absolute; frame per §5 |
-| 8      | u32  | fetch_size     | as in the child table: the exact byte range to fetch is `[frame_offset, frame_offset + fetch_size)` |
-| 12     | u32  | decoded_size   | MUST equal the frame's |
-| 16     | u16  | min_level      | a `u8` here and another at 17 through version 5, which is what moved the three fields below by two — into bytes this record has always held in reserve |
-| 18     | u16  | max_level      | |
-| 20     | u16  | flags          | bit 0: root page |
-| 22     | u16  | group_count    | |
-| 24     | u16  | cluster_count  | |
-| 26     | [u8; 6] | reserved    | |
-
-**Directory integrity**: `dir_block_checksums` holds one xxh3-64 per 128 directory
-records (one 4 KB block), seed = `asset_id_high64 XOR block_index`. Readers that use
-the directory fetch it at block granularity and MUST verify.
-
-## 10. Reader requirements
-
-Standard runtime operation is **pure traversal** — the directory is not involved. Every item
-below is marked with what `format/read/` does about it: *(shipped)*, *(open)*, or a split where
-the mechanics are there and the policy is the caller's. Where a requirement is *policy*, the
-implementation is `renderer/geometry/virtual/residency/` rather than `format/read/` — a sibling of
-the format, not part of it, because what may be resident and what may be in flight are questions
-about a scene and not about a container.
-
-- **Cold start** *(shipped)*: fetch `[0, 256)`, verify `header_checksum`, magic, versions (§4 reject
-  rules), then fetch `[root_page_offset, root_page_offset + root_page_fetch_size)` — the
-  level table (§4.1) sits between the two, so a head prefix covering both brings the whole
-  always-resident set in one request. The root frame's `decoded_size` MUST equal
-  `root_page_decoded_size` and its frame extent MUST match `root_page_fetch_size`, else
-  reject. Or speculatively fetch one larger head prefix — coarse-first layout makes every
-  prefix byte useful.
-
-  **How much of that prefix to keep, and for how long, is not a free choice at scale.** The
-  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 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
-  after those installed — while sitting outside `resident_bytes` and outside anything `evict` could
-  reach, which across a thousand open assets was a quarter of a gigabyte no budget could see.
-- **Refinement** *(shipped)*: a want is a `child_ref` in an installed page; its child-table entry
-  carries the exact byte range — one round-trip per cold page, no metadata fetch ever.
-  Wants dedup on `page_index` across clusters, groups, and instances. A want whose
-  target page is **already installed** resolves as an activation recheck of the
-  referenced group (below), never a fetch.
-
-  A want that goes stale mid-flight is cancellable: `VGeoByteSource.read` takes a per-read
-  `AbortSignal`, `vgeo_fetch_byte_source` passes it to `fetch` alongside the source's own, and
-  `VGeoContainerReader.cancel` abandons one page's request without touching the others.
-  **What a stale want does, decided:** it is aborted while it can still be aborted, and installed
-  once it cannot — the bytes are already paid for, and refusing to keep them costs the fetch *and*
-  the page. An arrival nobody wanted enters residency untouched, which under LRU on last-touched
-  makes it the first eviction candidate and free if the camera comes back.
-- **Activation (closure without dependency lists)** *(shipped)* — the selectable invariant:
-
-  *A group `g` is selectable iff every one of its `parent_cluster_count` references is
-  live — the referencing cluster's page is installed and that cluster's own group is
-  selectable. Groups with `parent_cluster_count = 0` (exactly the root page's topmost
-  level) are selectable at install.*
-
-  By induction, a selectable cluster's entire ancestor cone is installed and
-  selectable — the closure the cut rule needs, restored by a per-group counter instead
-  of dependency lists. Runtime bookkeeping: each resident group keeps a live-reference
-  counter; when a group becomes selectable, its clusters' references (child-table and
-  `SAME_PAGE` alike) increment the referenced groups' counters — cascading
-  transitively; installing a page counts the existing live references into it (the
-  runtime maintains a reverse-reference index for pending pages — the same structure
-  that carries wants). Counters only grow while the pages involved stay resident (the
-  eviction rule below guarantees referencing parents outlive children). Activation
-  flips whole groups; the cut rule's clamp reads *selectable*, not merely resident
-  (design §4/§6): resident-but-inactive groups draw nothing, their coarser selectable
-  ancestors keep covering that surface — **no holes and no double-draw, in any arrival
-  order**, because a group never draws before all pages holding its parents are
-  installed and selectable.
-- **In-flight protection** *(open)*: a fetch discovered through parent page P pins P until the
-  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 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;
-  the root page is pinned. `VGeoContainerReader.evict` does the dropping and the activation
-  retraction that goes with it — deliberately including the case where a caller evicts against
-  this rule, where the cascade is what stops an orphaned child page from staying drawable — but
-  it chooses nothing: which page to drop, and when, is the budget owner's.
-  `VGeoContainerReader.resident_child_count` is the lookup the rule is written in terms of, and it is
-  the whole of what the reader contributes.
-- **The budget owner** *(shipped, above the reader)*: `VGeoResidencyManager`. Readers register with
-  one; it holds the RAM tier's byte budget across every registered reader, admits a want against it
-  *before* the fetch out of the `decoded_size` the child table already carries, and evicts on the
-  rule above ordered by design §6's LRU on **last-touched** with a protect window no shorter than
-  feedback latency. It reaches nothing private: it is written entirely against the reader's public
-  surface, which is the test that the split is real rather than nominal.
-
-  A shared **fetch scheduler** comes with it, and has to: `VGeoReadOptions.max_concurrent_fetches`
-  bounds one reader and cannot do better, and four readers at that cap were measured issuing sixteen
-  concurrent range requests, eight readers at the default 6 issuing 48. `VGeoResidencyManager`
-  holds one total across every reader in a single `ConcurrencyGate` (`core/process/`), as one
-  priority queue — so a want's priority, which is pixels of projected error and therefore
-  comparable across assets by construction, is compared globally rather than within whichever
-  reader happened to ask first.
-
-  **Most of that shape already exists in this engine twice, and the bullet is more useful read as
-  the third one than as new work.** `renderer/texture/virtual/VTPhysicalCache` keeps a
-  `#last_touch` stamp per slot, a lock flag for slots that may never go, and
-  `find_eviction_candidate(current_frame, protect_window)` — LRU on last-touch under a protect
-  window justified by feedback latency, which is the rule above. Design §6 said so when it pinned
-  that rule ("the VT system already keys on touch for this reason"), so the resemblance is
-  convergent by instruction rather than accidental. `engine/asset/AssetManager` caps concurrent
-  top-level loads on `load_concurrency` for the reason the gate holds a total, and inverts
-  priority into a `BinaryHeap` the same way in `get_pending_asset_priority_score` — being the
-  third place to want that, and the second to write that inversion, is why the gate is now
-  `core/process/ConcurrencyGate` rather than a file in this directory, and `AssetManager` keeps
-  its own queue anyway for the reasons its `load_concurrency` doc records.
-  `VirtualTextureManager` caps `max_concurrent_loads` at 32 and drops queued requests untouched
-  for `queue_stale_window` frames, which is a stale-want policy of the kind `cancel` answers here.
-
-  **The narrow claim that survives that** is a *byte* budget across *several* readers, admitted
-  against before the fetch: `VTPhysicalCache` budgets a count of fixed-size slots and
-  `AssetManager` budgets nothing and evicts nothing. The retry-into-quarantine and the per-fetch
-  `AbortSignal` above are likewise new here — `AssetManager` records a failure and lets a later
-  `get` retry, and neither precedent can abort one request. Granularity is why the pages are not
-  simply `AssetManager` entries: an `AssetDescription` is a path and a type, where a page is a
-  byte range in a container the format gives no global id to (a cluster is a page plus an index),
-  at the 4,000 and 20,000 pages per container measured above and a thousand assets open at once.
-- *(shipped)* Verify every ranged response is `206` with the requested `Content-Range`; a `200`
-  means the server ignored the range — abort the transfer immediately (design §6).
-  `vgeo_fetch_byte_source` checks the status *and* the returned range: a proxy can answer 206
-  with a range other than the one asked for.
-- *(shipped)* Verify frame checksums (identity-seeded, §5) before decode, and `decoded_size`
-  against the child-table entry used to fetch and against the codec's decode bound
-  (§5) before allocating for it. On mismatch: bounded retries with
-  backoff, then **quarantine** the page — the clamped cut keeps a coarse stand-in
-  correct indefinitely — and surface telemetry. Never retry-loop: corruption at a
-  content-addressed URL is deterministic.
-  The decode bound and the exact-length decode are unconditional. The frame checksum is
-  `VGeoReadOptions.verify_frames`, off by default because a tool reading a file it just built is not
-  defending against a network — a runtime registering a reader with `VGeoResidencyManager` should
-  turn it on, and it is what lets the retries see corruption rather than only outages.
-  Retry and backoff are `fetch_retries` (2) and `fetch_retry_backoff_ms` (50, doubling); after them
-  the page enters `VGeoContainerReader.quarantine()` with its reason and is never fetched again, and
-  `install_wants` skips it rather than failing the batch — one bad page out of a thousand assets'
-  worth costs exactly that page. *When* to lift a quarantine is policy and is not the reader's:
-  a checksum that failed at a content-addressed URL will fail again, while a run of 503s from one
-  edge node is a different thing that a manager watching other assets arrive can tell apart, so
-  `clear_quarantine` exists and `VGeoResidencyManager.clear_quarantines` is who calls it.
-- *(open)* After install, stamp each cluster's selection row with its own page index and its
-  child page index/group (touch and want emission, design §6/§7). There is no selection buffer
-  yet; `VGeoPage` keeps a page's tables and the traversal reads them directly.
-- *(open)* Fetch batching: coalesce adjacent wanted pages into contiguous single ranges; ranges
-  never cross a band boundary by construction (coarse-first ordering), so coalescing
-  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)* 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 —
-  `VGeoContainerReader.validate` and `.install_all_pages` remain as deprecated shims for the
-  playground and the specs, and they reach the tools through a dynamic import so that a bundle that
-  only opens containers does not carry the validator at all. The audit takes the container as one
-  `ArrayBuffer`, because every §11 invariant is a cross-check between two places in the file; that is
-  a ceiling and not a slope, so it refuses above `VGEO_MAX_AUDIT_BYTES` (1 GiB) naming the size,
-  rather than failing in the allocator. Measured: a 514 MiB container audited in 19.4 s, and
-  installing every page of a 2,000-page container of 544 KB pages made 514 MiB resident in 210 ms.
-- *(shipped)* The reverse-reference index of the activation rule is bounded by the **residency
-  frontier**, not by how many pages a session has visited, and it is worth knowing which because it
-  has the shape of an index that leaks. An entry exists only while a resident, selectable cluster
-  refers into an absent page, and install/activation and evict/deactivation are symmetric. Measured
-  on a 20,000-page container with the 3,280 pages of its eight coarse bands pinned resident:
-  `pending_reference_page_count` was 6,561 after pinning and still 6,561 after touring all 6,561
-  pages of the band below them a window at a time and evicting each window. Dropping the pinned
-  pages too leaves 3.
-
-Build consequence (accepted): child tables hold downstream offsets — the format is
-optimized for reading, and the builder pays for it. Preferred strategy: emit frames
-with placeholder child tables, then **backpatch** them once all offsets are known, and
-finalize frame checksums last (the checksum covers the child table). Computing the full
-layout up front (compress all blobs → prefix-sum offsets → one forward emit) is equally
-valid. Both are cheap and non-circular **because child tables are plaintext in the
-frame**: a frame's extent (`24 + 48·children + stored_size`, with `stored_size` the
-blob's compressed size) never depends on the offset values, and patching plaintext
-bytes needs no re-compression. Build times are non-interactive by expectation —
-clustering and simplification dominate regardless.
-
-## 11. Build invariants (validated at build, assumed by readers)
-
-1. A group's clusters are contiguous in one page (`cluster_first/cluster_count`); a
-   group never spans pages. Non-root pages span a single contiguous level band.
-2. Child tables are exact: deduplicated, one entry per distinct **other** page
-   referenced by this page's clusters (`SAME_PAGE` references appear in no child
-   table); every `child_ref`/`child_group` resolves to a valid entry and group;
-   `frame_offset`/`fetch_size`/`decoded_size` agree with the referenced frame and the
-   directory (all referencing pages agree by construction).
-3. Acyclicity and reachability: every child-table `frame_offset` is strictly greater
-   than the owning page's frame offset (file order is topological), and every page is
-   reachable from the root page through child tables.
-4. File order (== page index order) is coarse-first: the root page first, bands by
-   descending level, spatial locality within a band. The root page contains the
-   complete topmost level(s) — at minimum a complete drawable cut of the DAG. A
-   cluster's child group is always in a page whose band tops out strictly below its own
-   page's, unless the reference is `SAME_PAGE`.
-5. Group size: `1 ≤ cluster_count ≤ 4096` (format cap; builders target far less —
-   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.
-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`
-   exactly for leaves; `parent_error = +∞` exactly for **the** root — there is exactly
-   one, and it is in page 0. Several parentless clusters would be several entry points,
-   and the cut only ever enters at one; it is also what an unconverged build leaves
-   behind, which is the likelier cause. All floats NaN-free.
-   `self_sphere`, `aabb` and `subtree_aabb` contain the cluster's decoded vertices; the header's
-   `object_sphere` and `object_bounds` contain the normalized source mesh. The `self_sphere` half is
-   what makes the LOD sphere usable as a conservative bound at all — the runtime's first frustum test
-   is on it, and a reader meeting a pre-5 container stands its cube in for `subtree_aabb`.
-8. Payload offsets and sizes are 4-byte multiples; every payload decodes/uploads
-   against `payload_encoding` with no external state beyond its own cluster record.
-   A leaf's `self_error` of 0 is only as honest as the simplifier's metric — see design
-   §2, boundary constraint quadrics — and no reader-side check can distinguish an
-   exact coarse cluster from one whose error went unrecorded.
-9. `asset_id` and `header_checksum` verify per §4 — including its zeroing rule, which excludes
-   every derived checksum field; every frame verifies per §5; the directory verifies per §9 and
-   byte-for-byte matches what a frame scan reconstructs. `header_checksum` covers bytes 0–255
-   only, so the level table's integrity rests on `asset_id`, which covers the whole file.
-10. Every page's node table is a tree over exactly that page's groups: node 0 is the root, an
-   interior node's children are a contiguous run at a strictly greater index, `1 ≤ child_count ≤ 4`,
-   and the leaves partition the group table — each group reached through exactly one leaf. Each
-   node's metric bounds its whole subtree: its sphere contains every child's, its `min_self_error`
-   is no greater than any child's, its `max_parent_error` no less. The page header's metric equals
-   the root node's. The table begins at `56 + 8·group_count` — derived, because the page header
-   carries no offset for it since version 6 — and the `u16` at 22 that its offset used to occupy is
-   zero.
-11. Every child-table entry's metric equals the header metric of the page it names. It is a copy
-   read before that page is fetched, so nothing else can catch it having drifted — and a traversal
-   that trusts a stale one skips a page it needed and leaves a hole.
-12. Every frame names a defined `codec` (§5); a raw frame's `stored_size` equals its
-   `decoded_size`; and no frame's `decoded_size` exceeds what its codec could produce from
-   `stored_size` bytes. Every blob decodes to exactly `decoded_size` — neither short nor long. A
-   short decode is a truncated page, and a page truncated to a plausible prefix is the one
-   corruption that reads as valid geometry with pieces missing; a long one is a blob that would
-   write past what the reader allocated from `decoded_size`, and is stopped while it is producing
-   rather than measured afterwards.
-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. `level_count ≥ 1`,
-   and no page's `max_level` reaches it.
-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.
-
-15. **Parent-table bounds.** `parent_entry_count ≤ 65,535`, so that a group record's u16
-    `parent_first` can index the whole table, and `parent_page_count ≤ parent_entry_count`, since
-    no entry can name more than one page. The first is a cap rather than a wider field because the
-    distance is not close: the worst page of 8,899 measured carries 26 entries, which leaves the
-    bound standing 2,521× above it, and widening `parent_first` would cost the group record its
-    8-byte size. A builder that ever approached the cap would split the page.
-
-16. **The two edges agree.** Every entry of a page's group-parent table (§6.3) resolves to a
-    cluster whose `child_group` is the group whose run the entry is in; each group's run holds
-    exactly the clusters that name it, with no repeats; and the run is sorted by
-    (page index, cluster index). The first is what makes a coarsen legal at all. The third is what
-    lets a runtime elect one appender out of a group's several parents by taking the first entry of
-    the run, rather than carrying a dedup bitmask sized by instances × groups — so the order is
-    load-bearing and not presentation.
-
-17. **`subtree_aabb` bounds the subtree.** It contains the cluster's own `aabb` and, for every
-    cluster of the group the cluster refines into, that cluster's `subtree_aabb` — so by induction
-    it contains every vertex anywhere below the cluster in the DAG. A leaf's equals its `aabb`.
-
-    **Exact, on the stored values, with no tolerance.** A union of float32 extremes is a float32
-    extreme, so unlike the spheres there is nothing here for rounding to eat and nothing to inflate
-    against it. That is half of why the runtime cull is a box: the other half is that a subtree of a
-    surface is a flat patch, and its AABB is a fraction of the volume of any sphere around it.
-
-    **Why the subtree and not the cluster.** The runtime's per-cluster frustum test decides whether
-    a cluster refines into its child group, so culling it removes that whole group — and everything
-    under it — from the cut. A step consumes one group and produces several parents, each naming the
-    *whole* consumed group, so what is reachable below a cluster carries its siblings' surface too
-    and grows with depth. A bound that covered only the cluster would cull a parent with on-screen
-    descendants, and a culled subtree leaves a hole with nothing standing in over it.
-
-## 12. Open
-
-- ~~Page codec ids beyond raw and LZ4~~ — `2` is raw DEFLATE through the platform's own zlib (§5)
-  and is what the builder writes by default: 1.369x against LZ4's 1.295x on the same pages, for four
-  and a half times the decode. Still open is a codec that knows what it is compressing —
-  meshopt-style over the payload rather than an LZ matcher over its bytes. The quantized-position `payload_encoding` is the other half of the same
-  question, and would take most of what either general-purpose codec currently finds.
-- ~~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).
-- Multi-geometry containers (v1: one geometry per file; scenes reference many files).