@woosh/meep-engine 3.28.0 → 3.30.0

package/src/shade/playground/caldera/README.md

@@ -0,0 +1,529 @@
+# `caldera` — a production map, whole
+
+Activision's [Caldera](https://github.com/Activision/caldera) — the Call of Duty: Warzone map — is
+17.5 million primitives and two billion points across two miles square, released as OpenUSD. This
+page converts it and hands the whole thing to the ordinary renderer.
+
+That last part is the point, and it is what makes this page different from
+[`../vgeo_scene/`](../vgeo_scene/README.md). `vgeo_scene` asks what a virtual-geometry cut costs
+across a whole scene, and to answer it puts *every* asset on the virtual backing, because the cut is
+the subject. This page asks the opposite question — **what does meep do when a real production map
+arrives all at once** — so the default backing is the plain meshlet path every game asset takes,
+the placements are ordinary mesh rows, and virtual geometry is a *promotion* a few hundred of the
+largest geometries get. Which is how a game would actually use it, and which puts both paths in one
+frame instead of across two pages.
+
+## Converting it
+
+Caldera is 63,683 binary crate (`PXR-USDC`) layers composed through sublayers, references, payloads,
+variants and native instancing. meep reads USD — `src/format/scene/usd/` — but only the ASCII form
+of a single layer, and it warns on a `references` arc rather than following one. Composition is what
+this data *is*, so the extraction runs under OpenUSD and nothing downstream of it knows USD exists.
+
+```bash
+pip install usd-core numpy
+python tools/caldera/caldera_extract.py H:/git/caldera H:/tmp/caldera-extract
+node tools/caldera/caldera_build.js H:/tmp/caldera-extract H:/git/caldera/meep
+```
+
+The first step is composition and nothing else: it opens each district at its `districtLod=full`
+variant, walks the composed stage, and writes triangle soup and matrices. The second is the engine's
+own code — meshlets, the BLAS, `.vgeo` — run offline across every core. `H:/tmp/caldera-extract` is
+scratch and can be deleted the moment the build finishes; `H:/git/caldera/meep` is the converted
+set.
+
+Both tools' docblocks are the reference for their options. The two decisions worth repeating here:
+
+- **Distinctness is content, not provenance.** Two placements of one model are two prims at two
+  paths, and keying on the layer that authored the points misses that one model is authored in
+  several prefabs. On `map_airfield` the layer key finds 88,583 distinct geometries where a content
+  hash finds 64,438 — a quarter of that district's containers would have been duplicates. The layer
+  key survives as a *pre*-filter, which is what keeps 3.8 million placements down to 683 thousand
+  mesh reads.
+- **The BLAS travels in the packs, and that is a measurement.** It is **51% of them** — the same
+  two districts build to 250.8 MiB with it and 122.9 MiB without — and leaving it out does not mean
+  shipping without one: `MeshletGeometrySerializationAdapter` rebuilds a missing BVH on load, at a
+  measured **34 ms per MiB saved** on this geometry. Over the whole set that is **253 seconds of
+  blocked main thread** to save 7.3 GiB of transfer off a local disk, which is the wrong way round
+  for a set whose point is how fast it opens. `--no-blas` inverts the trade for a slow network, and
+  watching it invert is a reasonable thing to do with this page.
+
+## Running it
+
+Three things: the dev server in front of the page, an asset server in front of the converted set,
+and a browser.
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+node tools/geometry/virtual/vgeo_serve.js H:/git/caldera/meep
+```
+
+Then `/src/shade/playground/caldera/index.html`.
+
+**With no parameters it opens all forty-five districts, and it does not survive that** — the device
+runs out of memory somewhere past two million rows. That and the dispatch ceiling this page found
+first, which is fixed, are both in [What broke](#what-broke-and-what-it-took), and finding them is
+what the default is for. The picture fills in district by district while it runs rather than
+appearing at the end, and the panel turns the placement count red past the largest row count this
+set has been held to fit in VRAM.
+
+For a look at the thing rather than at its limits, name a district: `?districts=map_capital` is
+487,464 placements in 19.5 s, `?districts=map_ruins` is 30,250 in under one, and `?districts=st_o`
+is the island's terrain in three. `?placements=1040000` is the largest scene measured, though it is no longer a correctness bound.
+
+**The asset server is not optional and Vite cannot replace it.** A `.vgeo` is streamed by `Range`
+and its reader refuses anything but a `206` naming the range it asked for; the meshlet packs are
+read the same way, by coalesced range, and a `200` there is a server handing back the head of a
+256 MiB file where the page asked for the middle of a geometry — silently, with entirely plausible
+bytes. Vite also refuses `/@fs/` outside the workspace, and a converted Caldera has no business
+inside one. `vgeo_serve.js` is ranges, CORS and nothing else.
+
+| parameter | what it does |
+|---|---|
+| `?districts=a,b` | open only these, in manifest order. The camera frames the first. |
+| `?placements=N` | stop after N rows. The way back down from a machine that cannot hold the map. |
+| `?vgeo=off` | draw the promoted geometries from their meshlet blobs instead |
+| `?tau=N` | the virtual cut's error threshold in pixels, before the first container opens |
+| `?pages=N` | page slots in the VRAM tier (default 16,384) |
+| `?side=front\|back\|double` | the whole map's draw side — `double` is the winding diagnostic |
+| `?origin=URL` | where the asset server is (default `http://localhost:5200`) |
+| `?scene=URL` | a manifest outright, for a set that is somewhere else |
+
+## What the converted set is
+
+```
+caldera.meep.json     the manifest: districts, packs, vgeo containers, bounds — a page of text
+geometry.table.bin    one 56-byte row per distinct geometry: where its blob is, how big it is
+pack.NNNN.mgpack      serialized MeshletGeometry blobs, concatenated in geometry-id order
+district/<name>.bin   that district's placements: geometry ids, then 4x4 matrices
+vgeo/<asset_id>.vgeo  the promoted geometries and the merged ones, as virtual-geometry containers
+```
+
+Three things about this shape are load-bearing.
+
+**The packs hold `MeshletGeometry`, which is the engine's own offline format.**
+{@link MeshletGeometrySerializationAdapter}'s docblock says so and says why: building meshlets at
+load costs *1,246 ms of unbroken main thread per 199k triangles*, measured, and reported as a defect
+when a level loader did it. Caldera is two orders of magnitude past that. So opening a district here
+is a range request, a deserialize and an upload, with no geometry processing anywhere on the path —
+and the panel's `open` row is that claim in milliseconds.
+
+**Packs rather than files.** Half a million geometries is half a million files a filesystem handles
+badly and a browser handles worse. Because the extractor assigns ids in first-use order, a
+district's own geometry lands in a contiguous run of one pack, and `caldera_coalesce_ranges` turns
+that layout into a handful of long reads — `map_ruins`' 900 geometries come out of **two** range
+requests with no over-fetch at all.
+
+**The geometry table is a table.** Half a million rows of JSON is tens of megabytes a page has to
+parse before it can draw anything; 56 fixed bytes a row is a `fetch` and six typed arrays. It
+carries each geometry's own bounds because the questions a page asks *before* fetching a geometry —
+where a district is, what is worth opening first — are questions about bounds.
+
+## Where the two backings meet
+
+`VirtualGeometry extends MeshletGeometry`, and that one fact is why this page can mix them at all:
+`place_primitive` takes either and the placement path never learns which it was handed. So the
+choice is per geometry and it is made twice —
+
+- **offline**, by `--vgeo-min-triangles`: a geometry past the threshold gets a `.vgeo` built for it
+  *as well as* its meshlet blob, never instead of it;
+- **at runtime**, by `?vgeo=off`: the page picks which of the two it opens, and the one it does not
+  open is never fetched.
+
+What that buys is an honest comparison inside one scene. The same map, the same rows, the same
+frame, with a few hundred of its heaviest geometries moved from "fetch and upload the whole thing"
+to "fetch a 2.5 KiB head and then whatever a threshold in pixels asks for".
+
+## The terrain is one asset, and that is the point of it
+
+Caldera's ground is a heightfield the source cut into pieces. The fourteen largest sit on an **exact
+832 m grid** aligned to the origin, one per `st_*` district, at one to two million triangles each:
+
+| geometry | triangles | x | z |
+|---|---:|---|---|
+| `st_k` | 2,087,424 | [0, 832] | [0, 832] |
+| `st_g` | 1,989,414 | [0, 832] | [-832, 0] |
+| `st_f` | 1,989,044 | [-832, 0] | [-832, 0] |
+| `st_j` | 1,822,742 | [-832, 0] | [0, 832] |
+| `st_o` | 1,656,202 | [0, 832] | [832, 1608] |
+
+Under them are finer patches at 54-89 m footprints. In all it is **452 distinct geometries placed
+728 times**, spanning 2,889 x 195 x 3,194 m, with summed footprints 0.89 of the union area — a
+tiling, not a scatter, and every piece placed exactly once.
+
+Converted a geometry at a time that is 728 containers: 728 cluster DAGs over one connected surface,
+728 roots, 728 sets of error bounds, and a cut that has to arbitrate between them at every seam.
+Virtual geometry is built for the opposite — one DAG over one surface, where a coarse level is free
+to simplify **across** a boundary because the boundary is not there any more. So
+`caldera_build.js --merge terrain` bakes every placement into world space, concatenates, and builds
+one `.vgeo` from the result. One container. One row.
+
+**Which geometry is ground cannot be decided from the geometry.** A 60 m terrain patch and a 60 m
+rock are indistinguishable by any test you can write over bounds and triangle counts — the first
+attempt here used a flatness ratio and threw away four of the fourteen grid tiles, because a tile of
+the volcano is 232 m tall over its 832 and is no less part of the ground for it. Provenance decides
+it instead: Caldera's terrain is authored under `superterrrain/` (its own spelling) and nothing else
+is, so `caldera_extract.py --group terrain=/superterrrain/` tags it at the source and the builder
+acts on the tag.
+
+**What is deliberately not merged is everything standing on it.** The `st_*` districts also hold
+38,257 distinct geometries across 417,094 placements — rocks, foliage, scatter — and those are
+heavily instanced: `st_k` alone places 8,051 of its geometries more than once. A geometry placed a
+thousand times is one container and a thousand matrices, which is the cheapest it will ever be;
+baking it out would turn 1,152 triangles into 1.1 million.
+
+Two things the merge has to get right, both of them silent when wrong:
+
+- **Normals go through the linear part and are renormalized**, not through the whole matrix. The
+  inverse transpose is the general answer and is unnecessary for rigid-plus-uniform-scale, which
+  every terrain placement here is — and the baker counts and reports any that are not, rather than
+  quietly mis-shading them.
+- **A reflected placement has its winding reversed in the indices.** The engine reverses a reflected
+  *instance* in the vertex shader off the row's own flag, and a merged asset has no per-piece
+  instance left to carry that, so the reversal has to happen at bake time or the piece is inside out
+  inside an otherwise correct surface.
+
+The merged asset is placed at the identity, has no meshlet blob to fall back to, and so is drawn
+through the virtual path whatever `?vgeo=off` says — that switch moves the *promoted* geometries and
+has nothing to move the ground onto.
+
+### What it came to
+
+| | |
+|---|---:|
+| source | 728 placements of 452 geometries |
+| triangles | **20,242,704** |
+| vertices | 10,140,561, welded down from 56,888,124 |
+| levels / clusters / pages | 52 / 437,999 / 3,142 |
+| container | **480.3 MiB** |
+| bake / build | 2.2 s / 1,465 s |
+| weld distance | 4.3 cm |
+
+**The vertex count is the part worth reading.** 56.9 million corner vertices welded to 10.1 million
+is a 5.6x collapse, and most of it is the tile seams: two tiles that shared an edge shared its
+vertices, and as separate assets each kept its own copy and each DAG stopped dead at the boundary.
+As one asset the seam is interior, and a coarse level simplifies straight through it.
+
+The effect on the set is that the ground stops being resident. **452 geometries and 728 rows become
+one container and one row**, the packs fall from 14.35 to **12.02 GiB**, and what is resident of the
+terrain is whatever the cut asked for — 598 pages of 3,142 with the capital in view. `map_capital`
+opens in **12.6 s against 19.5 s** before the merge, for the same picture plus the whole island
+underneath it.
+
+52 levels over a 4.3 km asset is deep, and it is what a single DAG over a 3 km surface should look
+like: each level halves, so the root is a few hundred triangles covering two square kilometres.
+That is the thing 452 separate DAGs could not do.
+
+## What the panel is saying
+
+`__state()` is the whole surface, and the panel shows nothing that is not in it — so a headless
+session and a screenshot can never disagree about what a frame did.
+
+**scene** is the conversion's claims. `source triangles` is the distinct geometry that has been
+opened; `instanced triangles` is what those geometries come to once every placement of them is
+counted, and the ratio between the two is how much of this map is reuse. `fetched` is every byte the
+page has pulled — packs, table, placements and container heads together. `open` is wall-clock from
+the first district's first byte to its last row.
+
+**frame** is `frame` (the rAF delta, smoothed) against `cpu` (measured around `render` alone). At
+this scale they separate: `cpu` is what the scene costs the main thread and `frame` is what the GPU
+and the compositor add to it.
+
+`mesh collection` and `meshlet collection` are the rasterization collections' **limits**, not their
+counts — what they have had to grow to in order to hold what the frame handed them. A collection
+that stops growing while placements keep arriving is one dropping the difference.
+
+`dropped` is **virtual geometry's drops only**, because the ordinary meshlet path publishes none.
+A zero there is not a statement that the frame is complete, and the dispatch ceiling below is what
+that gap cost when it was open: every counter on this panel reported a healthy frame while the
+screen was empty. The gap itself is still there — the fix removed the thing that fell into it, not
+the hole.
+
+**virtual geometry** is `vgeo_scene`'s panel in miniature. `clusters drawn` is what the cut selected
+this frame; `pages resident` against the tier's capacity is how close the budget is to being what
+selects the cut rather than the threshold; `refused / clamped` going non-zero is that having
+happened.
+
+The descent is seeded with one item per visible virtual instance, so `queue_capacity` is sized from
+the set's instance count rather than fixed — 12,147 instances at a 20,000-triangle promotion and
+172,764 at 4,096 are not the same scene for it, and an overflowed frontier is *thrown away* rather
+than refused. `?queue=` overrides, and `dropped` includes `queue_dropped` for exactly that reason.
+
+## What the conversion came to
+
+| | |
+|---|---:|
+| districts | 45 |
+| placements | 3,790,047 |
+| distinct geometries | **478,006** (of 683,222 by layer — content hashing collapsed 30%) |
+| distinct triangles | 122,483,082 |
+| **instanced triangles** | **2,692,595,763** |
+| placements after the terrain merge | 3,789,319 |
+| meshlet packs | 49 files, **12.02 GiB** |
+| geometry table | 25.5 MiB |
+| `.vgeo` containers | **7,148 promoted (1.80 GiB)** + 1 merged terrain (480.3 MiB) |
+| refused | 0 |
+
+**43 minutes of wall clock**: 13.4 for the USD composition, 6.3 for the meshlet and `.vgeo` build
+across 16 threads, and **23.6 for the merged terrain alone** — one 20-million-triangle DAG, on one
+thread, holding 24 GiB while it works. The intermediate between the two steps is 9.20 GiB and is
+deleted afterwards.
+
+The instanced-to-distinct ratio is **22:1**, and that is the number the whole design rests on: 2.7
+billion triangles stand on 122 million, because a geometry placed a thousand times is one container
+and a thousand matrices. The largest districts are `map_docks` (535,436 placements, 267.9M instanced
+triangles), `map_capital` (487,464 / 195.9M) and `map_airfield` (363,145 / 163.7M).
+
+**7,148 of 478,006** geometries — 1.5% — are past the default 4,096-triangle promotion, and between
+them they carry **68.4M of the 102.3M triangles that are not already in the merged terrain**. That
+ratio is the whole case for the threshold, and it is why the default is 4,096 rather than the 20,000
+this page started with; the measurement is below.
+
+## Measured
+
+An nvidia/lovelace adapter at 1578×746 in headless Chrome, against `vgeo_serve.js` on the same
+machine — so `fetched` is local disk rather than a network, which is the honest framing for a
+load-time claim and not the same claim over the wire.
+
+| scene | placements | geometries | instanced tris | fetched | open | frame / cpu |
+|---|---:|---:|---:|---:|---:|---:|
+| `map_ruins` | 30,250 | 900 | 23.5M | 168 MiB | **0.9 s** | — / 3.9 ms |
+| `map_ruins` + `map_gulags` | 90,400 | 3,385 | 63.1M | 257 MiB | **1.2 s** | — |
+| `st_o` (terrain) | 51,844 | 9,762 | 103.5M | 1.15 GiB | **3.0 s** | 33 / 10.2 ms |
+| 3 districts | 283,016 | 73,608 | 182.2M | 844 MiB | **4.3 s** | 33 / 6.4 ms |
+| `map_capital` | 487,464 | 116,512 | 195.9M | 1.67 GiB | **19.5 s** | 56 / 8.3 ms |
+| `map_capital` + merged terrain | 487,465 | 116,513 | 216.1M | 1.67 GiB | **16.4 s** | 48 / 7.4 ms |
+| the same at a 4,096 promotion | 487,465 | 116,513 | 216.1M | **1.17 GiB** | **13.7 s** | **35** / 7.6 ms |
+| 6 districts at 4,096 | 1,040,000 | 192,283 | 575.8M | **0.91 GiB** | **29.5 s** | **63** / 12.2 ms |
+| 6 districts, capped | **1,040,000** | 192,282 | **555.6M** | 2.15 GiB | **44-54 s** | 83 / 12.9 ms |
+
+The 1,040,000-row scene is a round number rather than a district boundary because it was measured
+against the dispatch ceiling below, **before** that was fixed in `962e79183`. Every row here except
+the merged-terrain one predates that fix, so they are a floor rather than a ceiling now; the scenes
+past a million rows want re-measuring.
+
+Open times move with the file cache — the same `map_capital` measured 12.6 s once, immediately after
+its own build, against 16.4 s and 21.0 s later. The warm figure is the one quoted, and an A/B is only
+honest if both sides are measured in the same state.
+
+The `map_capital` rows are the two dials, in order: the terrain merge put **more** geometry on screen
+(the whole island rather than one district's footprint) for less time, because 452 resident
+geometries became one container that streams; and the 4,096 promotion took another 30% off the bytes
+and a quarter off the frame.
+
+**The load-time claim holds, and the conversion is what makes it hold.** `map_capital` is 116,512
+distinct geometries and 14.1 million distinct triangles open in 19.5 seconds — a range request, a
+deserialize and an upload per geometry, and nothing else on the path.
+`meshlet_geometry_build_from_geometry` runs at **3.3 µs a triangle** on this machine, measured, so
+building the same district's meshlets at load would put **47 seconds of unbroken main thread** on
+top of that; the whole set would be **6.7 minutes**. That is the entire reason the packs hold
+`MeshletGeometry` and not triangles.
+
+`dropped` is zero throughout: the rasterization collections grew to hold the district (947,512
+meshes and 4,504,447 meshlets for `map_capital`) rather than discarding what would not fit.
+
+## What broke, and what it took
+
+This is the part the page exists for. Every one of these is an engine limit a production map found
+and no playground before it had.
+
+### The picture broke at 2²⁰ mesh rows — fixed, and it was never rows
+
+This is the first wall this page hit and the worst one, because nothing reported it. It is fixed:
+`962e79183` and `53deaa9b5`, *"the dispatch that will not fit one dimension is a grid, and the
+engine already flattens those"*.
+
+| rows | what is drawn |
+|---:|---|
+| 1,000,000 | correct |
+| 1,040,000 | correct |
+| **1,048,576 = 2²⁰** | |
+| 1,060,000 | **nothing** |
+| 1,100,000 | **nothing** |
+| ~1,564,000 | **garbage** — huge untextured triangles fanning across the frame |
+
+Each of those is the same scene loaded to a different `?placements=`, the same camera, the same
+first district in front of it. At 1,040,000 rows it is 555.6M instanced triangles at 81 ms a frame
+and 14.8 ms of CPU. At 1,060,000 it is an empty ocean.
+
+**Every counter says the frame is fine.** `dropped` is 0, the collections report 1,060,000 meshes
+and 12,487,826 meshlets, no WebGPU error is raised, nothing is logged, `render` does not throw, and
+the frame time goes *up* rather than down. The garbage at 1.5M is the same failure with the camera
+somewhere the corrupted geometry happens to cover — which says the rasterizer is fetching vertices
+from the wrong place rather than being handed nothing.
+
+The panel's own `dropped` row cannot catch this either: it reads the virtual-geometry cut's drop
+counters, and this is the ordinary meshlet path, which publishes none.
+
+**The diagnosis this page reached was wrong, and the way it was wrong is the lesson.** The paragraph
+that used to sit here ruled out `maxComputeWorkgroupsPerDimension` on the grounds that 65,535
+workgroups at the engine's group size of 128 comes to 8,388,480 — far past 2²⁰ — and went looking for
+a 20-bit field instead. The arithmetic was right and it was applied to the wrong quantity: **that
+dispatch is over meshlets, not rows.** This scene carries about twelve meshlets per row, so a
+`?placements=` knob that looks like it moves one number moves three, and 2²⁰ rows is simply where
+*this* scene's visible meshlet count crossed the real ceiling. A page with one knob for three
+quantities cannot say which of them broke, and this one confidently said the wrong one.
+
+What it actually is: **an indirect dispatch asking for more than 65,535 workgroups does not run at
+all.** Measured against Dawn on nvidia/lovelace — 65,535 workgroups write their elements, 65,536
+write none, with no validation error and nothing logged. Not a short pass; no pass. The collection's
+`count` was advanced by a separate single-thread dispatch either way, so every counter reported a
+complete frame over an element array nothing had written, and the rasterizer drew whatever the
+pooled frame-graph buffer last held — which is exactly the torn geometry at 1.5M.
+
+The fix is in `IndirectComputeCommandBuildPass`: a count that will not fit `x` is **folded** into
+`y` and then `z`, and the passes these commands drive flatten the grid back with
+`chunk_grid3d_to_index` — the same flattening the light and decal clusters have always used —
+instead of reading `global_invocation_id.x`, which carries the x dimension alone. One thread per
+element still, nothing dropped, and while `y` and `z` are 1 the index is `global_invocation_id.x`
+term for term, so a scene under the ceiling pays nothing for it. (The first attempt had each pass
+walk its collection with a stride loop instead, off a chunk written for the occasion; a workgroup
+count spread over three dimensions *is* a 3D grid, and the engine could already flatten one.)
+
+Folding is opt-in, because it is only correct once the shader on the other side indexes for it: a
+pass left on `global_invocation_id.x` under a folded command would run its first 8,388,480 elements
+once per `y`, which is worse than dropping the rest. The meshlet-scale passes take it and nothing
+else does — a scene is capped at 3,047,424 mesh rows by the `transforms` table, which is 23,808
+workgroups, so the mesh-scale passes cannot reach the ceiling to begin with.
+
+The cheap repro that found it is [`../mesh_row_ceiling/`](../mesh_row_ceiling/README.md), which has
+**one knob per quantity** — `?rows=` moves instances and `?segments=` moves meshlets per instance —
+and that separation is what this page could not offer. It also measures `coverage`, the fraction of
+canvas that is not the clear colour, because when every engine counter is lying the pixels are the
+only honest signal.
+
+### The BLAS node arena's region ceiling — fixed
+
+`GPUGeometryBVHManager` sized its allocator at **32,768 regions**, one per live tree plus the free
+gaps between them, on the stated reasoning that a scene's trees are "one per geometry plus one per
+skinned instance, so this is thousands of instances of headroom". Caldera's `map_capital` has
+116,512 distinct geometries and the whole map 478,006, so loading a *single district* asserted
+partway through:
+
+```
+BLAS node arena cannot place 3 nodes in 8177216; 32768 regions is the ceiling and grow() does not raise it
+```
+
+Raising it to 1,048,576 is a one-line change and it is what makes anything past a small district
+possible. It costs **28 MiB** of host memory, measured (0.93 MiB at 32,768 against 29.0 MiB at
+1,048,576), paid at construction whether a scene reaches it or not, because the allocator's node
+table is eager. The constant carries that reasoning now; a host that wants the 28 MiB back can put
+the old figure back and lose nothing but this map.
+
+That the failure was an assertion rather than a silent wrong picture is the system working.
+
+### The whole map runs out of VRAM — open, and the limit is residency
+
+All forty-five districts at once do not fit on a 24 GB card. Two runs, two ways of finding out:
+
+- the first reached **3,718,083 of 3,790,047 placements and 475,450 of 478,006 geometries** — 98% —
+  and then stopped answering: the main thread stopped returning to the point where CDP's
+  `Runtime.evaluate` no longer completed, while the GPU process held six cores busy for twenty
+  minutes;
+- the second said it outright, out of `render`, at 2,232,791 placements and 372,745 geometries:
+  **`Failed to allocate GPU memory for meshlet batch`**.
+
+Where it stops varies, which is what you would expect of a card that is also running a desktop. That
+it *says so* on the second path is the engine behaving well; the first path is the same wall reached
+through thrash rather than through a refused allocation, and there is nothing to report it.
+
+**It is cumulative, not a bad district.** `st_o` — the district the first run was inside when it
+stopped — opens **on its own in 3.0 seconds**: 9,762 geometries, 11.3M distinct triangles, 103.5M
+instanced, 1.15 GiB fetched. The same bytes, the same geometry, a fifth of a minute. What is
+different by the time the whole map reaches it is everything already resident.
+
+And residency is the whole of it. The packs are 14.35 GiB, roughly half of that is BLAS, and every
+byte is uploaded per geometry and then **kept forever** — nothing in this path evicts, because
+nothing in it was ever meant to hold a scene that did not fit. The host pays a second copy besides:
+the page holds the deserialized `MeshletGeometry` for every geometry, and Chrome was holding about
+16 GiB across its processes when the first run was killed.
+
+So the honest statement of *this* limit is: **the map ran out of VRAM at somewhere between 2.2 and
+3.7 million rows on a 24 GB card**, measured before the terrain merge and at the old 20,000-triangle
+promotion. Both of those have since moved a lot of geometry off the resident path — the ground
+entirely, and two thirds of what is left — so the wall wants re-measuring and it is further out than
+these numbers say. The way past it was never a bigger buffer. It
+is eviction, and the
+engine already has exactly one thing that does it: virtual geometry, whose two residency tiers exist
+to make the drawn set a function of the view rather than of the scene.
+
+`--vgeo-min-triangles` is the dial, and it has been turned. The reason it wants to sit so far from
+where this page started is that the distinct triangles are not where the distinct geometries are —
+counted after the terrain merge, over the 102.3M triangles that are not already inside it:
+
+| threshold | containers | instances | share of the unmerged triangles |
+|---:|---:|---:|---:|
+| 20,000 | 213 | 12,147 | 6.0% |
+| 8,192 | 4,091 | 51,236 | 49.8% |
+| **4,096** *(default)* | **7,148** | **172,764** | **66.9%** |
+| 2,048 | 10,206 | 314,965 | 74.9% |
+
+1.5% of the geometries carry two thirds of the triangles. Built both ways and measured on the same
+scenes, same camera, same page:
+
+| | thr 20,000 | thr 4,096 |
+|---|---:|---:|
+| **`map_capital`** — fetched | 1,707 MiB | **1,198 MiB** |
+| open (warm) | 16.4 s | **13.7 s** |
+| frame / cpu | 48.3 / 7.4 ms | **34.5** / 7.6 ms |
+| clusters drawn | 11,894 | **21,078** |
+| pages resident | 598 | 1,142 |
+| **1,040,000 rows** — fetched | 2.15 GiB | **0.91 GiB** |
+| open | 38.7 s | **29.5 s** |
+| frame / cpu | 87.8 / 11.5 ms | **62.6** / 12.2 ms |
+| clusters drawn | 12,579 | **33,779** |
+| pages resident | 864 | 2,083 |
+| dropped / refused | 0 / 0 | 0 / 0 |
+
+**58% fewer bytes, 29% faster frames, and 2.7x the clusters on screen** — more detail for less of
+everything, which is what moving geometry from "fetch and upload the whole thing" to "fetch a head
+and then whatever a threshold in pixels asks for" is supposed to buy. It costs 1.80 GiB of
+containers on disk and about half an hour of build.
+
+Lower is not obviously better, and this is where to stop rather than where to keep going: 2,048
+promotes half as many again for eight more percent of the triangles, and every promotion is one more
+container to open, one more geometry row in the virtual table, and more instances seeding the cut.
+172,764 instances at 4,096 is already fourteen times what 20,000 gave, which is why the page now
+sizes `queue_capacity` from the instance count rather than from a constant — see below.
+
+The page stops loading when a frame throws, keeps what it drew, and says where it got to. It did not
+before: the loader ran on for another twenty minutes behind a dead renderer, fetching geometry for a
+frame that would never come and burying the one message that explained what had happened.
+
+### Every geometry carries a BLAS, whether or not anything traces a ray
+
+Half the set's bytes are an acceleration structure for rays this page never casts, and there is no
+way for a scene that only rasterizes to decline it — `MeshletGeometrySerializationAdapter` rebuilds
+one when it is absent rather than leaving it out. Over 478,006 geometries that is ~7 GiB of disk,
+~7 GiB of VRAM and a large share of what a district spends opening.
+
+### A single geometry's deserialize is one long task
+
+The terrain tiles run to 2,087,424 triangles, and one of those is a ~250 MiB blob whose deserialize
+cannot be interrupted. The page's loop is time-budgeted around it (`DESERIALIZE_BUDGET_MS`), which
+keeps the scene responsive *between* geometries and can do nothing about one of them — the engine has
+no incremental or worker-side path from bytes to a `MeshletGeometry`, and `meshlet_geometry_transfer`
+exists precisely because someone wanted one.
+
+## The headless recipe
+
+`vgeo_runtime`'s, unchanged, and the first bullet of it is the one that costs an hour:
+**`--enable-unsafe-webgpu` and nothing else.** `--enable-features=Vulkan`, `--use-angle=vulkan` and
+`--disable-gpu-sandbox` all appear in the recipes people write down for headless WebGPU, and every
+one of them makes `requestAdapter()` return nothing on this machine — which the page then reports as
+"the browser supports WebGPU but would not provide a GPU to run on", a message that sounds like a
+driver problem and is a flag problem. Open the page as Chrome's startup URL rather than with
+`Page.navigate`, pick the CDP target by URL, and poll for `__state` rather than trusting `load`.
+
+`__state()`, `__look(eye, target)` and `__opened` are what a session drives it with.
+
+## What it does not do
+
+- **No materials, and that is the source.** Caldera ships without textures or materials — its own
+  README says so, and says the set is about the relationships between spatial elements rather than
+  about how they look. One material over the whole map is the honest representation of that.
+- **Nothing animates, and nothing simulates.** Every placement is static. Skinned prims in the
+  source are converted at their authored pose.
+- **`guide` purpose is dropped at conversion.** Those are the scene annotations — the grey boxes
+  USDView opens on — and they are not part of the map. `render` purpose is kept: that is the
+  clutter, the grass and the small scattered things, and it is most of what makes this heavy.