@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,607 +1,607 @@
-# `.vgeo` — Virtual Geometry Container Format
-
-Status: **writer and validator implemented; no reader yet.** 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 — and `build/` is the pipeline that produces it from a `Geometry`, glTF front end
-included. The node command line over both is at `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. The runtime side (pager, residency, cut pass) is still design only.
-
-## 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           | breaking layout changes only |
-| 6      | u16       | min_reader_version       | 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 |
-| 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        | build parameter, bytes; informational — readers MUST NOT assume (§11.5 exception) |
-| 100    | u16       | reserved                 | |
-| 102    | u8        | level_count              | levels `0..level_count-1` |
-| 103    | u8        | reserved                 | |
-| 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) |
-
-### 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 — 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.
-
-| 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; 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, and paying it 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.
-
-`1` is a **bare LZ4 block**, not an LZ4 frame: LZ4's own framing carries a magic, a
-checksum and a content size that this frame already carries better, and `decoded_size`
-is what the block is decoded against. Blocks are independent — 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 — *before* the allocation. A block 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.
-
-**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 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 ] [ Payload ]
-```
-
-PageHeader:
-
-| offset | type | field                 | notes |
-|-------:|------|-----------------------|-------|
-| 0      | u16  | group_count           | ≥ 1; group table immediately follows the header |
-| 2      | u16  | cluster_count         | ≥ 1 |
-| 4      | u8   | min_level             | page band; non-root pages span one contiguous band |
-| 5      | u8   | max_level             | |
-| 6      | u16  | node_count            | ≥ 1; ≤ 2·`group_count` (§6.1) |
-| 8      | u32  | cluster_table_offset  | |
-| 12     | u32  | payload_offset        | |
-| 16     | u32  | payload_size          | |
-| 20     | u32  | node_table_offset     | = `56 + 8·group_count`; the node table follows the group table |
-| 24     | [u8; 8] | reserved           | |
-| 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) |
-| 6      | u16  | reserved             | |
-
-### 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. Two kinds of spheres, 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) and the
-**culling bounds** (`bounds_sphere`/`aabb` — this cluster's own tight fits, never used
-in the cut test):
-
-| 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; 4] | bounds_sphere   | this cluster's own minimal bounding sphere (miniball), object-space — culling |
-| 56     | [f32; 6] | aabb            | this cluster's object-space AABB — culling, GPU metadata `bounds_box`, and the (future) dequantization grid |
-| 80     | u16      | child_ref       | index into this frame's child table; `SAME_PAGE` when the child group is in this page; `NO_CHILD` for leaves |
-| 82     | u16      | child_group     | group index within the child page (or this page, for `SAME_PAGE`); `NO_GROUP` for leaves |
-| 84     | u32      | cone_reserved   | reserved for backface-cone culling — **write 0**. No cull pass consumes a cone today and the producer needs a `BinaryTopology` port; the sub-encoding is pinned together with that pass, not before |
-| 88     | u32      | encoding_flags  | frozen bit table in §8 |
-| 92     | u32      | payload_offset  | into this page's payload section; ≡ 0 (mod 4) |
-| 96     | u32      | payload_size    | bytes; ≡ 0 (mod 4) |
-| 100    | u8       | vertex_count    | 3 ≤ n ≤ 128 |
-| 101    | u8       | triangle_count  | 1 ≤ n ≤ 128 |
-| 102    | u16      | reserved        | |
-| 104    | u64      | reserved        | |
-
-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     | u8   | min_level      | |
-| 17     | u8   | max_level      | |
-| 18     | u16  | flags          | bit 0: root page |
-| 20     | u16  | group_count    | |
-| 22     | u16  | cluster_count  | |
-| 24     | u64  | 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:
-
-- Cold start: 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.
-- **Refinement**: 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.
-- **Activation (closure without dependency lists)** — 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**: 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.
-- **Eviction**: 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.
-- 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).
-- 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.
-- 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).
-- 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.
-- Never assume `nominal_page_size`; per-page sizes come from child tables (traversal),
-  frames (prefix scan), or the directory (special tasks).
-
-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. A page holding one indivisible oversized group MAY exceed
-   `nominal_page_size`; the hard bound is the frame's u32 `stored_size`.
-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.
-   `bounds_sphere` and `aabb` contain the cluster's decoded vertices; the header's
-   `object_sphere` and `object_bounds` contain the normalized source mesh.
-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.
-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` — 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.
-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.
-
-## 12. Open
-
-- Page codec ids beyond raw and LZ4 (§5). LZ4 is the default and is where the cheap
-  ratio is; a slower, denser codec (meshopt-style over the payload, deflate-family over
-  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).
-- 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).
-- Backface-cone cull pass and, with it, the `cone_reserved` sub-encoding.
-- Multi-geometry containers (v1: one geometry per file; scenes reference many files).
+# `.vgeo` — Virtual Geometry Container Format
+
+Status: **writer and validator implemented; no reader yet.** 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 — and `build/` is the pipeline that produces it from a `Geometry`, glTF front end
+included. The node command line over both is at `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. The runtime side (pager, residency, cut pass) is still design only.
+
+## 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           | breaking layout changes only |
+| 6      | u16       | min_reader_version       | 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 |
+| 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        | build parameter, bytes; informational — readers MUST NOT assume (§11.5 exception) |
+| 100    | u16       | reserved                 | |
+| 102    | u8        | level_count              | levels `0..level_count-1` |
+| 103    | u8        | reserved                 | |
+| 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) |
+
+### 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 — 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.
+
+| 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; 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, and paying it 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.
+
+`1` is a **bare LZ4 block**, not an LZ4 frame: LZ4's own framing carries a magic, a
+checksum and a content size that this frame already carries better, and `decoded_size`
+is what the block is decoded against. Blocks are independent — 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 — *before* the allocation. A block 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.
+
+**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 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 ] [ Payload ]
+```
+
+PageHeader:
+
+| offset | type | field                 | notes |
+|-------:|------|-----------------------|-------|
+| 0      | u16  | group_count           | ≥ 1; group table immediately follows the header |
+| 2      | u16  | cluster_count         | ≥ 1 |
+| 4      | u8   | min_level             | page band; non-root pages span one contiguous band |
+| 5      | u8   | max_level             | |
+| 6      | u16  | node_count            | ≥ 1; ≤ 2·`group_count` (§6.1) |
+| 8      | u32  | cluster_table_offset  | |
+| 12     | u32  | payload_offset        | |
+| 16     | u32  | payload_size          | |
+| 20     | u32  | node_table_offset     | = `56 + 8·group_count`; the node table follows the group table |
+| 24     | [u8; 8] | reserved           | |
+| 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) |
+| 6      | u16  | reserved             | |
+
+### 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. Two kinds of spheres, 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) and the
+**culling bounds** (`bounds_sphere`/`aabb` — this cluster's own tight fits, never used
+in the cut test):
+
+| 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; 4] | bounds_sphere   | this cluster's own minimal bounding sphere (miniball), object-space — culling |
+| 56     | [f32; 6] | aabb            | this cluster's object-space AABB — culling, GPU metadata `bounds_box`, and the (future) dequantization grid |
+| 80     | u16      | child_ref       | index into this frame's child table; `SAME_PAGE` when the child group is in this page; `NO_CHILD` for leaves |
+| 82     | u16      | child_group     | group index within the child page (or this page, for `SAME_PAGE`); `NO_GROUP` for leaves |
+| 84     | u32      | cone_reserved   | reserved for backface-cone culling — **write 0**. No cull pass consumes a cone today and the producer needs a `BinaryTopology` port; the sub-encoding is pinned together with that pass, not before |
+| 88     | u32      | encoding_flags  | frozen bit table in §8 |
+| 92     | u32      | payload_offset  | into this page's payload section; ≡ 0 (mod 4) |
+| 96     | u32      | payload_size    | bytes; ≡ 0 (mod 4) |
+| 100    | u8       | vertex_count    | 3 ≤ n ≤ 128 |
+| 101    | u8       | triangle_count  | 1 ≤ n ≤ 128 |
+| 102    | u16      | reserved        | |
+| 104    | u64      | reserved        | |
+
+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     | u8   | min_level      | |
+| 17     | u8   | max_level      | |
+| 18     | u16  | flags          | bit 0: root page |
+| 20     | u16  | group_count    | |
+| 22     | u16  | cluster_count  | |
+| 24     | u64  | 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:
+
+- Cold start: 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.
+- **Refinement**: 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.
+- **Activation (closure without dependency lists)** — 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**: 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.
+- **Eviction**: 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.
+- 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).
+- 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.
+- 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).
+- 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.
+- Never assume `nominal_page_size`; per-page sizes come from child tables (traversal),
+  frames (prefix scan), or the directory (special tasks).
+
+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. A page holding one indivisible oversized group MAY exceed
+   `nominal_page_size`; the hard bound is the frame's u32 `stored_size`.
+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.
+   `bounds_sphere` and `aabb` contain the cluster's decoded vertices; the header's
+   `object_sphere` and `object_bounds` contain the normalized source mesh.
+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.
+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` — 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.
+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.
+
+## 12. Open
+
+- Page codec ids beyond raw and LZ4 (§5). LZ4 is the default and is where the cheap
+  ratio is; a slower, denser codec (meshopt-style over the payload, deflate-family over
+  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).
+- 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).
+- Backface-cone cull pass and, with it, the `cone_reserved` sub-encoding.
+- Multi-geometry containers (v1: one geometry per file; scenes reference many files).