@woosh/meep-engine 3.60.4 → 3.60.5

package/src/shade/renderer/global_illumination/probe_clipmap/PROBE_CLIPMAP_PROPOSAL_2026_10_27.md

@@ -1,4306 +0,0 @@
-# Probe clipmap GI — proposal, 2026-10-27
-
-Status: **revision (b): Alex's review of (a) applied, and his answers on every fork. Nothing is
-built.** Written against `4a3a41928`. Paths are relative to `packages/meep-engine/src/`. No fork is
-open; §15 records how each was settled.
-
-## What changed from (a)
-
-Alex reviewed revision (a). Items 1–8 are his; item 9 follows from them.
-
-1. **No triangle work per frame.** Every mesh is cached once as a sparse, NanoVDB-style SDF in size
-   classes: 2×2×2 bricks at least, then steps of two bricks per axis (§6.2). World bricks are
-   composed from those caches (§7.7). (a) gathered triangles per cell.
-2. **Material comes from a surface cache of cards**, Unreal's idea, with Lumen's payload: diffuse
-   albedo and emissive captured per (geometry, material) pair, and recaptured when the material
-   changes (§6.5, §6.6).
-   - (a) stored a voxel material lattice, which is expensive.
-   - The path tracer's material needs uvs, which an SDF cannot give.
-   - Cards holding uvs, with the material evaluated live, were offered as an alternative. Alex chose
-     the captured material.
-3. **A primitive can be absent from the SDF world**: drawn by the camera, invisible to GI, for
-   performance (§6.1).
-4. **Brick providers.** A pass that writes requested bricks plugs in; outputs merge per brick, so the
-   representation stays sparse and only bricks that scroll in or change are written. Virtual geometry
-   has caches of its own, baked from a proxy cut from each geometry and composed as a mesh's are (§7.8,
-   S8).
-5. **Skinned meshes** use their unskinned representation, with hooks for a dense animated patch later
-   (§6.3, §7.7, §17).
-6. **Pixels pick 2 of the 8 cage probes** by Brick4's weighted reservoir sampling, after a
-   visibility-only weight pass; only the two are read (§9.1). (a) evaluated all eight.
-7. **Rough specular blends the radiance tap with GGX-convolved SH2** (§9.3). (a)'s prefiltered
-   radiance levels sit badly with WebGPU's mip limits.
-8. **`GPUGeometrySDFManager` worked and is correct**: it is the bake's reference, generalised in place
-   (§6). The Brixelizer port is a reference, not reused.
-9. **The field is signed** (D2). (a) chose unsigned because a per-cell triangle gather cannot tell
-   inside from outside. A whole-mesh bake can, so (a)'s fork 2 dissolves.
-10. **(a)'s two other forks were taken as recommended**: a sparse probe cache (D31), and the mover
-    list at scene level with a skinned bit (D32).
-
-What was asked for:
-
-- A real-time GI built on 3-D clipmaps, selected by a new value of `ShadeIndirectLightingMode`, as a
-  separate subsystem.
-- Rays hit an SDF. Material comes from a scene representation beside it: voxels in the request, a
-  surface cache after the review.
-- The cascades are sparse, NanoVDB-style: fixed-size bricks in an atlas.
-- The SDF is 8-bit, traced with hardware texture filtering.
-- Shading samples a second 3-D clipmap, of probes. Each probe holds octahedral radiance, octahedral
-  depth, and SH2 irradiance (in this engine SH2 means L0 + L1, four coefficients).
-- Cascade count, cascade resolution, radiance and depth resolutions and rays per probe are settings.
-  They do not change between frames.
-- Existing code (the LPV above all) is reused as far as it goes, and the Enshrouded GI talk is the
-  main reference.
-- Performance and simplicity come first.
-
-## 0. Summary
-
-**Three cached representations and one sampling step.**
-
-1. **Geometry caches (§6)**, baked once and shared by every instance.
-   - A sparse SDF per geometry: 8³-texel bricks on 7³ voxels, signed `r8unorm`, on a grid of
-     (2i)×(2j)×(2k) bricks with coarser levels. The evaluator is the nearest point through the BLAS,
-     signed by UE 5.4's vote of 98 rays one band long (S3; first `GPUGeometrySDFManager`'s 64-ray vote).
-   - Surface cards: axis-aligned cards over depth slabs of the same brick grid, in 8×8-texel pages.
-     - The layout belongs to the geometry.
-     - The contents belong to each (geometry, material) pair: the material the SDF cannot hold,
-       diffuse albedo and emissive, captured through the path tracer's material sampling.
-     - They are recaptured when the material's version moves.
-   - These bakes and captures are the only place triangles are read.
-2. **The brick clipmap is the world as rays see it (§7).**
-   - `C_b` cascades of `N_b³` cells, one brick a cell on the same lattice. It is traced with one
-     hardware trilinear tap a step and a two-level skip in the NanoVDB manner.
-   - A cell that scrolled in, or that a change touched, is requested. Every registered provider writes
-     its part of the requested bricks, and the parts merge by a per-texel minimum.
-     - The mesh provider composes the cached SDFs of the instances overlapping the cell. It reads no
-       triangle.
-     - Plugins write their own; virtual geometry is the first.
-   - Each brick also names, per 2³-texel cell, the scene row whose surface is nearest. That is how a
-     hit finds its material.
-3. **The probe clipmap is what shading samples (§8)**, as in (a).
-   - A sparse cache, wanted from the depth buffer. Octahedral radiance `rgba16float`, depth moments
-     `rg16float`, SH2 in the engine's YCoCg L1 (`METRO_L1_IRRADIANCE_STRUCT`).
-   - A fixed ray budget. Hits are lit by emissive, the sun and one picked local light through shadow
-     rays traced in the bricks, and last frame's probes. Their diffuse albedo and emissive come from the
-     cards.
-4. **Pixels pick two probes (§9).**
-   - A visibility-only pass weighs the eight cage probes: trilinear × wrap back face × Chebyshev ×
-     crush.
-   - Brick4's WRS picks two. Only those two are read: their SH2 for diffuse; for specular, a radiance
-     tap blended with GGX-convolved SH2 by roughness, as LPV blends.
-
-**What is reused.**
-- `GPUGeometrySDFManager`'s evaluator (`blas_query_sdf`), `ray_query_blas_nearest` and the triangle
-  attribute chunks, for the bakes.
-- The clipmap toolkit, `GPUTileAtlas3D`, `OffsetAllocator`, the TLAS and its cooperative box query,
-  and the VSM's mover pass (moved to scene level).
-- `GPUResidentMaterialContext` and the path tracer's `sample_material_data`, for card capture.
-- The particle free list; the octahedral codec, skirt and solid-angle chunks; SH2 basis, Metro L1,
-  the GGX zonal fit and Chebyshev.
-- LPV's visibility weighting, specular blend, depth two-pass write and pass chain. Brick4's
-  reservoir pick and its noise sources.
-- The world light clusters; the deferred resolve and `compute_indirect_specular`; `ShaderSwitch`
-  binding by name; the frame-graph helpers.
-- The full map is §4.
-
-**What is new.**
-- The sparse mesh SDF storage; card placement, capture and recapture.
-- The brick clipmap's build passes, the provider contract and the mesh provider, and the tracer.
-- The probe lifetime, schedule and update passes; the pick and the sampling chunks; the Metro form of
-  the GGX resolve.
-- The `ProbeClipmap` mode value and its settings (§10).
-
-**Forks (§15).** None is open. The last two, both from (a), were taken as recommended:
-- probes are a sparse cache, not a dense lattice (D31);
-- the mover pass leaves VSM ownership for scene level (D32).
-
-## 1. What the tree has
-
-Audited read-only before designing, by area. The verdict legend is §4's.
-
-**Indirect lighting modes and their consumers.**
-- `ShadeIndirectLightingMode` = {IBL 0, Brick4 1, LPV 2}. `INDIRECT_LIGHTING` is
-  `ShaderSwitch.enum('indirect lighting', ShadeIndirectLightingMode)`, so a new member joins its
-  values by itself.
-- `Renderer#graph_indirect_lighting` (`shade/renderer/Renderer.js:1104-1313`) picks per mode a
-  diffuse/specular image-pass pair, or Brick4's fused pass when SSR is off. With SSR on,
-  `ssr.denoised` replaces the specular pass.
-- `shader_resolve_indirect_lighting` adds the pair to scene colour. Its contract: diffuse is
-  irradiance E with AO multiplied in, specular is radiance before Fresnel.
-- Exactly five chunks choose on the switch (`CodeChunkChoice.from(INDIRECT_LIGHTING)`):
-  - `forward_sample_indirect` (AVBOIT, MBOIT);
-  - `water_gi_irradiance` / `water_gi_specular`;
-  - `ssr_sample_radiance`;
-  - `ssr_add_hit_irradiance`;
-  - `irradiance_clipmap_gi_sample`, which feeds the particles' irradiance clipmap.
-- Every alternative declares its resources with `CodeChunk.requireResource`. Owners bind the union by
-  name. `switched_shaders_declare_bindings.spec.js` audits all variants.
-- **REUSE**: a new value is additive. Every file it touches is listed in §9.7.
-
-**The Light Probe Volume (LPV).** Per frame, `GPUProbeAtlas.graph_update` runs this chain:
-1. `shader_lpv_build_gbuffer`: one jittered ray per octahedral texel through `ray_query_nearest`. A
-   miss stores the sky.
-2. `graph_sample_light_probes`: hits sample the LPV itself for the next bounce, scaled by 0.97.
-3. `graph_lpv_shade`: every light, with an occlusion ray, then a temporal blend into an `r32uint`
-   rgbe9995 atlas with a one-texel border (64² texels, pitch 66).
-4. `shader_lpv_accumulate_depth` → `shader_lpv_atlas_write_depth`: depth moments in two passes,
-   because `rg16float` cannot be a read-write storage texture.
-5. Borders.
-6. `graph_lvp_atlas_to_sh` → `graph_reduce_atlas_to_sh` → `graph_lpv_store_sh`: SH2.
-
-Shading:
-- `lpv_mask_weights_by_visibility` (`shader/chunk/light/lpv/depth/`) is DDGI's weighting: the wrap
-  back-face term `((n·ω+1)/2)² + 0.2`, Chebyshev at a biased point, a crush below 0.2. It runs over the
-  four probes of a tetrahedron.
-- `chunk_lpv_sample_light` (`deferred/indirect/`) is the specular this design takes whole.
-  - The sample vector is `normalize(mix(r, n, α))`, Lagarde's dominant direction.
-  - A radiance-atlas tap along it is blended with `sh2_color_get_radiance_with_GGX` on the same
-    vector, by `roughness_to_mip_ratio(roughness)`.
-  - The ratio reaches 1, SH alone, at roughness 0.7 (`SPHERE_PROBE_MIP_MAX_ROUGHNESS`).
-
-Verdicts:
-- The chain is **GENERALISE**. It is a pass shape this design follows, but it is coupled to
-  `lpv_probes`, the tetrahedral mesh and triangle tracing.
-- The weighting is **EXTRACT**: the per-probe term becomes shared.
-- The specular blend is **REUSE**.
-- The depth two-pass is **GENERALISE**.
-- LPV's radiance readers do a manual four-load bilinear with rgbe decode, and the border it paints is
-  never read. Here the radiance must be hardware-filterable, which is one reason the atlas is
-  `rgba16float` (§8.2).
-
-**Brick4.** Its tree and its CPU bake are not applicable. Its sampler is, and (a) missed it:
-- `brick4_node_sample_probes_meta` weighs the eight cage probes without loading them: trilinear × a
-  back-face smoothstep.
-- `brick4_probe_meta_pick2` makes the pick:
-  - it draws one probe with `sample_discrete_wrs_mat2x4`, the weighted reservoir sampling of
-    Fajardo et al.'s *Stochastic Texture Filtering*;
-  - it zeroes that probe and draws a second with fresh noise;
-  - it renormalises the pair's weights into a blend.
-- Noise comes from two sources:
-  - image passes use STBN at (pixel, frame), as `brick4_sample_specular` and
-    `shader_brick4_indirect_lighting` do;
-  - forward passes use a hash of position, normal and frame, `jitter_from_vectors`, private to
-    `chunk_brick4_sample_forward_indirect.js`.
-- The fused pass picks once. It then re-weights the pair separately for diffuse (against the bent
-  normal) and for specular (against the specular direction).
-- Brick4's standalone diffuse (`brick4_sample_sh`) still evaluates all eight.
-- Verdict: **EXTRACT** the selection and the forward hash. Brick4 keeps its address mapping.
-
-**The irradiance clipmap** (`volumetrics/irradiance_clipmap/`):
-- 6 × 32³ cascades at 0.25 m, Y and CoCg `rgba16float` 3-D atlases on a `GPUTileAtlas3D`.
-- Its own stateless placement (`IrradianceCascadePlacement`) over linear storage, so a one-voxel move
-  rebuilds the cascade.
-- Per texel: GI SH from the mode, directional lights through their shadow maps, and world-cluster
-  point/spot lights up to `IRRADIANCE_CLIPMAP_LIGHT_BUDGET` = 32.
-- Lit particles are its only consumer.
-
-Verdicts: **REUSE** its light and shadow lookups. Its placement is not a model: it duplicates the
-clipmap toolkit (§16).
-
-**Clipmap toolkit.**
-- `ClipmapWindowSet` (hysteretic placement, `clamp_corner`, `storage_cell`, `decode`),
-  `window_scroll_regions` (at most three disjoint exposed boxes), `quantize_hysteretic`, and
-  `clipmap_select_finest` (CPU and WGSL).
-- `CLIPMAP_LEVEL_STRUCT` (32 B; `CLIPMAP_LEVEL_LIMIT` levels), `chunk_clipmap_contains`,
-  `chunk_clipmap_storage_coord` (no production user yet), `grid_tile_window_storage` (the fluid's).
-- The fluid's exposed-slab flow is `GPUFluidCascadeStack.record_tick` → `window_scroll_regions` →
-  `shader_fluid_cascade_fill`.
-- **REUSE** as is. This is what `GPUClipMap3D`'s deletion (`f2f6bc7b6`) named as its replacement.
-
-**Atlases.**
-- `GPUTileAtlas3D`: equal tiles with a border parameter and several synchronised formats. Its doc
-  names "a brick SDF atlas" as an intended client.
-- Slots are handed out on the host (`allocate`, `free`), and a grow replaces the texture.
-- **GENERALISE**: a bulk reserve, so the GPU free list owns the slots (§7.10).
-- `OffsetAllocator` (`core/binary/allocator/`) hands out ranges of a linear store. **REUSE** for the
-  mesh SDF indirection and the card page tables.
-
-**Scene distance fields.**
-- `GPUGeometrySDFManager` (`geometry/sdf/`):
-  - Storage: per geometry, a dense 50³ `r32float` tile in a `GPUTileAtlas3D`. The slot is the
-    geometry id and is never freed.
-  - Build: `shader_build_sdf` evaluates `blas_query_sdf` at every voxel:
-    - the exact nearest point through the BLAS (`point_query_blas_nearest`);
-    - a sign from 64 Fibonacci rays (`blas_query_volume_sign`), inside past 60% back faces;
-    - for open meshes, a wrap of negative distances past 4 voxels.
-  - Reach: it is not attached (`GPUGeometryManager.sdf` throws), and no frame reaches its readers
-    (`chunk_geometry_sdf_query_distance`, `chunk_sdf_geometry_raymarch`, `chunk_scene_sdf_raymarch`,
-    `shader_scene_sdf_debug_viz`). Its spec tests storage, not distances.
-  - Alex: it worked, and it is correct. **GENERALISE in place** (§6): the evaluator stays, the
-    storage becomes sparse.
-- `CascadedSceneSDF`:
-  - One dense `r16float` volume despite the name, built once from 65 scene queries per texel.
-  - It is constructed only by an uncalled `Renderer.obtains_scene_sdf`.
-  - It is the only precedent in the tree for hardware-filtered SDF sphere tracing
-    (`shader_scene_sdf_soft_shadows`). **Not applicable** as a cache.
-- `shadow/sdf/brixelizer/`: a port of FidelityFX Brixelizer's trace side. It was never verified and
-  does not compile. Alex: a reference only.
-
-**Scene rows.**
-- The entity is the row (`row_of_entity`). `GPUSceneRows.attach_mesh(entity, geometry, material,
-  skinned)` gives it a `meshes` row.
-  - `ShadedGeometrySystem` calls it for every `ShadedGeometry`, passing
-    `ShadedGeometryFlags.Skinned`.
-  - It calls it again when `shaded_geometry_announce_change` reports an in-place change.
-- `ShadedGeometryFlags`: InView 1, CastShadow 2, ReceiveShadow 4, DrawMethodLocked 8, Visible 16,
-  DeferredBoundsUpdate 32, Skinned 64. Shade reads none of them for meshes, and a row carries no flag
-  on the GPU.
-- `MESH_INSTANCE_METADATA_STRUCT` holds geometry, material, node, box, sphere and lightmap chart:
-  68 B of fields in an 80 B row. A `u32` fits without growing it, as `global_flags` did in
-  `NODE3D_STRUCT`.
-- Virtual geometry is a `MeshletGeometry` with `isVirtualGeometry`, on the same rows, and its BLAS is
-  empty.
-- A skinned row draws a per-instance clone (`GPUMeshSkinningContext.obtain_clone`). The CPU entry
-  keeps the source geometry.
-- Signals: `onMeshReleased`, and `for_each_mesh` for walks. Nothing announces a write.
-- **GENERALISE**: a `flags` word, an `SDFWorld` bit carried as `Skinned` is, and `onMeshWritten`
-  beside `onMeshReleased` (§6.1).
-
-**Scene queries.**
-- The TLAS (`GPUInstancesAccelerationStructure`) is GPU-resident and maintained by the scene context.
-  `graph_bvh_build_lbvh` rebuilds it in full whenever a row changes. Its leaves are mesh rows (the
-  leaf's `child_2`).
-- BLASes are built on the CPU per geometry over meshlets; skinned clones are refit on the GPU every
-  frame (`GPUBLASRefitBatch`).
-- `chunk_bvh_query_aabb_cooperative`: one 64-lane workgroup per box, level-synchronous, ≤ 128 sorted
-  candidates, drops counted, two seam functions. Its only user is fluid forcing.
-- `point_query_blas_nearest` and `ray_query_blas_nearest` answer per geometry; the sign vote uses the
-  second.
-- Verdicts: **REUSE** the TLAS and the cooperative query for the mesh provider (§7.7). Use the BLAS
-  queries in the bakes only (§6.4, §6.5).
-
-**Change detection.**
-- `shader_vsm_movers` + `shader_vsm_skinned_movers` append, for every mesh row whose matrix, box,
-  geometry or material changed, the union of its box now and before (`VSM_MOVER_LAYOUT`, 4,096
-  boxes, overflow counted).
-- Last-seen state is `VSMMoverTracker`.
-- It is a transient inside `graph_vsm_feedback` and exists only while a virtual shadow map is
-  registered.
-- **EXTRACT** to scene level (D32), with a bit telling a skinned row's box from a rigid one (§7.4).
-
-**Material.**
-- `sample_material_data` (`path_tracer/shader/chunk_sample_material_data.js`) does two things:
-  - it interpolates uv, vertex colour, normal and tangent from a triangle and barycentrics;
-  - it samples the material: albedo × colour factor × vertex colour, ORM, emissive × factor, opacity.
-- It reads `GPUResidentMaterialContext` (on `GraphicsContext`): the material table
-  (`INDIRECT_MATERIAL_STRUCT`) and a 2-D array of 64² texture slots, each with its mip chain down to
-  one texel since 2026-10-30, sampled by `indirect_sample_texture` at an explicit level with each
-  sampler's wrap mode: one stochastic tap of the trilinear filter by default, which at level 0 is the
-  stochastic bilinear tap it always was, or the filter itself where the shader's
-  `INDIRECT_TEXTURE_FILTER` is `Exact`.
-- Its taps and dither draw on the path tracer's random state. Alpha is stochastic: a hit is opaque
-  with probability equal to its opacity (`chunk_ray_shaded_query_occluded`, through
-  `sample_material_alpha`).
-- `ShadeMaterial.version` moves on every change. `GPUResidentMaterialContext.obtain_material` repacks
-  a material whose version moved, on walks it already makes: the scene's drawn list, and the
-  manager's materials when the manager's version moves. The single place that happens is
-  `#pack_material`.
-- **REUSE** both chunks in card capture, with a seed fixed per texel (§6.5). **GENERALISE** the
-  resident context with a signal from `#pack_material` when a material is repacked, which is what
-  recapture keys on.
-
-**What rays could not see.** vgeo rows are in the TLAS with an empty BLAS, and DynamicMesh has no row.
-Under (b):
-- virtual geometry is baked from a proxy cut from it, and composed as a mesh (§7.8, S8);
-- DynamicMesh stays out by construction: it changes every frame, and a cache of it would be a cache of
-  nothing (§17).
-
-**Lights at arbitrary world points.**
-- `shade_directional_lights` takes a position only.
-- Shadow maps do not answer off-screen points honestly. CSM reads *lit* outside its view-fitted
-  cascades. VSM pages exist only where the main view's depth demanded them, and with none resident a
-  point reads lit.
-- Local-light shadows are sampled by direction or projection, so they work anywhere in range. Their
-  refresh is scored by on-screen area, and a cleared region reads unshadowed.
-- The world light clusters (`light/world_cluster/`): 8³ cells per cascade, ≤ 128 lights per cell,
-  4,096 candidates. They are keyed by the irradiance clipmap's levels and built inside its
-  `graph_update`. **GENERALISE** the keying.
-- Misses: `sample_environment_color` (level 0 of the octahedral environment), `get_ibl_irradiance`,
-  `environment_sh`.
-
-**Settings.**
-- There is no settings class.
-- The precedent for "rarely changes, reallocate on change" is the shadow knobs: validated setters on
-  `Renderer`, pushed every frame into `GPUSceneShadowmapContext`, which rebuilds what was built with
-  another value.
-- Sub-objects (`avboit`, `ssr`, `volumetrics`) group a feature's fields.
-
-**SH conventions.**
-- `sh2_*` is L0 + L1, ordered `[DC, y, z, x]`.
-- `METRO_L1_IRRADIANCE_STRUCT` is {CoCg vec2f, Y vec4f}, 32 B, its Y in (x, y, z, DC) order.
-  - Its `1/(2π)` convention, under which the resolve returns E/π, is pinned by
-    `chunk_volumetrics_irradiance_sh.spec.js`.
-  - It has a diffuse resolve (`resolve_irradiance_sh_to_diffuse`) and no specular one.
-- `sh2_approximate_GGX_zh` is MJP's fit of the GGX lobe's band-1 zonal factor, `1.6671/(1.6572 + α)`.
-  `sh2_color_convolve_with_GGX` and `sh2_color_get_radiance_with_GGX` apply it to RGB SH2; LPV is
-  their user.
-
-## 2. What the field ships
-
-Ordered by how directly each shapes this design.
-
-### 2.1 Enshrouded (Keen Games) — the main reference
-
-Source: Jakub Kolesik, *Realtime Global Illumination in Enshrouded*, Graphics Programming
-Conference 2024 ([video](https://www.youtube.com/watch?v=57F1ezwH7Mk), 50 min; read from its
-captions, so the numbers are as spoken). Timestamps in brackets.
-
-**Building blocks** [2:32–4:34]
-- A "spatial cascaded cache": a 32³ world-aligned grid around the player, 12 cascades, 2 m spacing
-  at cascade 0, doubling per cascade.
-  - Cells are activated by the depth buffer and by a buffer of ray-hit positions.
-  - It is capped at 16k live cells, always full, and garbage-collected: a cell that leaves the
-    screen loses quality over frames and expires, and is reused if seen again before then.
-- The world as a simplified SDF traced by "SDF rays". Very small objects are absent and medium ones
-  appear only at high settings.
-  - They had Vulkan ray-tracing prototypes and chose SDF rays to have **one code path on all
-    hardware**, scalable by SDF resolution and by which SDFs a tier uses.
-- A BVH sits over the SDFs.
-
-**Three probe kinds** [4:34–11:12]
-1. **Frustum probes.** Cells activated by the depth buffer, pushed out of walls with the SDF, then
-   offset toward the camera and along the surface normal.
-   - Octahedral radiance 32² (ultra), 16² (mid), 8² (low) with a hand-made border, plus octahedral
-     irradiance at 12² or 8².
-   - Both are RGB9E5 in a 128×128-probe atlas. Distance is RGBA16F, because the occlusion test
-     needed the precision.
-2. **World-cache probes** at ray hits where no frustum probe exists. Same shaders; 4×4 octahedral
-   with no border; SH irradiance; denser, and storing no occlusion.
-   - The chain stops there: point lights get three bounces and full GI two.
-3. **Ambient probes** for fog: 16³ × 8 cascades. They trace nothing and accumulate about 10% of the
-   other probes' ray segments.
-   - They feed a 32×32-tile froxel volume with 384/256/128 slices, about 50 µs on low-end hardware.
-
-**Pipeline** [11:12–19:54]
-- Fully GPU-driven with indirect dispatches.
-- A fixed ray budget: 100k / 250k / 500k rays a frame on low / mid / high (Q&A [45:27]).
-- A new probe asks for 512 rays and decays fast to 16, rising again when it sees change. Requests
-  are scaled down to the budget.
-- Rays are batched by a probe-index scan.
-- Ray directions are importance-sampled from each probe's own radiance (a linear CDF walk with a
-  rotating start corner), because 16–32 uniform rays a frame left the probes flickering.
-  - **Uniform rays every 5th frame** keep the depth moments alive, which importance sampling
-    starves.
-- Rays are sorted by position and direction, and hits by kind (terrain, sky, building) to avoid
-  shader branches.
-- **Hit shading** [19:23]: emissive from the voxel; directional light with an SDF shadow ray shot
-  beforehand; point lights from a "light cache" (a cascaded grid of per-cell light lists) with SDF
-  shadows; then GI from the probes.
-
-**Temporal and spatial filtering** [20:25–26:33]
-- A moving-average estimator (short and long-term means, variance-driven blend; from the
-  *Stochastic All The Things* talk and Ray Tracing Gems) at 5 × u32 per texel, which the talk
-  counts as a heavy bandwidth cost.
-- Depth is a per-texel mean and mean² clamped to the probe spacing, tested with Chebyshev and
-  filtered in LDS.
-- Ray and history reprojection between neighbouring probes, 4:1, which carries light hundreds of
-  metres into caves.
-- Irradiance by a cosine-weighted loop over the rays.
-
-**Specular** [27:03]: radiance prefiltered by a cosine-weighted blur and downsample into mip-like
-levels, tuned against a ground-truth mode, then blended with FidelityFX SSSR because characters are
-not in the SDF [33:10].
-
-**Sampling** [29:04–31:39]
-- Trilinear over the eight cage probes, but **stochastic**: one probe per frame by weight (trilinear
-  × Chebyshev), with stochastic cascade crossing in the overlap.
-- Two screen-space reservoirs, temporally reprojected and spatially filtered.
-- An à-trous denoise, needed mostly for specular.
-- Dead probes are those whose rays sum to under 1 mm, i.e. inside a wall. They are excluded but
-  still trace 16 rays a frame.
-
-**Lessons stated** [41:19–42:53]: bandwidth dominates (Steam Deck); RGB9E5 everywhere, decoded in
-LDS; fixed buffer sizes; settings for every system. The admitted hole is foliage: trees are not in
-the SDF [49:08].
-
-**What this design takes, and what it leaves.**
-
-| Enshrouded | Here | Why |
-|---|---|---|
-| SDF rays instead of hardware RT | same (§7) | one path on every WebGPU device; the request |
-| material from the voxel world; normal from the SDF | surface cards holding captured diffuse albedo and emissive (Lumen's payload); normal from the field's gradient (§6.5, §6.6) | the review: voxel attributes are expensive |
-| very small objects absent, medium ones only on high | a per-primitive membership flag (§6.1) and a per-cascade resolution cull (§7.7) | the review; the cull keys on a runtime fact (E4) |
-| a BVH over the SDFs | the TLAS over instance boxes, queried per requested cell (§7.7) | reuse |
-| cascaded cache, depth-buffer activation, expiry | probe clipmap with want → slot → retention (§8.3) | memory follows what is visible, not the grid |
-| octahedral radiance + border; distance with mean/mean² | same, `rgba16float` and `rg16float` with the engine's skirt chunks (§8.2) | hardware bilinear for every consumer tap |
-| irradiance as octahedral 12² (frustum) or SH (world cache) | SH2 YCoCg L1 for every probe | the request; 32 B a probe |
-| fixed ray budget; per-probe requests scaled to it | budget in rays a frame; period follows the live count (§8.5) | same intent, deterministic schedule |
-| importance-sampled directions + every-5th-frame uniform | the same: every 5th update uniform, the rest a CDF walk over the probe's history from a rotating corner, each texel held under 64 rays (§8.6, as built 2026-10-29) | Alex found the noise of one jittered ray a texel visible (D11) |
-| moving-average estimator, 5 u32 per texel | the same estimator, its short mean over a response time in seconds; 6 words a texel with the atlas's (§8.8) | built 2026-10-29, once Alex judged the noise visible (D11); the knob stays physical |
-| SDF shadow ray per hit for the sun | same (§8.6) | shadow maps answer "lit" off screen (§1) |
-| light cache for point lights | the world light clusters, keyed by this clipmap (§8.7) | reuse |
-| world-cache probes at hits | hits want the probes they read, one step from the screen, the one probe kind (§8.3) | the off-screen bounce measured short at S5a (D31) |
-| stochastic 1-of-8 + reservoirs + denoise | 2 of 8 by Brick4's WRS, resolved by TAA (§9.1, §9.4) | the review; two probe reads, no denoiser |
-| prefiltered radiance levels for specular | the radiance tap blended with GGX-convolved SH2 by roughness (§9.3) | the review: WebGPU's mips; LPV's blend |
-| ambient probes and froxel GI | the existing irradiance clipmap samples this mode's probes (§9.5) | fog has no GI in any mode today |
-
-### 2.2 UE 5.4 Global Distance Field
-
-The production reference for the brick clipmap.
-
-**Clipmaps**
-- 4 clipmaps (up to 6) of 252 voxels a side, i.e. 36 pages × 7 voxels.
-- Clip 0 is a ±25 m half-extent at 19.8 cm voxels, doubling per clipmap.
-
-**Pages and atlas**
-- **A page is 8³ texels in the atlas with 7 unique voxels**: texel 7 duplicates the next page's
-  texel 0, every page computes all 512 itself, and the lookup `offset·8 + frac(uv·36)·7 + 0.5`
-  keeps trilinear inside the page. There is no border pass.
-- Atlas: 3-D `R8_UNORM`. Page table: `R32_UINT` with `0xFFFFFFFF` = no page, allocated from a GPU
-  free-list stack.
-- Distance is encoded `saturate(d/(2R) + 0.5)` with **R = 4 voxels**.
-- A page is kept iff its centre's distance is within R plus the page radius.
-
-**Empty-space skipping**: a dense `R8` coarse mip at a quarter of the resolution, rebuilt by five
-eikonal propagation passes whenever a clipmap updates. Pages are read only where the coarse distance
-is under 4 voxels.
-
-**Composition**: from the mesh distance fields of §2.3, culled per tile into lists of up to 511
-objects, with a minimum object radius of max(20 cm, ½ voxel).
-
-**Invalidation and budget**
-- Add, remove and transform changes record the old and new boxes, expanded by R. At 1,024 boxes or
-  more the clipmap is fully recaptured.
-- 2 clipmaps update a frame, staggered.
-- Scrolling is toroidal and exposes slabs only.
-
-**Trace**
-- Starts in the first clipmap containing the point by over half a voxel, clipping the ray to each
-  clipmap box shrunk by half a voxel.
-- At most 256 steps a clipmap. A hit is d < ~½ voxel (the "expand"); the minimum step is ½ voxel.
-- The normal is a 6-tap central difference.
-
-### 2.3 UE 5.4 mesh distance fields, composition, and Lumen's surface cache
-
-The production reference for §6 and §7.7.
-
-**Mesh distance fields**
-- Bricks of 8³ texels with 7 unique on the corner lattice, `G8`, a band of 4, and 3 mips. An empty
-  brick is `0xFFFFFFFF` and reads +band.
-- Resolution: 0.2 voxels a centimetre (5 cm) × a per-mesh scale. Mip 0 is capped at 128 voxels a
-  side at scale 1, 18 bricks. Mip i has ⌈mip₀ / 2^i⌉ bricks a side and is re-voxelised from the mesh,
-  not downsampled.
-- The band is 4 voxel *diagonals*, and the encoding is the global field's `(d + band) / 2band`.
-- A brick is stored unless all its texels saturate at one end, so a brick wholly inside reads +band,
-  as here.
-- Sign:
-  - Rays are traced only where the unsigned distance is inside the band.
-  - There are 98 of them (a 7×7 stratified hemisphere and its mirror), each one band long.
-  - The voxel is inside when more than 25% hit back faces. Two-sided triangles never count.
-- Translucent sections, and primitives with distance-field lighting disabled, are left out: the
-  precedent for the membership bit (D25).
-
-**Composition**
-- Objects are culled to the clipmap, then to tiles of 4³ pages, then to each page's 4³-voxel tile in
-  LDS, 511 a pass. The passes loop, so there is no hard cap.
-- Per object:
-  - an early-out when the box distance is already past the running minimum;
-  - inside the volume, the mesh SDF scaled by the object's smallest axis scale;
-  - outside it, the SDF at the clamped point plus the box distance.
-- The resolution cull is radius > max(20 cm, ½ voxel). Emissive objects are exempt.
-- The mip is not chosen by the clipmap's voxel. A sample walks the resident mips from coarse to fine
-  and stops at the first whose distance exceeds a quarter of its band. Mips stream in by distance:
-  3 inside clipmap 1's box, 2 inside clipmap 3's, 1 elsewhere.
-- Mostly-static and movable layers are merged by a minimum: the static/dynamic category E4 refuses.
-
-**The object grid**
-- Layout: a page has 4³ cells. Each cell holds the 4 nearest objects as a `uint4`: a 24-bit instance
-  index and an 8-bit distance. That is 1 KiB a page.
-- It is filled by its own pass, one thread per cell.
-- At a hit:
-  - the lookup point is the hit plus half a voxel along the field's normal;
-  - each entry's mesh cards are sampled in turn, until the summed weight reaches 0.9 or an entry is
-    empty.
-
-**Mesh cards**
-- Cards are axis-aligned in mesh space, six directions.
-- Surfels:
-  - Per column of a 10 cm grid, 32 jittered rays march through successive hits.
-  - A hit is kept if it faces the card and follows an empty cell. Its minimum ray Z is the layer after
-    the previous hit.
-- Clustering, per direction:
-  - first the outer projection (near plane 0);
-  - then, greedily, the near plane that best covers the unassigned surfels. A near plane N sees a
-    surfel at layer Z when its minimum ray Z ≤ N ≤ Z.
-  - This is how concave meshes get interior cards.
-- The weakest clusters are dropped down to 12 cards a mesh (32 at most; the runtime lookup is a
-  32-bit mask per direction).
-- A mesh with no card has no fallback.
-
-**The surface cache**
-- Layers: 128² physical pages in a 4096² atlas, holding depth `G16`, diffuse albedo `RGBA8` (stored
-  as its square root), opacity, normal, emissive `R11G11B10`, and three lighting layers.
-- Card resolution:
-  - recomputed from distance at every update, 8 to 2048 texels;
-  - a locked distance level always resident, with finer pages paged in by GPU feedback;
-  - idle pages kept for 256 frames.
-- Capture:
-  - the mesh is rasterised through an ortho camera on the card, at most 300 pages a frame;
-  - a recapture follows a resolution change, an explicit surface-cache invalidation on the
-    primitive, or a slow refresh of the oldest pages;
-  - a material change is not tracked.
-
-**Sampling at a hit**
-- Cards are selected by the normal's sign per axis, weighted by n², and every card holding the point
-  within the bias is blended.
-- Depth test: four depth taps, each weighted by `1 − saturate((|t − depth| − bias)/(¼·bias))` in card
-  depth units. For a global-SDF hit the bias is three half-voxels of the hit's clipmap.
-- With no valid card, the hit is opaque black.
-
-**Lumen**: probe rays trace the global distance field and are lit by the surface cache's final
-lighting. 5.4 has removed the voxel lighting that earlier versions used for global-SDF hits.
-
-### 2.4 UE 5.4 Lumen world-space radiance cache
-
-The production reference for sparse probe allocation.
-
-**Clipmaps and allocation**
-- 4 clipmaps of 48³ at 1.04 m (clip 0).
-- The indirection (`R32_UINT`) is cleared and rebuilt every frame: consumers mark the eight probes
-  around each sample, and a probe is reused if marked within 8 frames, else freed.
-- 16,384-probe capacity (128² atlas). Overflow renders incorrectly.
-
-**Probes**
-- 32² equal-area octahedral `R11G11B10F` radiance plus `R16F` hit distance.
-
-**Tracing**
-- A budget of 300 probes × cost per frame. Never-traced probes go first, then priority by how long
-  since each was traced relative to its use.
-- **No history blend and no jitter**: a retrace overwrites.
-- 256–4,096 rays per probe, against the global distance field only; hits are lit by the surface
-  cache.
-
-**Sampling**
-- Eight-probe trilinear with sphere parallax.
-- Visibility weighting (Chebyshev³ × `((n·ω+1)/2)² + 0.2`) is used only in the off-by-default
-  irradiance mode.
-
-Lumen can overwrite on every retrace because its screen probes filter downstream. Here consumers
-sample the probes directly, so the blend stays (§14, D11).
-
-### 2.5 AMD FidelityFX Brixelizer and Brixelizer GI
-
-From the FidelityFX SDK manual and source (v1.1.4) and the GDC 2024 talk. The port in
-`shadow/sdf/brixelizer/` is a reference only.
-
-**The field**
-- Cascades of 64³ voxels (up to 24), each voxel holding at most one brick through a 1 MiB brick map.
-  The toroidal wrap is `(voxel + offset) & 63`.
-- Bricks are 8³ samples spanning one voxel (7 intervals, shared samples, no apron) in a 512³ R8
-  atlas: 2^18 bricks, 128 MB.
-- The manual calls them **unsigned** distance fields; the stored value saturates at one voxel.
-- Two-level per-cascade AABB trees (4³ fan-out) skip empty space.
-
-**The build**
-- Triangles are referenced into every voxel their box overlaps. Each writes exact distances into
-  its box's brixels through 32-bit `InterlockedMin`, then a 12-sweep eikonal fill runs per brick.
-- *Static* cascades persist under invalidation jobs; *dynamic* cascades are rebuilt every frame,
-  merged by a per-brixel min. That is the static/dynamic category this engine refuses (E4).
-- The per-triangle scatter is the footprint-dependent cost E3 refuses.
-
-**Brixelizer GI**
-- The SDF carries no material, so its radiance cache is fed only by reprojecting previous frames.
-- Screen probes 8×8 octahedral, a per-brick SH2 cache, about 2 ms at 4K at half scale on an RX 7900
-  XTX.
-
-What this design keeps from it: the per-texel min as the merge of independent writers (§7.6), here
-between providers rather than between static and dynamic cascades.
-
-### 2.6 DDGI
-
-Majercik et al., JCGT 2019 and 2021, and the RTXGI SDK.
-
-**2019 paper**
-- Irradiance `R11G11B10F` at 8×8 octahedral per probe; distance and distance² `RG16F` at 16×16;
-  one-texel gutters.
-- Hysteresis 0.85–0.98 across its results.
-- 64–128 rays a probe a frame.
-- Distance texels gathered with a cosine power (50 in RTXGI).
-- Leak control: Chebyshev visibility, a shading point offset along the normal and toward the eye,
-  the wrap back-face weight `((n·ω+1)/2)² + 0.2`, and crushing of small weights.
-  `lpv_mask_weights_by_visibility` already is this.
-- 1–2 m spacing for human-scale scenes.
-- 6 ms at 1080p on an RTX 2080 Ti for its teaser scene.
-
-**2021 additions**
-- Probe states and relocation out of geometry.
-- A back-face hit writes irradiance 0 and shortens its depth by 80%.
-- A per-texel convergence boost: a change over 25% drops the hysteresis by 0.15; over 80%, to 0.
-- Scrolling volumes clear only the plane that wraps.
-
-**RTXGI defaults**
-- 256 rays; hysteresis 0.97.
-- Normal bias 0.1 and view bias 0.1, in world units.
-- Back-face threshold 0.25 for the fixed classification rays (0.1 for random rays); minimum
-  front-face distance 1.0.
-- Relocation clamped to 45% of a cell.
-- A probe every 2–3 m recommended.
-
-### 2.7 Godot 4 SDFGI, and the HDDAGI draft
-
-**SDFGI** (4.3 source and docs)
-- Up to 8 cascades of 128³ cells, Y at 75%.
-- Voxelized albedo, emission and facing at half size.
-- The SDF is built by jump flood from solid voxels and stored **unsigned** in R8 as `(1 + cells)/255`.
-- Probes: 17³ per cascade, 8 cells apart, *all updated every frame*, 16 rays by default; L3 SH in a
-  30-frame history ring.
-- Its documented limits: visible cascade shifts; convergence time; an SDF that updates only when the
-  camera crosses cascades, so moved doors give stale GI; dynamic meshes contribute nothing; leaks;
-  one of the engine's most demanding GI options.
-
-**HDDAGI** (reduz, PR #86267, an open draft never merged; revived as #119869 in May 2026)
-- Replaces the full-cascade jump flood with HDDA over local updates.
-- Claims 2.43 → 0.93 ms on a GTX 1650, unaffected by camera motion.
-
-The lesson taken here: **never rebuild a whole cascade, and never update every probe every frame.**
-§7.4 rebuilds only exposed and changed cells; §8.5 traces only wanted probes, within a budget.
-
-### 2.8 kajiya's irradiance cache
-
-Embark Studios' research renderer.
-- 12 sparse 32³ clipmaps over a dense indirection, with a 65,536-entry pool. Entries are allocated
-  on demand and freed a few frames after their last use.
-- Each entry is a 4×4 octahedral set of temporal reservoirs, 4 texels refreshed a frame, convolved
-  to L1 SH.
-- Usually under 16k entries, about 0.55 ms on an RX 6800 XT.
-- It is queried only at ray hits: a cache behind a screen-space solver, not the shading
-  representation. That is why it can be so small.
-
-### 2.9 Specular from two SH bands
-
-- **The GGX lobe as a zonal kernel.** Convolving radiance SH with a radially symmetric lobe scales
-  each band by the lobe's zonal factor. MJP's *SHforHLSL* fits GGX's band-1 factor as
-  `1.6671/(1.6572 + α)`: about 1 at α = 0, and 0.63 at α = 1, near the clamped cosine's 2/3. The
-  tree has the fit as `sh2_approximate_GGX_zh`.
-- **Dominant direction.** Lagarde and de Rousiers (*Moving Frostbite to PBR*, 2014) bend the lookup
-  from the reflection vector toward the normal as roughness grows. LPV and Brick4 both do this.
-- **Luma and chroma.** Metro Exodus (GTC 2019) stores luma as L0 + L1 and chroma as a constant, and
-  rescales chroma by the ratio of directional to mean luma at resolve. The same ratio carries over to
-  a GGX resolve (§9.3).
-- **The blend.** Two bands cannot hold a sharp lobe, and a single radiance tap cannot hold a wide
-  one. LPV blends the two by `roughness_to_mip_ratio`, Frostbite's roughness-to-mip curve.
-
-### 2.10 What wins on performance and simplicity
-
-| Component | Chosen | Over | Because |
-|---|---|---|---|
-| Brick layout | UE page: 8³ texels, 7 voxels, corner lattice | 8³ + apron (10³) | no border pass; 512 B a brick; Brixelizer agrees |
-| Distance | signed `r8unorm` over ±4 voxels, ½-voxel hit | unsigned shell, (a) | whole-mesh bakes know the sign; relocation and back faces follow from it; the ½-voxel hit keeps thin walls (D2) |
-| Empty space | 4³-cell occupancy count + cell entry (HDDA) | UE's coarse eikonal mip; Brixelizer's AABB trees | incremental, toroidal, no propagation passes and no tree build |
-| World build | composed from cached per-mesh SDFs, as UE composes | triangles per cell, (a); per-triangle scatter (Brixelizer); raster voxelize (Godot) | no triangle is read per frame; cost follows the instances in a cell |
-| Mesh SDF | sparse bricks in size classes, with levels | `GPUGeometrySDFManager`'s dense tiles | the review; memory follows the surface |
-| Material | cards holding diffuse albedo and emissive captured per (geometry, material), recaptured when the material's version moves | the voxel lattice, (a); cards holding uvs with the material evaluated live | the review: no material work at a hit (§15) |
-| Probe residency | sparse cache from the screen | dense lattice | 10× less memory and work at the same lattice (§11) |
-| Rays | Enshrouded's: guided by the probe's radiance, every 5th update uniform (§8.6) | one jittered ray per texel, (b) as first built | its noise measured visible (D11) |
-| Temporal | exponential over a response time | moving-average estimator | one history, 8 B a texel |
-| Pixel sampling | 2 of 8 by WRS | all eight, (a); 1 of 8 + reservoirs + denoise (Enshrouded) | the review; two probe reads, no denoiser |
-| Specular | radiance tap ⊕ GGX-convolved SH2 | prefiltered levels | the review; LPV's blend |
-
-## 3. Requirements
-
-**From the request (R)**
-1. A new `ShadeIndirectLightingMode` value selects a separate subsystem.
-2. Rays hit an SDF. Material comes from a scene representation beside it (R11).
-3. The scene clipmap is sparse: fixed-size bricks in an atlas.
-4. The SDF is 8-bit and traced with hardware filtering.
-5. Shading samples a 3-D clipmap of probes: radiance and depth octahedral, irradiance SH2.
-6. Cascade count, cascade resolution, radiance and depth resolutions and rays per probe are settings.
-   A change reallocates; nothing changes per frame.
-7. Maximal reuse; the LPV is an explicit source.
-8. Enshrouded is the main reference.
-9. SotA first, prioritising performance and simplicity.
-
-**From the review of (a) (R)**
-10. No triangle work per frame: meshes are cached as SDFs, NanoVDB-style, in size classes of 2×2×2
-    bricks and up in steps of two bricks per axis.
-11. Material comes from a surface cache in Unreal's manner, not from voxels: diffuse albedo and
-    emissive captured per (geometry, material), recaptured on a material change.
-12. A primitive can be absent from the SDF world.
-13. Providers write requested bricks; their outputs merge per brick; virtual geometry is served by
-    one.
-14. Skinned meshes use their unskinned representation now, with hooks and TODOs for a dense patch.
-15. Pixels pick 2 of 8 probes by Brick4's WRS, after visibility-only weights.
-16. Rough specular blends radiance with GGX-convolved SH2.
-17. `GPUGeometrySDFManager` is the reference for the bake; the Brixelizer port is not reused.
-
-**From the engine's rules (E)**
-1. **Work follows the live count.** Dispatches are indirect over device counts; capacity sizes memory
-   only.
-2. **Bounded per-thread loops**, with budgets in tens. Each is stated with what is lost past it.
-3. **Gather per bin.** No thread's cost follows an element's footprint.
-4. **No static/dynamic category.** A row's treatment follows facts re-observed each frame, such as
-   "changed this frame" and its size against the voxel.
-5. **The CPU does O(changes)** and never passes over GPU-resident state.
-6. **GPU consumers sample on the GPU**, at their own resolution.
-7. **Separate passes for separate cost profiles.** Share data, not shaders.
-8. **Shader switches, not overrides or template codegen**; concrete modules.
-9. **Physical knobs in world units and seconds.** Caps are safety nets, stated as chosen numbers.
-10. **The scalable path first.** A small-n fast path keys on the runtime count.
-11. **No allocation in per-frame host code.**
-12. **Tests on all four tiers.** No mocks, hooks or `.each`; a fix is red then green.
-
-## 4. The reuse map
-
-Verdicts:
-- **REUSE**: as is.
-- **GENERALISE**: the piece grows a parameter, and its clients move onto it.
-- **EXTRACT**: the piece becomes shared, and its current owner migrates.
-- **COMPOSE**: built from existing pieces.
-- **NEW**: written generic.
-
-### 4.1 Host side
-
-| Need | Engine machinery | Verdict |
-|---|---|---|
-| Mesh SDF bake, cache lifetime | `GPUGeometrySDFManager` | **GENERALISE in place**: sparse bricks in size classes with levels, `r8unorm`, cards, a budgeted bake queue (§6) |
-| Mesh SDF indirection, card page tables | `OffsetAllocator` | **REUSE** |
-| Window placement, nesting, exposed slabs | `ClipmapWindowSet`, `quantize_hysteretic`, `window_scroll_regions` (`core/geom/clipmap/`) | **REUSE** for both clipmaps |
-| Exposed-slab flow | `GPUFluidCascadeStack.record_tick` → `window_scroll_regions` → fill pass | **REUSE as pattern**; the brick and probe passes are their own kernels |
-| World and mesh brick atlases | `GPUTileAtlas3D` (r8unorm, content 8³, border 0) | **GENERALISE**: `reserve(capacity)` grows the footprint without the host handing out slots; the GPU free list owns them |
-| Card pages; probe radiance and depth atlases (2-D) | `GPUProbeAtlas`'s tile placement (`index_to_grid2d`, width at `maxTextureDimension2D`, growth in rows) | **EXTRACT** a format- and tile-parameterised 2-D tile atlas; LPV keeps its 66-texel pitch on it |
-| Free slot stacks | the particle pool (`shader_particle_init_free_list`, `dead[--DEAD]`) | **EXTRACT** the init pass and the pop/push chunk into `gpu_primitive/`; particles migrate |
-| Growth on demand | the vgeo high-water pattern; `GPUDatabaseReadback` | **REUSE**: failures counted on the device, read back, capacity doubled, never shrunk |
-| Changed world boxes | `shader_vsm_movers`, `shader_vsm_skinned_movers`, `VSMMoverTracker`, `VSM_MOVER_LAYOUT` | **EXTRACT** to a scene-level mover list with a skinned bit; VSM and this mode read it (D32) |
-| SDF membership | `ShadedGeometryFlags`; `ShadedGeometrySystem` → `attach_mesh`; the row's tail padding | **GENERALISE**: an `SDFWorld` bit forwarded as `Skinned` is, mirrored into a row `flags` word (§6.1) |
-| Row change stream | `GPUSceneRows.onMeshReleased` | **GENERALISE**: `onMeshWritten` beside it |
-| Skinned source geometry | the rows' entry keeps the source; `GPUMeshSkinningContext.obtain_clone` | **REUSE**: a clone's SDF header aliases its source's (the hook, §6.3) |
-| Material slot means; material changes | `GPUResidentMaterialContext` (`#pack_material`); `ShadeMaterial.version` | **GENERALISE**: a mean per texture slot when the slot is written (§6.6), and a signal when a material is repacked, which recapture keys on (§6.5) |
-| Settings | the shadow knobs' validate → push → rebuild-on-mismatch; the `avboit` / `ssr` sub-objects | **REUSE as pattern**: `ProbeClipmapSettings` (§10) |
-| Mode plumbing | `INDIRECT_LIGHTING`, `ShaderSwitchSet`, `#graph_indirect_lighting` | **REUSE**: additive (§9.7) |
-| Frame graph | `graph_compute_pass`, `graph_compute_indirect_pass`, `graph_import_texture` / `_buffer`, `IndirectComputeCommandBuildPass`, `build_indirect_compute_dispatch_command` | **REUSE** |
-| Profiling and stats | `GPUProfileSession`, `graph_record_stat` | **REUSE** |
-
-### 4.2 WGSL
-
-| Need | Engine chunk | Verdict |
-|---|---|---|
-| Exact distance and sign at a point | `blas_query_sdf`, `point_query_blas_nearest`, `blas_query_volume_sign` | **REUSE** in the bake. S3 replaced the vote with UE's, `blas_query_band_sdf` over the BLAS's point and ray queries, and deleted the other two |
-| A ray against one geometry | `ray_query_blas_nearest` | **REUSE** in card capture |
-| The triangle at a hit | `geometry_read_triangle_vertices` | **REUSE** in card capture |
-| Material at a triangle hit | `sample_material_data`, `sample_material_alpha` | **REUSE** in card capture, with a seed fixed per texel |
-| Clipmap levels, finest level, blend weight | `CLIPMAP_LEVEL_STRUCT`, `clipmap_select_finest`, `chunk_clipmap_contains` | **REUSE** |
-| Toroidal storage coordinate | `chunk_clipmap_storage_coord` (no production user) | **REUSE**: it gets its first users |
-| Folded indirect dispatch | `chunk_folded_workgroup_index` | **REUSE** |
-| Instances overlapping a box | `chunk_bvh_query_aabb_cooperative` (TLAS seam) | **REUSE**: second user |
-| Mesh and node rows | `scene_read_mesh`, the scene database access chunks, `NODE3D_STRUCT` | **REUSE** |
-| Octahedral direction codec | `uv_octahedral_unit_encode` / `_decode` (the one WGSL pair) | **REUSE** |
-| Octahedral skirt for hardware bilinear | `texture_octahedral_skirt_texel_uv`, `texture_octahedral_skirt_uv` | **REUSE** (the environment map's, not LPV's unread border) |
-| Texel solid angle | `octahedral_solid_angle` | **REUSE** |
-| SH2 basis; L1 storage and diffuse resolve | `sh2_basis_at`; `convert_to_irradiance_sh`, `resolve_irradiance_sh_to_diffuse`, `get_color_from_irradiance_sh`, `METRO_L1_IRRADIANCE_STRUCT` | **REUSE** |
-| GGX zonal factor | `sh2_approximate_GGX_zh` | **REUSE**; its Metro-form resolve is NEW (§9.3) |
-| Specular blend and sample vector | `chunk_lpv_sample_light`'s mix by `roughness_to_mip_ratio`; `normalize(mix(r, n, α))` | **REUSE** |
-| Chebyshev bound | `compute_chebyshev_weight` | **REUSE** |
-| Probe weight (wrap back face, crush) | inside `lpv_mask_weights_by_visibility` | **EXTRACT** a per-probe `probe_visibility_weight`; LPV migrates |
-| Pick 2 of 8 | `sample_discrete_wrs_mat2x4`; the selection inside `brick4_probe_meta_pick2` | **REUSE**; **EXTRACT** `pick2_wrs_mat2x4`, Brick4 keeps its address mapping |
-| Noise | `chunk_stbn_sample_vec2`; `jitter_from_vectors` (private to Brick4's forward chunk) | **REUSE**; **EXTRACT** the hash |
-| Directional lights | `directional_lights_iteration_mask`, the light database records | **REUSE** |
-| Local lights at a world point | `world_light_cluster_metadata_by_texel`, `irradiance_clipmap_get_point_light_info_by_index` / `_spot_…` | **GENERALISE** the cluster keying from `IRRADIANCE_CLIPMAP_STRUCT` to a `CLIPMAP_LEVEL_ARRAY`; the light chunks **REUSE**. Their shadows were `volumetrics_{point,spot}_light_shadow` until 2026-10-30, and are shadow rays in the bricks since (§8.7) |
-| Sky for misses; final fallback | `sample_environment_color`, `get_ibl_irradiance` | **REUSE** |
-| Specular split at a pixel | `compute_indirect_specular`, `tSplitSum`, inside the deferred resolve | **REUSE** |
-| SDF soft-shadow penumbra | inside `shader_scene_sdf_soft_shadows` | **EXTRACT** the estimator as a pure chunk; the dense-volume shader keeps calling it. Not done (S3e): its classic estimate cannot meet §12's oracle, and the brick clipmap's was Quílez's two-sided one (§7.9), itself replaced by shadow rays on 2026-10-30 (§8.7) |
-| Appends | `chunk_collection_u32_append` | **REUSE** |
-| Parallax toward a probe's hit | LPV's iterative correction in `lpv_sample_light` | **GENERALISE** to take a depth-moment reader (§9.3) |
-
-### 4.3 Writing what does not exist
-
-| Need | Verdict |
-|---|---|
-| Mesh SDF classify, evaluate and store passes; card placement, capture and recapture; the bake and capture queues | **NEW**, inside `GPUGeometrySDFManager`, which owns every cache's storage |
-| The (geometry, material) pair bookkeeping and the row → card set table | **NEW**, on the GI, which decides what is requested |
-| `mesh_sdf_sample`, `mesh_card_surface` | **NEW**, emulator-testable pure chunks |
-| World brick clear, store, scroll, mover marking, coarse occupancy passes; the provider contract | **NEW** |
-| `MeshSDFBrickProvider` | **NEW**, written against the same contract as any plugin |
-| `brick_clipmap_trace`, `brick_clipmap_distance`, `brick_clipmap_object`, `brick_clipmap_soft_shadow` | **NEW**, emulator-testable pure chunks over seam readers |
-| Probe retire, want, admit, schedule, trace, shade, accumulate, publish passes | **NEW**; the chain follows LPV's (trace → shade with feedback → temporal → border → SH) |
-| `probe_clipmap_pick`, `probe_clipmap_sample_irradiance` / `_radiance` / `_sh` | **NEW**, on the extracted weight and pick |
-| `resolve_irradiance_sh_to_specular` | **NEW**, beside the diffuse resolve in `l1i/` |
-| `ProbeClipmapSettings`, `GPUBrickClipmap`, `GPUProbeClipmap`, `GPUProbeClipmapGI`, `BrickProvider` | **NEW** |
-| A triangle voxelizer, and (a)'s per-cell triangle gather | **not written**: the caches replace both |
-
-## 5. Architecture
-
-**Geometry caches** belong to `GPUGeometrySDFManager` on the geometry manager. They outlive the mode,
-and any future SDF reader can use them.
-
-**Per view**, one `GPUProbeClipmapGI`. It owns a `GPUBrickClipmap` and a `GPUProbeClipmap`, both
-anchored on the view's camera, and a list of providers with the mesh provider first. It allocates on
-the first frame rendered in the mode, and destroys on leaving the mode, on a settings change and with
-the renderer. There is one graph scope a frame, after the G-buffer and the shadow maps and before
-volumetrics:
-
-```
-host: place brick + probe windows; scroll boxes per moved cascade (≤ 3 each)
-      read back last frame's failure counts → grow capacity (rare)
-      bake queue: ≤ mesh_sdf_bake_budget bricks a frame, only while caches fill
-
-geometry caches (once per geometry):  classify ─► evaluate ─► store ─► place cards ─► capture
-                                      │ mesh brick atlas + indirection, card pages
-scene mover list (EXTRACTed, read by VSM too) + GI invalidation list
-         │
-brick:   scroll ─► movers ─► take ─► clear ─► providers (mesh, vgeo, …) ─► free ─► store ─► coarse
-         (pending ring, ≤ brick_build_budget a frame)
-                                                   │ brick map, SDF atlas, object cells, occupancy
-probe:   retire ─► want (depth) ─► admit ─► schedule ─┐
-                                                      ▼
-         trace (+ sun shadow rays) ─► shade ─► light (+ local shadow ray) ─► accumulate ─► publish
-         (rays = trace list × rays_per_probe ≤ ray_budget)
-                                                   │ indirection, states, records (SH2),
-                                                   │ radiance + depth atlases
-pixels:  weigh 8 (visibility only) ─► WRS pick 2 ─► SH2 diffuse; radiance ⊕ GGX-SH2 specular
-consumers: deferred diffuse / fused pass, AVBOIT + MBOIT, water, SSR, irradiance clipmap
-```
-
-Every dispatch is sized by a live count (E1):
-- an indirect command over a count an earlier pass wrote on the device;
-- or a count the host knows exactly: the scroll boxes' cells, one thread per 8×8 screen tile for
-  `want`, one per occupancy block for `coarse` (≤ `C_b·(N_b/4)³`), and the bake's queued bricks.
-
-Nothing is sized by a capacity. Persistent resources are imported every frame and written as side
-effects, so a frame that has no reader for them culls nothing that has to persist.
-
-## 6. Geometry caches
-
-### 6.1 What is cached, and for which rows
-
-**A row is in the SDF world** when both hold:
-- its `ShadedGeometry` carries `ShadedGeometryFlags.SDFWorld`, a new bit (128), on by default as
-  `CastShadow` is;
-- its material is not `TransparencyMode.Transparent`. Glass does not occlude GI rays; this is (a)'s
-  rule, now applied at the row.
-
-How the bit travels:
-- `ShadedGeometrySystem` forwards it to `attach_mesh`, as it forwards `Skinned`. A change goes
-  through `shaded_geometry_announce_change` and re-attaches, as a material change does.
-- `GPUSceneRows` mirrors it into a new `flags` word of the `meshes` row: bit 0, `MESH_FLAG_SDF_WORLD`.
-  The word sits in the row's tail padding, so the row stays 80 B.
-- A row outside the SDF world is drawn by the camera and invisible to every GI ray. It occludes
-  nothing, emits nothing into GI and bounces nothing. That is the point of the bit: performance.
-
-**A geometry is cached** when at least one row in the SDF world draws it.
-- A virtual geometry's cache is baked from a proxy cut from it, and adopted into it (§7.8, S8).
-- DynamicMesh has no row, so it is absent by construction.
-
-**What is cached, and keyed by what**:
-- per geometry: the sparse SDF (§6.2–6.4) and the card layout (§6.5). Every instance and every
-  material shares them.
-- per (geometry, material) pair: a card set, the captured contents of that layout (§6.5). Every
-  instance drawing the pair shares it.
-- A material change recaptures that material's card sets and rebuilds nothing else.
-
-**Ownership and lifetime.** `GPUGeometrySDFManager`, generalised in place, owns the storage of all
-three and runs the bakes and captures. Its evaluator stays; its dense tiles go.
-- A geometry and a pair are requested on the first `onMeshWritten` of a row in the SDF world that
-  draws them. The event is new, beside `onMeshReleased`.
-- The GI keeps row counts per geometry and per pair on the CPU, updated by the two events
-  (O(changes), E5). A row that changes material moves one count to another.
-- At zero rows a pair's card set is freed, and with the geometry's last row its SDF and layout go
-  too. A geometry or pair that comes back is baked or captured again.
-- Triangles are read only by the bake, once per geometry, and by capture, once per pair and again per
-  material change.
-
-### 6.2 Grid and size classes
-
-- **Voxel.** v = `mesh_sdf_voxel_size`, in the geometry's local units. The default 0.125 is the
-  world's finest voxel, so a mesh at unit scale is as fine as cascade 0.
-- **Grid box.** The geometry's bounds grown by R = 4v on every side, so the band fits.
-- **Bricks per axis**: `b_a = max(2, 2·⌈E_a / 14v⌉)`, with E_a the grid box's extent on axis a. The
-  spare voxels pad both sides evenly.
-  - These are Alex's size classes: 2×2×2 bricks at least, then steps of two bricks per axis,
-    independently.
-  - Even counts make the first coarser level exact, and the minimum leaves a one-brick level.
-- **Safety net.** `b_a ≤ mesh_sdf_max_bricks` (default 18, i.e. 126 voxels: UE's per-mesh cap at
-  unit scale, §2.3). Past it, v grows for that geometry until the longest axis fits. Such a geometry
-  is coarser than asked, and the bake counts it.
-  - The cap also bounds a geometry's level-0 indirection to 18³ entries, 23 KiB.
-  - At the default voxel it reaches 15.75 m before a mesh coarsens.
-- **Levels.** Level k has voxel v·2^k and ⌈b_a / 2^k⌉ bricks per axis, down to one brick per axis:
-  L = 1 + ⌈log₂ max_a b_a⌉, from 2 to 6 levels. A coarse cascade samples a coarse level (§7.7).
-
-### 6.3 Encoding and storage
-
-- **Value**: signed, in UE's encoding: `e = saturate(d/(2R) + 0.5)`, R = 4 voxels of the level, in
-  `r8unorm`. One LSB is 8/255 = 0.031 voxel.
-- **Bricks**: 8³ texels on the corners of 7³ voxels, the world's lattice (§7.2). Every geometry and
-  level shares one `r8unorm` `GPUTileAtlas3D`, the mesh brick atlas. Slots come from the extracted GPU
-  free list.
-- **Indirection**: per level, one `u32` per brick: a slot, or EMPTY on one side of the surface. An
-  EMPTY brick has no texel within the band: EMPTY (`0x80000000`) reads +R, EMPTY inside
-  (`0x80000001`) reads −R. All levels of all geometries share one storage buffer; ranges come from
-  `OffsetAllocator`.
-  - Amended in S2 (2026-10-27). EMPTY first read +R on both sides. More than a band inside a solid,
-    a band brick below zero then met an EMPTY brick at +R, and the two read as a surface that is not
-    there: on Sponza, card captures and the scene march stopped on it. Alex chose the sign.
-  - Amended in S3 (2026-10-27), when Alex chose UE 5.4's vote (§6.4). A texel with no surface within
-    the band casts no ray and reads +R, so a brick with none is outside and the bake writes EMPTY
-    alone. EMPTY inside stays in the format and its readers; no mesh bake writes it.
-  - As built (S2), the same buffer is the bake's arena. It holds the bake's counters at word 0, the
-    frame's log and tallies, and each geometry's count of bricks still to settle, one word before
-    its first entry. The ring's buffer carries the frame's staging.
-  - That keeps evaluate at ten storage buffers, beside the five a BLAS query reads, within
-    `SHADE_DEVICE_FLOOR`. Classify and evaluate first bound 12 and 14.
-- **Header**: `MESH_SDF_STRUCT`, 64 B per geometry id. It holds:
-  - grid origin and v;
-  - brick counts and level count;
-  - the levels' indirection offsets;
-  - the card layout's offset (§6.5);
-  - a state: requested, baking, resident.
-- **Deep interiors** read −R (amended in S2): a solid is below zero all through, and its surface is
-  its one zero crossing. UE's mesh distance fields are instead a signed shell as deep as the band,
-  and read +R past it.
-  - `GPUGeometrySDFManager`'s wrap of negative distances past 4 voxels existed so that an open mesh's
-    false inside could not run away. The wrap is dropped (D27).
-  - With EMPTY signed, the band no longer bounds a false inside: an open mesh reads −R as far as its
-    vote calls inside. **Measured on Sponza** (S2): its geometry 102 is an open box around the
-    building — a bottom and four outer walls, wound outward, no top. From the building's air more than
-    60% of the vote's rays meet its faces from behind (57 to 61 of 64), so that air is inside it, and
-    all of it reads −R, the courtyard included. With EMPTY at +R the same vote put a false floor R above the floor. At every
-    point the vote calls inside, at least 3 of the 64 rays leave through the open top and meet
-    nothing; from inside a closed mesh none does. Put to Alex.
-  - Amended in S3 (2026-10-27): with UE's vote, deep interiors read +R again, past a signed shell.
-    Measured on Sponza, over the 7 geometries checked in S2: UE's vote calls outside 401,141 texels
-    the 64-ray vote had inside and more than R/2 deep, 382,809 of them in nearly closed geometry 2.
-    102's false inside is a floor 0.338 m deep, where the 64-ray vote filled the building's air to
-    9.56 m. A ray from deeper than the shell inside a solid can stop where the vote's sign flips,
-    about R/2 in, as a ray down the courtyard stops on 102's false floor. Alex chose this with the
-    measurement before him (`ue-vote-measurement-2026-10-27.md`, in the shared notes).
-  - A probe inside a solid reads −R, and its rays hit at their first step (§7.2, §8.4).
-- **Skinned (the hook).** A skinned row draws a clone geometry id.
-  - The clone's header is an alias: it names its source's id, and readers follow it once. It is
-    written when `obtain_clone` makes the clone, so it tracks the source through baking to resident.
-  - The bind pose stands at the row's node.
-  - TODO: a dense patch rebuilt from the deformed vertices replaces the alias (§17).
-  - Until then, a character whose pose strays far from its bind pose is better left out of the SDF
-    world. Enshrouded keeps characters out entirely.
-
-### 6.4 The bake
-
-Geometries go through a host queue in request order. Each runs four steps:
-1. **classify**: one thread per (level, brick).
-   - It finds the exact unsigned distance from the brick's centre to the mesh with
-     `point_query_blas_nearest`: one BLAS query a brick.
-   - If that distance, less the brick's half-diagonal (6.06 voxels), is at least R, no texel can be in
-     the band, and the brick is EMPTY.
-   - Then **sign** (amended in S2): a 64-lane workgroup per classified brick. A brick classify dropped
-     casts the 64-ray vote from its centre, a ray a lane, and its last lane writes EMPTY or EMPTY
-     inside. A kept brick's workgroup leaves at once.
-     - Amended in S3 (2026-10-27): sign is gone. UE's vote casts no ray where the surface is not
-       within the band, so classify settles a brick it drops as EMPTY, as before S2.
-     - Classify first cast the vote itself, a thread's 64 rays one after another. It then cost
-       1,250 µs at the median on the 4090 against 89 µs without the vote, and 2,835 µs on the iGPU,
-       28 ms at worst. As its own pass, sign costs 56 µs at the median on the 4090 (761 µs at p90,
-       919 µs at worst), and classify is back to its 89 µs. On the iGPU sign costs 1,832 µs at the
-       median, 6.1 ms at p90 and 31 ms at worst, against the serial vote's 2,835 µs, 4.5 ms and 28 ms:
-       there the cost is the vote's rays either way, all in the frame that admits a large geometry,
-       and they are not budgeted.
-2. **evaluate**: a thread per texel of each surviving brick, eight 64-lane workgroups a brick, as the
-   dense build maps them.
-   - Each texel is `blas_query_sdf`, as the dense build evaluates it: exact nearest point plus the
-     64-ray vote at 60%.
-     - Amended in S3 (2026-10-27): each texel is `blas_query_band_sdf`, UE 5.4's vote (§2.3). It
-       takes the nearest point within the band, and only there casts 98 rays one band long, in UE's
-       directions; the texel is inside past 25% back faces.
-     - A field is two-sided while one of its holders' materials draws both sides. Then no face is a
-       back face, and it casts no ray at all. A change of its holders' side bakes it again at the
-       next bake, so holds that move within a frame bake nothing.
-   - A brick whose texels are all at |d| ≥ R is EMPTY after all, on the side most of its texels are.
-     Under UE's vote such a texel cast no ray and reads +R, so the brick is EMPTY (S3).
-   - Amended in S2 (2026-10-27). This revision first had one 64-lane workgroup per brick, eight
-     texels a lane. A lane then runs its eight texels' votes one after another, and a single brick
-     cost more than the 1 ms budget (see **Budget**).
-3. **store**: a slot is popped and 512 bytes written.
-   - As built, the frame's take hands out no more bricks than the free list has slots, so no pop
-     fails.
-   - A take held back by the slots logs itself starved. The host then doubles the atlas and the free
-     list, and the held bricks wait on the ring for a later frame. This replaces counting failed pops.
-4. **cards**: the layout's placement (§6.5). Capture runs per pair once the layout exists.
-
-**Budget.** At most `mesh_sdf_bake_budget` bricks are evaluated a frame.
-- A brick costs 512 × (1 + 64) ≈ 33k BLAS queries, and what that takes follows its geometry's tree.
-  Under UE's vote (S3) it is at most 512 × (1 + 98), and only texels with the surface within the band
-  cast rays, each one band long.
-- This is a time knob like `shadow_update_budget`. Its default, **23**, is set by measurement against
-  1 ms a frame on the 4090.
-
-The mapping, measured in S2 on Sponza's largest geometry (6,722 bricks, 2,211 triangles), over its
-first N bricks with timestamp queries. All three write the same bytes.
-- *8 a lane*: one 64-lane workgroup a brick, eight texels a lane (this revision's first).
-- *1 a thread*: a thread a texel (as built).
-- *1 ray a lane*: a workgroup a texel, a vote ray a lane.
-
-| bricks | 4090: 8 a lane | 4090: 1 a thread | 4090: 1 ray a lane | iGPU: 8 a lane | iGPU: 1 a thread | iGPU: 1 ray a lane |
-|---:|---:|---:|---:|---:|---:|---:|
-| 1 | 1,208 µs | 103 µs | 36 µs | 1,705 µs | 806 µs | 1,566 µs |
-| 8 | 1,564 µs | 142 µs | 142 µs | 3,481 µs | 2,107 µs | 9,062 µs |
-| 64 | 2,009 µs | 234 µs | 2,374 µs | 14,425 µs | 12,690 µs | 72,844 µs |
-| 512 | 4,212 µs | 2,169 µs | 23,201 µs | — | — | — |
-
-**The default.** Measured over Sponza's whole fill, with budgets from 16 to 192 cycled in blocks of
-frames in one process, so that each saw every stretch of the fill.
-- Sponza has 103 geometries, all coarsened by the cap. Its glTF merges each material's copies into
-  one mesh that spans the building.
-- On the 4090, evaluate costs 798 µs plus 8.6 µs a brick at the median, which reaches 1 ms at 23
-  bricks.
-- At 23, the whole fill's evaluate costs 840 µs a frame at the median, 1.66 ms at p90 and 5.3 ms at
-  worst. Every geometry is resident after 5,712 frames of baking.
-- On the AMD iGPU, 23 bricks cost 26 ms a frame at the median and 79 ms at worst. No budget fits
-  1 ms there: one brick costs 2.3 ms. A frame of 2,048 bricks outlasted the 2 s TDR and lost the
-  device.
-
-**UE's vote differs** (§2.3). It casts 98 rays, each only one band long, and counts back faces past
-25%, never on two-sided triangles. The bake keeps `GPUGeometrySDFManager`'s vote (64 unbounded rays,
-60%), which Alex has confirmed correct. If the bake measures slow, UE's band-length rays are the first
-lever, since a ray that stops at the band is far cheaper than one that crosses the mesh. That changes
-which points vote inside, so it would be measured against the current vote first. It is not needed to
-meet the 4090's 1 ms. Whether the iGPU's cost above calls for it is put to Alex.
-
-**Adopted in S3 (2026-10-27).** Measured against the 64-ray vote (`ue-vote-measurement-2026-10-27.md`,
-in the shared notes):
-- the 4090's evaluate is the same at the median, 559 + 5.58 µs a brick against 568 + 5.54;
-- the iGPU's is 16–19% less a frame;
-- sign's 5.0 ms over Sponza's fill is gone.
-
-Alex chose it.
-
-**Completion.** The header turns resident, and the GI invalidates the world boxes of the geometry's
-rows in the SDF world (§7.4). The CPU knows those rows from its bookkeeping (§6.1). Each box is the
-row's geometry box under its entity's `Transform64`, projected as `GPUSceneRows.compute_world_bounds`
-projects one.
-
-### 6.5 Surface cards
-
-**Placement** runs on the bake's level-0 occupancy once the geometry is resident: five passes a
-geometry, as built in S2 (below). It is UE's surfel clustering (§2.3) at brick granularity.
-- The directions are ±X, ±Y, ±Z of local space.
-- Along a direction δ, a column is a line of bricks.
-- A **run start** is an occupied brick at layer z whose predecessor along δ is empty or outside the
-  grid. Its m is the layer after the previous run's end (0 for the first run).
-- A card (δ, [k₀, k₁)) looks along δ through brick layers k₀ to k₁ − 1.
-  - In each column it sees the first surface after layer k₀.
-  - It covers a run start (z, m) when m ≤ k₀ ≤ z < k₁: nothing occupied lies between its near face
-    and the run.
-- The search:
-  - Each direction starts with one card over the whole grid, its outer projection. This covers each
-    column's first run.
-  - Each further card splits a slab of some direction at the layer that newly covers the most run
-    starts. The split's far part covers from its own near face whatever the near part loses, so
-    coverage never shrinks.
-  - It stops when every run start is covered, or at 32 cards a geometry, UE's ceiling (its default is
-    12). A run start left uncovered reads the material mean (§6.6).
-- A convex mesh gets six cards; a room or an atrium gets interior slabs.
-
-**The layout**, per geometry.
-- A card's texels are the brick grid projected along δ at level-0 resolution: one 8×8-texel page per
-  column, on the corner lattice of the bricks' faces.
-- A page exists only where the slab holds an occupied brick in that column. The layout records which
-  columns those are.
-
-**Card sets**, one per (geometry, material) pair: the layout's contents for that material.
-- Per card, a page table: one `u32` per column of the card, naming its page. As built, the tables
-  are the layout's, shared by every card set of the geometry, and a card set's pages are a run of
-  atlas tiles from `OffsetAllocator`, in the layout's page order (below).
-- A header: on the device the geometry, the material's resident id, the first tile and the emissive
-  scale s_e; on the host the material version captured and a state (waiting for its layout,
-  capturing, resident).
-- Pages live in the extracted 2-D tile atlas as two `rgba8unorm` planes:
-  - √(diffuse albedo), and depth;
-  - emissive / s_e, and a channel kept at 0.
-- **Diffuse albedo** is albedo × (1 − metalness), Lumen's diffuse colour. It is stored as its square
-  root, as UE stores it, which spends the 8 bits where dark albedos need them.
-- **Emissive** is divided by s_e, the largest component of the material's emissive factor. The
-  resident emissive textures are 8-bit, so emissive never exceeds s_e, and 8 bits under that scale
-  lose nothing the source had.
-- **Depth** is the surface's distance from the slab's near face over the slab's depth, mapped onto
-  [1/255, 1]. A texel whose ray found nothing in the slab stores 0.
-- A texel costs 8 B and a page 512 B, the size of one SDF brick.
-
-**The row → card set table**: one `u32` per `meshes` row, written by the GI on `onMeshWritten` from
-the row's pair.
-- It holds `GPU_DATABASE_NULL` for a row with no card set: a virtual geometry, or a pair still
-  capturing.
-- A skinned row's pair names the source geometry, which its CPU entry keeps.
-
-**Capture**, one thread per page texel of a pair:
-1. A ray in local space starts at the slab's near face and runs along δ, with t ≤ the slab's depth,
-   through `ray_query_blas_nearest`.
-2. Alpha is treated as the path tracer treats it. A hit is opaque with probability equal to its
-   opacity (`sample_material_alpha`), drawn from the texel's fixed seed.
-   - A transparent draw continues the ray past the hit, at most 4 times (chosen). Past that the texel
-     is empty.
-3. At the opaque hit, `sample_material_data` runs with the material's resident row and an identity
-   instance transform (the card is in local space).
-   - Since 2026-10-30 both reads take the material's textures at the texel's footprint, trilinearly
-     (`mesh_card_texture_level`; the capture is `INDIRECT_TEXTURE_FILTER` `Exact`): the card's texel
-     steps carried along δ onto the triangle and through its uv per position, the level
-     log2(texels × 64), the last level for a triangle edge-on.
-   - Its random state is seeded from (pair, texel), which fixes its alpha draws and its dither.
-   - A recapture of an unchanged material therefore writes the same bytes.
-4. The texel stores √(albedo × (1 − metalness)), depth, and emissive / s_e.
-
-**Capture by raster** (`MeshCardCaptureMode.Raster`, the default since 2026-10-30), UE's way: the
-cards are drawn rather than traced, through the material's own template.
-- The trace above took one level-0 tap of the material's 64² resident copy a texel and kept it, a
-  point sample of a texture a card texel covers many texels of. On Sponza's outer wall the brick
-  texture's dark band repeats every 12.8 card texels; it landed on a row of sample points once and
-  between rows at its other repeats, a hard seam across the wall. It now reads the copy's mips at
-  the footprint (step 3), and over that wall its cards differ from the raster's by 0.77 codes on
-  average, against 10.5 before.
-- A pair is taken whole. Its cards are drawn by one indirect draw, an instance a meshlet of each card
-  the layout has (a compute pass writes the count), each card into a cell of the pair's region of a
-  scratch: orthographic along δ, the lattice point at the texel's centre, the slab the depth range,
-  so the hardware clips to it as the trace's t ≤ depth does. Culling is off: a card sees either side.
-- The fragment stage is the template's `material_surface` and `material_opacity`, with the material's
-  one bind group, the G-buffer pass's: its textures, their mips and hardware filtering, at the card
-  texel's footprint, unbiased (mip bias 0). Coverage is
-  drawn as the trace draws it, from a seed fixed per (pair, card, texel); the depth test keeps the
-  nearest opaque draw. A template without a surface function is traced.
-- A scatter then moves each page's texels from the pair's cells into its atlas tiles, in the trace's
-  encoding.
-- Measured on Sponza: the cards' colours agree with the trace's to 3 codes on average over the wall,
-  floor, ceiling and banners, without the seam or the trace's speckle. Recapturing all 154,138 pages
-  at the largest budget, interleaved in one process, cost the trace 9.1–12.7 ms and the raster 0.6 ms
-  on the RTX 4090, and 335 ms against 33 ms on the AMD iGPU.
-
-**Recapture.**
-- `GPUResidentMaterialContext` signals when it repacks a material whose version moved (§4.1). The GI
-  keeps the reverse map from a material to its pairs and queues each for recapture: O(changes), E5.
-- A recapture rewrites the pair's pages in place, since the layout is the geometry's and has not
-  changed. Until then, the pair's hits read the previous capture.
-- A material that changes every frame stays queued, and its GI lags by the queue's wait. The budget
-  bounds what that costs. UE has the same lag, and does not notice a material change by itself
-  (§2.3).
-
-**Budget.** At most `card_capture_budget` pages a frame: new pairs first, then recaptures in the
-order queued.
-- A page costs 64 texels × (a ray, up to 4 alpha draws, a material sample).
-- This is a time knob. Its default, 16,384 pages, is derived against 1 ms a frame on the RTX 4090, as
-  the bake's is.
-  - Sponza's 103 card sets (154,138 pages) were recaptured with the budgets interleaved frame by frame
-    in one process. 16,384 pages cost 0.33, 0.43 and 0.87 ms at the median in three runs, and
-    32,768 went past 1 ms in all three: the cost turns steeply between the two.
-  - The runs shared the 4090 with another load of 40–73%, which is in the medians. The least loaded
-    frames cost 0.11 ms at 16,384.
-  - At the default Sponza's cards are captured in 10 frames.
-  - On the AMD iGPU (RDNA2) a page costs 0.78 µs. 16,384 pages cost 33.5 ms at the median, and about
-    1,290 fit 1 ms (1,024 cost 0.80 ms).
-
-**As built in S2.**
-- Placement is five passes a geometry, each sized by a count the host knows or by the merge's
-  dispatch:
-  - histogram, a thread a column of the six directions: run starts by (m, z);
-  - split, a thread a direction: its 2-D prefix sums, then its greedy splits by gain;
-  - merge, one thread: the six directions' splits taken by gain, the global greedy; the card records;
-    the page pass's dispatch;
-  - pages, a thread a column of every card;
-  - log.
-- Placement runs in a range sized for any layout of the grid. Its log record gives the columns and
-  pages it took. On that readback the geometry gets a range of exactly that size, and the next bake
-  copies the layout into it and gives the placement's range back.
-  - The layout is then its header, the records, the column tables and the page list:
-    131 + columns + pages words.
-  - At most 7 geometries are placed a frame, ⌊1 ms / 140 µs⌋ on the 4090.
-- A recapture writes the record, s_e included, at its first page. A recapture longer than a frame
-  reads its pages not yet recaptured under the new s_e until it finishes.
-- Measured over Sponza's fill (103 geometries, one material each):
-  - 12 cards a geometry at the median, 26 at most, none at the ceiling;
-  - 1,322 pages a geometry at the median, 154,138 in all, 79 MB of atlas; the layouts 391,055 words,
-    1.5 MB.
-- Placement costs 140 µs a geometry at the median on the 4090, and 220 µs on the iGPU. The split pass
-  is most of it, 76 µs and 130 µs: its six threads walk up to 26 steps over every layer each, 2.3 ms
-  at worst on the 4090.
-
-### 6.6 Material at a hit
-
-`mesh_card_surface(p, n, row) -> surface`:
-1. The row → card set table gives the card set. If it is null, go to step 6. The row's node gives
-   `global`. Move p and n into local space, with the inverse taken on demand as the scene's other
-   readers take it.
-2. Take the directions that face the surface. For each axis a with n_a ≠ 0, the cards look along
-   −sign(n_a)·e_a, with weight n_a², as UE weighs them.
-3. Scan each such direction's cards, which are sorted by near layer and number at most 32 in all. A
-   card passes when both hold:
-   - its slab holds p's depth within the tolerance τ;
-   - its nearest texel's stored depth is within τ of p's depth.
-     Otherwise the card sees something in front of p.
-
-   τ is 1.5 voxels of the hit's cascade, in local units, plus one LSB of the slab. That is UE's bias
-   for a global-SDF hit, three half-voxels of its clipmap (§2.3). A hit is only as exact as its
-   cascade, so the tolerance must grow with it.
-4. Within a direction, the passing card nearest the surface serves.
-5. Each serving card gives its nearest texel, and the texels are blended by n_a², as UE blends every
-   card that passes:
-   - diffuse albedo, Σ w·(stored)² / Σ w;
-   - emissive, Σ w·stored·s_e / Σ w.
-   - One texel a card is enough: UE's four depth-weighted taps per card smooth what a probe's many
-     rays average anyway.
-6. With no passing card, or no card set (a virtual geometry, a plugin's object, a pair still
-   capturing), the hit takes the **material mean**:
-   - diffuse: the colour factor × the albedo slot's mean × (1 − the metallic factor × the ORM slot's
-     mean metalness);
-   - emissive: the emissive factor × the emissive slot's mean.
-   `GPUResidentMaterialContext` computes a slot's mean when it writes the slot: one reduction per
-   upload (§4.1).
-   - UE has no such fallback: a hit no card sees is opaque black. Here it keeps the bounce's energy
-     roughly right.
-
-Cost per hit:
-- one table entry, one row and one node read;
-- for each facing direction, a scan of its cards with a page and two texel loads per candidate;
-- no material evaluation.
-
-As built in S2, `mesh_card_surface(card_set, p, n, tolerance)` takes the card set and p and n in
-local space: steps 2–5. The table lookup and the move to local space are the caller's: the
-MeshCards debug view's now, the hit shading's in S4. The material mean (step 6) comes with S4.
-
-**As built (S4d, 2026-10-28)**:
-- **Steps 1 and 6** are `probe/chunk_probe_clipmap_hit_surface.js`, around `mesh_card_surface`. The
-  row's node moves the hit into local space by `mat4_inverse`, the normal by the transpose of the
-  node's linear part, and the tolerance by the transform's mean scale, the cube root of its
-  determinant. Row 0 names no object and is black.
-- **The texture slots' means** are `material/resident/shader_resident_texture_means.js`, two passes
-  `GPUResidentMaterialContext.build_textures` records after it writes the slots: a lane a row of a
-  slot's 64, then a thread a slot over its rows. No thread reads more than 64 values. The means are
-  stored as the atlas stores texels, so an albedo's is premultiplied by its coverage and `rgb / a` is
-  the mean colour of what the slot covers. They live in `buffer_texture_means`, which doubles when the
-  slots outgrow it.
-  - The four layout constants moved out of the material context into
-    `RESIDENT_MATERIAL_TEXTURE_LAYOUT.js`, which the passes and their readers share.
-- On the device, Sponza: 70 slots, each mean within 7.5e-7 of the atlas read back and averaged on
-  the CPU, on both GPUs.
-
-## 7. The brick clipmap
-
-### 7.1 Cascades
-
-- `C_b` cascades (`brick_cascade_count`, default 6), each a window of `N_b³` cells
-  (`brick_cascade_resolution`, a power of two, default 32).
-- A cell is one brick of 7 voxels a side. The voxel is `h_c = h₀·2^c` (`brick_voxel_size` = h₀,
-  default 0.125 m).
-- At the defaults, a cell is 0.875 m at cascade 0, and the windows span 28, 56, 112, 224, 448 and
-  896 m.
-- h₀ = s₀/8 puts eight voxels across one probe cell at the probe defaults (§8.1).
-- **Placement** is `ClipmapWindowSet` (size `N_b`, step 1, hysteresis 0.1 cells, the fluid's
-  value), coarsest first. Each child is held inside its parent by `clamp_corner` with a one-parent-
-  cell margin, so a ray leaving cascade c is inside c + 1.
-  - As built (S3): the fluid's `FluidCascadePlacement` already composed these with a jump that
-    re-places the stack, and is generalised into `ClipmapCascadePlacement` (`core/geom/clipmap/`)
-    with the step, hysteresis and margin as options. The fluid keeps its own.
-- **Storage wraps**: a cell sits in storage cell `cell mod N_b` (a mask, since `N_b` is a power of
-  two). Cascades stack along z of one texture.
-
-### 7.2 Brick layout and encoding
-
-- **Lattice.** 8³ texels sit on the corners of the brick's 7³ voxels. Texel `t` is at voxel
-  `7·cell + t`; texel 7 duplicates the next brick's texel 0, and every brick computes all 512 of its
-  own.
-- **Lookup.** The atlas texel coordinate is `slot_origin + 0.5 + (p − cell_min)/h`, with the local
-  part in [0, 7]. Hardware trilinear never reads a neighbouring slot, and there is no border pass.
-  This is the UE page, and the mesh bricks use the same lattice (§6.3).
-- **Value.** Signed, `e = saturate(d/(2R) + 0.5)` with R = 4 voxels of the cascade, decoded
-  `d = 2R·(e − 0.5)`.
-  - One LSB is 0.031 voxel, UE's precision.
-  - `r8unorm` storage writes need `texture-formats-tier1`, which is on `SHADE_DEVICE_FLOOR`.
-- **Hit.** A ray hits when d < ½ voxel of its cascade (UE's surface expand), so a wall thinner than a
-  voxel stays a hit.
-- **Normal.** The field's gradient, which points out of the solid.
-- **Inside.** A ray that starts inside a solid reads a negative distance at its first step and hits
-  there at once. §8.4 counts it as a back face.
-- **Filter precision.** RDNA2 rounds bilinear weights to 1/256 (measured in the octahedral skirt
-  work). Neighbouring texels differ by at most one voxel (|∇d| ≤ 1), so the weight error is at most
-  1/256 voxel per axis, about 1/128 of the hit threshold.
-
-### 7.3 Storage
-
-**Brick map**: `r32uint`, `N_b × N_b × N_b·C_b`. Each entry is one of:
-- `0xFFFFFFFF`, **UNKNOWN**: not classified since entering the window. The engine's null.
-- `0x80000000`, **EMPTY**: no surface within one voxel of the cell, outside.
-- `0x80000001`, **EMPTY inside** (S3): the same, inside a solid, on the side most of its staged
-  texels are on, as a mesh brick's EMPTY is (§6.3). A ray that starts in one hits at once (§7.2).
-- a slot index.
-- Between free and store only, `0x80000002` marks a cell that needs a brick and holds no slot yet.
-
-**Occupancy**: `r32uint`, `(N_b/4)³` blocks per cascade, stacked. The value is the count of the
-cells among a block's 64 that a ray must read: bricks, UNKNOWN and EMPTY inside. 0 means the tracer
-may skip the whole block.
-- As built (S3): blocks are in storage space, as the map is. A window whose corner is not a
-  multiple of 4 puts cells of both its ends in one block, so a ray clamps a block it skips to the
-  window. The window's step stays one cell.
-
-**SDF atlas**: the `GPUTileAtlas3D` above, usage `TEXTURE_BINDING | STORAGE_BINDING`, sampled with
-a linear clamp sampler.
-
-**Object cells**: a storage buffer, 64 `u32` per slot. Entry i is the `meshes` row whose surface is
-nearest in the brick's i-th 2³-texel cell.
-- 0 means none: row 0 is the scene root and never a mesh.
-- 256 B a slot, against (a)'s 1 KiB material lattice.
-
-### 7.4 What is built each frame
-
-**Pending cells** live in a persistent FIFO ring of *storage* cell keys (cascade + storage index,
-one word). A per-storage-cell pending bit keeps any key from appearing twice.
-- A taken key builds whatever world cell its storage slot holds at that moment, decoded from the
-  current window. A cell that scrolled out while queued is therefore never built, and the cell that
-  replaced it is.
-- The ring never holds a stale entry, and it holds every key at most once: `C_b·N_b³` words, 768 KiB
-  at the defaults.
-  - As built (S3): the ring's capacity is the power of two at or past `C_b·N_b³`, 1 MiB at the
-    defaults, because its head and tail run on through the u32 wrap and a power of two divides it.
-  - A key's pending bit clears in free, once the key is off the ring and built, so a mover may
-    queue it again.
-
-The ring is fed by three passes:
-- **scroll** (one thread per exposed cell, a count the host knows from its scroll boxes):
-  - the storage cell's old entry, if a slot, is pushed to the free list (the cell it belonged to has
-    left the window);
-  - the entry becomes UNKNOWN;
-  - the key is queued unless already pending.
-- **movers** (one thread per (occupancy block, box) pair):
-  - The boxes are:
-    - the scene mover list's, except boxes flagged skinned, because skinned rows stand in bind pose
-      (the hook: a dense patch reads them, §6.3);
-    - the GI's invalidation list: boxes the host writes on bake completions (§6.4) and on SDF
-      membership changes it sees through `onMeshWritten`, and boxes providers append on the device
-      (§7.6).
-  - Every box is expanded by that cascade's R.
-  - The resolution cull: a box whose diagonal is under half a voxel of the cascade is skipped there.
-  - An overlapping pair tests the block's 64 cells (bounded) and queues the overlapped ones.
-  - The pair count is blocks × boxes: it follows the box count and never a box's footprint (E3).
-  - Past 1,024 boxes (UE's full-recapture threshold), or a list past its capacity, every key of every
-    cascade is re-queued instead: one pass over the keys rather than millions of pairs.
-  - As built (S3d):
-    - The movers' command, one thread, reads the scene list's count and the host's row count and
-      writes either the pair dispatch or the full re-queue's, into a buffer of its own that the
-      movers and the re-queue only read.
-    - A pair skips a pose-only box (bind pose, the hook). Otherwise it tests its block's 64 cells
-      against the box grown by the cascade's band, each cell's world position decoded from the
-      window.
-    - A row's box is read from the `meshes` table on the device. The host's list comes from the GI's
-      holds: rows drawing a geometry whose bake completed, and rows whose SDF membership changed.
-      They are rows as the tables address them, `row_of_entity`, not entities.
-      - Entities were what the first device run listed. Every completion rebuilt its neighbour's
-        box, and the cells inside Sponza's hull were never rebuilt. Once that was fixed, a build
-        made under caches turning resident is the same, cell by cell, as one made after they are
-        all resident.
-    - A fresh clipmap skips the movers: its scroll has queued every cell. On the iGPU, the first
-      frame's joins and movers, about 200 boxes the size of Sponza, had cost 35.8 ms for nothing.
-    - Measured on Sponza: the movers cost 3 µs at the median on the 4090 (25 µs at p90, 524 µs at
-      worst), and 1.6 µs on the iGPU (0.85 ms at worst). An idle frame of the whole build is now
-      19–20 µs on the 4090 and 13–14 µs on the iGPU.
-- **take** (one thread): `n = min(count, brick_build_budget)` keys leave the ring, each with a build
-  slot 0..n−1, and the indirect commands are written.
-  - As built (S3): no more than the free list's slots, as the mesh bake's take is (§6.4). Every cell
-    taken may need a slot, so no pop of store's fails. A take held back counts itself starved,
-    and the host grows the capacity on the readback. That replaces counting failed pops and
-    re-queueing their cells.
-  - The commands, with the taken keys' first and count, go into a buffer of their own that every
-    later pass binds read-only and dispatches through. A dispatch that writes a buffer cannot use
-    it as its indirect command, and free and store write the free count (the device's validation
-    refused the first build, which kept them in one buffer).
-
-### 7.5 The build
-
-- **clear**: one thread per staging word. Distance bytes become 255 (+R) and objects 0.
-- **providers**: in registration order, each its own indirect passes over the taken keys (§7.6).
-- **free**: one thread per taken key.
-  - `needs_brick` holds when some staged texel has |d| < 1 voxel. Every point of the cell is within
-    √3/2 voxel of a texel and |∇d| ≤ 1, so a surface crossing the cell always qualifies.
-  - If not, and the entry is a slot, the slot is pushed and the entry becomes EMPTY.
-  - As built (S3): a workgroup a taken cell, eight texels a lane. Its last lane decides, so that
-    nothing waits on a barrier. A cell that needs no brick becomes EMPTY on the side most of its
-    512 texels are on. One that needs a brick and holds no slot is marked for store.
-- **store**: one workgroup per cell that needs a brick.
-  - The slot is the existing one, or one popped by lane 0.
-  - A failed pop leaves the entry UNKNOWN, counts the failure for growth, and re-queues the cell.
-  - Otherwise the 512 staged bytes go into the atlas tile and the 64 objects into the object cells.
-  - As built (S3): a workgroup a taken cell. Lane 0 pops for a marked cell, writes the entry, and
-    hands the slot to the other lanes through `workgroupUniformLoad`. Take's bound keeps every
-    pop from failing.
-- **coarse**: one thread per occupancy block of every cascade touched this frame. It counts the
-  block's non-EMPTY cells.
-  - As built (S3): a 64-lane workgroup per taken cell recounts that cell's block, a lane a cell,
-    sized by take's count. Scroll marks each block it exposes as all to read until its cells are
-    built, since a ray must not skip a cell it should read from the next cascade out. A first
-    version counted every block of every cascade each frame: 31 µs a frame on the iGPU with
-    nothing to build.
-  - Measured on Sponza with no provider yet, so every cell builds EMPTY. On the 4090 the first
-    frame costs 332 µs, scrolling all 196,608 cells in 52 µs, and a frame of the fill (4,096
-    cells) 31–42 µs. An idle frame costs 10–14 µs, the floor of five passes. On the iGPU the
-    first frame costs 3.45 ms, a fill frame 545–562 µs, an idle one 7–19 µs. In the fill a block
-    is recounted by each of its taken cells, about 140 µs of the iGPU's frame. Store's first
-    dispatch costs 249 µs on the 4090 and 2.06 ms on the iGPU, once.
-
-Frees run before pops (separate dispatches), because a stack under concurrent push and pop is not
-safe. The staging is 768 B a build slot: 3 MiB at the default budget.
-
-### 7.6 The provider contract
-
-This is the plugin system.
-
-**Host interface.**
-- A `BrickProvider` has one method, `graph_write_bricks(graph, ctx)`.
-- `GPUProbeClipmapGI.add_provider(provider)` and `remove_provider(provider)` manage the list.
-- The mesh provider is registered first and is written against the same contract as any plugin.
-- `ctx` holds:
-  - the taken keys, with their count on the device;
-  - the brick levels uniform;
-  - the staging: distance bytes and objects;
-  - the scene database and the TLAS;
-  - the invalidation append list.
-
-**The contract.**
-1. **Ownership.** A workgroup owns whole taken cells: within a pass no two threads touch the same
-   staged word, and there are no atomics.
-2. **Distance.** Per texel, `staged = min(staged, q(d))`, where q is the shared encoding of §7.2.
-   - q is monotone, so the minimum of the bytes is the byte of the minimum.
-   - The order of providers cannot change the result.
-3. **Object.** Per 2³ cell, the provider's row at its own nearest texel replaces the staged object
-   when the provider's cell minimum is below the staged cell minimum (taken from the staged bytes
-   before its own merge). Ties keep the staged object.
-4. **Safety.** A provider may under-estimate distance, which only slows steps. It never
-   over-estimates, which would tunnel.
-5. **Objects are `meshes` rows**, so a hit finds its material through the row (§6.6). A provider that
-   cannot name a row writes 0, and its hits take the material of no row: zero albedo, counted.
-6. **Invalidation.** When a provider's data for a region changes (streaming, an edit), it appends that
-   world box to the invalidation list, and next frame's movers queue the cells.
-7. **Retry** (S9). A provider that could not finish a cell this frame sets the cell's retry word in the
-   staging (`BRICK_STAGING_RETRY_WORD`). Free decides the cell as any other, keeps its key pending and
-   puts it back on the ring, so the cell is built again from the start. What was merged meanwhile is
-   published for those frames, and can over-estimate where the unfinished work would have read lower;
-   the frame that finishes the cell keeps contract 4.
-
-A provider sees every taken key. One with nothing in a cell writes nothing and pays only its own
-early-out.
-
-### 7.7 The mesh provider
-
-**Superseded in part by S9 (2026-10-29).** Alex, after S8's holes: "Go with (b): batches of 64 spread over
-workgroups by count, with an atomic min/max merge." The cap of 64 instances below bound from cascade 2 on Zorah, and
-the instances it kept were the lowest rows, in load order: the ground under the greenhouse's ring lost to the kitbash
-numbered before it. The accept, the per-instance level and the texel stand; the cap, and one workgroup doing all of a
-cell, are gone. What is built now is "As built (S9)", at the end of this section.
-
-`MeshSDFBrickProvider` runs one 64-lane workgroup per taken key.
-
-**Gather.** A TLAS cooperative query with box = cell ⊕ R_c. The leaf accept takes a row when all of
-these hold:
-- `MESH_FLAG_SDF_WORLD` is set;
-- its geometry's header is resident (a skinned clone resolves through the alias, the hook);
-- the resolution cull passes: box diagonal ≥ ½ voxel of the cascade.
-  - UE uses max(20 cm, ½ voxel) and exempts emissive objects.
-  - Here an emissive object under the cull is out of that cascade. The ½-voxel hit would fatten it
-    into a lamp a voxel wide, and at cascade 5 that is 4 m.
-- the geometry is not virtual (a virtual geometry has no header).
-
-**Per instance**, up to 64 in LDS:
-- the inverse of `node.global`, and the instance's world box;
-- σ, the smallest axis scale. It is exact for uniform scale and an under-estimate otherwise (contract
-  4). UE scales the same way;
-- the level `k = clamp(⌊log₂(h_c / (σ·v))⌋, 0, L − 1)`, the coarsest level no coarser than the
-  cascade.
-  - Inside the clamp, its voxel is within a factor of two of the cascade's, and its band
-    (4·σ·v·2^k) reaches past half the cascade's (4·h_c).
-  - Past a level's band a sample under-estimates (contract 4). That only slows steps, and it can only
-    keep `needs_brick` true, never make it false.
-  - At the clamps: an instance scaled up past the cascade's voxel samples level 0, coarser than
-    asked. A small geometry at a far cascade samples its one-brick level.
-- Past 64 instances, the rest are dropped and counted; a dropped instance can leave a hole. UE loops
-  its LDS passes instead and has no cap, at the price of an unbounded loop. The cap is chosen: coarse
-  cascades are where it binds, since a 28 m cell at cascade 5 holds every instance over the 2 m cull.
-  The LDS is 64 × 64 B.
-
-**512 texels**, eight a lane: the minimum over instances of `σ·mesh_sdf_sample(header, k, M⁻¹·p)`,
-with the argmin row.
-- First the box test, UE's early-out: an instance whose box lies farther than the texel's running
-  minimum is skipped. At coarse cascades most of the 64 are only this test.
-- `mesh_sdf_sample`:
-  - outside the grid box, the distance to the box plus R. This is a true lower bound: the surface lies
-    inside the bounds, which lie at least R inside the box. UE instead adds the box distance to the
-    SDF at the clamped point;
-  - in an EMPTY brick, ±R by its side (§6.3);
-  - in a slot, one hardware trilinear tap of the mesh brick atlas.
-- Per 2³ cell, the argmin row of the cell's nearest texel. Then the merge (contract 2 and 3).
-
-**Cost.** Per texel, at most 64 box tests, plus one 3×4 transform, one indirection load and one tap
-for each instance the box test lets through. It follows the instances in the cell, never a triangle
-count (E3), and no triangle is read.
-
-**As built (S3c).**
-- The box test skips an instance whose box lies farther than the running minimum, or than zero
-  when the minimum is inside a solid. So a deeper overlapping instance is still sampled, and the
-  minimum does not depend on the order of the instances. Under non-uniform scale it can skip an
-  instance whose under-estimated sample would have been lower; the result still never
-  over-estimates (contract 4).
-- Objects: a 2³ cell's four lanes fold their texels into workgroup atomics, and the last of them
-  decides, so that no lane waits on another.
-  - One word holds the nearest texel's byte and its row, the lowest row on a tie.
-  - Rows fit in 24 bits; a row past them names no object (contract 5).
-- The kernel's barriers keep it off the emulator, as the cooperative query is kept. Its parts are
-  tier-2 pure chunks: the leaf filter, the instance, the texel, the object bid. The texel is held to
-  the analytic distance of two scaled spheres within the field's error, and to the least of what
-  each instance reads alone. The glue is checked on the device.
-- Measured on Sponza (S3c), the bricks made again once every cache was resident:
-  - The 4090: the provider costs 58 µs at the median a frame of 4,096 cells, 166 µs at p90, 315 µs
-    at worst; a frame of the fill totals 80–350 µs.
-  - The iGPU: 1.06 ms, 2.1 ms and 6.1 ms; a frame of the fill 1.6–6.7 ms.
-  - All 196,608 cells are built in 48 frames, 5,315 of them with a brick (5,311 on the iGPU, whose
-    bilinear weights round to 1/256), within the initial capacity of 12,288.
-  - 58 instances were dropped past 64 in a cell, the gather itself dropping nothing.
-  - With EMPTY signed (§6.3) the building's air reads inside its open hull (geometry 102), so the
-    courtyard is solid in the world bricks too; put to Alex.
-
-**As built (S9, 2026-10-29)**: every instance whose box comes within the band of a taken cell is sampled there,
-however many. Three passes, each sized by a count on the device, and a one-thread command
-(`shader_mesh_brick_command`) before each but the walks from the root:
-- **Walk** (`shader_mesh_brick_gather`), a workgroup a walk: the cooperative query's level-at-a-time expansion and
-  the S3 accept, nothing dropped.
-  - A level keeps 512 nodes (`MESH_BRICK_FRONTIER`); the children past them leave in task records of 64 nodes, each
-    walked by the next round of the same kernel. On Zorah's TLAS (12,608 leaves, 27 levels) the widest level of a
-    cell's walk is 758 nodes at cascade 2 and 2,410 at cascade 5, so every walk ends in its third round.
-  - Rounds start at two and grow by one, from a read-back count, when the last round could not finish a walk, up to
-    six: enough for any LBVH of 2^20 leaves.
-  - Accepted rows leave in batch records of 64, and the rows left when the walk ends in one more.
-  - An iteration of a level costs the workgroup a barrier and a `workgroupUniformLoad`: lane 0 hands every lane
-    where the next iteration's children start and, on the level's last, how many nodes the next level holds.
-- **Batch** (`shader_mesh_brick_batch`), a workgroup a record: its rows sorted, its 64 instances in workgroup memory,
-  512 texels × 64 as S3c samples them, merged into the cell's accumulators by atomic maxima of 255 less the byte and
-  of the object key.
-- **Resolve** (`shader_mesh_brick_resolve`), a workgroup a cell the walks listed: its accumulators into the staging
-  by contracts 2 and 3. A walk lists a cell the first time it flags it, for a batch made or a walk left unfinished;
-  most taken cells have no instance within their band and cost the walk from the root alone.
-- Contract 7: a record past its capacity, a level past the budget, or nodes past the last round's frontier leave the
-  cell unfinished. It is retried, and the capacity grows to the power of two at or past the most asked for, or the
-  rounds by one. Of the records a walk asks for at once, those below the capacity are kept, so a command never
-  dispatches a record that went unwritten.
-- The texel compares in the staged byte, the lowest row on a tie, so the object no longer depends on the order of
-  the instances; the batch sorts its rows, so a cell of one batch reads the same whatever order its walk found them.
-- **Device, Zorah** (S8's load, filled; from the aerial view, the GI released and all 196,608 cells of the windows
-  built again, 60 frames; S8's provider against this one in one process, old/new/new/old), with the frontier at 1,024
-  nodes as S9 landed it; the 512 it has now follows below:
-
-  | | iGPU, S8 → S9 | 4090, S8 → S9 |
-  |---|---|---|
-  | brick view's hole pixels | 10,323–10,379 → 41 | 10,071–10,078 → 36 |
-  | the provider over the rebuild | 76.9–78.0 → 132.6–132.7 ms | 7.2–7.6 → 16.0–18.1 ms |
-  | walk / batches / resolve | 71.4 / 56.4 / 4.7 ms | 5.5–7.6 / 8.5–9.7 / 0.5–1.1 ms |
-  | a frame of it, p50 / p90 / worst | 1.15 / 2.0 / 6.4 → 1.08 / 3.6–4.2 / 17.7 ms | 0.09–0.11 / 0.17 / 0.9–1.4 → 0.20 / 0.65–0.73 / 1.3–1.4 ms |
-  | at rest | 1.4–1.5 → 8.5–11.2 µs | 3.1 → 16.4 µs |
-  | rebuild against rebuild, bricks that differ | 276 → 0 | 254 → 363 |
-
-  - The 36–41 pixels left are the dome's lattice, thinner than cascade 2's voxel: S8's open item, not the cap. The
-    ground cells under the ring, S8's open item, were the cap.
-  - Nothing retried, no record past a capacity, and every walk ended in the second round: at most 1,431 batches and
-    220 tasks a frame (iGPU), within the initial capacities; at most 805 cells a frame listed for the resolve.
-  - Where the cost goes, from one-off arms in the same process with a part of the work deleted:
-    - The batches sample every instance: 257,216 rows a rebuild, where S8's provider dropped 37,780 instances past 64
-      a cell, 93,700 candidates past 128 and 43,500 frontier nodes, so sampled at most 125,736. The batch pass with
-      nothing sampled costs 0.3–0.5 ms, and its sort 1.7 ms on the iGPU (within the noise on the 4090).
-    - The walk's floor, a workgroup a taken cell with its memory cleared and its task read, is 25.8 ms on the iGPU and
-      0.67 ms on the 4090; S8's walk alone, 48.3 and 2.3–2.4 ms. On the 4090 this walk cut to what S8's walked (256 nodes
-      a level, the rest dropped) costs 3.3 ms against its 4.4 ms: 1.1 ms is walking every node, and the 0.9–1.0 ms
-      left over S8's walk is this walk's own bookkeeping, not split further.
-    - Alex asked for a hand-off once a window of four iterations instead of each, the spill and the ring sized for the
-      window (11.3 KiB of workgroup memory against 9.1). Measured paired against this walk, it was no faster on the 4090
-      (the walk's median 4.36 against 4.29 ms, six trials each) and 27% slower on the iGPU (90.3 against 71.3 ms, four
-      each); a window of two was 4% slower there. Not taken: on the iGPU the walk slows with its workgroup memory.
-    - So the frontier went the other way, halved to 512 nodes (Alex, on this measurement): the walk's workgroup memory
-      from 9.1 to 5.1 KiB. Paired against 1,024 (four trials each on the iGPU, six on the 4090, after a warm-up whose
-      rounds grew to three, retrying 8 and 2 cells; none after): on the iGPU the walk 71.1 → 43.0 ms, the provider
-      over the rebuild 132.0 → 104.1 ms, its median frame 1.08–1.27 → 0.65 ms; on the 4090 the rebuild even (17.9 ms
-      by the mean). At rest the third round's command and walk add 2.0 µs on the iGPU and 4.1 µs on the 4090 (9.8 and
-      20.5 µs); batches 7,077 → 7,331, the rows of a cell split over more walks; holes alike. Against 1,024, 30 of the
-      iGPU's 2,684 bricks differ, the texel's box test being order-dependent for a one-sided field, as before.
-    - At rest, seven dispatches (three one-thread commands, and four passes dispatched with no workgroup) against S8's
-      one.
-- Tier 2: free's retry (red on S8's free), the resolve's contracts, list and tail, the command, the walk's spill
-  partition, the texel's order-free row (red on S8's chunk). Tier 3: the provider's dispatches and their commands, its
-  buffers and their growth. The walk and the batches run on the device only. 25 of 25 mutants were killed.
-
-**TODO hook (skinned).** The leaf accept, where a clone resolves to its source's header, is where a
-dense animated patch takes over later.
-
-### 7.8 The virtual geometry provider
-
-**Superseded by S8 (2026-10-29).** Alex, after S7e: "Move vgeo to per-geometry signed SDF caches (baked once from a
-cut, composed per instance) instead of fixing the per-cell sign in place." The per-cell provider below (S7b–S7e) is
-deleted; S7a's cut refactor and S7e's measurements stand. What is built now is "As built (S8)", at the end of this
-section.
-
-S7, its own stage. vgeo rows are mesh rows with a virtual geometry: their BLAS is empty and they have
-no cache. The provider, per taken key:
-1. **Gather**: the mesh provider's TLAS query, accepting vgeo rows in the SDF world only.
-2. **Cut**: a box cut of each instance's cluster DAG. It takes clusters whose error is under ½·h_c
-   and whose bounds overlap cell ⊕ R. This is the §4 traversal of `VIRTUAL_GEOMETRY_DESIGN.md`, with
-   an error bound in world units in place of the pixel threshold.
-   - Where children are not resident, the resident ancestor serves, and a want is recorded.
-   - When the finer pages arrive, the provider appends the cell's box to the invalidation list
-     (contract 6).
-3. **Distance**: 512 texels per cell against the cut's triangles, up to 256 in LDS (chosen; past it,
-   dropped and counted).
-   - The sign comes from the nearest triangle's orientation.
-   - A texel it cannot sign is written unsigned. That is positive, so the ½-voxel hit still catches
-     the surface.
-4. **Objects**: the vgeo row. Hits take the material mean (§6.6) until vgeo has cards, which belong to
-   its own plan.
-
-Triangle work here happens per requested cell (scroll-ins and changes), never per frame. It is bounded
-by the cut error: at error ½·h_c, a cell's triangles number on the order of its surface in voxels.
-
-**What the vgeo runtime gave, read before building (2026-10-29)**. The plan and its choices are the shared
-note `s7-vgeo-provider-plan-2026-10-29.md`; Alex took them with "make sure we don't introduce more
-coupling. If you need to refactor how wants work - please do so. Keep performance in mind. [...] DRY and
-KISS".
-- vgeo rows are ordinary `meshes` rows in the scene's TLAS with an empty BLAS;
-  `geometries[row.geometry].vg_row` names the geometry's root page and page lookup.
-- The cut's rule was fused into the camera's traverse kernel with its drawing, claims and subgroup
-  scheduling, so no other kernel could call it.
-- Wants reach the residency only through the frame's feedback slots, whose reading wrote a view's fields.
-- No event says a page arrived: counters and lookups only.
-- A cut of its own a lane a pair would be a per-thread loop of hundreds of steps. The camera cut's wavefront
-  is the engine's answer to that (one item a lane a step, a uniform step bound, spills between dispatches),
-  so the box cut runs it rather than a walk of its own.
-
-**As built (S7a, 2026-10-29)**: the vgeo runtime, refactored so that a box cut runs the camera cut's rule and
-descent, the camera's cut unchanged.
-- `chunk_vgeo_cut_rule`: the cut's items and expansions, and the rule as two verdicts, `vg_cut_node` and
-  `vg_cut_cluster` (`VGEO_CUT_VERDICT`). The importing kernel defines the two culls,
-  `vg_cut_sphere_outside` and `vg_cut_box_outside`.
-- `chunk_vgeo_cut_descent`: what the descent does with a verdict (counts, wants, claims, the walk up) and the
-  wavefront's scheduling, with one more hook, `vg_cut_take`, for what taking a cluster means. The camera's
-  traverse is that chunk with its frustum culls and `vg_draw`.
-- `graph_vgeo_cut_descent`: the seam's seed, wavefront and tail, for any cut's instance records and traverse
-  kernel. The seam keeps its collect.
-- `vg_want` and `vg_stat` are chunks of their own, so a kernel that only counts binds no claim buffer.
-- A feedback slot is any `VGeoFeedbackConsumer`'s: the loop hands each consumer its slot's counters through
-  `read_feedback`, and whether it shared the slot. `VGeoViewCut` implements it. The runtime fills a slot's
-  own params (`fill_slot_params`) for any cut.
-- Measured on Zorah (the textured UE rebuild: 1,012 containers, 12,597 instances) from its manifest's camera
-  at 1280×720. Blocks of frames alternated the refactored traverse with the one before S7a, for every cut of
-  the frame, once after the rule moved and again after the descent did.
-  - The frame view's counters are the same between the arms on both GPUs: 32,618 clusters drawn, 163,353
-    items, 10,822 pages, 144,079 clusters tested once settled. The 4090's second run held 118 clamped
-    clusters in both arms.
-  - The traverse's 80 dispatches a frame cost the same: p50 0.96 and 1.00 of before on the RTX 4090
-    (1.93 against 1.92 ms the second time), 0.99 and 0.98 on the AMD iGPU (4.19 against 4.27 ms).
-- Tier 2: the cut agreement spec runs the traverse on the emulator unchanged. `VGeoFeedbackLoop.spec.js`
-  adds a consumer that is not a view (handed its counters, told when it shared its slot) and a slot's params
-  against the feedback's wire layout, which no spec held before. `graph_vgeo_expand.spec.js` counts the
-  wavefronts a cut records and encodes a cut's graph on the software device, which no spec did either.
-  20 of 20 mutants were killed.
-
-**As built (S7b, 2026-10-29)**: the gather and the box cut, which leave each taken cell a list of the clusters in
-its cut. Not registered yet: S7c's distance pass is the lists' reader.
-- `VGeoBrickProvider`, a `BrickProvider` with a `VGeoViewCut` of its own. In a frame the scene's vgeo runtime has
-  open, it records the gather, the claim widths scanned by `graph_prefix_scan_csdldf`, and `graph_vgeo_cut_descent`
-  with `shader_vgeo_brick_traverse`, then publishes the cut's feedback: its wants reach the residency through its
-  own slot, ranked with the camera's, and its counters come back to its cut. With no runtime, or none open, it
-  records nothing.
-- `shader_vgeo_brick_gather`: a 64-lane workgroup a taken cell, dispatched by take, running the mesh provider's
-  cooperative TLAS query over the cell ⊕ R.
-  - `vgeo_brick_accept` takes a row in the SDF world whose geometry is virtual and whose box is at least ½ voxel
-    across.
-  - `vgeo_brick_pair` writes a cut's instance record for each. k is σ_max/(½·h_c), the distance weight is 0 and
-    there is no eye, so `vg_project` is the world error over ½·h_c against τ = 1. The cell ⊕ R box, taken into the
-    instance's object space as the bounds of its eight corners, goes in the record's frustum words, and the
-    taken cell in word 30.
-  - A flattened instance makes no pair. Pairs past `budget × 8` records are dropped and counted, as is what the
-    query drops.
-- `shader_vgeo_brick_traverse`: `chunk_vgeo_cut_descent`, culled by the box's six faces, a sphere as its cube.
-  The take puts a cluster onto its cell's list as its pair and its meshlet row, up to 64. A list counts past what
-  it holds, and the clusters past it are counted dropped (`MESHLETS_DROPPED`).
-- Shared rather than copied: `chunk_vgeo_cut_instance` (what any collect writes of an instance record, now under
-  the camera's collect too) and `chunk_brick_provider` (a taken cell's key, window, voxel and band, and the
-  resolution test, now under the mesh provider too).
-- Tier 2, on the emulator:
-  - `vgeo_brick_traverse.spec.js` runs the seed, prepare, the box traverse and the remainder over a built torus
-    of 26 pages. Each list is the CPU oracle's cut at the pair's error with the pair's box as its planes
-    (`VGeoCutView.plane_count`, new: a camera tests five).
-    - Six fine cells around the ring and over and under the tube take 8 to 10 clusters each, and the whole ring
-      at a coarse error 7 over 3 pages.
-    - With a page withheld, the cell takes the oracle's stand-in, counts the clamp, and wants the page through
-      the cut's slot.
-    - Ten instances in one cell take 70 clusters: the list holds 64, counts 70, and 6 are counted dropped.
-  - `vgeo_brick_pair.spec.js` covers the accept and the record under a skew turn and a non-uniform scale:
-    k, w, the eye in a buffer of stale NaNs, the box, the cell, and the cut's own fields. It also covers the
-    drops.
-- Tier 3: `VGeoBrickProvider.spec.js` on the software device.
-  - Nothing is recorded without an open runtime.
-  - The gather runs through take, then the cut's wavefronts, between clear and free.
-  - τ is 1 with the camera's at 3; the cut has a slot of its own; its tail publishes the frame's feedback;
-    destroy gives back what it made.
-- 37 of 38 mutants were killed. The survivor never culls by a sphere, which changes nothing on the torus: its
-  pages hold a node each. A page's sphere lies outside the box only if the cluster refining into it does, so
-  the sphere decides at a page's inner nodes alone.
-- The gather is a barrier kernel the emulator cannot run, as the mesh provider's is. Its glue is checked on the
-  device in S7c, once the lists have a reader.
-
-**As built (S7c, 2026-10-29)**: the distances, and the provider registered: the GI runs it after the mesh
-provider, before the plugins.
-- `shader_vgeo_brick_distance` runs a 256-lane workgroup for each taken cell that the box cut put a cluster in.
-  The traverse lists a cell at its first take (`vgeo_brick_filled`), and `graph_build_indirect_dispatch_command`
-  turns the count into the dispatch. The plan's two passes are kept as the cut and this one: the triangles are
-  culled at the start of this pass, so the frame carries each cell's 516-byte cluster list rather than a triangle
-  list (about 42 MB at 4,096 cells).
-  - Triangles: a lane a triangle, two of the list's clusters at a time. A triangle whose box misses its pair's
-    (the cell ⊕ R, in the instance's space) lies past the band from every texel and is skipped. The rest go into
-    workgroup memory, up to 256 (§7.8's choice), past it dropped and counted. They are held in the cell's own
-    space, the translation taken less the cell's origin first, and wound out of the surface their instance
-    draws: `triangle_winding_is_reversed` swaps b and c.
-  - Texels, two a lane, `vgeo_brick_texel`: the nearest triangle within the band, signed by its side. Of
-    triangles as near, the one whose normal lies most along the texel's offset decides; "as near" is a tolerance
-    derived from the closest points' rounding in the cell's space, 2.0·10⁻³ of the squared distance. A material
-    drawn on both sides signs positive, as UE's two-sided fields do. Past the band a texel is unsigned, so
-    positive.
-  - The merge: the bytes meet in workgroup memory. A lane a staged word takes each byte's least (contracts 1 and
-    2). A lane an object cell writes the vgeo row where its nearest texel is nearer than the staged minimum from
-    before the merge (contract 3).
-- Shared rather than copied:
-  - `chunk_brick_object`: the encoding and the object bids, out of the mesh provider, renamed `brick_*`;
-  - `chunk_read_meshlet_triangle_positions`, which `read_meshlet_triangle_bounds` is now built on;
-  - `chunk_brick_provider_cell`, split out of `chunk_brick_provider`;
-  - `chunk_vgeo_brick_box`, the traverse's too.
-
-  A cell's list carries its key. `graph_vgeo_cut_descent` returns the records at the seed's version, their claim
-  bases in them.
-- Tier 2, `vgeo_brick_distance.spec.js`:
-  - the cull, past each of the six faces;
-  - the placement: a turn, a scale, an offset origin, reversed, the reach, sided;
-  - the texel over an octahedron against a brute force of the closest points: the distance to 5 places, the
-    sign, the row's triangle as near as the nearest, and none past the band;
-  - two faces meeting at 15°, whose planes disagree in front of their edge: the face the texel stands over
-    decides, in either order;
-  - a two-sided surface, positive on both sides.
-
-  `vgeo_brick_traverse.spec.js` holds the filled list: each cell that took a cluster, once. Tier 3: the
-  distance pass between the cut and free; the GI's order with the scene's vgeo open. 30 of 30 mutants were
-  killed.
-- Device, on both GPUs: two tori built in the page (128×48, 40 pages), one of them mirrored. The mode was entered
-  again until no fill clamped, which was the second fill (S7d is the re-queue), and every brick texel was held to
-  the analytic distance.
-  - The mean error is 1.9–2.4 bytes and p99 is at most 8 bytes (a quarter voxel), against the half-voxel bound
-    of 17. No cell the surface crosses is without a brick.
-  - 65 texels at cascade 0 (of 180,751 within the band) have the wrong sign. The vgeo builder's simplification
-    flipped 2 of the torus's triangles, at its inner top (cos −0.99 and −0.66 against the analytic normal), and
-    the nearest triangle's side follows them.
-  - The 256-triangle cap: 538 triangles were dropped, in cascade-1 cells whose 3.75 m box takes in a quarter of a
-    torus. 159 texels there are over the bound on the 4090, 178 on the iGPU, since atomic order picks the
-    triangles dropped. On a coarser torus (64×24) 275 are dropped and cascade 1 is clean, while three 15 m
-    cascade-3 cells over both tori drop instead.
-  - Inside the tube past the band (1.05 m against cascade 0's 0.5 m band), 24,314 texels are unsigned, so
-    positive, as §7.8 writes them.
-  - A fill frame, p50 / p90 / max:
-
-    | | gather | cut | distances |
-    |---|---|---|---|
-    | 4090 | 10 / 12 / 12 µs | 39 / 138 / 881 µs | 58 / 91 / 399 µs |
-    | iGPU | 605 / 619 / 728 µs | 20 / 63 / 248 µs | 1.3 µs / 1.04 / 6.49 ms |
-
-    The gather is a workgroup a taken cell, whose launch is the iGPU's 605 µs; the mesh provider's 1.07 ms here
-    is the same floor. With no vgeo in any cell, the cut's empty wavefronts cost 22 µs (4090) and 20 µs (iGPU).
-  - Dispatching the distances by the taken cells instead cost 1.73 ms on the iGPU with no vgeo in any cell, all
-    of it launch. By the filled count it costs 1.3 µs.
-- Sponza's census is the same on the tree before S7b and after, so both refactors left the mesh provider as it
-  was: 7,171 bricks in every census (progressive, again, fresh), every cascade's counts, and the instances
-  dropped past 64 (402, 460, 58).
-
-**As built (S7d, 2026-10-29)**: a cell built with a stand-in waits, and is built again once what it waited on
-arrives (contract 6).
-- The box traverse records a cell's first stand-in in its list header (`VGEO_BRICK_CELL_OFFSET`): the page it
-  stood in for, as its lookup word, and the group in that page. The first claimant writes them, decided by an add
-  on the header's count of stand-ins, so no compare-and-swap is needed. A clamp (the page not resident) and a held
-  group (resident, not selectable) wait alike, until the page is resident and the group selectable.
-- The distance pass puts each cell with a stand-in on a waiting list. The list holds budget × 4 cells; those past
-  it are dropped and counted.
-- `shader_vgeo_brick_wait` heads the provider's passes each frame, a thread a cell the last frame left waiting.
-  A cell whose page is resident and whose group is selectable is queued with `brick_clipmap_enqueue`, so exactly
-  the cells that stood something in are built again, once what they waited on is there. The rest wait on, onto
-  the list this frame's distances add to; the two lists trade places each frame.
-- Contract 6's seam on the device: the provider context hands a provider the clipmap's queue, as `state`, `ring`
-  and the new `pending` bits. A pass that queues cells writes `state` and hands its version on.
-- `vg_group_row` and `vg_group_selectable` move into `chunk_vgeo_cut_arena`, so a pass that asks whether a group
-  is drawable binds only the arena.
-- Tier 2, `vgeo_brick_wait.spec.js`, over the runtime's tables with a page withheld:
-  - a cell is queued, while one waits on the missing page and one on a group that page holds back;
-  - installing the page queues those two and no other;
-  - a key already pending is not queued twice;
-  - a list whose count runs past its capacity is read only as far as it holds.
-
-  `vgeo_brick_traverse.spec.js` checks that a clamp records its page and group, and that nothing is recorded when
-  all is resident; the torus's lookup now starts past word 0. Tier 3: the wait runs before the gather, indirect;
-  the distances bind the list the wait keeps onto; the lists trade places; destroy gives them back. 16 of 17
-  mutants were killed. The survivor drops the gather's reset of a cell's stand-ins, inside a barrier kernel that
-  only the device runs.
-- Device, on both GPUs: the tori of S7c in one fill, never left.
-  - The 4090 had 187 cells waiting at frame 10 and none at frame 20, by when all 15 pages were resident; nothing
-    clamped after frame 20. On the iGPU none waited at frame 10, and nothing clamped after it.
-  - The bricks are those S7c built by entering the mode again until no fill clamped. At cascade 0 the mean error
-    is 1.865 bytes on the 4090 and 1.862 on the iGPU, p99 6, with the same 66 and 64 texels of the wrong sign.
-    Cascades 2 to 5 have the same counts and errors; cascade 1 differs only in the texels the 256-triangle cap
-    leaves over the bound, by atomic order. No cell the surface crosses is without a brick.
-  - The wait costs 4.1 µs a frame at p50 on the 4090 (11 µs at worst) and 1.8 µs on the iGPU (6.2 µs).
-  - The iGPU's distances reached 13.1 ms in one frame, against a p90 of 1.4 µs. Zorah (S7e) is where that is
-    measured on a real scene.
-
-**As built (S7e, 2026-10-29)**: Zorah lit by its own geometry, measured; and the wait keeps its cells' wants.
-- Zorah, the textured UE rebuild (1,012 containers, 12,597 instances, 332,613 pages), one grey material, the
-  manifest's sun, 1280×720. Zorah has no other geometry, so all the probes see of it is the vgeo provider's bricks.
-  - At ground level, in an arcade, IBL leaves the frame black (mean luma 6.3 of 255; Zorah's IBL sky is black).
-    ProbeClipmap lights it from the sunlit floor: 19 to 37 over five runs, the probes 240 frames after the fill.
-  - Of the probes' rays, 70% hit Zorah's bricks at the manifest camera, 76% at ground level and 48% from the air.
-- Timings, p50 of a settled frame.
-  - The AMD iGPU: IBL 39.5 ms, ProbeClipmap 62.8 ms (+23.3 ms). That is the trace's 11.0 ms (8 ms on Sponza: Zorah's
-    bricks are denser), the fused indirect pass's 9.3 ms (as S6c2 measured it), light 2.1 ms, and every other pass
-    under 0.6 ms. The provider at rest costs ~20 µs: wait 3.5, gather 1.6, cut 11.1, distances 1.4.
-  - The 4090, sharing its GPU with another process (its medians stand, its maxima do not): 6.9 → 8.3 ms. The trace is
-    1.2 ms and the fused pass 81 µs.
-  - The fill on the iGPU (196,608 cells at 4,096 a frame, and the cells queued again): 62 ms a frame at p50, 69 ms
-    at p99 and 132 ms at worst. The distances take 56.6 ms in their worst frame, the cut 6.6 ms and the gather 3.6 ms.
-- **§7.8's bound does not hold on Zorah: its caps bind as budgets.** Over one fill on the iGPU (the 4090 is within
-  10%):
-  - 46% of the clusters the box cut took are past a cell's 64 (1.44M of 3.13M): 39% in cascade 0, rising to 79% in
-    cascade 5;
-  - 18–19.5M triangles are past a cell's 256: 9.8M in cascade 0, 6.4M in 1, 2.0M in 2;
-  - 80–150k pairs are past the records (103k in cascade 1), and the TLAS query drops 182–224k candidates and 48k
-    nodes.
-
-  A cell ⊕ R box in kitbashed content holds many overlapping instances and layered surfaces. The cut's error bounds
-  how big a triangle is, not how many surfaces cross a box.
-- What the image measures, and what it does not come from.
-  - Holes: from the air the ground plane's bricks are missing beside the greenhouse, and cells of the ground, the
-    greenhouse and the tower read inside out.
-  - Of the probes, 17–48% are dead and 8–16% of rays meet back faces. Sponza on the mesh caches has 1.6–4% dead and
-    2% back-face rays.
-  - With the provider's cut 4× and 16× coarser, the drops fall about threefold (triangles 19.3M → 6.2M → 5.6M,
-    clusters past a list 46% → 26% → 29%). The back faces, the dead probes and the holes stay. **The caps are not
-    what the image suffers from.**
-  - Each texel the least over its instances of that instance's own signed distance, in place of the nearest
-    triangle of all of them, is no better: back faces 8–18% and dead probes 18–54%. The nearest triangle's side is
-    the open question on content made of single-sided, interpenetrating pieces.
-  - The two tori of S7c, as vgeo and as plain meshes: of the probes deep inside a tube, vgeo leaves 4 alive and 36
-    dead, while the meshes' signed fields relocate 26 out alive and leave 14 dead. Past the band a vgeo interior is
-    unsigned (§7.8), so its probes die where a mesh's move out.
-- **The wait keeps its cells' wants.** On Zorah, 826 cells (iGPU) and 888 (4090) waited for ever, every one on a
-  page not resident.
-  - A want lasts the reading it is in: past its 64 fetches a reading, `VGeoResidency.apply` drops what it defers.
-    The camera's cut wants its pages again every frame; the box cut wants only while it cuts.
-  - Now the traverse records what a cell's first stand-in's want is made of, in the cell's header
-    (`VGEO_BRICK_WAIT_OFFSET`): the page, the group, the row the stand-in was found in and that page's own index, the
-    child-table entry, and the error. The distances copy it onto the waiting list whole.
-  - Each frame, the wait wants an absent page again through the provider's slot, while that row still holds that page
-    (`vg_lookup[lookup + source_page] == source`). Once the row holds another page, the cell is queued again instead.
-    The wait writes the frame's feedback ahead of the gather and hands its version on.
-  - A group held back carries no want, as in the cut.
-  - On Zorah no cell is left waiting on an absent page (827 → 0). 7 to 47 wait at rest, every one on a resident page
-    whose group the activation rule holds back. That is the runtime's own gap, which the 4090's camera cut shows
-    too: 1,539 clusters held for good, where S7a saw 118.
-- Tier 2 (`vgeo_brick_wait.spec.js`, over the runtime's tables with a page withheld): a cell waiting on an absent page
-  wants it again each frame, through its source, at its error; one whose source row holds another page is queued
-  again and wants nothing; a held group wants nothing; the cells kept go onto the list whole. The traverse spec holds a
-  clamp's want words to what the residency needs: the source row holds the page named, whose child table names the
-  page withheld at the entry recorded, and the error is above τ. Tier 3: the wait binds the frame's feedback and the
-  want stamps. 17 of 18 mutants were killed. The survivor shortens the distances' copy onto the list, inside a barrier
-  kernel that only the device runs.
-- Open, measured, cause not established: on both GPUs, the lit frame at the manifest camera has dark blotches on a
-  lattice over a column whose bricks are clean.
-
-**As built (S8, 2026-10-29)**: a virtual geometry's cache is baked from a proxy cut from it, adopted into it, and
-composed by the mesh provider; the per-cell provider is deleted. The plan and its one fork are the shared note
-`s8-vgeo-geometry-caches-plan-2026-10-29.md`; Alex took (a), a readback of the cut's triangles into the host's own
-geometry path.
-- **The caches** (`GPUGeometrySDFManager`).
-  - `onRequested` is sent with a record each time its cache is queued: at its first holder, at a new voxel size, and
-    when its holders' side changes. `is_requested` says a cache waits queued, held or not, as the bake bakes it until
-    a trim; `holds_two_sided` says the side a bake of it takes.
-  - **Sources** (`add_source`, a `MeshSDFSource`) run first in each `graph_bake`. A source makes the caches of
-    geometries with no tree of their own, which wait queued as a geometry whose tree is not resident yet does.
-  - `adopt(target, proxy)`: the resident cache baked for the proxy becomes the target's, nothing copied. The target's
-    header takes the proxy's layout, entries and side, and the proxy's reads None, as dropped; `onBaked` is sent with
-    the target. The cache has no cards, the target having no tree to capture them with, so a vgeo hit keeps the
-    material's mean (§17). Held for another side than the proxy was baked for, it is queued again at the next bake.
-  - A bake is recorded only for work there is: a queue of geometries no bake can admit yet, and placements dropped or
-    adopted away, record none.
-- **The source** (`VGeoSDFProxies`, made with the runtime by `GPUSceneContext.enable_virtual_geometry`).
-  - A job a geometry asked for, 32 at once. Each frame a job's geometry is cut whole by the camera cut's own descent:
-    `shader_vgeo_sdf_collect` writes its record (`chunk_vgeo_cut_instance`), the claim widths are scanned, and
-    `graph_vgeo_cut_descent` runs `shader_vgeo_sdf_traverse`, which culls nothing and puts every cluster in the cut onto
-    a list under its job, counting stand-ins and the clusters past the list. It cuts under a slot of its own at τ = 1,
-    k = 1/(½·v₀) in the geometry's own units, v₀ its cache's level-0 voxel. A clamp wants its page there; since a want
-    lasts one reading, the job is cut again each frame until its cut stands nothing in.
-  - `shader_vgeo_sdf_decode`, a workgroup a listed cluster, counts every job's vertices and triangles. For a job
-    whose last cut stood nothing in, it writes the clusters out in room those counts made: positions as stored,
-    triangles as indices into the job's own vertices.
-  - One readback a frame: the jobs' counters, the cut's own (a subtree left undescended voids the frame for every
-    job), and the meshes. A write-out whose counts disagree with its room's is cut again.
-  - The proxy: one a frame on the host, `meshlet_geometry_build_from_geometry` (2.2–4.1 µs a triangle, measured),
-    added to the geometry manager, its cache held with the side the geometry's holders draw. When it turns resident,
-    the next update adopts it into the geometry and removes the proxy. A proxy whose mesh another's has is that one's
-    record: only one adopts, and the other geometry is extracted again.
-  - A job whose geometry is no longer queued is let go; a new voxel size restarts every job.
-- **The holds** (`ProbeClipmapSceneHolds`): a vgeo row holds its cache as a mesh row does. Its pair's card set waits for
-  good, since an adopted cache has no card layout.
-- **Deleted**: `brick/vgeo/` (the gather, the box cut, the distances, the wait and their specs), its registration in
-  the GI, and the provider context's `budget` and `pending`, which only it used.
-- **Device, Zorah** (as S7e loads it: 1,012 geometries, 12,597 instances, one grey material, the manifest's sun,
-  1280×720), entered once with the default settings.
-  - The fill: every one of the 1,012 caches resident after 3,160 frames on the 4090 (31 s) and 3,200 on the AMD iGPU
-    (247 s). 1,013 proxies were built, one twice (a proxy came out alike to another's), from 423,584 triangles: step
-    0's "a few hundred thousand". 8 geometries were coarsened (step 0's 8). The bake evaluated 52,911 bricks, the
-    atlas grew to 65,536 slots, and the caches hold 35.3 MB. Their cuts took 34–42k clusters over ~1,180 readings and
-    stood one in 6–9k times while their pages came; no wavefront ran out, nothing was dropped, and the cluster list
-    never grew past 4,096.
-  - The fill's pace, 0.32 geometries a frame, is mostly the bake's budget of 23 bricks a frame, at 52 bricks a
-    geometry: it averaged 16.7 a frame, idle in 27% of the frames while proxies waited on their pages, their write-out
-    or their build. Zorah's proxies cost less a frame than Sponza's meshes: the evaluate is 652 µs at p50 and 9.0 ms at worst on
-    the 4090, 3.7 ms at p50, 17.7 ms at p90 and 48.9 ms at worst on the iGPU, inside what the budget costs on Sponza
-    (§6.4: 26 ms at the median and 79 ms at worst on the iGPU). The extraction's own passes, in the 1,734 frames that
-    cut: the cut 48 µs at p50 and 499 µs at worst on the 4090 (36 and 337 µs on the iGPU), the decode 4 µs at p50.
-  - The host: a frame that builds a proxy is 4.4 ms at p50 against 3.0 ms without on the 4090's host, 20.7 ms at p99,
-    and 190 ms once, for the largest geometry's proxy (the iGPU run's host: 4.8 / 3.2 / 20.4 / 150 ms).
-  - The frame while filling, p50 / p90: 3.82 / 5.56 ms on the 4090 and 66.0 / 80.5 ms on the iGPU (158.9 ms at worst).
-    At rest nothing of the extraction runs: 3.28 ms on the 4090 and 63.0 ms on the iGPU, S7e's 62.8 ms.
-  - The probes and their rays, after the fill, both GPUs alike:
-
-    | view | dead probes, S7e → S8 | back-face rays, S7e → S8 | lit luma, S7e → S8 |
-    |---|---|---|---|
-    | manifest | 23% → 3.2% | 12% → 4.7–5.0% | 89 → 91 |
-    | aerial | 18% → 2.0% | 9% → 4.5–5.1% | 74 → 76 |
-    | ground | 49% → 6.8–7.0% | 17% → 5.5–6.6% | 21 → 79–83 |
-
-    Sponza on the mesh caches has 1.6–4% dead and 2% back-face rays. The arcade at ground level, which S7e lit at 19 to
-    37, is lit at 79 to 83 from the sunlit floor. From the air the bricks read as Zorah, the greenhouse's dome and the
-    tower whole, where S7e's read inside out (`s8f_igpu_aerial_bricks.png` against `s7e2_aerial_bricks.png`).
-  - Sponza's census is unchanged (4090): 7,171 bricks, every cascade's counts, 104 geometries baked, resident at frame
-    355.
-  - Open, measured, cause not established: from the air, cells of the ground under the greenhouse's ring are still
-    black (the ray passed through); the column at the manifest camera still has its dark blotches on a lattice; its
-    flutes, narrower than a voxel, read as back faces in the brick view. A proxy's id is not given back
-    (`GPUGeometryManager` hands ids out once), so the fill takes Zorah's ids from 1,012 to 2,024.
-- Tier 2 (`vgeo_sdf_extract.spec.js`, over a built torus in the runtime's tables and in a meshlet pool): a job's list is
-  the CPU oracle's cut at its error with no cull, and its counts are the listed clusters'; written out, its mesh is
-  every triangle of those clusters as the meshlet pool's own reader reads them back; a room too small takes no cluster
-  past it; a missing page is a stand-in, wanted through the slot; past the list's capacity the count runs on. Tier 3:
-  the caches' adopt, sources, requests and waits (`GPUGeometrySDFManager.spec.js`, a bake done on the device standing
-  in its log); the proxies' host half end to end (`VGeoSDFProxies.spec.js`, the device's readbacks standing in); a vgeo
-  row's hold. 43 of 43 mutants were killed.
-
-### 7.9 Tracing
-
-`brick_clipmap_trace(origin, direction, t_min, t_max)` is a pure chunk over seam readers, so the
-emulator can run it against CPU-built bricks (§12).
-
-- **Start**: the finest cascade whose window holds the origin by ½ voxel.
-- **Loop**, at most 64 steps (chosen):
-  - **Window**: if `p = o + t·d` leaves the window shrunk by ½ voxel, move to the next cascade; past
-    the last cascade the ray is a MISS.
-  - **Block**: an occupancy of 0 advances t to the block's exit (slab test).
-  - **Entry**:
-    - UNKNOWN continues in the next cascade from the current t. Unbuilt space is read from the
-      parent, not passed through.
-    - EMPTY advances to the cell's exit.
-    - A slot reads d. If d < ½ voxel the ray HITs; otherwise `t += max(d, ½ voxel)` (UE's minimum
-      step).
-- **Hit**: position, cascade and slot. The normal is a 4-tap tetrahedral gradient, its taps clamped
-  to the brick's [0, 7] (UE uses 6).
-- **Unresolved**: a ray whose budget is spent is returned as unresolved, and its caller discards the
-  sample (§8.8).
-- **Per step**: one occupancy load, one entry load, and one atlas sample inside bricks.
-
-Three more chunks:
-- `brick_clipmap_distance(p)` is the finest cascade's signed sample at p, with an EMPTY cell read as
-  ≥ R. It is for probe relocation.
-- `brick_clipmap_object(hit)` reads the object cell of the texel nearest to the hit moved ½ voxel
-  along the normal, onto the ray's side. With a thin wall's two faces inside one voxel, this picks the
-  face the ray hit. UE offsets its object lookup the same way.
-- `brick_clipmap_soft_shadow(origin, direction, sin_angle)` is the same march. It returns the
-  classic penumbra estimate: the minimum over its steps of `d / (t·sin θ)`, clamped to [0, 1].
-  - The estimate is extracted from `shader_scene_sdf_soft_shadows`.
-  - θ is the light's angular radius from its record (`disk_radius`), a physical quantity, not a
-    softness knob.
-
-**As built (S3e)**, `brick/chunk_brick_clipmap_trace.js`:
-- The cascade count is a parameter of each chunk: `brick_clipmap_trace(origin, direction, t_min,
-  t_max, cascade_count)`, with `direction` unit length so that `t` is a distance.
-- They read `brick_levels`, the map and the occupancy as sampled `u32` textures, the atlas through
-  the mesh bricks' sampler, and `brick_objects`.
-- The hit carries its kind (hit, miss, unresolved), `t`, cascade, slot, position, normal, the
-  field where it stands, and its cell's corner.
-- A step past the hit's threshold is `d` itself, at least half a voxel, so UE's minimum step needs
-  no `max`.
-- EMPTY inside is a hit where the march stands. Its field reads −R and its normal is along the
-  ray, so §8.4's gradient rule counts it as a back face with no case of its own.
-- A skipped block is clamped to the window at both ends (§7.3). Past the window's far edge the
-  ray goes on in the next cascade from there, never from the block's storage end.
-- `brick_clipmap_distance`: in a point no window holds, or one only UNKNOWN cells cover, it reads R
-  of the coarsest cascade.
-- `brick_clipmap_object` moves the hit along the normal, out of the solid. A front face's normal
-  faces the ray, and a back face is counted, never shaded (§8.4), so the ray's side needs no test.
-- Tier 2, `brick_clipmap_trace.spec.js`, on spheres, boxes and planes built into bricks on the CPU
-  the way the build makes them:
-  - every hit lies within half a voxel and one LSB of the surface, with its normal;
-  - skipping blocks finds the same hits as a march that reads every block;
-  - a skip stops at either edge of a window whose corner is not a multiple of 4;
-  - UNKNOWN cells defer to the parent;
-  - a ray through empty space crosses four 16-cell windows within its 64 steps, which it could not
-    cell by cell;
-  - a ray grazing a plane between half a voxel and one spends its steps unresolved;
-  - a wall thinner than a voxel is hit, and each of its faces reports its own row.
-- Mutants: 31 of 32 killed. The survivor, the start's half-voxel inset, is equivalent: without it
-  the loop's window test moves the ray on at its first step.
-- `brick_clipmap_soft_shadow` is not built yet. §12's oracle cannot be met by the estimate above,
-  and that is put to Alex. At a sphere's edge, where the ray to the light's centre grazes it, half the
-  disk shows. The classic estimate reads 0 there, so its penumbra lies wholly outside the geometric
-  shadow, and it is 0.55 from the analytic fraction at worst. Quilez's two-sided estimate marches on
-  into the occluder, clamps the minimum to [−1, 1] and maps it through `¼(1 + x)²(2 − x)`; it is
-  0.085 from it at worst (θ = 0.05 rad, a unit sphere 10 units away).
-
-**As built (S3e's soft shadow, 2026-10-28)**: Alex asked for quality where its cost is a fair trade, and
-left the estimator to the measurement. It is Quílez's two-sided estimate.
-- `brick_clipmap_soft_shadow(origin, direction, t_min, t_max, sin_angle, cascade_count)` walks the
-  tracer's march, which both now share (`brick_clipmap_march`). A step passes empty space or changes
-  cascade, leaves the last window, or stands in a cell to read.
-- In each brick it reads the clearance: the field less the tracer's half-voxel expand, so that a wall
-  thinner than a voxel shadows as it is hit.
-  - The least of the clearance over `t·sin θ` goes below zero inside the occluder. The march goes on
-    into it, half a voxel a step, until the least reaches −1.
-  - Clamped to [−1, 1], the least maps through `¼(1 + x)²(2 − x)`.
-- EMPTY inside is dark. An EMPTY cell or a skipped block adds nothing: its clearance is at least a
-  voxel, wider than a sun's cone within its cascade's range.
-- **Quality**, on the CPU, against the analytic disk past the surface the tracer hits. 12 cases of θ
-  (the sun's 0.0047 to 0.05 rad), radius and distance, each marched as the tracer marches:
-
-  | estimate | mean error | worst error | at the edge (0.5) |
-  |---|---:|---:|---:|
-  | classic, one-sided (above; `shader_scene_sdf_soft_shadows`) | 0.129 | 0.566 | 0 |
-  | the engine's `scene_sdf_soft_shadow`, with Aaltonen's triangulation | 0.330 | 1.0 | 0 |
-  | **two-sided** | **0.0145** | **0.099** | 0.5 ± 0.022 |
-
-  Aaltonen's triangulation breaks under the expand: a step can more than double the clearance, and
-  its square root's argument goes negative.
-- **Cost**, paired against the one-sided estimate: the sun's shadow rays on Sponza, from random origins
-  about the camera.
-  - On the 4090 it is the same within its noise (1M rays: 725 against 755 µs). On the iGPU it is 33–36%
-    more: 8.9 against 6.7 ms for 131,072 rays, 68.2 against 50.1 ms for 1M.
-  - For a 0.05 rad light it costs 24% / 59% more.
-  - The cost is the inner penumbra's rays, which the one-sided estimate stops dark and this one
-    marches on. Stepping by the field's depth inside the occluder did not change it.
-- **What it buys** on Sponza: 8.7% of the sun's rays, which the one-sided estimate reads as umbra, see
-  part of the sun. The mean visibility is 0.584 against 0.560.
-- The tracer through the shared march costs 2.9% more on the iGPU, paired, with the same hits. The
-  alternative was a second copy of the traversal.
-- Tier 2:
-  - past a sphere, within 0.1 of the analytic disk (0.043 measured), and half at the edge within 0.1
-    (0.512);
-  - dark under its middle, lit well clear of it;
-  - a wall thinner than a voxel hides the sun;
-  - a ray inside a solid, in a brick or EMPTY inside, is dark;
-  - one past `t_max` or out of every window is lit.
-- Mutants: 13 of 15 killed.
-  - A linear map in place of `¼(1 + x)²(2 − x)` survives within the oracle's tolerance. On the CPU its
-    mean error is 35% more, and its worst no more.
-  - Never stopping in the umbra is equivalent: the least only falls.
-- **Replaced 2026-10-30** by a shadow ray toward a point of the sun's disk, and the chunk deleted (§8.7, as
-  built): the estimate reads the field's clearance about one ray, so two occluders from either side of
-  the cone read as one. Under a slit narrower than the disk it saw 0.675 of the sun where the disk is
-  0.327 open.
-
-**As built (S3f)**: `ProbeClipmapDebugView.BrickClipmap` traces each pixel's camera ray through the
-world's bricks (`debug/graph_probe_clipmap_debug_brick_clipmap.js`).
-- A hit shows the field's normal, tinted warmer the coarser its cascade; a back face is red, and a
-  ray whose steps ran out magenta.
-- `GPUBrickClipmap.write_bindings` hands a reader what the tracer's chunks read, as the geometry
-  caches' does.
-
-Measured on Sponza with its caches resident, at the defaults: 6 cascades of 32³, 0.125 m voxels,
-4,096 cells a frame. The numbers are for the RTX 4090 / the AMD iGPU.
-- **Build**: a fresh clipmap builds in 48 frames, 196,608 cells at 4,096 a frame.
-  - It holds 7,171 bricks, 5,147 of them in cascade 0. No cell is UNKNOWN and none is EMPTY inside,
-    the same on both GPUs.
-  - Under the 64-ray vote, S3d's fresh build held 5,315 bricks and 2,564 cells EMPTY inside.
-    UE's vote leaves deep interiors at +R, and their shells add cells with a surface.
-  - A frame of the fill costs 145 µs / 1.63 ms at the median and 411 µs / 6.8 ms at worst, 7.2 /
-    106 ms in all. The mesh provider is most of it, 104 µs / 1.08 ms at the median.
-- **Idle**: 22 µs / 15 µs a frame.
-- **Walking** 13.4 m through the building at 3.35 m/s, the build keeps up: nothing is queued at any
-  fourth frame. A frame costs 27 / 15 µs at the median and 125 µs / 1.56 ms at worst.
-- **Trace, coherent**: the debug view at 1280×720, a ray a pixel, costs 63–88 µs / 9.3 ms. The Mesh
-  SDF view of the same pixels costs 1.7–2.1 ms / 160–189 ms.
-- **Trace, incoherent**, as probes cast rays: random origins in a 28 m box about the camera, uniform
-  directions.
-  - 131,072 rays, the default `ray_budget`, cost 165–215 µs / 6.9–7.0 ms to the clipmap's edge, and
-    165–195 µs / 3.1–3.2 ms within 8 m.
-  - 1,048,576 rays cost 650–725 µs / 54 ms, about 1.5 G / 19 M rays a second.
-  - 0.6–0.7% of them run out of their 64 steps unresolved; within 8 m, 0.01%. 3.6–4.7% start inside
-    a solid and meet a back face.
-
-### 7.10 Capacity and growth
-
-- **Initial capacity** is `2·N_b²·C_b` bricks (12,288 at the defaults): a ground plane through every
-  cascade, two cells thick.
-- **Growth**: failures are counted on the device and read back. On a non-zero reading the host
-  doubles capacity (as built in S3, the count is take's starved takes, §7.4):
-  - `GPUTileAtlas3D.reserve`, which adds layers and widens past `maxTextureDimension3D`, copying
-    texels;
-  - the object cells, reallocated with a copy;
-  - the free list, extended by the new slot range.
-- The mesh brick atlas and the card pages grow the same way.
-- Nothing shrinks, in the manner of the vgeo descent bound.
-- **Ceiling**: the atlas's `capacity_limit` (256³ slots at 2048) and the adapter's
-  `maxStorageBufferBindingSize`.
-
-## 8. The probe clipmap
-
-### 8.1 Cascades and lattice
-
-- `C_p` cascades (`probe_cascade_count`, default 5) of `N_p³` lattice points
-  (`probe_cascade_resolution`, a power of two, default 32).
-- Spacing is `s_c = s₀·2^c` (`probe_spacing` = s₀, default 1 m), so the windows span 32 to 512 m.
-- **Probes sit at the world-aligned lattice points `s_c·i`.** A point uses cascade c's cage, the
-  eight corners of `floor(p/s_c)`, when the whole cage is in the window.
-- **Placement and nesting** are the bricks' (§7.1). The brick clipmap's 896 m outer window is wider
-  than the probes' 512 m, so rays from the outermost probes travel at least 192 m before they read
-  as sky.
-- **Cascade choice and blend** use `clipmap_select_finest` over the probe levels, with a blend
-  skirt of 2 cells: one cell of the coarser cascade, the distance over which the spacing doubles.
-
-### 8.2 Storage
-
-| Resource | Layout |
-|---|---|
-| Indirection | `r32uint`, `N_p × N_p × N_p·C_p`, toroidal; slot or `0xFFFFFFFF` |
-| States | storage buffer, one `u32` a slot: NEW / ALIVE / DEAD and the update count. Its own array, so the pick reads 4 B and not a record (§9.1) |
-| Records | storage buffer, 64 B a slot: cascade and world cell (3 × 21-bit signed, two words), wanted frame, traced time (s), relocation offset (3 × f16), back-face fraction, SH2 as `METRO_L1_IRRADIANCE_STRUCT` (32 B) |
-| Radiance | 2-D `rgba16float` atlas; a slot's tile is `(n_r + 2)²`: the octahedral map plus a one-texel skirt. One level only (§9.3). Slots are placed by `index_to_grid2d`, as in `lpv_atlas_patch_texel_coord` |
-| Depth | 2-D `rg16float` atlas, tile `(n_d + 2)²`. Moments of `min(t, (1 + 0.45)·√3·s_c)/s_c`: normalised by spacing, so every cascade has the same precision, and clamped at the farthest a cage tests a relocated probe (D9), past which a hit cannot occlude anything the cage shades |
-| Wanted bits | `N_p³·C_p` bits, cleared each frame |
-| Lists | active (double-buffered), wanted, trace (≤ U, §8.5) |
-| Free list | the extracted slot stack (§4.1) |
-
-`n_r` is `radiance_resolution` (default 16) and `n_d` is `depth_resolution` (default 8). Both are
-powers of two and independent.
-
-**Why `rgba16float` and not LPV's `r32uint` rgbe9995.** Every consumer reads radiance with one
-hardware bilinear tap per probe. LPV's packed format forces four loads plus decodes and a manual
-bilinear. The memory measurement on the AMD iGPU found manual octahedral sampling 12× slower than
-hardware taps.
-
-The price: a texture cannot be read and written in one dispatch without `texture-formats-tier2`, so
-the update is two passes (§8.8). That is LPV's own answer for its depth atlas.
-
-**As built (2026-10-30), the record packed**, 48 B a slot, `PROBE_RECORD_STRUCT.pack()`:
-- the cell, `vec3<i32>`;
-- one flags word: the back-face share as unorm16 in the low half; ten bits of flags above it, the screen's
-  mark the first; the cascade in the top six bits;
-- the wanted and the traced frame, `u32`, of the frames the clipmap has recorded: exact where f32 seconds
-  lose their step as the clock runs on, and an update happens in a frame anyway. The blend's Δt is the
-  frames since the update and τ is `response_frames` (default 30, half a second at 60 fps), so the probes
-  take no clock from the caller. Eviction's age buckets count frames: 0, 1, 2–3, 4–7, … Retire evicts by the bucket a probe was
-  counted in, its age a frame before. With integer ages a probe one frame younger than an asked bucket
-  aged into it between schedule and retire, and was taken uncounted;
-- the SH, `vec3<u32>` of half floats: Y's xy, Y's zw, CoCg, held to ±65,504. Half the Metro L1 struct's
-  32 B.
-
-### 8.3 Lifetime
-
-Per frame, in this order:
-
-1. **retire** (thread per active probe). A probe is freed when either holds:
-   - its world cell is no longer in its cascade's window (`clipmap_contains` against the current
-     corner);
-   - it was last wanted more than `retention_time` ago (default 1 s). Since 2026-10-30 instead: the last
-     frame's schedule evicted it, by the pressure on the slots, least recently wanted first (as built,
-     below the measured churn).
-
-   Freeing it means:
-   - its slot is pushed;
-   - its indirection entry is cleared if it still names this slot.
-   The rest are re-appended to the active list.
-   - Running this before `want` means a scroll needs no pass of its own: the vacated storage cells
-     are emptied before any newly exposed cell can claim them.
-2. **want** (thread per 8×8-pixel tile; 32,400 at 1080p).
-   - One pixel per tile per frame, chosen by STBN. Its world position comes from depth and its
-     normal from the G-buffer; sky pixels are skipped.
-   - The biased point (§9.1) picks cascade c. The eight cage cells of c, and of c + 1 inside the
-     blend skirt, are `atomicOr`'d into the wanted bits. A bit that was clear appends its cell to the
-     wanted list.
-   - At a cascade's outer edge a probe cell projects to `H / (N_p·tan(fov/2))` pixels: 58 px at
-     1080p and 60°, 19 px at 120°. A tile size of 8 therefore samples every cell several times a
-     frame.
-3. **want hits** (thread per ray of the last frame's updates; S5a, D31 reversed).
-   - A front-face hit that bounces anything wants the cages its pick reads, as a pixel does, since the
-     next bounce reads those probes (§8.7). So a probe a hit needs is admitted where nothing on screen
-     wanted one, and kept while hits read it.
-   - Only a probe a pixel wanted has hits that want: the chain stops after one step, as Enshrouded's
-     world-cache probes do. Unstopped, every surface the windows hold would come to want a probe, the
-     dense lattice D31 turned down.
-   - It reads the last frame's rays before this frame's trace writes over them.
-4. **admit** (thread per wanted cell).
-   - An EMPTY entry pops a slot (a failure is counted), writes a NEW state, a record and the
-     indirection entry, and appends to the active list.
-   - An existing probe refreshes its wanted frame.
-   - Either way the record is marked the screen's when a pixel wanted the point, and the hits'
-     otherwise: what the next frame's hits read to stop the chain.
-
-Consumers weight a NEW probe at zero until its first update.
-
-**As built (S4a, 2026-10-28)**, `probe/`: `GPUProbeClipmap` places the windows, keeps the storage, and
-records the frame's lifetime as one graph pass: retire, want, admit's command, admit, schedule.
-- **The levels uniform holds the cage windows**: the lattice window's corner, a size of `N_p − 1`, the
-  cascade's spacing. `clipmap_select_finest` over it answers the finest cascade whose whole cage holds a
-  point (§8.1). Retire tests a probe's point against the lattice window, one point wider.
-- **The record is plain fields**, 64 B as §8.2 sized it: the cell as `vec3<i32>`, the cascade, the
-  wanted time, the traced time, the back-face fraction, the Metro L1 struct. §8.2's three 21-bit cells
-  and a cascade are 66 bits, which two words do not hold. (S4a kept the relocation offset here; S4b
-  moved it into the state.)
-- **"Wanted this frame" is the wanted bit**, which the frame clears. Retention reads a **wanted time**,
-  seconds since the clipmap's first frame on the caller's clock: the renderer's wall clock, since the
-  probes are a cache of the lighting, not part of the simulation (its `time_delta_seconds` is 0 by
-  default).
-- **The indirection is filled with none on the first frame**, a thread a texel: a new `r32uint` texture
-  reads 0, which is a slot.
-- **Want skips a cage the bias moves out of its window**: its points would alias storage cells other
-  points hold. In the skirt the next cascade's cage is wanted on its own.
-- **Want claims each cage once a workgroup.** A workgroup's 64 tiles want a few cages between them, so
-  the first lane to want a cage claims it in a 256-slot table in workgroup memory and sets its bits; the
-  rest want it through that lane. Storage wraps by the power-of-two mask, not by the Euclidean mod, an
-  integer division on the iGPU.
-  - Measured on Sponza at 1280×720, paired in the same frames: on the iGPU want took 343 µs as first
-    written, 264 with the mask alone, 317 with the claims alone, and **117** with both. On the 4090:
-    32.8, 29.7, 9.2 and **7.2** µs.
-  - What it cost as first written, on the iGPU: 105 µs of loads, selection and keys, 140 of the bits'
-    atomics, 90 of the appends.
-- **The lifetime a frame**, p50 on Sponza at 1280×720 with about 770 probes live: on the 4090 about 24
-  µs (retire 7, want 7, admit 5, the two commands 2 each); on the iGPU about 129 µs (want 117, retire 6,
-  admit 4).
-- **On the device** (one-offs on both GPUs): free plus live is the capacity, every live probe has one
-  indirection entry and no two share one, a walk through the building admits and scrolls without
-  starving, and the probes a turn to the sky leaves unwanted go after the retention time.
-- Commands: admit's command (one thread) sizes admit over the wanted list, and schedule (one thread)
-  sizes the next frame's retire over the frame's active list; S4b gives schedule the period and the
-  trace list. Every dispatch is indirect over a device count, or want's screen tiles.
-- **Extracted**: `chunk_folded_dispatch` (`gpu_primitive/indirect/`), the folded command the
-  one-thread passes write; the brick take, the brick movers' command and the fluid forcing's command
-  migrated onto it.
-- Capacity at the defaults: 16,384 slots. Growth doubles on a pop the free list could not serve.
-- Tier 2, `probe_clipmap_lifetime.spec.js`, two cascades of 8³ points on the emulator:
-  - a pixel wants its cage, and admit gives each point one NEW probe there, named by its entry;
-  - in the skirt the next cascade's cage too, biased by its own spacing;
-  - the bias moves a cage across a cell face, and out of its window;
-  - the sky and a point no window holds want nothing; two tiles' shared points are admitted once;
-  - a probe wanted again keeps its slot; one unwanted keeps it for the retention time, then gives it
-    back;
-  - a probe whose point leaves its window gives its slot back before the point the move exposed in that
-    storage cell claims it; one at the window's far lattice point stays;
-  - a pop the free list cannot serve is counted;
-  - admit's and schedule's commands cover their lists.
-  - a lane's two cages are claimed apart though their least points share a storage cell.
-- Mutants: 29 of 29 killed.
-- Tier 3, `GPUProbeClipmap.spec.js`: the first frame's fills and the passes' order, sizes and commands;
-  the cage windows; the clock; the capacity; growth; destroy.
-
-**As built (S5a, 2026-10-28), the hits' wants**: `probe/shader_probe_clipmap_want_hits.js`, between want
-and admit's command, through the launch the last frame's rays had, `PROBE_DISPATCH_RAYS`.
-- **Want's cages are one chunk**, `probe/chunk_probe_clipmap_want.js`: the pick's cages, the claims and
-  the appends. Want and the hits' wants both call it, so a hit wants what its pick reads.
-- **A wanted list entry's top bit says a pixel wanted the point**, `PROBE_WANTED_SCREEN`. Want runs
-  first, so a point both want is listed once, as the screen's. Admit copies the bit into the record's
-  `screen` word, which sits in the padding the record had: still 64 B.
-- **The row says which rays want**: shade leaves a front-face hit's albedo there and zero in every other
-  ray's, so a ray that takes no bounce wants nothing.
-- **The trace list is cleared after the hits' wants**, which read the last frame's list, origins and
-  rays, told that frame's U and R by the host.
-- Tier 2, `probe_clipmap_lifetime.spec.js`:
-  - a pixel's points are listed as the screen's, and so are their probes;
-  - a front-face hit of a screen probe wants its pick's cage where its ray ends, and admit gives the
-    points NEW probes, the hits';
-  - a probe only hits wanted has hits that want nothing;
-  - misses, unresolved rays, back faces, black hits, and updates past the list's count or bound want
-    nothing;
-  - a point a pixel and a hit both want is listed once, as the screen's;
-  - a probe the screen wanted and then only hits did becomes the hits', and the screen's again; a slot a
-    screen probe gave back is the hits' when a hit's point takes it;
-  - the cage viewed back along the ray, and the next cascade's in the skirt.
-- Tier 3, `GPUProbeClipmap.spec.js`: the pass's place, its command, and the last frame's U and R.
-- Mutants: 24 of 24 killed.
-
-**Measured (2026-10-30), the churn in a still scene.** Sponza at 1280×720, the clock at 60 Hz, the camera
-and the light still, 3,600 frames settled. Then 600 frames, each read back: every slot's state and record,
-the wanted list, the trace list and the period. A slot's probe is followed by its point and its update
-count. Modelled as §8.5 has it, due agreed with the trace list on every probe past its first update, those
-a full list turned away aside: 2.7 million checks on each GPU, none apart.
-- **Hits' probes come and go, about four a frame.**
-  - The RTX 4090 admitted 3.9 a frame and retired 3.8–3.9 (three runs); the AMD iGPU 4.1 and 4.0.
-  - The screen admitted none.
-  - Every probe retired had gone unwanted for 1.017 s, the retention time and a frame.
-- **They are the probes up to three updates old**, §8.6's 11%. Of the 4090's 501 (11.4% of the alive),
-  487 were admitted within the 600 frames; of the iGPU's 532 (12.2%), 509. The few others are hits'
-  probes wanted on about one frame in twenty, whose want seldom falls on their turn.
-- **The same points come back.** Of the 896 points admitted in the 10 s, 650 were admitted again, three
-  times at the median.
-- **Each is wanted by one far ray.** A twin of the hits' wants kept, for each point, its shortest wanting
-  hit and the rays that wanted it.
-  - A point admitted was wanted by one ray (p50 and p90), 10.8 m from its probe at the median (p10
-    5.3 m). Of those rays 60% were a uniform update's.
-  - A point kept was wanted by 6 rays a frame at the median, at 3.2 m.
-- **Why far.** A radiance texel's ray stands for the texel's cone, t·√(4π)/n_r across where it lands:
-  0.22·t at n_r = 16, which past t = 4.5 m is wider than a cage of the finest cascade. That cascade holds
-  95% of the admissions. Such a cage is landed in by chance, once every few seconds (a probe both
-  admitted and retired within the 600 frames lived 1.3 s at the median), and the retention frees its
-  probes in between. The next landing finds no probe, so its ray takes no bounce from them.
-- **What it costs**: the admitted probes' first updates and their next three cast 2,560–2,870 of the
-  frame's 52,600–53,700 rays on both GPUs, 4.8–5.5%, and are 1.3% of the updates. On the AMD iGPU the
-  passes a ray (trace, shade, light, the hits' wants) take 5.4 ms at the median and those a probe 2.0 ms,
-  so by those shares about 0.3 ms a frame; not timed against a build without it.
-- **What moves it**, on the 4090, in admissions a frame against 3.9:
-  - a retention of 3 s: 0.7. Those up to three updates old fall to 5.9%, and 3.5% more probes are live;
-  - every request held at R, 256: 3.0. Those are the rays before the variable requests (§8.6), 2.3 times
-    as many, so the requests are not the cause;
-  - half the ray budget, T from 6 to 10: 5.1, and 15.9% up to three updates old. A hit renews a probe
-    at most once a hitter's period, while the retention is in seconds, so the churn grows with the live
-    count;
-  - the hits' wants and the light pass's pick at the finest cascade whose spacing covers the texel's
-    footprint, a twin of both: 2.4, with 11% fewer probes live and 4% fewer rays. At twice the footprint:
-    1.9, with 30% fewer probes and 9% fewer rays. Both gather their admissions where the cascade changes
-    (t of 4.4 m and 2.2 m at the median). The cascade then follows each ray's distance, not the point, so
-    a point's wants split between two cascades.
-  - The frame's mean luma: 72.3 as built (72.4 on the iGPU), 71.5 at 3 s, 71.9 and 71.8 by footprint.
-    As built read 71.0–72.0 between runs (§8.6).
-- **Hits' probes are retraced less often than every T frames.**
-  - The 3,077 hits' probes alive through the 600 frames were wanted on 67% of frames at the median, 11%
-    at p10.
-  - They were updated 6.8 times a second at the median and 0.8 at p10; the screen's, at least 6.6.
-  - At p90, 1.2 s had passed since their last update; at p99, 6 s.
-  - A hit wants a probe in the frame after its hitter's update, so its point's bit is set on fewer of
-    the probe's turns than a pixel's is.
-- The passes did what this section and §8.5 said. The churn was the retention's, on points that hits land
-  in once every few seconds; a fixed retention was the departure from Enshrouded, whose cache evicts by
-  pressure (Alex, 2026-10-30), built below.
-
-**As built (2026-10-30), eviction by pressure, not by a retention time.** Enshrouded's cache stays full and
-evicts every frame, more the fuller it is, so a probe keeps its history as long as there is room.
-- **Retire** frees a probe whose point left its window, or one the last frame's schedule asked for.
-  `retention_time` is gone, from the settings and the passes: a hard break.
-- **How many**: as many slots as the free ones fall short of the frame's wanted points and 5% of the
-  capacity (`PROBE_FREE_SLACK`, Alex's). The wanted points are the most a frame can admit, a camera cut's
-  included, and the slack is room for a burst of them the frame it comes.
-- **Which, the least recently wanted first**: retire counts each probe it keeps and could evict into one of
-  32 binades of the seconds since it was last wanted (`probe_clipmap_age_bucket`, the float's exponent, 1 s
-  beginning the middle one), `PROBE_COUNTER_AGES` on. Schedule walks them from the oldest, taking a bucket
-  whole while the shortfall takes it and the rest of the shortfall from the next, and writes that to
-  `probe_eviction`; retire's threads take that bucket's while a counter, `PROBE_COUNTER_EVICTED`, is under
-  it. Past the youngest bucket anything was counted in, schedule asks for nothing. No sort, no pass of its
-  own, nothing read back.
-- **In use, never evicted**: a probe a want waits on, NEW or wanted since its last update (§8.5), and one
-  wanted the last frame (retire takes that frame's time). Where those fill the slots, an admission starves
-  and the capacity grows, as before.
-- **Device, Sponza, the 4090**, the still view, 600 frames, against the base before §8.5's as-built note:
-  - admitted 0.007 probes a frame against 3.9, retired none against 3.8;
-  - the young probes' rays 19 a frame against 2,600; the frame's 54,800 against 53,800 (with §8.5's change
-    alone 58,500, the churn's probes taking their second updates);
-  - 5,400 probes live against 4,500;
-  - the probes up to three updates old still 11.3% of the alive: probes kept that hits want once in a few
-    seconds, updated when they are.
-- **A walk**, the courtyard's length and back over 1,200 frames, the 4090:
-  - at the default capacity, 16,384, at least 6,849 slots stayed free: nothing was evicted;
-  - at N = 16, 4,096 slots, 488 frames evicted, no admission starved and the capacity never grew. The
-    frame's wanted points were half the slots there, so a frame short of room freed every probe out of use
-    older than about two frames.
-- **The sun doubled**, frames to 50%, 90% and 95% of the change in the mean band 0 of the probes wanted:
-  37–42, 98–106 and 117–133, against the base's 38–41, 85–99 and 117–135, two runs each.
-- **The AMD iGPU**, the still view, separate processes and not paired, against the base:
-  - admitted 0.007 a frame against 4.0, the young probes' rays 24 against 2,840, the frame's 54,700
-    against 53,700;
-  - a want waited 6 frames for its update at the median, the screen's 13 and the hits' 20 at p99;
-  - the trace list held U, 512, nearly every frame against 477 a frame: the period counts every probe a
-    want waits on (§8.5), so the update fills its budget, where the hits' probes it skipped left it
-    short. The probe passes summed 7.91 ms at the median against 7.55, of which trace, shade and light
-    5.25 against 5.02;
-  - retire 26.6 µs against 21.3, admit 13.6 against 8.3, schedule 3.5 against 0.8, the due passes 9.4
-    against 15.4.
-- Tier 2, `probe_clipmap_lifetime.spec.js`: a probe nobody wants keeps its slot while there is room; past
-  the room the probes wanted longest ago go first, as many as the room lacks, a bucket in part where it
-  lacks part of one; one that leaves its window as its bucket is partly evicted takes none of it; a NEW
-  probe and one wanted the frame before are never evicted, and an admission the room still lacks starves;
-  a shortfall the evictable probes cannot cover asks for those counted, none younger. The first three
-  were red against the retention time; the rest guard the protections. Mutants: 13 of 13 killed.
-- Tier 3, `GPUProbeClipmap.spec.js`: retire's times, schedule's slack, the eviction zero as made.
-
-### 8.4 Relocation and classification
-
-**Relocation**, at the start of every update:
-- With q the lattice point and d = `brick_clipmap_distance(q)`: while d < d_min,
-  `q += ∇d·(d_min − d)`, at most 3 times. The field is signed, so a probe inside the band is pushed
-  out.
-- The offset is clamped to 0.45·s_c, RTXGI's 45%. The probe stays in its own Voronoi cell, and the
-  cage stays the lattice's.
-- d_min = ¼·s_c.
-- As built (S4b): see §8.5's as-built note; relocation's offset lives in the state's second word.
-  - RTXGI's minimum front-face distance is 1.0 m at its recommended 2–3 m spacing, about a third of
-    a cell. Lumen offsets only below 0.05 of a cell.
-  - A quarter keeps a probe well clear of the 0.1·s_c receiver bias (§9.1) and of the ½-voxel
-    expand its own rays start beside.
-
-**Classification**: DEAD when more than 25% of an update's rays hit back faces. That is RTXGI's
-threshold for its fixed classification rays, and UE's mesh-SDF sign vote uses the same fraction.
-Every update's rays cover the whole sphere, one per texel, which is what the fixed-ray threshold
-assumes.
-- A back face is a hit whose field gradient points along the ray: the ray came from inside a solid.
-  A ray that starts inside one hits at its first step (§7.2).
-- A probe deeper than the band reads +R and is not relocated, but its rays reach the band from
-  inside, as back faces.
-- A DEAD probe weighs zero and is traced once every 8 periods, so it notices when the scene changes.
-
-### 8.5 Scheduling
-
-- At most `U = floor(ray_budget / rays_per_probe)` probes update a frame (512 at the defaults).
-- **schedule** (one thread): `P_w` = probes wanted this frame, and `T = max(1, ceil(P_w / U))`. T
-  frames is the period, so it follows the live count.
-- Then one thread per active probe. A probe is **due** if it was wanted this frame and any of these
-  holds:
-  - it is NEW;
-  - `(frame + h(slot)) mod T == 0`;
-  - it is DEAD and `(frame + h(slot)) mod 8T == 0`.
-- NEW probes append first, as their own dispatch; the rest fill the trace list up to U.
-- Every wanted probe is retraced every T frames. With 8,000 wanted probes that is T = 16: 0.27 s at
-  60 fps.
-- A camera cut that admits more than U new probes spreads them over frames. The stale ones simply
-  wait a period.
-
-**As built (S4b, 2026-10-28)**:
-- **The state is two words**: the kind and updates, then where relocation moved the probe, three
-  10-bit two's-complement fields of 0.45 of its spacing (a step under a thousandth of it, zero at the
-  lattice point). §9.1's pick needs every corner probe's position for its wrap term and its depth tap,
-  and §8.2's 4-byte state left the offset in the 64-byte record: a corner is now one 8-byte load.
-- **Schedule** (one thread) sets T from the wanted list's count, and writes the command over the
-  frame's active list that the due passes dispatch through, and the next frame's retire.
-- **Due** runs twice over the active list: NEW probes, then ALIVE ones on their turn and DEAD ones on
-  theirs in eight periods. "Wanted this frame" is the point's wanted bit. A probe's turn is
-  `(frame + lowbias32(slot)) mod T`. Past U the list's count goes on rising and nothing is written; the
-  update's command clamps to U.
-- **Relocate** is its own pass over the trace list, a thread a probe, in a second graph pass that reads
-  the brick clipmap's last write of the frame (`GPUBrickClipmap.graph_update` now returns it), so it
-  orders after the build. The field's gradient is the new `brick_clipmap_gradient`: four taps of
-  `brick_clipmap_distance` a voxel across, zero where the field is flat.
-- **On the device**, Sponza at 1280×720 with the caches baked:
-  - relocation moved 450 of 769 live probes on the 4090 (430 of 746 on the iGPU), some to the limit;
-    wanted probes are the cages of visible surfaces, so most sit within a quarter cell of one;
-  - T = 2 for 646 wanted at U = 512; nothing starved;
-  - schedule, the two due passes and the update's command: about 11 µs on the 4090, 8 on the iGPU;
-  - relocate: 24.6 µs on the 4090 and 23.4 on the iGPU for 512 probes. The same on both, so it is
-    latency-bound: three dependent steps of five field reads, over a launch of eight workgroups.
-- Emulator fixed alongside: `extractBits` on `i32` now sign-extends (WGSL §17.9); it had zero-extended
-  both types, and the offset's decode depends on it.
-- Tier 2: `probe_clipmap_schedule.spec.js` (the period, NEW first, unwanted never due, the turns, the
-  bound, the commands), `probe_clipmap_relocate.spec.js` (free space, a face, inside a solid, a
-  concave corner, the limit, a flat field, the cascade's own clearance), `chunk_probe_clipmap.spec.js`
-  (the offset's encoding), and the gradient in `brick_clipmap_trace.spec.js`.
-- Mutants: 19 of 21 killed. The two survivors are equivalent on the fields the specs build: the early
-  exit where the field is flat, and the gradient's flatness threshold on fields exactly flat.
-
-**As built (2026-10-30), due waits on a want, not on this frame's bit.** The hits' wants (§8.3) set a
-point's bit the frame after their probe's update, so a probe only hits keep had its bit on few of its
-turns: measured on Sponza (§8.3), the hits' probes were updated 0.8 times a second at p10 against the
-screen's 6.6 at the least, and 6 s had passed since the last update at p99, 21 s at most.
-- **Waiting**: a probe is NEW, or a pixel or a hit wanted it since its last update, its wanted time past
-  its traced time. The update comes after admit in its frame, so a want in the frame of an update is
-  served by it. Due lists the NEW in its first pass, and a waiting ALIVE or DEAD probe on its turn.
-- **The period counts the waiting**, `T = max(1, ⌈P_w / U⌉)` with P_w the probes waiting, not the
-  points wanted this frame. Retire counts the waiting probes it keeps and admit those the frame's wants
-  add, one atomic a subgroup each (`subgroup_atomic_add_u32`), into `PROBE_COUNTER_WAITING`, the
-  counters' fourth word; schedule takes the period from it and empties it.
-- **Device, Sponza, the 4090**, the same still view and 600 frames, against master:
-  - the hits' probes alive through them, 2,984: 4.7 updates a second at p10 and 8.2 at the median,
-    against 0.8 and 6.8; 0.42 s since the last update at p99 and 1 s at most, against 7.2 s and 21 s;
-  - the screen's: 8.3 a second at the median against 10.8, the period 7 frames against 5–6;
-  - the frame's rays 58,500 against 53,800, the young probes' 5,300 of them against 2,600: the churn's
-    probes now take their next updates when a hit wants them again (§8.3);
-  - the trace list held more than U on 454 of the 600 frames, 524 a frame on average: due lists every
-    NEW probe besides a period's share of the waiting, so its count sits at U, and the last ones past it
-    wait their next turn.
-- Tier 2: `probe_clipmap_schedule.spec.js` (the period over the waiting; a probe wanted between its turns
-  due on its turn; one whose wants its update served, the same frame's included, not due; a NEW one at
-  once), `probe_clipmap_lifetime.spec.js` (retire and admit counting each waiting probe once, through the
-  period). Each was red against the shaders before. Mutants: 8 of 8 killed.
-
-### 8.6 Rays
-
-**trace**: one thread per ray, `trace_count × rays_per_probe` rays.
-- **Texel**: R = `rays_per_probe`.
-  - R ≥ n_r²: R/n_r² rays per texel.
-  - R < n_r²: the texels `(update·R + k)` under a fixed bit-reversal permutation of the n_r²
-    texels, so each update covers a spread subset.
-- **Direction**: `uv_octahedral_unit_decode((texel + ξ)/n_r)`, with ξ from STBN at (slot, update
-  count). This is one stratified jittered ray per texel, LPV's own pattern.
-- **Origin and range**: the relocated probe, with t_min = one voxel of the brick cascade there.
-- **Sun**: after `brick_clipmap_trace`, a hit traces `brick_clipmap_soft_shadow` toward each
-  directional light that casts shadows, up to 2 (a chosen cap; further lights are unshadowed at
-  hits).
-  - The shadow ray starts one voxel off the hit along the field's normal, outside the ½-voxel expand.
-  - This is the same pass because it is the same cost profile, an SDF march (E7).
-- **Output**: a hit record {t, or MISS / UNRESOLVED; cascade; slot; normal; back-face bit; sun
-  visibilities}.
-
-**As built (S4c, 2026-10-28)**, `probe/shader_probe_clipmap_trace.js`:
-- **The ray record** is 24 B (`PROBE_RAY_STRUCT`; 28 B with the light in three half floats until
-  2026-10-30, now one RGB9E5 word): `t`; the direction and the hit's normal,
-  each octahedral in two unorm16; the `meshes` row of the hit's surface, from `brick_clipmap_object`;
-  the flags (kind, back face, the hit's cascade); and the light. Trace writes the
-  direct irradiance there and shade writes the radiance over it. The hit's position is the ray's
-  start plus `t` along the direction, which shading recomputes; the start was the probe's origin until
-  the ray origins below. (S4c's record held the two suns'
-  visibility in place of the light; S4d moved E_dir into the trace, below.)
-  - **The light as RGB9E5 (2026-10-30, Alex: the half floats were a poor encoding).** The engine's
-    `rgbe9995` chunks: one word, the three channels sharing an exponent. The encoder clamps to its
-    largest value, 65,408, which replaced the half-float holds in shade and the light pass and still
-    keeps the half-float atlases finite. A channel far below the brightest loses precision: beside
-    65,408, 2 and 3 round to 0.
-  - Measured paired in one process. The five passes that read or write the record (trace, shade,
-    light, accumulate, the hits' wants) ran as twins built from master's WGSL, swapped in at
-    `setPipeline`, the two encodings each twice. There were 120 frames an arm, the clock at 60 Hz:
-    - 4090: Sponza +14 µs a frame across the five, all in the trace (+3%; its repeats differ by 3–10
-      µs); Emerald Square's avenue the same.
-    - iGPU: Sponza −124 µs (−2%; shade and light −4% each); Emerald the same.
-  - The image, settled 1,200 frames, master and the tree in separate processes: on Sponza they differ
-    by 1.6–1.7 codes a channel on average, and two runs of the tree by 1.8. The probes' noise is not
-    the same from process to process. On Emerald's avenue they differ by 0.01.
-- **The texel mapping** is `chunk_probe_clipmap_ray_texel`, both ways (a ray's texel, a texel's rays),
-  so accumulation finds each texel's rays without a scatter. The bit-reversed subset repeats every
-  n_r²/R updates, which keeps its product in range.
-- **The noise** is STBN at the texel moved by the slot's hash, so neighbouring probes do not jitter
-  alike, and at the update count.
-- **The origin** is the lattice point plus the state's offset; t_min one voxel of the brick cascade
-  there; t_max the coarsest window's diagonal. Since S4d relocation writes it, `vec4(origin,
-  spacing)`
-  at the probe's place in the trace list (`probe_origins`), at the offset as encoded, and the update's
-  passes after it read it there.
-- **Back faces** follow the gradient rule as written. Of a probe inside a solid, a ray heading out
-  through the nearer face is one; a ray nearly along the solid's faces can read as a front face, but
-  classification's share stays well past a quarter (over half for a probe in a slab, in the spec).
-- **A surface turned from a light marches no shadow toward it**: the light gives it `max(0, n·l)`,
-  zero there. The light keeps its place among the shadowed, so which lights are shadowed does not turn
-  on the surface's orientation.
-- **E_dir is the trace's** since S4d: Σ colour·max(0, n·l)·visibility over every directional light,
-  the first two that cast shadows by their soft shadow (a shadow ray since 2026-10-30), at a front-face hit. The trace reads the lights
-  already, and shade would have needed the light table as an eleventh storage buffer (below).
-- **On the device**, Sponza at 1280×720 with the caches baked, 131,072 rays a frame (U = 512 × R = 256):
-  96% hit, 3.4% miss, 0.2% unresolved, 2.5% back faces; the mean hit at 2.6 m; 13% of the sun seen at
-  front-face hits.
-
-  | | AMD iGPU, p50 | RTX 4090, p10 |
-  |---|---:|---:|
-  | trace, as built | 7.9 ms | 355 µs |
-  | without the sun's shadow | 4.2 ms | 62 µs |
-  | the march alone, no lights, no object | 3.9 ms | 57 µs |
-
-  - The facing test saved 4–7% of the shadow: most hits are on walls nearly parallel to Sponza's high
-    sun, whose shadow rays graze the wall they leave.
-  - On the 4090 the pass's p50 swung between runs, to 2–4 ms on some, while the same frame's twin
-    without the shadow held at 60 µs. Not explained yet; S4g measures it on a quiet machine.
-  - **At the default ray budget the update's rays cost about 8 ms a frame on the iGPU.** Reported with
-    S4's timings: `ray_budget` is the knob (§10), and the cost is linear in it.
-- Tier 2, `probe_clipmap_trace.spec.js`, over bricks built from analytic fields:
-  - a ray a texel, every texel once; more rays a texel each, each inside it; fewer, a spread subset
-    that a run of updates covers;
-  - a miss out of every window; a hit at a sphere within half a voxel, with its row;
-  - a ray from inside a solid hits at its first step, a back face out through the nearer face; from
-    past the band, always; a probe beside a solid sees only front faces;
-  - the sun whole under an open sky, none under a roof; only the first two shadowed lights traced; no
-    shadow from a back face or from a surface turned from the light;
-  - neighbouring probes jitter apart; a probe within half a voxel of a surface steps off it; the ray
-    starts at the relocated probe; the rays of a probe past U are not traced.
-- Mutants: 18 of 18 killed.
-
-**As built (ray guiding, 2026-10-29): Enshrouded's importance-sampled rays** (D11 reversed in its rays'
-half). Alex found the noise of one jittered ray a texel visible and asked for Enshrouded's scheme,
-rotating corner and all.
-- **Which updates are guided**: every `PROBE_UNIFORM_PERIOD`-th update (5, the talk's) is uniform, as
-  above. So are a probe's first n_r²/R updates, one when R ≥ n_r², which together reach every texel:
-  Enshrouded gives a new probe its most rays for the same reason, and the guide would weigh a texel no
-  ray has reached as dark. Every other update is guided, except a DEAD probe's, which are all uniform:
-  readers weigh it at nothing, and only uniform rays reclassify it. Guided, its rare updates kept it dead
-  for 40 periods, and Sponza's dead probes rose by a quarter.
-- **The guide** (`probe/shader_probe_clipmap_guide.js`), three passes a thread a row of each listed
-  probe's radiance map before the trace, per-invocation as projection is:
-  - rows: the luminance of the row's history texels;
-  - weights: each texel's share of the probe's luminance in fixed point (`PROBE_GUIDE_SCALE`), held to
-    `(PROBE_TEXEL_RAYS − 2 − R/n_r²)/R`;
-  - starts: the first ray of each walk position, `⌈R·Σ_{q<p}(w_q + e)/W − φ⌉`, with `e` the even share
-    of what the weights leave of the scale, and `φ` a hash of slot and update count. The walk is the
-    map's rows from the corner `updates mod 4` names.
-  - Integer weights make the walk's sums exact, so trace and accumulation read the same rays for each
-    texel. The hold leaves every texel under 64 rays, the gather budget, and what it takes off is spread
-    over every texel. A dark history spreads its rays evenly, which classification can trust.
-  - Kept: `probe_clipmap_guide_words` = 2·n_r² + 2·n_r + 2 words a listed probe (1.1 MiB at U = 512).
-- **The trace** bisects the first rays for its walk position, at most log2(n_r²) steps. A texel's later
-  rays rotate its STBN jitter by R2 (`probe_clipmap_guided_ray_jitter`). The light pass, shade and the
-  hits' wants are unchanged: any per-ray noise serves the light pass's pick.
-- **What it does to the rays**: on Sponza the back faces fall from 3–4% of the rays to 2.5–3%. The
-  hits shift toward lit surfaces, whose sun shadow rays are the trace's cost.
-- **Measured, Sponza 1280×720.** Every comparison is the tree at period 1 (every update uniform, the
-  tree without guiding) against period 5, in separate runs on each GPU; values are given as AMD iGPU /
-  RTX 4090.
-  - **Screen, S4g's stability method.** TAA and AO were off; SSR on, so that the deferred diffuse and its
-    twins draw. The runs took 240 frames after the bake and 240 to settle, with the probes' clock fixed
-    at 60 Hz. Each number is the mean relative luma change of a pixel against the previous frame at the
-    same surface point, and **none moves**:
-
-    | p50, period 1 → 5 | still | orbit |
-    |---|---|---|
-    | eight corners blended (the probes alone) | 0.55 → 0.56% / 0.54 → 0.55% | 3.83 → 4.01% / 3.95 → 4.09% |
-    | the shipped pick | 14.1 → 14.4% / 14.3 → 14.2% | 19.0 → 19.7% / 18.7 → 20.1% |
-    | the frame, SSR off (fused pass) | 10.7 → 10.3% / 10.3 → 10.2% | |
-
-    Per frame, the pick's draw of two of eight is most of the diffuse's change (14% against 0.55% with
-    all eight blended), as S6's estimator session also found.
-  - **Probes**, the estimator session's probe-level method (`msme.js`, `probe_reads`):
-
-    | period 1 → 5 | AMD iGPU | RTX 4090 |
-    |---|---|---|
-    | texels, an update apart, p50 | 1.05 → 1.37% | 0.92–1.03 → 1.27–1.29% |
-    | SH band 0, an update apart, p50 | 0.27 → 0.40% | 0.26–0.28 → 0.36–0.38% |
-    | atlas texels, 24 frames apart, Σ abs(ΔL) / Σ L | 8.7 → 7.5% | 8.7 → 7.2% |
-    | a doubled sun, 50% / 90% taken | | 44 / 160 → 34 / 117 frames |
-    | its halving, 50% / 90% | | 55 / 183 → 44 / 140 frames |
-
-    Guiding makes the probes follow a light change about a quarter sooner. Their noise between one
-    update and the next rises a third, while over four updates it falls by a sixth. The uniform update
-    every fifth, which gives a texel one ray where the guided ones gave it several, is the likely source
-    of the update-to-update jitter; this is not isolated.
-  - **Before the multi-scale mean** (master at d1ca833d6, the exponential blend) the probes' noise fell
-    without the rise: the atlas 24.9 → 18.0% / 24.6 → 17.9%, the eight corners' p90 1.30 → 0.92% /
-    1.24 → 0.87%. The screen did not move then either. The estimator took most of what guiding
-    took off.
-  - Dead probes fall by 9–17%. An alive probe is re-tested only on its uniform updates, a dead one on
-    every update, so a probe near the quarter spends more of its time alive. A probe inside a solid is
-    dead from its first update, which is uniform.
-- **Paired cost**: one page, periods 1 and 5 alternating in blocks of 16 frames (ABBA, the first 4 of
-  each dropped), the camera still, p50 in each arm, on master with the multi-scale mean:
-
-  | | AMD iGPU | RTX 4090 |
-  |---|---:|---:|
-  | trace | 6.79 → 7.58 ms | 335 → 470 µs |
-  | accumulate | 429 → 676 µs | 11 → 21 µs |
-  | the guide's three passes (both arms) | 496 µs | 28 µs |
-  | shade and light | +76 µs | ±1 µs |
-
-  In all, **+1.6 ms a frame on the iGPU and +0.17 ms on the 4090**. The trace's rise is the sun's soft
-  shadow at the lit hits that guided rays favour.
-- Tier 2: `probe_clipmap_guide.spec.js` (a dark history's even spread, shares by luminance, the hold,
-  the corner, U), `probe_clipmap_trace.spec.js` (each walk position's run in its texel, a texel's rays
-  apart, a uniform update and a DEAD probe ignoring the guide), `probe_clipmap_accumulate.spec.js`
-  (a texel's run averaged, the period by rarity on uniform updates for radiance and depth, a depth texel
-  as a mean of means), `probe_clipmap_project.spec.js` (a guided update keeps the kind; a dark guide's
-  update and a DEAD probe's classify).
-- Mutants: 16 of 16 killed, among them the trace, accumulation and projection as they were.
-
-**The adversarial review (2026-10-29) found two defects in the first cut, both fixed and pinned:**
-- **With R < n_r², a new probe took 5× the updates to see its sphere.** Its first update reached R texels
-  and cleared the rest, and the guide weighed the cleared ones dark. At n_r = 16 and R = 64, the whole
-  sphere was seen at update 15, not 3.
-  - Now a probe's first n_r²/R updates are uniform (above).
-  - Measured on the 4090, Sponza orbiting at R = 64, two runs each: the alive probes' mean irradiance
-    (E/π) was 0.0137 every update uniform, 0.0079 before the fix, and 0.0121 after it.
-  - The 12% that remains is not traced. The likely source is the guide itself at R < n_r²: a texel
-    whose sample read dark takes its next ray from the uniform updates, which reach it once in
-    5·n_r²/R updates. At the default R = n_r², still, the guided irradiance matches the uniform within
-    0.5%.
-- **A guided depth texel took only the radiance texels that took rays**, so where it mixes lit and dark
-  directions (a back face, a shadowed wall) its depth leaned to the lit ones'.
-  - Now a guided update takes a depth texel only when every radiance texel inside it took rays. Its
-    period counts the least reached of them.
-  - Measured on Sponza at the defaults, still: the median depth moment was 1.590 every update uniform,
-    1.599 before the fix, and 1.584 after it. The means agree within 0.3%, so on Sponza the bias was
-    small.
-
-**As built (ray origins, 2026-10-29): each ray starts at a point of its own**, uniform in a ball of
-`PROBE_RAY_ORIGIN_JITTER` = 1/16 of the spacing around the probe, as Brick4's bake jitters its probes
-(Alex's request).
-- The point is `chunk_probe_clipmap_ray_origin`'s, a hash of the probe's slot and the ray's packed
-  direction. Shade, light and want hits put the hit back together from the same start, so the record
-  carries nothing new. The trace's jitter moves the direction every update, and the start with it.
-- A sixteenth is half a brick voxel at the default sizes, well inside the relocation clearance (¼), so
-  wherever relocation reached the clearance every ray starts outside the solid.
-- Measured on Sponza, the camera still, two runs a radius on the 4090 and one on the iGPU (harness:
-  session 481e40f0's scratchpad, `device/oj.js`):
-
-  | radius, of the spacing | texel change an update apart, p50 | dead probes | depth σ, p50 |
-  |---|---:|---:|---:|
-  | 0 | 1.11–1.19% | 3.2% | 0.046 |
-  | 1/16 | 1.00–1.01% | 3.5% | 0.051 |
-  | 1/8 | 1.17–1.26% | 4.5% | 0.073 |
-  | 1/4 | 1.40–1.67% | 5.9% | 0.122 |
-
-  - Alex compared the converged eight-corner diffuse at ¼ against 0. The jittered image is markedly
-    smoother, and sharp-contrast artifacts are gone. The whole-image |Δ|/L read under its own noise floor,
-    so the change is local, and that metric misses it. He chose 1/16.
-  - Brick4's own radius, 5e-5 m, changes nothing here: an SDF march has no float ties for it to break.
-  - Rebuilding hits from the probe instead of the ray's start is measurably wrong from ⅛ up: E/π +3.5–4%
-    and 10–13% more probes, from hits wanting the wrong cells. Matching costs at most one timer step a
-    pass on either GPU.
-  - Cost, measured at ¼ (paired by blocks of frames in one page): the trace +3.5% on the 4090 (442 →
-    458 µs), nothing on the iGPU.
-- Tier 2: `probe_clipmap_trace.spec.js` (the starts within the ball and spread over it; a wall's `t`
-  from each ray's own start), `probe_clipmap_light.spec.js` (a probe of one ray placed by its start; the
-  pick's hits from it), `probe_clipmap_lifetime.spec.js` (a hit across a lattice plane from its probe
-  wants the cage its start puts it in).
-- Mutants: 5 of 6 killed. The survivor is shade rebuilding its hit from the probe: its spec has no card
-  resident, so no hit position reaches its output.
-
-**As built (a probe's own count of rays, 2026-10-30): the frame's rays are laid out by listed probe**, the
-first stage of `PROBE_RAYS_VARIABLE_AND_SORTED_SCOPE_2026_10_30.md`. Every probe still casts R; what
-changes is that nothing assumes it.
-- **The layout.** After the trace command, the ray counts pass writes each listed probe's count of rays
-  (`probe_ray_counts`), and `graph_prefix_scan_csdldf`'s shaders scan them into `probe_ray_sums`. The k-th
-  probe's rays are `[sums[k − 1], sums[k])`, and the last sum is the frame's count, which a one-thread pass
-  turns into the rays' command.
-- **Each pass finds its probe.** Trace bisects the sums (`lower_bound_branchless`, as the mesh expansion
-  does) and writes the probe's place in the list into the ray's flags, above the cascade, which is now
-  three bits. Shade and the hits' wants read it there. The light pass, accumulation and the guide also
-  read the probe's own count from the sums.
-- **Past the last ray.** The threads of the launch's last workgroup past the frame's last ray write a
-  record of no ray (kind 3, `PROBE_RAY_NONE`). Every pass after trace stops there, so none needs the
-  frame's count. The rays buffer is rounded up to whole workgroups for them.
-- **R still means the uniform update.** A probe's first n_r²/R updates are uniform, and the rate's
-  uniform term (§8.8) keeps the settings' R. A guided update's walk, its gather and its expected rays
-  take the probe's own count.
-- **Storage buffers:** shade stays at 9, the light pass and accumulation go to 9, and trace goes to 8.
-- **Device, Sponza, 4090,** clock at 60 Hz, 900 frames settled, two runs of each build alternating:
-  master and the layout agree within master's own run-to-run spread (frame luma 71.8/71.8 against
-  71.0/72.0, alive probes 4,393–4,463 against 4,400–4,403, SH E/π mean 0.0131–0.0134 against 0.0133).
-  The passes' times are unchanged. The ray counts cost 4 µs and the rays' command 2 µs.
-- Tier 2: `probe_clipmap_trace.spec.js` (a probe casting its own count after the probes before it, each
-  ray naming it; the records of no ray), `probe_clipmap_accumulate.spec.js` (two rays a texel averaged
-  where R says one), `probe_clipmap_guide.spec.js` (the walk sharing out the update's own count),
-  `probe_clipmap_schedule.spec.js` (the ray counts and the rays' command). Each was red against the
-  shaders before it.
-
-**As built (variable rays, 2026-10-30): each probe asks for its next update's rays**, the second stage of
-`PROBE_RAYS_VARIABLE_AND_SORTED_SCOPE_2026_10_30.md`: Enshrouded's requests, on the period kept (F1).
-- **Counts and requests.** The ray counts pass writes two parts for each listed probe. The first is what
-  the budget does not scale: a uniform update's R (a NEW probe's among them), and a DEAD probe's fewest,
-  n_r²/4 (`PROBE_RAYS_PER_TEXEL_MIN`). The second is what it does scale: a guided update's request, at
-  least the fewest. Both are scanned, and the ray layout pass gives the requests what the budget leaves
-  past the counts: all of it when they fit, in proportion when they do not (F2). The k-th probe's rays
-  end at its counts' sum plus its requests' sum so scaled, rounded down, so the frame never passes the
-  budget and needs no third scan.
-- **The request** is the slot's own record, `probe_requests` (16 bytes a slot, not packed into `screen`
-  as F6 had it: the statistics below need three words). Projection writes it after every update:
-  - after a probe's first update, the most, 4·n_r² (`PROBE_RAYS_PER_TEXEL_MAX`), Enshrouded's new probe;
-  - when its light has moved, the most again;
-  - otherwise half the last request, down to the fewest.
-- **Moved.** Accumulation leaves each blended texel's fall from its mean, luminance, in its own
-  deviation and held to ±3 (`PROBE_CHANGE_SIGNIFICANCE`), in a fourth word of the maps. Projection sums
-  them over the root of their count: the update's change score. Moved is the score past 3 of the probe's
-  own running deviation (at least 1) from its own running mean, both kept over the estimator's variance
-  window, 2τ, a running mean while young. A score past their reach counts at it, so a change in the light
-  does not widen the probe's spread at once, while a lasting shift of its own is taken in within a few
-  windows. A first update clears the slot's statistics, which were the last owner's.
-- **DEAD probes** are due every period at the fewest rays (F4), not every eighth at R;
-  `PROBE_DEAD_PERIODS` is gone.
-- **Not built: F3**, weighing a sample by its rays in the estimator. It waits on a measurement.
-- **Device, Sponza, 4090,** clock at 60 Hz, the camera and the light still:
-  - false alarms, the probes past 64 updates asking for the most, 3,600 frames settled: 4.2% when the
-    change score summed the raw falls against zero, 3.2% with each texel's fall bounded, 1.1–1.3% as
-    built, against the normal tail's 0.27%;
-  - the probes up to three updates old are 11% of the alive ones (477 of 4,387) and 69–76% of them ask
-    for the most, as new probes do. That churn is the lifetime's admissions and retirements, measured in
-    §8.3, not the request's;
-  - the frame's rays, the last frame's layout of each run: 48,704–65,856, against master's U·R;
-  - trace p50 404–600 µs against master's 726–790 µs, separate processes and not paired;
-  - the noise between reads six frames apart: texels 1.25–1.49% against master's 1.23%, band 0
-    0.38–0.46% against 0.35%;
-  - the sun doubled, the alive probes' mean band 0 reaches 50%, 90% and 95% of the change in 40, 156
-    and 246 frames, against master's 42, 177 and 257;
-  - the post-load dark spell is unchanged: measured with the first build of the request, the probes
-    were resident at 17.6 s and converged at about 32–35 s, master's timeline.
-- **Storage buffers:** the ray counts pass binds 5, the ray layout 3, projection's probe pass 6.
-- Tier 2: `probe_clipmap_project.spec.js` (the most after a first update; moved past three deviations
-  and the halving to the fewest; a steady offset sips once held; a jump asks the most while it lasts; a
-  lasting shift is taken in; a new probe forgets the slot's last owner), `probe_clipmap_accumulate.spec.js`
-  (the fall in its own deviation, bounded), `probe_clipmap_schedule.spec.js` (the counts by kind, the
-  budget's proportion, DEAD every period). Each was red against the shaders before it.
-
-**As built (the probes' order, 2026-10-30): the trace list is sorted by its probes' places, and the rays
-are not sorted**, the end of `PROBE_RAYS_VARIABLE_AND_SORTED_SCOPE_2026_10_30.md` §2, where every
-measurement is.
-- **The order pass** (`shader_probe_clipmap_order.js`) runs after the update's command: a workgroup a run
-  of 1,024 listed probes (`PROBE_ORDER_RUN`, through `PROBE_DISPATCH_ORDER` over the live count) sorts
-  its run in place by the cascade above the Morton code of the probe's lattice point in the cascade's
-  window, with the bitonic workgroup sort (`chunk_sort_bitonic_workgroup`). Every pass after it reads a
-  probe's place from the sorted list, so neighbouring probes' rays run in neighbouring waves. Past one
-  run, the list is ordered within each run.
-- **Why not the rays.** A wave already holds one probe's rays walking its texels in rows. Every ray sort
-  measured costs more than it buys: global radix keys, local sorts by direction (8×8 or 4×4 bins, chunks
-  of 2,048 to 512), within each probe, and position bits above the bin. On the iGPU at 131k rays the
-  local sorts lose 4–22%, a hash-keyed control 29–57% of the trace. The 4090 is level throughout.
-- **Device:** iGPU 1–4% off the rays' stretch at 131k rays in most batches, the 4090 level; the pass
-  costs 11.8 µs on the 4090. Storage buffers: 3.
-- Tier 1: the validity spec. Tier 2: `probe_clipmap_schedule.spec.js` (a workgroup a run, up to U). Tier
-  3: `GPUProbeClipmap.spec.js` (the pass after the update's command, through its command). The sort
-  itself runs workgroup barriers the emulator cannot, so the device checks it: each run ordered and a
-  permutation of the list.
-
-### 8.7 Hit shading
-
-**shade**: one thread per ray.
-
-| Ray | Radiance |
-|---|---|
-| MISS | `sample_environment_color` along d |
-| UNRESOLVED | no sample |
-| back face | 0, counted for classification; its depth sample is 0.2·t (DDGI 2021's 80% shortening), so the probe reads as occluded that way |
-| HIT | `L = emissive + ρ_d·E/π`, with E = E_dir + E_loc + E_ind |
-
-The surface comes from `brick_clipmap_object` and `mesh_card_surface` (§6.6): diffuse albedo ρ_d and
-emissive.
-
-The three irradiance terms of a HIT:
-- **E_dir** is Σ colour·max(0, n·l)·visibility over `directional_lights_iteration_mask`.
-- **E_loc** comes from the world light clusters at the hit, generalised to this mode's brick levels
-  so that every hit position has a cell.
-  - At most 32 lights, `IRRADIANCE_CLIPMAP_LIGHT_BUDGET`'s value. Past that, lights are dropped.
-  - Each light goes through `irradiance_clipmap_get_{point,spot}_light_info_by_index`. One of them is
-    picked by WRS on its luminance there and divided by the chance of the pick; its shadow is a ray
-    traced in the bricks (as built 2026-10-30, below). Until then each light was summed, its shadow from
-    `volumetrics_{point,spot}_light_shadow`, and a light whose shadow map was cleared lit hits
-    unshadowed.
-- **E_ind** is this mode's own diffuse sampling (§9.2) at the hit, with last frame's SH: the next
-  bounce.
-  - Its pick takes the ray's own STBN sample as noise; the probe blend averages it.
-  - Where no probe exists, the bounce is **zero**, not the environment. A hit behind the camera in a
-    cave must not bring daylight in.
-  - The hit wants its cage (§8.3), so its probes stand there a frame or two later.
-  - LPV's 0.97 factor is dropped: albedo below 1 already bounds the series.
-
-**Hits are diffuse only**, as Lumen's surface cache lights diffusely (D7).
-- The cards hold diffuse albedo and emissive: the payload Alex chose.
-- A metal's diffuse albedo is zero, so a metal bounces nothing but its emissive. That is Lumen's
-  limitation too.
-
-**As built (S4d, 2026-10-28)**, `probe/shader_probe_clipmap_shade.js`, a thread a ray after trace
-through the same command:
-- **Its radiance goes over the ray's light** (RGB9E5 since 2026-10-30): no buffer of its own. With one, shade
-  would bind eleven storage buffers, past the ten a stage has (§12): the rays, the origins, the trace
-  list, the scene database, the texture means, the SDF headers and indirection, the card sets, the card
-  rows, and the radiance. In place it binds nine.
-- A miss takes `sample_environment_color` along its direction; a front-face hit `emissive +
-  ρ_d·E_dir/π`, its surface from `probe_clipmap_hit_surface` (§6.6) at its cascade's voxel; an
-  unresolved ray and a back face zero. Radiance is held to the largest half float, so a bright sky
-  cannot write an infinity that a zero weight turns into a NaN.
-- **The depth samples are accumulation's**: they follow from t, the kind and the spacing, which
-  accumulation reads anyway.
-- E_loc and E_ind join E at S5 (§13).
-- On the device, Sponza: 93–94% of the 131,072 rays are front-face hits. Cards serve 88.2% of them;
-  the material mean serves the other 11.8%, rows whose card set does not see the point. No hit
-  lacked a card set or an object. Misses see a black environment, as the harness's scene sets none.
-  87% of front-face hits come back black: they are in the sun's shadow, and E_loc and E_ind come at
-  S5.
-
-  | | AMD iGPU, p50 | RTX 4090, p50 |
-  |---|---:|---:|
-  | shade, as built | 3.27 ms | 45 µs |
-  | every hit on its material's mean, no card read | 224 µs | |
-  | the shell: the record, the decode, a miss's sky | 207 µs | |
-
-  - **The card lookup is 93% of the pass on the iGPU.** `mesh_card_surface` reads every card
-    record's direction for each facing axis, up to 96 records a hit, and a page and two texels for
-    each candidate.
-  - **So the layout's header names each direction's first card** (`MESH_CARD_LAYOUT_DIRECTION_FIRST`,
-    six words the merge writes, the records being direction by direction already), and the scan reads
-    its direction's run alone. Measured interleaved against the old scan, first and second alternating
-    frame by frame, 120 frames, p50: iGPU 1.64 ms against 3.29 ms, 4090 26.6 µs against 42 µs.
-- Tier 2: `probe_clipmap_shade.spec.js` (misses by direction, the material mean lit by E/π, nothing
-  from an unresolved ray or a back face, row 0 black, the half-float cap, the rays past U); the card
-  branch in `mesh_cards_capture.spec.js`, through a node twice the size, turned and moved, at hits
-  within 1.25 voxels of the surface and past the tolerance; the means in
-  `shader_resident_texture_means.spec.js` against means taken on the CPU, across rows, columns and
-  layers of slots.
-- Mutants: 43 of 44 killed. The survivor removes the means' dispatches, which the software device
-  cannot see on the texture build's own encoder; the device check reads the means back against the
-  atlas.
-
-**As built (S5a, 2026-10-28)**, E_ind: `probe/shader_probe_clipmap_light.js`, a pass of its own after
-shade, through shade's own launch.
-- **Why its own pass.** Shade binds nine of a stage's ten storage buffers, and the pick takes two more.
-  The light pass binds five.
-- **The albedo.** Shade leaves a front-face hit's diffuse albedo in the ray's `row`, `pack4x8unorm`, and
-  zero in every other ray's. Nothing after shade reads `row`.
-- **The pick** is made at the hit, along its normal, with the view back along the ray.
-  - Its noise is the ray's own jitter, `probe_clipmap_ray_jitter`, extracted from the trace into
-    `chunk_probe_clipmap.js`; the trace aims its ray with it.
-  - It reads last frame's SH, since the projection writes the records later in the frame.
-  - Where nothing is found the bounce is zero, as above.
-- **Tier 2.**
-  - `probe_clipmap_light.spec.js` checks:
-    - a hit takes its albedo by its probes' SH;
-    - misses, unresolved rays, back faces and black hits keep their light, and nothing is found nowhere;
-    - the pick is made at the hit, viewed back along the ray, with the ray's own jitter, across two
-      probes, against the chunks themselves;
-    - the half-float hold;
-    - a fresh jitter each update and round.
-  - Shade's stash is checked in `probe_clipmap_shade.spec.js`.
-  - Mutants: 18 of 18 killed, six by tests added for them.
-- **Measured, the multi-bounce furnace**: a closed room of ρ = 0.5 glowing L_e, no light, the clock held
-  at 1/60 s, 900 frames. On the RTX 4090:
-  - With the rule above, E reaches **0.836 of πL_e/(1 − ρ)** at p50, p01 0.718.
-  - 12% of the front-face hits find no probe. Every one lies on a wall the camera does not see, behind it
-    or beside it, since probes stand only where pixels want them, and the rule makes their bounce zero.
-  - A twin that falls back to the tracing probe's own SH where nothing is found reaches 0.994 (p01
-    0.988), but only because a uniform room makes every probe's irradiance the right one.
-- **Alex, 2026-10-28: the hits want their probes (D31 reversed in part), and nothing stands in.** "If we
-  get no indirect bounce, it is better to lose energy than to invent energy." A hit whose cage has no
-  probe wants it (§8.3), and its bounce is zero until that probe's first update, a frame or two later.
-- **Measured with the hits' wants**, same room and clock:
-  - E reaches **0.994** at p50 (p01 0.988) on the RTX 4090 and on the AMD iGPU, against 0.836 without.
-    No front-face hit finds nothing, against 12%. At ρ = 0.8 it reaches 0.992 after 1,800 frames.
-  - The room holds 418 probes, against 228: the walls the camera does not see.
-- **On Sponza in the sun**, the camera still at 1280×720, the defaults (512 probes a frame), with the
-  hits' wants and without:
-
-  | | nave view | toward a side wall |
-  |---|---|---|
-  | irradiance before AO, mean of the frame, 4090 | 0.108 vs 0.110 | **0.054 vs 0.050** |
-  | the same, iGPU | 0.112 vs 0.110 | **0.055 vs 0.050** |
-  | points wanted a frame | 2,600–3,200 vs 640 | 2,000–2,100 vs 160 |
-  | live probes | 4,600 vs 770 | 3,500 vs 180 |
-  | period T | 6–7 vs 2 frames | 4–5 vs 1 |
-  | the hits' wants pass | 25 µs 4090, 0.44 ms iGPU | 17 µs, 0.42 ms |
-  | trace, iGPU | 6.6 vs 4.9 ms | 7.6 vs 2.2 ms |
-
-  - Toward the wall, where most of the building is off screen, the hits bring 7–9% more light. In the
-    nave view the frame's mean moves less than its own frame-to-frame swing.
-  - **Stability is unchanged** by the longer period: S4g's measure, the change of the diffuse from frame
-    to frame at reprojected points, p50 on the 4090, still 16.3% against 16.3%, orbiting 22.3% against
-    25.1%. A probe the hits keep around the camera is there when the orbit brings its surface on screen.
-  - **The cost is the budget**: with the hits' probes wanted, each frame's updates reach U where the
-    screen alone left them under it, so the trace costs what the ray budget allows (§8.5). On the iGPU
-    that is most of the GI's growth.
-
-**As built (S5b, 2026-10-28)**, E_loc, in the light pass beside E_ind:
-- **The world light clusters take any clipmap's windows.** `graph_build_world_light_clusters` binds a
-  uniform that starts with a `CLIPMAP_LEVEL_ARRAY`, and is told the cascade count and a border of the
-  clipmap's own cells. The irradiance clipmap passes its uniform and its tiles' skirt, as it always had
-  them; the probe clipmap the bricks' levels and no border, so every hit has a cell.
-- **A cell by position**, `chunk_world_light_cluster_lookup_at`: the cell of a cascade holding a world
-  point, the nearest past the cells.
-- **At a front-face hit**: the cell of the hit's brick cascade, at most `IRRADIANCE_CLIPMAP_LIGHT_BUDGET`
-  point lights and as many spots, each the irradiance clipmap's at the footprint of a voxel of that
-  cascade, its cosine at the normal, its map's nearest texel from a voxel off the surface. The light pass
-  binds 8 storage buffers. The renderer hands the GI the frame's shadow map atlas.
-- **Measured on the device**, a closed room of albedo 0.5, nothing glowing, one point light inside: one
-  frame through a twin that adds E_loc alone, every front-face hit facing the light against I·cosθ/d²
-  under the range window.
-  - 0.9958 at p50 on both GPUs, and 1.0039 above p99: the albedo the hits read, 127/255 from the cards
-    and 128/255 from the material mean, against the 0.5 the check assumed. E_loc is exact.
-  - 0.27% of those hits read shadowed, all within a few centimetres of the floor's far corner 7.6 m from
-    the light, at a grazing angle, their points 0.12 m into the slab: acne a voxel's lift does not clear
-    there. None do without the light's shadow.
-- **Its cost**, paired on Sponza (the light pass with E_loc and a twin without it, alternating frames),
-  p50:
-
-  | | 4090 | iGPU |
-  |---|---:|---:|
-  | no local light | 28.7 against 27.6 µs | 1.70 against 1.64 ms |
-  | 8 shadowed point lights along the nave | 34.8 against 27.6 µs | 2.32 against 1.58 ms |
-
-- Tier 2: `probe_clipmap_light.spec.js`, against the light chunks themselves; `world_light_clusters.spec.js`
-  for assign with one light, which the emulator's lane-serial run serves exactly, since lane 0 loads the
-  batch before any lane reads it, and for the lookup.
-- Mutants: 27 of 29 killed. The two left: the cascade bound in assign, which the launch sized by the
-  cascade count makes redundant; the cull box's far corner, which the host spec has no light to cull
-  against, and which the device check shows holding its light.
-
-**As built (2026-10-30), shadow rays at hits.** Alex: a shadow map is made for the main view, so where rays
-reach it is wrong in most places, and the sun's cone soft shadow is made in another domain than the rays',
-so it is bound to leak light and shadow. Both are traced now, through the bricks the hit's own ray met:
-- **The sun**, in the trace pass: for each of the first `PROBE_SHADOWED_SUNS` lights that cast shadows, one
-  ray from a voxel off the hit along its normal toward a point of the light's disk, drawn as the path
-  tracer draws it (`cone_sample_direction`), from `pcg3d` of the ray's slot and packed direction and the
-  light's place among the shadowed. The sun is seen whole if the ray misses, not at all if it hits or
-  spends its steps. The probe's blend of its rays integrates the penumbra.
-- **The local lights**, in the light pass: one of the cell's point and spot lights, picked by weighted
-  reservoir sampling over their luminance at the hit, with one number stretched over the candidates as
-  `sample_discrete_wrs` does. The pick lights the hit by its irradiance over the chance of its pick, w/W,
-  so the probe's blend averages the picks to the cell's sum. Its shadow is one ray from a voxel off the
-  surface toward a point of the light's sphere (`sphere_sample_volume`, as the path tracer), stopping short
-  of it by the light's near clip or a voxel, whichever is more: the field's half-voxel expand at that end,
-  as the lift is at the other. A light that casts no shadow traces none. The pick and the point are
-  `pcg4d` of the ray's slot and direction, apart from the origin's draw.
-- What a ray cannot answer is no light, not all of it: a march that spends its steps shadows.
-- The light pass binds the brick textures in place of the shadow atlas, the same 8 storage buffers. The
-  GI no longer reads the shadow maps, and the renderer no longer hands it their atlas.
-- `brick_clipmap_soft_shadow` is deleted with its specs; nothing else called it.
-- **Cost**, paired on Sponza at 1280×720 (the sun and the playground's 8 shadowed point lights along the
-  nave; HEAD's passes and these in blocks of 4 frames, ABBA, each block's first frame dropped), p50:
-
-  | | 4090 | iGPU |
-  |---|---:|---:|
-  | trace (the sun) | 364.5 against 415.7 µs | 9.01 against 9.25 ms |
-  | light (local lights) | 43.0 against 28.7 µs | 3.38 against 2.43 ms |
-  | shade, unchanged, the clock's check | ×1.000 | ×0.995 |
-
-  A hit ray stops at its first occluder, where the cone estimate marched on into the umbra, so the sun
-  costs less. One traced ray in the light pass costs more than reading every light's map. On the iGPU the
-  two together are 0.72 ms a frame more.
-- Tier 2:
-  - `probe_clipmap_trace.spec.js`: under a slit 0.5 m wide in a roof, a sun of 0.25 rad, 128 probes'
-    rays each see the whole sun or none, and on average 0.258 of it against the 0.327 of the disk the
-    slit lets through, computed on the CPU with the walls standing out half a voxel (1,024 rays read
-    0.295: the bricks round the slit's corners). The cone estimate read 0.675 there.
-  - `probe_clipmap_light.spec.js`, over bricks built from boxes: a slab between a point light and the
-    hit shadows it, the floor under the hit and a slab past the light do not, and a light that casts no
-    shadow is lit through the slab; a slab shadows a spot; a light 3 cm under a ceiling lights 16 hits
-    from under it to 4 m out; over 256 rays at one hit, each ray is one of four lights over the chance of
-    its pick, each light picked within four sigma of its share, and the mean is their sum.
-  - Red against HEAD's passes, its light pass given a cleared atlas, as a light never drawn has: the
-    slab between the point light and the hit lit it, so did the slab over the spot, and every ray was the
-    four lights' sum.
-- Mutants: 11 of 11 killed: no division by the pick's chance; the first light always; the number not
-  stretched; the ray to the light's point, or short of it by its near clip only; from the surface, not
-  a voxel off it; a light's no-shadow flag ignored; a hit counted as light, for the sun and the local
-  light; the sun's disk centre alone; one draw for every probe.
-
-### 8.8 Update
-
-**accumulate**: one workgroup per traced probe.
-- **Blend weight**: α = 1 on the first update. After that, α = max(1/(n+1), 1 − e^(−Δt/τ)), with Δt
-  the seconds since the probe's previous update and τ = `response_time` (default 0.5 s).
-  - DDGI's 0.97 a frame at 60 fps is τ = 0.55 s.
-  - As built (2026-10-30): Δt is the frames since the update and τ = `response_frames` (default 30), §8.2.
-- **Radiance**: each texel hit this update takes the mean of its rays, blended with its history.
-  The history is read from the atlas through a sampled binding.
-- **Depth**: each depth texel takes the moments of the rays landing in it (a miss counts as the
-  depth limit, D9), blended the same way.
-- Texels without a ray keep their history; so does an unresolved ray's texel.
-- **The transient holds the probe's whole maps**, new texels and kept ones: n_r² × 8 B + n_d² × 4 B
-  per traced probe, 1.2 MiB for U = 512. `publish` cannot read the atlas it writes, and it needs
-  every texel to rebuild the skirts.
-- **SH2**: Σ over all n_r² texels (new or kept) of `radiance × sh2_basis_at × octahedral_solid_angle`.
-  The reduction is a subgroup sum plus one LDS pass, stored through `convert_to_irradiance_sh`. There
-  is one temporal state, the radiance; the SH follows it.
-- **Classification**: the back-face fraction updates the state (§8.4).
-- **Stall bound**: a blended value stops moving when α·|Δ| is under half a half-float ULP. That is
-  within 0.5 ULP/α of its target: about 0.1% at T = 16, and 1.6% when probes update every frame.
-  - Measured on the 4090, `rgba16float` render-target writes truncate toward zero. Whether storage
-    writes do is unmeasured; if they do, this bias is one-sided. §12 measures it.
-
-**publish**: one workgroup per traced probe. It rewrites the probe's whole tiles from the transient
-through storage bindings, with their one-texel skirts (`texture_octahedral_skirt_texel_uv` names each
-skirt texel's fold twin).
-
-**As built (S4e, 2026-10-28)**: four passes after shade, each a thread an element, through commands the
-update's command writes. **The one-workgroup-a-probe design above is not what was built.** The emulator
-runs a workgroup's lanes one after another and treats a barrier as a no-op, and its subgroup sum
-returns the lane's own value, so a reduction across a workgroup cannot be tested there. Every pass is
-a per-invocation function instead. Each is tier 2 whole, and no thread's loop runs past 64.
-- **accumulate** (`probe/shader_probe_clipmap_accumulate.js`): a thread a texel of the n_r² radiance
-  and n_d² depth maps. It gathers its rays through `probe_clipmap_texel_ray` and writes the probe's
-  maps (`probe_maps`, `probe_clipmap_maps_words` = 3·n_r² + n_d² words a probe): rgba as half floats,
-  then the texel's resolved and back-face rays, then the depth moments.
-  - **α is a texel's, not the probe's**: max(1/(a+1), 1 − e^(−Δt·p/τ)), where a is the texel's count of
-    the updates that reached it, kept in the radiance's alpha and capped at 255, and p the updates
-    between a texel's rays (n_r²/R below a ray a texel). Below a ray a texel, a texel's first ray is
-    then taken whole whenever it comes, which the probe's count would get wrong. Depth blends by the
-    probe's α.
-  - **The radiance is a multi-scale mean since 2026-10-29** (D11; `shader/chunk/filter/chunk_multiscale_mean.js`):
-    the texel's sample feeds Enshrouded's estimator. Its state past the mean is a slot's n_r² ×
-    16 B in `probe_estimators` (short mean, deviation, blend reduction, inconsistency, as halves
-    rounded stochastically): 4 KiB a slot at n_r = 16.
-    - The short mean blends by the α above, its variance by the same with 2τ. The mean takes at least
-      1/(a+1) until the count's cap, so a young texel is its running mean; the estimator's blend
-      reduction starts at nothing and would otherwise hold a new probe on its first ray.
-    - **The blend reduction follows by the reference's 0.1 a sample** (fixed 2026-10-29), not by the short
-      blend as first built. The catch-up takes the last sample's reduction. Once samples are a response
-      time apart, the short blend is 1 − 1/e, the reduction tracked each sample, and the long mean fell back
-      fastest from the bright ones. Measured on the emulator over samples of mean 1 and deviation 1, at
-      short blends of 0.55, 0.63, 0.78 and 0.9:
-      - the texel settled 7, 18, 28 and 39% low;
-      - at 0.1 a sample, 2, 3, 7 and 15%, with the same step response.
-
-      A texel the guide passes over has a short blend of 0.63 at 60 Hz with a period of 6 frames. At
-      15 fps, every texel's short blend is past 0.55. At the short blend of 0.18 that the table below ran
-      at, the fix moves nothing (error 13.9 → 14.0%, update to update 0.69 → 0.70%), and that table was
-      not measured again.
-    - The firefly clip, `0.1 + short + 8·deviation`, waits until 1/(a+1) is no longer the variance's
-      blend. Its 0.1 is the reference's, in radiance units; on Sponza under a sun of 7.2 a texel's
-      luma is under 0.26 at p99, so it clips only far outliers there.
-    - Measured on Sponza, the camera still, 4090 (`scratchpad/device/msme.js`, 2026-10-29):
-
-      | τ | texel change an update | band 0 change | 50% / 90% of a doubled sun | 50% / 90% of its halving |
-      |---|---|---|---|---|
-      | 0.5 s, before | 10.8% | 1.54% | 29 / 105 frames | 29 / 102 |
-      | 0.5 s | 1.0% | 0.27% | 55 / 389 | 54 / 212 |
-      | 0.25 s, before | 20.5% | 3.0% | 17 / 79 | 17 / 77 |
-      | 0.25 s | 5.0% | 1.24% | 23 / 234 | 24 / 99 |
-      | 0.125 s | 26% | 4.9% | 19 / >390 | 6 / 37 |
-
-      The screen's diffuse barely moved: a frame against the last at the same point, 4.72% → 4.66% of
-      all eight corners and 16.1% → 15.8% of the pick, still; 9.4% → 9.0% orbiting. The SH averages
-      a probe's texels, so what changes a still frame's diffuse is not the probes' radiance.
-    - Cost, the old pass beside the new in the same frames, which goes first alternating: 4090 15–16
-      against 13 µs; AMD iGPU 860–1,264 against 337–523 µs, 2.0–2.5×. A twin with the estimator's
-      arithmetic replaced by a plain blend costs what the shipped pass does: the time is the state's
-      load and store, not the estimator. Run order moves the iGPU's figures by 2×, so the split
-      between loading and packing the state is not settled.
-  - **A new probe's history is its slot's last owner's**: on its first update a texel no ray reached is
-    cleared, radiance to nothing and depth to a miss's moments (L, L²), L the depth limit (D9).
-  - Depth samples, in spacings: a miss L, a back face 0.2·t, a hit t, each held to L. A depth texel
-    gathers R/n_d² rays, so the GI refuses R > 64·n_d².
-  - **Since ray guiding (2026-10-29, §8.6)**: on a guided update a texel's rays are its run in the guide.
-    Its mean needs no weight for the guide's choice, since its rays spread evenly over it.
-    - p is one over the share of updates that reach the texel, averaged over the uniform period:
-      (min(R/n_r², 1) + (P − 1)·min(R·pdf, 1))/P. A texel the guide passes over then blends what the
-      uniform updates bring as fully as its rarity asks, and the response stays τ.
-    - A guided depth texel is the mean of its radiance texels' own means, taken only when every one of
-      them took rays. A plain mean would lean to the brighter ones' depths, and so would a mean over
-      only the lit ones. Its period counts a uniform update as reaching it, and a guided one as often
-      as its least reached radiance texel.
-    - Classification takes only uniform rays: a guided update keeps the kind and the back-face share,
-      since guided rays shun back faces (§8.4).
-- **the projection** (`probe/shader_probe_clipmap_project.js`): a thread a row of a probe's radiance
-  map sums its texels as `convert_to_irradiance_sh(L, ω)·dω/(2π)` and its rays' counts; then a thread a
-  probe sums its rows into the record's SH, its back-face share, its time, and its state: dead past a
-  quarter, alive at or below, its kind kept by an update with no ray resolved, its update counted.
-- **publish** (`probe/shader_probe_clipmap_publish.js`): a thread a texel of the probe's two tiles,
-  skirts included, each skirt texel its fold twin's (`texture_octahedral_wrap_texel_coordinates`), the
-  atlases stored into and nothing else.
-- On the device, Sponza: after the caches bake and 60–90 still frames, 742–769 live probes, every
-  one updated (about 300 updates on the 4090, 112 on the iGPU). 13 are dead, the back-face share's
-  p50 is 0.8% and its p90 3.5–3.9%, and no SH is not finite. Irradiance resolved facing the six
-  axes, E/π: p50 0.0003–0.0004, p90 0.045–0.046, max 0.38, the same on both GPUs. Most of their rays
-  hit surfaces in the sun's shadow (87%, §8.7), and the sun is the only light until S5.
-
-  | p50 | AMD iGPU | RTX 4090 |
-  |---|---:|---:|
-  | accumulate | 163 µs | 8.2 µs |
-  | the projection's rows | 295 µs | 7.2 µs |
-  | the probes' projection | 15.8 µs | 12.3 µs |
-  | publish | 189 µs | 6.1 µs |
-
-  The rows are most of it on the iGPU. They work out each texel's solid angle and SH afresh, for
-  every probe.
-- Tier 2: `probe_clipmap_accumulate.spec.js` (a first update whole, α's two terms and the count's cap,
-  the time between a texel's rays, unresolved rays and back faces, a new probe's clearing, depth by
-  kind in spacings, a finer depth map, U), `probe_clipmap_project.spec.js` (a constant radiance and a
-  lit hemisphere against the engine's own resolve, the dead threshold, a blind update, U),
-  `probe_clipmap_publish.spec.js` (both tiles' skirts against the fold, nothing else written).
-- Mutants: 33 of 33 killed, five of them by tests added for them: a new probe's depth cleared, each
-  texel's solid angle against one integrated from the decode, and the three launches the update's
-  command adds.
-
-**Measured (S4g, 2026-10-28): the stores round toward zero, so accumulate rounds them itself.**
-- Both GPUs gave the half toward zero for all 131,072 values tried, on each of three paths:
-  `pack2x16float`, `textureStore` into `rgba16float`, and a render target's write. The stall above is
-  therefore a whole ULP/α, and one-sided: below the target.
-- α follows the frame rate, since the GI's clock is the caller's (`performance.now()` in `Renderer`).
-- On §12's closed room glowing L, after 900 frames to settle, E/πL was:
-
-  | | 60 Hz | 240 Hz |
-  |---|---:|---:|
-  | rounded by the store, toward zero | 0.985 | 0.941 |
-  | rounded to nearest before the store | 0.992 | 0.970 |
-  | rounded stochastically (built) | 0.999 | 0.999 |
-
-  The first row is the 1.5% and 5.9% that ULP/α predicts.
-- **Accumulate now rounds every stored component stochastically onto a half itself**, for radiance and
-  for depth: `shader/chunk/math/chunk_f16_round_stochastic.js`, with noise from `pcg3d(slot, texel,
-  updates)`.
-  - The value it hands the store is a half already, so the device's own rounding never applies.
-  - The blend moves in expectation however small its step.
-- The emulator's `pack2x16float` rounds to nearest even, so tier 2 sees half the devices' stall, and on
-  both sides. `probe_clipmap_accumulate.spec.js` pins convergence from either side at α = 1/64; it was
-  red before the change.
-
-**As built (re-sampling, 2026-10-30): Enshrouded's probe reprojection, a step of its own, off by default.**
-Alex asked for it as a prototype he can switch for testing, chasing convergence, blur accepted.
-- **The step**: `probe/shader_probe_clipmap_resample.js`, recorded before accumulate only when
-  `ProbeClipmapSettings.resampling` is on. A thread a radiance texel of each listed probe B, through the texels'
-  command. It traces nothing: it reads the atlases as the last publish left them.
-  - 4 distinct of B's 26 neighbours in its cascade's 3×3×3 (`PROBE_RESAMPLE_NEIGHBOURS`), a start and a stride
-    coprime with 26 from a hash of the slot, the texel and the update count. Over its updates a texel meets
-    all 26.
-  - The point B sees: along the texel's centre at B's mean depth there. A neighbour (ALIVE, its record's cell
-    the point asked for, since the storage wraps) is read toward it, weighed by how well its depth confirms a
-    surface there: s²/(s² + (d − μ)²), s² its depth's variance plus the receiver bias squared.
-  - Two-sided because a neighbour that sees past the point is looking past a point in mid-air, which B's
-    texel puts there where it mixes a near depth with a far one.
-  - Nothing depth cannot confirm: a texel whose depth is at the limit takes nothing, nor is a point at the
-    limit or past it from the neighbour read.
-- **Accumulate** pools a texel's rays with its re-samples, each a ray's worth at a visibility of one, through
-  the `PROBE_CLIPMAP_RESAMPLING` switch (`probe/chunk_probe_clipmap_resampled.js`): off, its WGSL is what it
-  was. Only a texel some ray reached takes them.
-- **Measured on Sponza, both GPUs (`scratchpad/device/resample.js`, 2026-10-30)**: settle at one end, cut the
-  camera to the other, where the finest probes are new. The eight-corner diffuse in 8×8 blocks each frame,
-  against a reference of four times the rays without re-sampling. 3 runs an arm; mean error, [range]:
-
-  | frames after the cut | 4090 off | 4090 on | iGPU off | iGPU on |
-  |---|---|---|---|---|
-  | 1–10 | 0.140 [0.106–0.181] | 0.158 [0.139–0.174] | 0.119 [0.100–0.129] | 0.132 [0.113–0.158] |
-  | 11–30 | 0.090 | 0.105 | 0.089 | 0.101 |
-  | 31–120 | 0.055 | 0.073 | 0.058 | 0.067 |
-  | 121–480 | 0.038 | 0.080 | 0.039 | 0.069 |
-  | 481–1200 | 0.037 | 0.094 | 0.030 | 0.081 |
-  | first frame under 5% | 53–108 | never | 71–101 | never |
-
-  - Worse in every window on both GPUs, and growing: the re-samples are the neighbours' histories, which hold
-    the re-samples they took, so the field settles on a fixed point of its own and drifts toward it. Against its
-    own settled frame, re-sampling converges no faster either (4 and 3 runs: 4090 31–120 frames 0.087 against
-    0.060; 481–1200, 0.022 against 0.026).
-  - Settled: frame-to-frame change 0.0064 against 0.0069; the mean +4.7% (4090) and +3.3% (iGPU) over the
-    reference, against +2.0% and +0.4% off; |diff| 9.3% and 7.8% against 3.6% and 2.3%.
-  - Taking what depth cannot confirm made it worse: one-sided Chebyshev, with B's far texels read along their
-    own direction and points past the limit at the limit alone, came out +11.5% on the 4090; two-sided, +9.8%;
-    without the points past the limit, +6.5%; without either, +3.2% in its first run.
-  - The sun doubled once settled: 90% of the step in 182–288 frames on the 4090 against 190–260; on the iGPU
-    280–335 against 192–261.
-  - Cost, the arms alternating frame by frame in one process: the pass 18.4 µs on the 4090 (the update's trace
-    ~0.9 ms), 1.03 ms on the AMD iGPU (its trace 4.9 ms); accumulate unchanged on both.
-- Tier 2: `probe_clipmap_resample.spec.js` (the picks, every neighbour met, the weight both ways and with the
-  neighbour's spread, the read direction, nothing unconfirmed, the wrap, the kinds, a texel no ray reached),
-  `probe_clipmap_accumulate.spec.js` (the pool, the switch off, a texel no ray reached); 12 of 12 mutants of the
-  pass killed, 3 of 3 of the pool. Tier 3: `GPUProbeClipmap.spec.js` (recorded only when on, before accumulate,
-  through the texels' command).
-
-**As built (re-sampling confidence, 2026-10-30): a re-sample weighs what it reads.** Alex asked for the
-neighbour's estimator spread, its sample count and its age.
-- **Confidence**: σ²_B / (σ²_B + σ²_A / n_A). σ²_A is the deviation of the neighbour's texel the point falls in
-  (`probe_estimators`, luma), n_A that texel's count (the radiance alpha), so σ²_A / n_A is the variance of its
-  mean; σ²_B is the variance of one of B's own rays, from B's texel. Both absolute, floored at 1e-5, so a dark
-  neighbour is not doubted for being dark. A neighbour no noisier than one of B's rays counts as one; one whose
-  mean is as noisy as a ray, as half.
-- **Freshness**: e^(−age / `response_frames`), age the frames since the neighbour's `traced_frame`.
-- Still at most a ray's worth: visibility × confidence × freshness.
-- **No solid angle.** Rays are jittered over their texel's octahedral square and averaged unweighted; the
-  solid angle enters at the projection, per texel. A re-sample is one tap along B's texel centre, and the
-  neighbour's bilinear tap averages its own texel's footprint, which is not B's. Neither is corrected.
-- **Measured** (`scratchpad/device/ab/`, 2026-10-30): plain is the pass of the block above, confidence this
-  one, against references of four times the rays without re-sampling taken that day. 4090 3 runs an arm, iGPU 2;
-  mean [range]. Stability settles 1,500 frames, TAA off: |Δ| frame to frame over the frame's mean, the same pixel
-  still, the reprojected point on an orbit; probe texels |Δ| between two reads of a probe updated between them.
-
-  | | 4090 off | plain | confidence | iGPU off | plain | confidence |
-  |---|---|---|---|---|---|---|
-  | still, eight corners | 0.0506 | 0.0476 | 0.0481 | 0.0506 | 0.0474 | 0.0482 |
-  | still, pick | 0.144 | 0.130 | 0.131 | 0.144 | 0.131 | 0.132 |
-  | orbit, eight corners | 0.111 | 0.076 | 0.090 [0.084–0.096] | 0.110 | 0.075 | 0.083 |
-  | orbit, pick | 0.237 | 0.152 | 0.201 [0.180–0.215] | 0.238 | 0.151 | 0.176 |
-  | probe texels an update | 0.019 | 0.023 | 0.022 | 0.020 | 0.033 | 0.027 |
-  | vs reference, 31–120 | 0.082 | 0.073 | 0.098 | 0.056 | 0.070 | 0.078 |
-  | vs reference, 121–480 | 0.046 | 0.064 | 0.066 | 0.032 | 0.079 | 0.061 |
-  | vs reference, 481–1200 | 0.030 | 0.069 | 0.053 | 0.029 | 0.084 | 0.055 |
-  | first frame under 5% | 197–282 | never | 455–888 | 32–117 | never | 465–494 |
-  | vs own settled, 31–120 | 0.070 | 0.071 | 0.087 | 0.055 | 0.065 | 0.073 |
-  | vs own settled, 121–480 | 0.035 | 0.036 | 0.049 | 0.031 | 0.028 | 0.046 |
-  | settled mean vs reference | −0.9% | +2.2% | −0.7% | +0.6% | +3.2% | +0.5% |
-  | sun ×2, 90% (frames) | 234–255 | 245–287 | 237–263 | 220–229 | 224–251 | 216–218 |
-  | the pass (µs) | | 18.4 | 34.1 | | 905 | 1,484 |
-
-  - Confidence takes the bias out: the settled mean is off's on both GPUs. The per-pixel error stays above
-    off's, so what is left is spatial, the blur.
-  - Re-sampling is quieter in every arm, most on an orbit: plain −31% at the eight corners, −36% at the pick;
-    confidence keeps about half of that. Still, −5% to −10% in both.
-  - It converges no faster in any arm, toward the reference or toward its own settled frame; confidence is the
-    slowest of the three toward its own. A probe's texels move more an update with re-sampling.
-  - Confidence doubles the pass.
-- Tier 2 adds to `probe_clipmap_resample.spec.js`: the confidence (a count of 4 and of 1, a dark neighbour,
-  the floor, the floor against a deviation above it), the freshness at two ages, the spread read from the
-  neighbour's texel the point falls in. Every mutant of the terms killed. Tier 3: the pass's frame and
-  response immediates, the estimators bound.
-
-## 9. Sampling
-
-### 9.1 The pick: `probe_clipmap_pick(position, normal, view_direction, ξ) -> pick`
-
-1. `clipmap_select_finest` gives cascade c and the blend weight b toward c + 1.
-2. **Biased point**: `p_b = p + (0.8·n + 0.2·v)·0.1·s_c`.
-   - The mix is LPV's `mix(normal, view_direction, 0.2)`.
-   - The length is a chosen value between the precedents: RTXGI's defaults are 0.1 m along each of n
-     and v at a recommended 2–3 m spacing, and LPV's is 0.05 of its probe span. It is a tuned order of
-     magnitude in both, not a derivation, and the leak cases of §12 check it.
-3. **Weigh the eight corners of `floor(p_b/s_c)`, visibility only.** Per corner:
-   - the indirection entry, then the state word: missing, NEW or DEAD probes weigh 0;
-   - one bilinear depth tap toward p_b at distance `|p_b − probe|/s_c`;
-   - weight = trilinear × `probe_visibility_weight`: the wrap back face, Chebyshev from the tap, and
-     the crush.
-   - The wrap is `((n·ω+1)/2)²`, without DDGI's + 0.2. With it, a probe behind Sponza's thin outer
-     wall, which Chebyshev passes at 0.94–0.97 through the grazing texels of an 8² depth map, held ≈0.25,
-     above the crush: 11% of the wall's pick, 32% in cascade 1, where the wall sits 0.15 of a spacing past
-     the lattice plane, a dark lattice of blotches. Without it, 0.1% and 0.6%.
-
-   No SH and no radiance is read here.
-4. **Pick two**, the extracted `pick2_wrs_mat2x4`, which is Brick4's selection:
-   - one draw of `sample_discrete_wrs_mat2x4` over the eight weights with ξ₀;
-   - the drawn weight is zeroed, and a second draw is made with ξ₁;
-   - blend t = w₂ / (w₁ + w₂).
-   - A single non-zero weight is drawn twice, at t = 0.
-5. **In the blend skirt**, steps 3–4 run for c + 1 as well, and the two picks are lerped by b: four
-   probes there, and no noise across the cascade boundary.
-6. **Σ w = 0** tries the next cascade. With none left, the fallback is the caller's:
-   - pixel consumers take `get_ibl_irradiance(n)`;
-   - hit shading takes zero (§8.7).
-   A pixel's probes are wanted, admitted, traced and published in the same frame before shading reads
-   them. A pixel reaches the fallback only when NEW probes overflow U (a camera cut), or when it has
-   no depth of its own (a transparent surface in open air).
-
-Per pixel and cascade the visibility pass makes 8 indirection loads, 8 state words and 8 bilinear
-depth taps. Then the pick reads two probes: two SH records and, for specular, two radiance taps. (a)
-read eight 64 B records and resolved eight SH.
-
-**As built (S4f, 2026-10-28)**, `probe/chunk_probe_clipmap_pick.js`:
-- **The cage is want's.** `probe_clipmap_cage` and `probe_clipmap_biased` live in
-  `probe/chunk_probe_clipmap_cage.js`, and want calls them too, so a pixel reads the cage it wanted.
-- **A corner's weight**, `probe_clipmap_corner_weight`:
-  - No slot, or a state that is not ALIVE, weighs 0.
-  - The probe sits at its lattice point plus the relocation offset in its state's second word.
-  - The tap is toward the biased point, at its distance in the cascade's spacings, which is how
-    publish writes depth (§8.8). The wrap back-face term is taken from the point itself.
-- **The weight is LPV's, extracted**: `probe_visibility_weight` and `probe_visibility_chebyshev` in
-  `shader/chunk/light/probe/chunk_probe_visibility_weight.js`. `chunk_lpv_mask_weights_by_visibility`
-  and `chunk_lpv_get_visibility_mask` call it, unchanged.
-- **The pick is Brick4's, extracted**: `pick2_wrs_mat2x4` in
-  `shader/chunk/random/reservoir/chunk_pick2_wrs_mat2x4.js`, which `chunk_brick4_probe_meta_pick2`
-  now calls.
-  - It reads and clears the drawn weights through masks, because indexing the matrix by a value puts
-    it in local memory. That cost 3% of the diffuse on the iGPU: 7.29 → 7.06 ms, A/B in one frame
-    with the order alternating.
-  - Extracting it found a defect in the draw it is built on: `sample_discrete_wrs_mat2x4` and
-    `_vec4` drew NaN after leading zero weights, 0/0 in the first step. It is fixed and pinned in
-    `5a3c8e968`.
-- **Reads** per cascade: 8 indirection loads, 8 state words and 8 depth taps. The pair's two slots
-  are loaded again by index rather than kept, so no array is indexed by a value.
-- **A depth tile's place takes no integer division** since S4g: `index_to_grid2d_reciprocal`, through
-  the reciprocal the sampling uniform carries. RDNA2 emulates integer division. The iGPU's diffuse went
-  from 7.08 to 6.65 ms, paired, with the image the same to the bit on both GPUs.
-- **The clipmap's shape is a uniform**, `PROBE_SAMPLING_STRUCT`: C_p, N_p, n_d, the depth atlas's
-  tiles a row and its texel size. `GPUProbeClipmap.write_sampling_bindings` puts it and the six
-  resources into a reader's bindings.
-- **Tier 2**, `probe_clipmap_pick.spec.js`:
-  - picks as often as the weights, and dead, new and missing corners passed over;
-  - the depth read toward the point, at its direction's own texel, in the cascade's spacings;
-  - a relocated probe weighed from where it moved;
-  - the fallback cascade, the skirt's share, nothing found;
-  - two weighing corners blended in every draw;
-  - the SH mixed by the weights.
-
-  `chunk_probe_visibility_weight.spec.js` and `chunk_pick2_wrs_mat2x4.spec.js` cover the extracted
-  pieces, and LPV's and Brick4's specs pass unchanged.
-
-### 9.2 Diffuse: `probe_clipmap_sample_irradiance(position, normal, view_direction, ξ) -> E`
-
-- The two picked records' Metro L1 structs are mixed by t, then resolved once with
-  `resolve_irradiance_sh_to_diffuse(SH, n)`. Brick4 likewise mixes its SH before evaluating.
-- The resolve returns E/π by its convention. The pass multiplies by π, because the resolve pass takes
-  irradiance E.
-
-**As built (S4f)**: there is no `probe_clipmap_sample_irradiance`. `probe_clipmap_sample_sh` returns the
-mixed Metro L1 struct and whether anything was found, and the caller resolves at the normal it
-chooses. The deferred pass uses two normals where this section has one n:
-- it picks with the surface's own normal, as want chose its cage;
-- it resolves at the bent normal, as IBL's pass does.
-
-### 9.3 Specular: `probe_clipmap_sample_radiance(position, normal, view_direction, roughness, ξ) -> L`
-
-The two probes of the same pick are used. Per Brick4's fused pass, the pair's blend is re-weighted for
-this lobe: the wrap term is taken against the sample vector instead of the normal, and the pick itself
-is shared.
-- **Sample vector**: `s = normalize(mix(r, n, α))`, with r the reflection of the view direction and
-  α = roughness². This is LPV's and Brick4's.
-- **Radiance**: one hardware bilinear tap per probe along s, after a one-step parallax. The reflected
-  ray is intersected with a sphere around the probe whose radius is the probe's mean depth along s.
-  That is Lumen's sphere parallax, with the radius taken from the probe's own depth instead of a
-  constant. The two taps are blended by the re-weighted t.
-- **GGX-convolved SH2**: `resolve_irradiance_sh_to_specular(SH, s, α)`, NEW in `l1i/`, on the mixed SH.
-  It is the diffuse resolve with the GGX zonal factor `g₁(α)` from `sh2_approximate_GGX_zh` in place
-  of the clamped cosine's 2/3:
-  - `Y = max(0, 2π·(0.28209·Y_w + g₁(α)·0.48860·(Y_xyz · s)))`;
-  - chroma rescaled by the ratio of directional to mean luma, as the diffuse resolve rescales it;
-  - at g₁ = 2/3 it is exactly the diffuse resolve, and constant radiance L returns L for every α.
-    Both are spec invariants.
-- **Blend**: `L = mix(radiance, sh_ggx, roughness_to_mip_ratio(roughness))`, `chunk_lpv_sample_light`'s
-  blend. It is SH alone from roughness 0.7.
-- Output: radiance before Fresnel, per the resolve's contract.
-
-**Why no prefiltered levels** (Alex's point). An atlas's hardware mips mix neighbouring tiles. Levels
-per probe would be manual strips, with their own skirts and their own downsample pass, written one mip
-per storage binding. Two SH bands hold the rough end of the lobe well, and a single tap holds the
-smooth end.
-
-**As built (S6a, S6b, 2026-10-28)**:
-- **The GGX resolve**, `resolve_irradiance_sh_to_specular` in `shader/chunk/spherical_harmonics/l1i/`
-  (S6a). Its spec holds both invariants above. 7 of 7 mutants were killed.
-- **The sample**, `probe_clipmap_sample_radiance` in `probe/chunk_probe_clipmap_sample_radiance.js` (S6b).
-  It returns the radiance and whether anything was found, as the SH sample does.
-  - *The pick* is the diffuse's, `probe_clipmap_pick`.
-  - *The re-weight* takes each picked probe's whole weight again with the lobe in place of the normal,
-    at the visibility it was picked at. That visibility is recomputed, one depth tap toward the biased
-    point. The crush below 0.2 keeps a ratio of the wrap terms alone from standing in for it.
-  - *The parallax* takes the far root of the reflected ray against the sphere, so a point inside the
-    sphere always meets it. Where the ray misses the sphere, the tap is along the lobe itself.
-  - *The radiance tap* reads the radiance atlas through the depth's sampler, bilinear and clamped. Its
-    tiles are placed as the depth's are, and the sampling uniform now carries the radiance atlas's shape
-    as well (`radiance_resolution`, its tiles a row, its texel and the row's reciprocal).
-  - *The blend* is `roughness_to_mip_ratio`, between the renormalised taps and the SH. The SH is mixed
-    by the same shares and resolved for the lobe.
-  - *Reads a picked probe*: its record, its state word, two depth taps (visibility and parallax) and one
-    radiance tap.
-  - *The probes' sampling group* takes the radiance atlas, so every reader binds it in every mode. The
-    GI's placeholders gained a texel of radiance.
-  - *The deferred diffuse pass* listed seven of those declarations by hand. A frame graph pass must declare every
-    input it is given, so it threw under SSR on once the mode had probes. It declares the group whole since the
-    fix that followed S6c1, pinned by its spec running it in a frame graph on the GI's bindings.
-  - *Tier 2*: `probe/probe_clipmap_sample_radiance.spec.js` uses tiles whose interior texels hold their
-    own uv, so a tap shows what it read. It covers the parallax tap at a depth that varies with
-    direction, the GGX-resolved SH at the rough end, the mip ratio's blend between, the re-weighted
-    shares with a relocated probe, and nothing found. 16 of 16 mutants were killed.
-
-### 9.4 Noise and its resolve
-
-- Image passes take ξ from STBN at (pixel, frame), `chunk_stbn_sample_vec2`, as Brick4 does.
-- Forward passes and the irradiance clipmap take the extracted `jitter_from_vectors(position, normal)`,
-  a position-and-normal hash with the frame index.
-- The pick's variance follows how much the eight probes disagree, which is largest across light
-  boundaries. TAA resolves it, as it resolves Brick4's specular.
-- §12 measures the frame-to-frame change on an orbit and a dolly against the eight-probe evaluation,
-  as a one-off.
-
-### 9.5 The five switch alternatives
-
-| Choice | This mode |
-|---|---|
-| `forward_sample_indirect(p, v, n, roughness, &radiance, &irradiance)` | one pick (hash noise); irradiance from §9.2, radiance from §9.3 (environment until S6) |
-| `water_gi_irradiance(p, n)` / `water_gi_specular(p, n, v, roughness)` | §9.2 with v = n, since the irradiance call has no view direction / §9.3 (environment until S6); hash noise |
-| `ssr_sample_radiance(p, n, v, roughness, coord)` | §9.3 with STBN at coord (environment until S6) |
-| `ssr_add_hit_irradiance(&result, confidence, p, hit_vs, hit_n, coord)` | albedo·E/π at the hit when confidence > 0.05, E the deferred pass's own at the hit's texel (as built; LPV's body with §9.2 measured 41% of the resolve) |
-| `irradiance_clipmap_gi_sample(p) -> array<vec3f,4>` | `probe_clipmap_sample_sh(p)` × `INDIRECT_LIGHT_INTENSITY`: the pick without the back-face term (there is no normal), returned as RGB SH2 |
-
-Each alternative declares `PROBE_CLIPMAP_RESOURCES` with `requireResource`:
-- the levels uniform;
-- the indirection texture;
-- the states and records buffers;
-- the depth atlas;
-- the radiance atlas (from S6);
-- a linear sampler.
-
-Union bindings were measured free in stage 2 of the switch proposal (p50 1.000).
-
-**As built (S5c, 2026-10-28)**:
-- **The probes are bound in every mode.** A reader binds every mode's resources, and the GI is released
-  out of its mode. So `GPUProbeClipmapGI.write_sampling_bindings` hands out its probes' bindings once it
-  has probes. Before that, or out of the mode, it hands out a clipmap of no cascade: the sampling
-  uniform counts none, so the pick selects no cascade and reads nothing past the levels. These are six
-  objects of a few bytes, made on the first ask and destroyed with the GI. The seven declarations are
-  `PROBE_CLIPMAP_SAMPLING_GROUP`, in `probe/chunk_probe_clipmap_pick.js`; the sampler comes from its
-  declaration's descriptor.
-- **SSR's hit**, `chunk_ssr_add_hit_irradiance_probe_clipmap`: albedo × the deferred pass's indirect
-  diffuse at the hit's texel / π, where the hit's confidence passes 0.05. That output is E with AO in,
-  so a reflection shows the indirect diffuse of the surface it hits, with its AO, its pick and its IBL
-  fallback.
-  - The renderer records the diffuse pass before SSR, which it reads nothing of, and hands it to SSR as
-    `input_indirect_diffuse` under this mode. The resolve's `tIndirectDiffuse` is black for the others.
-  - Tier 2: `chunk_ssr_add_hit_irradiance.spec.js` reads the hit's texel of both inputs, and nothing at
-    confidence 0.05. `SSR.spec.js` binds the diffuse under this mode alone. 7 of 7 mutants were killed.
-- **Why not the pick at the hit** (§9.5's first form, LPV's body; built in `9208dd7cf`, replaced by Alex's
-  call the same day). Measured on Sponza at 1280×720, sun only, SSR on, the probes settled. The arms
-  alternated frame by frame over one set of probes, and each frame's resolve was also drawn by every
-  arm on the same inputs.
-  - 0.81% of the pixels have a confident hit.
-  - The pick's cost is its work at scattered hits, where a wave pays the whole pick for a few lanes. Its
-    code present but never run is about a sixth of it.
-
-  | SSR resolve, p50 | RTX 4090 | AMD iGPU |
-  |---|---:|---:|
-  | no bounce (IBL's variant) | 39.9 µs | 2.06 ms |
-  | the pick's code present, never run | 42.0 µs | 2.19 ms |
-  | the pick at the hit | 54.3 µs | 2.91 ms |
-  | **as built**: the deferred pass's texel, against no bounce in the same run | × 1.019 | × 1.034 (2.03 → 2.10 ms) |
-
-  The SSR trace, which no arm touches, reads 1.00 between arms on both GPUs.
-  - The pick lit 0.64% of the pixels and added 2.4% of the reflections' light.
-  - The texel lights 0.70%: where no probe weighs anything, the diffuse pass's IBL fallback lights the
-    hit too. It adds 1.9% of the reflections' light, with the hit's AO now applied.
-  - Neither darkens a pixel, and both leave the metadata the same to the bit.
-- **Forward**, `rasterize/forward/chunk_forward_sample_indirect_probe_clipmap.js`: one pick by the
-  shading normal and the view, jittered by `jitter_from_vectors(p, n)`. That hash is extracted from
-  Brick4's forward sampling into `shader/chunk/random/`.
-  - E = π × the SH resolved at the normal, or the environment's where nothing is found.
-  - The specular is the environment's until S6.
-  - The AVBOIT draw and MBOIT's resolve add the probe declarations to their group 2, which both stages
-    see, and set those entries to the fragment stage alone. The probes' two storage buffers would
-    otherwise take the vertex stage to 10, the floor.
-- **Water**, `chunk_water_gi_probe_clipmap` in `water/chunk_water_gi.js`: the forward pick with v = n,
-  since the irradiance call has no view, and the environment's specular until S6. The optics'
-  brick4/view group takes the probes, and `water_pipeline` keeps them fragment-only.
-- **Bindings**: the owners write `write_sampling_bindings` into their hand-built bindings. The renderer
-  hands the GI to the transparency orchestrators, and AVBOIT's hands it on to the water's side channel
-  (`avboit_prepare`'s `probes`).
-  - Tier 2 is `chunk_forward_sample_indirect_probe_clipmap.spec.js` and `water/chunk_water_gi.spec.js`
-    against the pick and the environment map, the fragment-only test in
-    `indirect_lighting_consumers.spec.js`, and the AVBOIT orchestrator's water optics in every mode.
-  - 18 of 19 mutants were killed. MBOIT's resolve without the probes survives because no spec draws
-    MBOIT; the device check below draws it.
-- **Measured** on Sponza at 1280×720, sun only, with five half-transparent boxes down the nave. Each
-  pass alternated frame by frame with IBL's variant over one set of probes.
-
-  | p50, IBL → the probes | RTX 4090 | AMD iGPU |
-  |---|---:|---:|
-  | AVBOIT draw | 13.3 → 28.7 µs | 132 → 312 µs |
-  | MBOIT's resolve | 11.3 → 26.6 µs | 129 → 317 µs |
-
-  - Per transparent fragment, that is about what the deferred pick costs a pixel.
-  - Averaged over 24 frames, 2.8% of the pixels, the boxes, move by 14 of 255 between the arms. The noise
-    floor, an arm against itself, is 0.1–0.25%. The boxes are lit brighter by the probes than by the
-    sky (luma 97 against 88), the same on both GPUs and in both techniques.
-  - The water optics compile under every mode on both GPUs.
-- **The irradiance clipmap**, `chunk_irradiance_clipmap_gi_sample_probe_clipmap`: the pick at the voxel,
-  with no normal and no view, jittered by `jitter_from_vectors(p, 0)` and the view's frame. Where nothing
-  is found, the environment SH.
-  - The probes' Metro L1 is handed over as the radiance SH2 that `volumetrics_irradiance_sh_add_radiance`
-    turns back into it: [DC, y, z, x] = [YCoCg→RGB(2π·(Y.w, 0.28209·CoCg)), 2π·Y.y, 2π·Y.z, 2π·Y.x], the
-    band-1 terms grey.
-  - The build binds the probes as a group of its own, which brings it to 9 of the floor's 10 storage
-    buffers, and binds the view.
-  - The cascades are a cache, so a voxel's pick holds until its cascade is rebuilt: cascade 0 and the
-    ruler's each frame, the others as their windows move.
-  - Tier 2: `chunk_irradiance_clipmap_gi_sample.spec.js` accumulates the handed-over SH2 as the build
-    does and gets the pick back, with the frame's noise and the environment where nothing is found.
-    `graph_build_froxel_gi.spec.js` finds the GI's probes and the view bound to the build. 11 of 11
-    mutants were killed.
-  - **Measured** on Sponza at 1280×720, sun only. A sink kept the volume, which only lit particles read.
-    The build's p50 went from 7.2 to 15.4 µs on the 4090 and from 127 to 430 µs on the iGPU, for two
-    cascades of 34³ voxels a frame.
-  - The volume's band 0 moves by 0.0016 between the arms, 6× the probe arm's own change from one run to
-    the next (0.00026). The IBL arm is steady to the bit. The sun is most of the volume here, so its mean
-    moves by 0.5%.
-
-**As built (S6c2, 2026-10-28)**: SSR's fallback, `chunk_ssr_sample_radiance_probe_clipmap`, is §9.3 at the pixel:
-the probes' specular picked by its normal and view, with STBN at the pixel and the resolve's frame index, as
-Brick4's is. Where no probe weighs anything, it is the environment's.
-- The resolve binds the probes' sampling group again, through SSR's `probes`, in every mode.
-- The radiance chunk now declares what it reads itself. `switched_shaders_declare_bindings.spec.js` audits it
-  since SSR's resolve links it.
-- Tier 2: `chunk_ssr_sample_radiance.spec.js` runs the fallback against `probe_clipmap_sample_radiance` with the
-  STBN texel at the pixel and frame, and against the environment where nothing is found. `SSR.spec.js` binds the
-  probes in every mode; `indirect_lighting_consumers.spec.js` finds the probes' specular in this mode's variant
-  alone. 7 of 7 mutants were killed.
-- **Measured** on Sponza at 1280×720, sun only, SSR on, the probes settled. One of three arms a frame, in turn,
-  over one set of probes; 131 frames an arm, p50:
-
-  | arm | deferred pass | SSR resolve | together, RTX 4090 | together, AMD iGPU |
-  |---|---|---|---:|---:|
-  | **as built**: the fallback picks again | 87 µs / 6.64 ms | 140 µs / 10.39 ms | 227 µs | 17.03 ms |
-  | S5c: IBL's fallback | 87 µs / 6.64 ms | 61 µs / 2.09 ms | 148 µs | 8.74 ms |
-  | the deferred pass's one pick writes the specular too, and the fallback reads its texel | 114 µs / 9.02 ms | 61 µs / 1.93 ms | 175 µs | 10.95 ms |
-
-  - The SSR trace, which no arm touches, reads 0.98–1.01 between arms.
-  - The fallback runs at every foreground pixel, so its pick is the whole pick again: 4.96× the resolve on the
-    iGPU. The texel arm's light is the as-built arm's in the mean; 1% of the pixels differ, by the pick's noise.
-  - The probes' fallback lifts the reflections' mean luma 28× over the harness's dim sky. No pixel goes darker.
-- **Alex kept the pick** (2026-10-28), as this section designs it, with these measurements before him.
-
-**As built (S6d, 2026-10-28)**: the forward passes' and the water's specular from the probes, §9.3.
-- **Forward**, `chunk_forward_sample_indirect_probe_clipmap`: one pick for both lobes, as the fused deferred pass
-  takes it (S6c1). The irradiance is the pick's SH resolved at the normal, as before. The specular is
-  `probe_clipmap_radiance_of` the same pick, at the fragment's roughness. Where no probe weighs anything, both are
-  the environment's.
-- **Water**, `water_gi_specular`: `probe_clipmap_sample_radiance` by the surface's normal and view, its noise the
-  irradiance's hash, or the environment's where nothing is found. The optics ask for the irradiance at other points
-  and by other normals (the in-scatter's column, a receiver's downwelling light), so each call picks for itself.
-- **Bindings** are unchanged. Each of the three passes has declared the probes' group whole since S6b, the radiance
-  atlas with it, fragment-only.
-- **Tier 2**: `chunk_forward_sample_indirect_probe_clipmap.spec.js` and `water/chunk_water_gi.spec.js` give each
-  probe a colour of its own over its radiance tile. They check the specular against `probe_clipmap_sample_radiance`
-  with the call's own noise, view and roughness, and against the environment where nothing is found.
-  `indirect_lighting_consumers.spec.js` finds the probes' radiance in this mode's forward and water variants alone.
-  16 of 16 mutants were killed.
-- **Measured** on Sponza at 1280×720, sun only, with S5c's five half-transparent boxes down the nave and S5c's
-  harness. Each pass alternated frame by frame with IBL's variant over one set of probes. IBL's arm reads within
-  1 µs between S5c's run and this one.
-
-  | p50, IBL → the probes | S5c: the irradiance | S6d: both lobes |
-  |---|---:|---:|
-  | AVBOIT draw, RTX 4090 | 13.3 → 28.7 µs | 12.3 → 31.7 µs |
-  | MBOIT's resolve, RTX 4090 | 11.3 → 26.6 µs | 11.3 → 30.7 µs |
-  | AVBOIT draw, AMD iGPU | 132 → 312 µs | 131 → 379 µs |
-  | MBOIT's resolve, AMD iGPU | 129 → 317 µs | 130 → 383 µs |
-
-  - The specular adds 26–27% (4090) and 35–38% (iGPU) to what the probes' light costs each pass over IBL's.
-  - Averaged over 24 frames, 3.6–3.8% of the pixels move by more than 4 of 255 between the arms, against 2.8–3.0% in
-    S5c: the boxes' reflections now take the probes' light too. An arm against itself moves 0.2–0.7% of them
-    (S5c 0.1–0.25%), since the specular carries the pick's noise; TAA is off in this harness.
-  - The water optics compile under every mode on both GPUs.
-
-### 9.6 Deferred
-
-A new case in `#graph_indirect_lighting`, shaped like Brick4's:
-- **SSR off**: a fused image pass, `shader_probe_clipmap_indirect_lighting`. It picks once and
-  re-weights the pair for each lobe, as Brick4's fused pass does: one cost profile, the same two
-  probes.
-- **SSR on**: `shader_probe_clipmap_diffuse` plus SSR, whose fallback is this mode's
-  `ssr_sample_radiance`.
-
-Until S6, specular is `shader_specular_IBL`, as LPV mode does today.
-
-**As built (S4f, 2026-10-28)**: `probe/shader_probe_clipmap_diffuse.js` serves SSR on and off alike.
-The fused `shader_probe_clipmap_indirect_lighting` waits for S6, since until then there is no probe
-specular to fuse with.
-- `Renderer` swaps the pass in for `shader_diffuse_IBL` once `GPUProbeClipmapGI.has_probes`, that
-  is, once the mode has run a frame.
-- A pixel with no probe found takes `get_ibl_irradiance(bent normal)` inside the pass.
-- AO multiplies the result, as in the IBL pass.
-- **Tier 2**: `shader_probe_clipmap_diffuse.spec.js` runs the pass whole on the emulator:
-  - π × the SH resolved at the bent normal × occlusion;
-  - IBL's output where nothing is found;
-  - the pick by the surface normal and the view, against `probe_clipmap_sample_sh` itself.
-- **Mutants**: 32 of 32 killed (the pick 16, the visibility weight 3, the pick of two 2, the cage 1,
-  the host's uniform 2, the pass 8). Four were killed by tests added for them:
-  - a relocated probe weighed from where it moved;
-  - the pair's second slot and the blend's direction, both by two corners blended in every draw;
-  - the depth read at its direction's own texel.
-- **Measured** on Sponza at 1280×720, a still camera, the caches baked. The frame's mean luma goes
-  from 2.6 under IBL to 66 under the probes (8-bit), the same on both GPUs.
-
-  | p50 | AMD iGPU | RTX 4090 |
-  |---|---:|---:|
-  | the diffuse | 7.06 ms | 58 µs |
-
-  The iGPU's time, split by twins drawn in the same frame:
-
-  | part | iGPU |
-  |---|---:|
-  | depth taps and Chebyshev | 2.37 ms |
-  | the draw of two | 1.30 ms |
-  | SH reads and the resolve | 0.18 ms |
-  | the skirt | 0.04 ms |
-  | the pass without a pick | 0.42 ms |
-  | the rest of the corner weights: indirection loads, state words, the trilinear and back-face terms | ~3.0 ms |
-
-**As built (S6c1, 2026-10-28)**: `probe/shader_probe_clipmap_indirect_lighting.js`, the fused pass, with SSR off.
-- `Renderer` draws it in place of the diffuse, specular and resolve passes once `has_probes`, as Brick4's fused
-  pass replaces its three. With SSR on, the diffuse pass and SSR stay.
-- **One pick a pixel**, by its own normal and the view, with the frame's STBN, for both lobes.
-  `probe_clipmap_sh_of(pick)` and `probe_clipmap_radiance_of(pick, …)` take a pick already made;
-  `probe_clipmap_sample_sh` and `probe_clipmap_sample_radiance` make one and call them.
-- **The diffuse** is the diffuse pass's: the pick's SH resolved at the bent normal, times π, times AO. Its
-  shares are not re-weighted for the bent normal, as Brick4's are. The diffuse pass takes them as picked (S4f),
-  so the fused pass lights the diffuse as SSR on does.
-- **The specular** is `probe_clipmap_radiance_of` at the surface's roughness, as the IBL pass samples its own.
-- A pixel no probe weighs anything for takes the environment's pair, as the IBL passes give it. The pair is
-  resolved as `shader_resolve_indirect_lighting` resolves it and added to the scene's colour.
-- **Tier 2**: `shader_probe_clipmap_indirect_lighting.spec.js` runs the pass on the emulator against the
-  diffuse pass, `probe_clipmap_sample_radiance` and the resolve pass on the same pixel. Where nothing is found,
-  it runs against the IBL pair. The pixel's bent normal is placed so that its visibility cone ends across the
-  specular lobe, and the specular occlusion shows. 14 of 14 mutants were killed.
-- **Measured** on Sponza at 1280×720, sun only, SSR off, the probes settled. The fused pass's node drew one of
-  three arms a frame, in turn, over one set of probes. 138 frames an arm; p50 of the indirect light's passes:
-
-  | arm | RTX 4090 | AMD iGPU |
-  |---|---:|---:|
-  | **as built**: the fused pass | 265 µs | 9.66 ms |
-  | before: the probes' diffuse, IBL's specular, the resolve | 270 µs (208 + 31 + 33) | 8.17 ms (6.65 + 0.62 + 0.91) |
-  | the same light unfused: the probes' diffuse, a pass of their specular, the resolve | 480 µs (208 + 237 + 36) | 16.18 ms (6.65 + 8.62 + 0.92) |
-
-  - The probe trace, which no arm touches, reads 0.97–1.00 between arms.
-  - One pick for both lobes costs 0.55× (4090) and 0.60× (iGPU) of the two picks unfused. Against the passes it
-    replaces, the probes' specular costs nothing measurable on the 4090 and 1.5 ms on the iGPU.
-  - The fused pass's light matches the unfused passes' to 0.6% of a pixel's luma, their f16 intermediates. The
-    probes' specular lifts the indirect light's mean luma 36% over the sky's, which is dim in this harness. Both
-    GPUs agree.
-
-### 9.7 Every file the change touches
-
-The new mode value:
-- **Definition**: `ShadeIndirectLightingMode.js`.
-- **The five choice files** of §9.5, and the resource sets:
-  - `shader_avboit_draw.js` and/or `SHADING_LIGHT_RESOURCE_GROUP.js`;
-  - `shader_oit_resolve_moments.js`;
-  - `water/shader_water.js`;
-  - `ssr_resolve_shader.js`;
-  - `shader_irradiance_clipmap_build.js`.
-- **Owners**: `graph_rasterize_meshes_transparent_avboit.js`, `graph_rasterize_meshes_transparent_oit.js`,
-  `GPUWaterRenderer.js`, `SSR.js`, and `GPUViewVolumetrics.js` → `GPUIrradianceClipmap.js`.
-- **`Renderer.js`**: the switch at 1138, the hand-offs at 1266-1267 and 2791, the per-frame update
-  (beside `update_lpv`), `enquirePipelines`, `destroy` and `indicate_view_change`.
-- **Specs that encode per-mode facts**: `indirect_lighting_consumers.spec.js`, `SSR.spec.js` and
-  `graph_build_froxel_gi.spec.js`.
-
-The caches, the membership bit and the extractions:
-- `engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js` (the `SDFWorld` bit) and
-  `engine/graphics3/ShadedGeometrySystem.js` (forwarding it).
-- `scene/rows/GPUSceneRows.js` (the bit, the `flags` word, `onMeshWritten`) and
-  `scene/MESH_INSTANCE_METADATA_STRUCT.js`.
-- `geometry/sdf/GPUGeometrySDFManager.js`, `shader_build_sdf.js` and its spec, and the four readers of
-  the dense tiles, ported to `mesh_sdf_sample`.
-- `material/resident/GPUResidentMaterialContext.js`: slot means, and the repack signal.
-- Brick4's `chunk_brick4_probe_meta_pick2.js` and `chunk_brick4_sample_forward_indirect.js` (the pick
-  and the hash, extracted).
-- `shader/chunk/spherical_harmonics/l1i/` (the specular resolve).
-
-## 10. Settings
-
-`renderer.probe_clipmap`, a `ProbeClipmapSettings`: plain validated fields, pushed every frame, on
-the shadow knobs' pattern.
-- **Structural fields** (the cascade counts and resolutions, the voxel size, the spacing, the
-  radiance and depth resolutions): a change destroys and rebuilds the instance, and the caches warm
-  up again.
-- **The mesh cache fields** (`mesh_sdf_voxel_size`, `mesh_sdf_max_bricks`): a change rebakes every
-  cached geometry.
-- **Budgets and times** (`brick_build_budget`, `mesh_sdf_bake_budget`, `card_capture_budget`,
-  `rays_per_probe`, `ray_budget`, `response_frames`): uniforms and transient sizes, so
-  they take effect the next frame without a rebuild.
-
-| Setting | Default | Range | Changes |
-|---|---|---|---|
-| `brick_cascade_count` | 6 | 1–8 | brick map depth, initial capacity |
-| `brick_cascade_resolution` | 32 | 16, 32, 64 | cells per axis per cascade |
-| `brick_voxel_size` | 0.125 m | > 0 | finest voxel; every cascade doubles it |
-| `brick_build_budget` | 4,096 | ≥ 64 | cells written a frame (a time knob, as `shadow_update_budget` is) |
-| `mesh_sdf_voxel_size` | 0.125 | > 0 | mesh voxel, in the geometry's local units |
-| `mesh_sdf_max_bricks` | 18 | even, 2–64 | bricks per axis before the voxel grows (a safety net; UE's per-mesh cap); 64 bounds the levels a thread walks |
-| `mesh_sdf_bake_budget` | 23 | 1–8,191 | bricks evaluated a frame while caches fill (a time knob; derived in §6.4) |
-| `card_capture_budget` | 16,384 | 1 – 65,535 | card pages captured a frame, new pairs first, then recaptures (a time knob; derived in S2, §6.5) |
-| `probe_cascade_count` | 5 | 1–8 | probe levels |
-| `probe_cascade_resolution` | 32 | 16, 32, 64 | lattice points per axis per cascade |
-| `probe_spacing` | 1 m | > 0 | finest spacing; every cascade doubles it |
-| `radiance_resolution` | 16 | 4–32, power of two | octahedral radiance texels per side |
-| `depth_resolution` | 8 | 4–32, power of two | octahedral depth texels per side |
-| `rays_per_probe` | 256 | a power of two in [n_r²/4, 4·n_r²] | rays per probe update; below n_r² an update covers a spread subset of texels, above it each texel averages several |
-| `ray_budget` | 131,072 | ≥ `rays_per_probe` | rays per frame (a time knob) |
-| `response_frames` | 30 | > 0 | the radiance's short mean's time constant τ in frames (§8.8), and the depth's blend's |
-
-`retention_time` (1 s) was removed on 2026-10-30: probes are evicted by the pressure on the slots (§8.3).
-
-The defaults:
-- They sit between Enshrouded's low and mid tiers (100k and 250k rays; radiance 8 and 16).
-- The probe cascade matches Lumen's 1.04 m and DDGI's usual 1–2 m.
-- The brick voxel is UE's 19.8 cm order, and the mesh voxel matches it at unit scale.
-
-**Fixed, not settings**:
-- the brick's 8³ / 7 layout, for world and mesh bricks alike;
-- R = 4 voxels;
-- the size-class step of two bricks;
-- the hit threshold and minimum step, ½ voxel;
-- 64 steps a ray;
-- the mesh provider's 64 rows a batch and 512 nodes a level of a walk, past which the work goes on in more
-  batches and rounds (S9);
-- 32 cards per geometry, and 4 alpha continuations per capture texel;
-- the 2³-texel object cell;
-- 2 probes per pick;
-- 2 shadowed suns and 32 local lights per hit;
-- the 4³-cell occupancy block;
-- the 25% back-face threshold.
-
-Each is stated where it is used, with what is lost past it.
-
-## 11. Budget
-
-Derived counts at the defaults. **No time here is measured.** §13 measures each stage on the 4090
-and on the AMD iGPU before the next begins.
-
-**Memory**
-
-| Resource | Size |
-|---|---|
-| brick map + occupancy | 32³ × 6 × 4 B + 8³ × 6 × 4 B = 0.76 MiB |
-| world bricks at initial capacity 12,288 | SDF 512 B + objects 256 B → 9 MiB |
-| pending ring | 196,608 × 4 B = 768 KiB; as built, 262,144 × 4 B = 1 MiB (§7.4) |
-| probe indirection + wanted bits | 32³ × 5 × 4 B + 20 KiB = 0.64 MiB |
-| per probe | radiance 18² × 8 B + depth 10² × 4 B + record 64 B + state 4 B = 3,060 B |
-| probes at initial capacity 16,384 | 48 MiB |
-| geometry caches | per surface brick of a cached geometry: 512 B of SDF and about a seventh more for the levels, once however many instances draw it |
-| card sets | per surface brick and per (geometry, material) pair: two to four pages of 512 B (a surface faces two of the six directions, and slabs add few). Measured in S2: Sponza's 103 card sets hold 154,138 pages, 79 MB. Most geometries draw with one material, so most have one card set |
-| transients | build staging 4,096 × 768 B = 3 MiB; ray records 131,072 × 24 B = 3 MiB; probe maps 512 × 2.25 KiB = 1.2 MiB |
-
-The initial probe capacity is `2·N_p²·C_p` = 10,240 (a visible surface crosses each cascade as a
-one-cell-thick shell, doubled for the cage), rounded up to a power of two. It matches the 16k that
-Lumen and Enshrouded settled on.
-
-**Dense comparison** (D31): every lattice point of 5 × 32³ has a probe. That is 163,840 probes,
-478 MiB, and at the same ray budget a period ten times longer.
-
-**Work a frame**
-- Rays ≤ 131,072, each ≤ 64 steps of 2–3 loads, plus up to 2 sun shadow marches.
-- Shading: an object load, the card surface (§6.6), up to 32 lights, and a pick.
-- World bricks ≤ 4,096 cells. An empty cell costs one TLAS level. A cell with instances costs, per
-  texel, ≤ 64 box tests, plus a transform, an indirection load and a tap per instance that passes.
-- Pixels: 8 × (an indirection load, a state word, a depth tap), then 2 records and 2 radiance taps.
-- Bakes: only while caches fill, ≤ `mesh_sdf_bake_budget` × 33k BLAS queries a frame.
-- Captures: only for new pairs and changed materials, ≤ `card_capture_budget` × 64 texels a frame,
-  each a ray, up to 4 alpha draws and a material sample.
-- **Passes**: about 20 dispatches a frame, counting the one-thread command builders. A pass on the
-  4090 costs a measured 5–8 µs however small (2–3 µs for one thread), so the floor is near 0.1 ms
-  before any work. It is stated so the measurement can be read against it.
-
-## 12. Verification
-
-**Tier 1, WGSL parse and validation**: every new module, through the existing `*_wgsl_validity`
-specs. A real compile on a device catches what the validator misses.
-
-**Tier 2, emulator**: pure chunks against CPU oracles.
-- **Mesh caches**:
-  - Size classes: every axis even, ≥ 2, grown in steps of two; the voxel grows past the cap.
-  - The bake's texels against `blas_query_sdf` evaluated on the CPU at the same points, for a sphere,
-    a box and an open plane. Exact distances within one LSB; signs right on the closed meshes.
-    - As built (S3): against UE's vote evaluated in doubles, which pins as well the shell behind an
-      open quad, a closed box drawn two-sided, and a texel past R/2 inside a large face.
-  - Classify never drops a brick that evaluate would keep.
-  - `mesh_sdf_sample` outside the grid box never exceeds the true distance (contract 4).
-  - Card placement covers every run start of a hollow box and of an L-shaped room within 32 cards.
-  - A capture of a textured quad matches `sample_material_data` at the same points under the same
-    seed: diffuse albedo and emissive, each within one LSB of its encoding.
-  - A recapture of an unchanged material writes the same bytes.
-  - The card depth tolerance passes a hit displaced by up to ½ voxel of its cascade, at every
-    cascade.
-- **World bricks**:
-  - `r8unorm` encode/decode round trip within one LSB.
-  - The mesh provider's texels against a brute-force minimum over the same instances' CPU distances.
-  - The merge: two providers in either order produce the same bytes and, outside ties, the same
-    objects.
-  - `brick_clipmap_trace` against analytic spheres, boxes and planes built into bricks on the CPU:
-    the hit distance error is ≤ ½ voxel + 1 LSB.
-  - The occupancy skip never misses a hit that a brute-force march finds.
-  - UNKNOWN cells defer to the parent.
-  - The soft-shadow penumbra matches the analytic disk light at a sphere's edge.
-    - As built (S3e): against the disk past the surface the tracer hits, half a voxel out, within 0.1;
-      half at the edge within 0.1.
-    - Since 2026-10-30 the hits' shadows are rays: under a slit narrower than the sun's disk, each ray
-      sees all of the sun or none, and their mean the part of the disk the slit lets through (§8.7).
-  - `mesh_card_surface`: a hit on a card's surface returns that texel's diffuse albedo and emissive,
-    and a hit hidden from every card returns the material mean.
-- **Probes**:
-  - Every generated direction encodes back into its own texel.
-  - SH2 projection of constant radiance L gives E = πL for every n.
-  - A single bright texel matches the SH2 of that cone.
-  - The update blend reproduces α for a known Δt.
-  - A ray from inside a solid is a back face at its first step.
-- **Sampling**:
-  - The pick's frequencies converge to the normalised weights over many ξ.
-  - A probe behind a slab, per its depth moments, weighs under the crush and is never picked.
-  - The cascade blend is continuous across the skirt.
-  - `resolve_irradiance_sh_to_specular` at g₁ = 2/3 equals `resolve_irradiance_sh_to_diffuse`, and
-    returns L under constant radiance L at every α.
-- **Extracted pieces** (probe weight, pick, hash, free-list pop/push): their
-  old callers' specs stay green. LPV's and Brick4's sampling are unchanged to the bit.
-
-**Tier 3, SoftwareGPUDevice**: host orchestration, black-box on what reaches the device.
-- A one-cell anchor move produces exactly the scroll boxes' cells in the pending ring and frees the
-  vacated slots: host-written bytes and dispatch counts.
-- Every dispatch is sized by a live count: indirect over a device count, or host-known for `scroll`,
-  `want`, `coarse` and the bake. None is sized by a capacity.
-- A row whose `SDFWorld` bit is cleared reaches the device with bit 0 of its `flags` clear, and the
-  host pushes its box.
-- A geometry is baked once however many rows draw it, and freed when the last row goes.
-- A pair is captured once however many rows draw it.
-  - A row that changes material moves one pair's count to another.
-  - A material whose version moves recaptures exactly its own card sets, once.
-  - A pair still capturing reads null in the row → card set table.
-- A provider registered after the mesh provider runs after it, over the same taken keys.
-- A settings change reallocates to the new sizes.
-- Entering and leaving the mode leaves `device.live_resources` as it was (the leak-spec pattern).
-- The mover list is produced once a frame and read by both VSM and this mode.
-
-**Tier 4, device** (headless Chrome; few hundred frames at small sizes, never sweeps):
-- **White furnace**: a closed box of albedo ρ and emission L_e converges to L = L_e/(1 − ρ). This
-  checks multi-bounce energy end to end.
-- **Cornell box** against the accumulating path tracer, with an error metric.
-- **Leak cases**: a sunlit wall thinner than a coarse voxel; a closed room beside daylight.
-- **Absence**: a bright emissive mesh out of the SDF world lights nothing through GI.
-- **Recapture**: an emissive material switched on lights the scene through GI after its card sets are
-  recaptured. The lag is measured in frames at the default budget.
-- **Stability**: an orbit and a dolly, the same path for A and B, measuring frame-to-frame change of
-  the indirect term. A still camera proves nothing. The pick's noise is measured here against the
-  eight-probe evaluation, as a one-off.
-- **Counters**: dropped instances and triangles, oversize geometries, unresolved rays, dead probes,
-  allocation failures, period T.
-- **The storage-write rounding question of §8.8.**
-
-**As built, S4's done-when (S4g, 2026-10-28)**: one bounce, on both GPUs. The harness is the session's
-scratchpad `device/s4g.js`.
-- **How the runs were held.** The GI's clock is the caller's `performance.now()`, so α followed each run's
-  frame pacing, and a furnace read differently from run to run. Every run below holds the GI's clock at
-  1/60 s a frame by wrapping `GPUProbeClipmapGI.graph_update`. The furnaces then let it settle 900
-  frames, 30 τ.
-- **White furnace, one bounce.**
-  - *A closed room* of 8 × 4 × 8 m, every face glowing L, no light. Before AO, E/πL is 0.9991 at p50 and
-    0.994 at p01, on both GPUs and at 60 or 240 Hz. Every ray hits, every texel holds L, and the
-    records' E/π is 0.4998 against 0.5. The 1.5% and 5.9% short before were the store's rounding (§8.8).
-  - GTAO's occlusion multiplies the probes' diffuse, as it does IBL's. The room's corners then read p10
-    0.886 and p01 0.557: the probes see those walls glowing, and AO calls them dark. A furnace therefore
-    reads E before AO.
-  - *An open sky* of radiance L over a dark floor of 200 m, no light. L1 holds a lit hemisphere's
-    irradiance exactly at its pole, so πL is the floor's exact answer. E/πL is 0.997 on the iGPU and
-    0.980 on the RTX 4090. **Open, not root-caused**: the shortfall is in the 4090's probes, not the
-    resolve, since the surface normal gives 0.983 against the bent normal's 0.981.
-    - Texel by texel, every probe holds L from 10° above the horizon up on both GPUs. At 2–10° the
-      4090's texels hold 0.98 and 0.96 of L, against the iGPU's 0.996 and 0.993, on rays that resolve
-      alike.
-    - **D4's reversal condition is met here.** 64 steps leave 63% of the rays within 2° above the
-      horizon unresolved, 41% at 2–5°, 28% at 5–10° and 10% at 10–20°. Over Sponza it is 0.24–0.34% of
-      all rays.
-- **Stability**, on Sponza with the sun: each pixel against the same surface point a frame before,
-  reprojected through the previous frame's view-projection. The two GPUs agree to the per-mille.
-  - Raw, the indirect diffuse before TAA:
-
-    | p50 | still | orbit | dolly |
-    |---|---:|---:|---:|
-    | the eight corners blended (a twin) | 5.0% | 10.1% | 9.2% |
-    | the pick of two (shipped) | 16.9% | 26.4% | 17.6% |
-    | pixels matched | 99.6% | 95.8% | 98.3% |
-
-  - With TAA, the final image:
-    - Still: the pick 0.95% against the eight's 0.65%.
-    - Orbiting, the medians are alike, 14.3% against 13.1%, which is texture detail resampled.
-      **The tails are not: p90 50% against 21%, mean 22.9% against 13.5%.** TAA does not resolve the
-      pick's noise under motion in a tenth of the frames, which §9.4 expected it to.
-  - The eight corners' cost, paired in one frame with the order alternating: iGPU 5.93 ms against the
-    pick's 6.64 ms, **0.72 ms less**; RTX 4090 65.5 µs against 58.4 µs.
-  - **Alex kept the pick of two** for the diffuse (2026-10-28), with these measurements before him.
-- **Counters**, on Sponza:
-  - live probes: 769 still, 1,341 orbiting; dead: 13 and 54;
-  - the period 2, and nothing starved;
-  - rays: 3–5% miss, 0.24–0.34% unresolved, 2% back faces;
-  - all 103 geometries' fields coarsened; the bake starved 16 frames and skipped 90.
-- **Timings**, Sponza at 1280 × 720, p50:
-
-  | | AMD iGPU (orbit) | RTX 4090 (still) |
-  |---|---:|---:|
-  | want | 116 µs | 7 µs |
-  | relocate | 20 µs | 25 µs |
-  | trace, with the sun's shadow | 5.16 ms | 310 µs |
-  | shade | 1.04 ms | 26 µs |
-  | accumulate, the projection's rows and probes, publish | 0.75 ms | 33 µs |
-  | the diffuse | 6.65 ms (7.06 before S4g's tile address) | 58 µs |
-  | the rest, each | under 8 µs | under 8 µs |
-
-**As built, S5's done-when (S5d, 2026-10-28)**. The harness is the session's scratchpad `device/s5d2.js`.
-- **The multi-bounce furnace** reads 0.994 once a hit wants its probes (S5a, §8.7).
-- **Cornell box against the path tracer.**
-  - *The scene*: a box 4 m inside, open toward the camera, under a black sky, lit by a point light 0.4 m
-    below the ceiling. The walls have the classic reflectances (white 0.73, red (0.63, 0.065, 0.05),
-    green (0.14, 0.45, 0.091)), with a short and a tall white box inside.
-  - *The images*: 480×360, tone mapping NONE at a fixed exposure, the sRGB transfer undone on the CPU.
-    Each image's mean is taken per surface, the surface found by casting each pixel's ray on the CPU.
-    The probes' image is the mean of 64 frames after 900 frames of settling.
-  - *The reference is the accumulating path tracer through twins of its shader.* The engine's tracer
-    stops at three bounces (`BOUNCE_LIMIT = 3u`). In this box that leaves its total at 84–94% of the
-    converged one, and its indirect at 72–77%. So the reference traces 24 bounces at 512 samples a
-    pixel, and a twin at one bounce gives the tracer's own direct light.
-
-  | surface | total, probes / traced | indirect, probes / traced | direct, raster / traced |
-  |---|---:|---:|---:|
-  | floor | 0.88 | 0.89 | 0.88 |
-  | ceiling | 0.90 | 0.94 | 0.89 |
-  | back | 1.03 | 1.07 | 0.98 |
-  | red wall | 1.03 | 1.15 (r 1.41, g 0.78, b 0.73) | 0.87 |
-  | green wall | 0.99 | 1.04 (r 0.82, g 1.09, b 0.76) | 0.92 |
-  | the boxes | 1.14 | 1.55 | 0.64 |
-
-  The iGPU's probe image agrees with the 4090's within 0.5% on every surface.
-  - **The direct light differs before the GI does.** The rasterizer's point light is 2–13% under the
-    tracer's on the walls and 36% under on the boxes. That is the direct path's, not the probes'; it was
-    measured here and not looked into.
-  - **The indirect alone**, each image less its own direct, is within −11% to +7% on the floor, ceiling,
-    back and green wall, +15% on the red wall, and +55% on the boxes.
-  - **The colour bleed is too saturated** on the coloured walls: the red wall's indirect is redder than
-    traced, the green wall's greener. The probes keep chroma in the constant band alone (Metro L1), so a
-    probe beside a coloured wall lends its colour to every direction.
-  - **None of these gaps is a follow-up** (Alex, 2026-10-28). The tracer at three bounces is the engine's
-    reference, and a probe GI cannot match a path tracer: angular resolution, depth bias and the probes'
-    sampling offsets bound it. S5's done-when is the comparison, not parity with it.
-- **Timings**, the probe clipmap's passes summed at their p50, Cornell at 480×360: **0.22 ms** on the 4090
-  and **5.6 ms** on the iGPU. The iGPU's trace is 2.8 ms of it, the light 0.62 ms, the diffuse 0.80 ms,
-  shade 0.34 ms and the hit wants 0.32 ms.
-
-**As built, S6's done-when (S6e, 2026-10-28)**. The harness is the session's scratchpad `device/s6e.js`.
-- **The room** is S4g's, 8 × 4 × 8 m inside six slabs, with no light under a black sky. SSR is off, so the fused
-  pass draws, and the probes settle for 900 frames. Captures drawn beside the fused pass, on its bindings, write
-  the probes' specular at each pixel as the pass reads it: `probe_clipmap_sample_radiance` with the pixel's STBN
-  noise. A twin of the sample without the parallax, which taps along the lobe, is drawn beside it every frame.
-- **Reflections in a closed room, as a furnace.** Every face glows L with albedo 0, so every probe texel holds L.
-  The specular over L at roughness 0.05, 0.3, 0.6 and 1 is 0.9995 at p50 and at least 0.996 at p01, on both GPUs,
-  with the parallax and without.
-- **The parallax A/B.** The walls and the ceiling each glow a colour of their own with albedo 0; the floor is black
-  metal at roughness 0.05. Each floor pixel's specular, averaged over one cycle of the STBN (64 frames), is held
-  against the exact mirror: the face the pixel's mirror ray meets, cast on the CPU.
-  - *Right face* is the share of floor pixels whose nearest face colour is that face's.
-  - *The error* is |L − L_face|₁ / |L_face|₁.
-  - The table gives the range over two runs on each GPU; the two GPUs agree within half a percent.
-
-  | the mirror ray's face is | with the parallax (as built) | without |
-  |---|---:|---:|
-  | under 2 m away (17% of the floor) | 87.5–87.8% right, error 0.200–0.202 | 97.0%, 0.105–0.107 |
-  | 2–4 m away (32%) | 97.2–97.3%, 0.146–0.148 | 95.5–95.9%, 0.141–0.144 |
-  | 4–8 m away (51%) | 87.8–88.4%, 0.255–0.258 | 79.6–79.9%, 0.245–0.246 |
-  | the whole floor | 90.7–91.0%; error p50 0.159–0.162, p90 0.384–0.390 | 87.6–87.9%; 0.140–0.143, 0.384–0.388 |
-
-  - The parallax puts more of the reflections from 2 m out on their face, and fewer of those under 2 m. The
-    ceiling, 4 m and more above the floor, is the one face it does worse on as a whole: 85.7–87.0% right against
-    100%.
-  - *Two other forms were measured and not taken.*
-    - Leaving the parallax out where the depth reads its √3 limit gives 86.1–86.4% right and a p90 error of
-      0.44–0.45. Each probe decides alone, so a picked pair can tap along two inconsistent directions.
-    - Meeting the sphere where the ray enters, for a point outside it, is the same from 2 m out and worse under
-      it: 85.3% right, error 0.222.
-  - The parallax costs the capture 133 against 126–128 µs on the 4090 and 4.86 against 4.59 ms on the iGPU, at
-    960 × 540 with every pixel the room's.
-- **The parallax stays as built.** It places more of the floor's reflections, and the far ones most; the near ones
-  it misplaces about four times as often as a flat tap does.
-
-## 13. Stages
-
-Each stage lands suite-green and is measured before the next.
-
-| Stage | Scope | Done when |
-|---|---|---|
-| S0 | enum value, `ProbeClipmapSettings`, lifecycle; the five alternatives and the deferred case behave as IBL | consumer specs green with the new value; leak spec |
-| S1 | scene-level mover list with the skinned bit (D32), VSM migrated; the `SDFWorld` bit through `ShadedGeometrySystem` into the row's `flags`; `onMeshWritten` | VSM specs and playground unchanged; rows specs |
-| S2 | geometry caches: `GPUGeometrySDFManager` sparse (classify, evaluate, store, levels, size classes); cards (placement, capture, recapture on the resident context's repack signal); the pair bookkeeping and the row → card set table; the bake and capture queues and budgets; the four readers ported; debug views of a mesh's bricks and cards | tier-2 oracles; bake and capture timings, which set `mesh_sdf_bake_budget` and `card_capture_budget` |
-| S3 | brick clipmap: windows, map, atlas, free list, scroll, movers, clear, the provider contract, the mesh provider, store, occupancy, object cells, trace chunks, a ray-marched debug view | tier-2 oracles; device timings of build and trace |
-| S4 | probe clipmap: lifetime, relocation, schedule, trace with sun shadow, shade (emissive, sun, sky; the card surface), accumulate, publish; deferred diffuse through the pick | furnace (one bounce), stability, timings |
-| S5 | next bounce (E_ind); local lights via generalised world clusters; the forward, water, SSR-hit and irradiance-clipmap alternatives | furnace (multi-bounce), Cornell vs path tracer |
-| S6 | specular: radiance ⊕ GGX-SH2, parallax, fused pass, SSR fallback, forward and water specular | parallax A/B, reflections in a closed room |
-| S7 | the virtual geometry provider: box cut, streaming invalidation | Zorah lit by its own geometry; timings |
-| S8 | virtual geometry's caches per geometry (Alex, 2026-10-29): a proxy cut from each, baked by the mesh path, adopted; the per-cell provider deleted; then measured follow-ups only (§17) | Zorah's holes, back faces and dead probes against S7e's and Sponza's; the frames and cost of the bake; the frame at rest |
-| S9 | the mesh provider without its cap (Alex, 2026-10-29): walks that hand on what they cannot hold, batches of 64 spread over workgroups by count, an atomic merge, the resolve on the cells the walks listed; contract 7, retry | Zorah's holes against S8's; the provider's cost on both GPUs, paired with S8's |
-
-## 14. Decisions taken here
-
-Each says what would reverse it.
-
-- **D1. Brick = 8³ texels on 7³ voxels (corner lattice)**, for world and mesh bricks alike. UE pages
-  and mesh distance fields agree. *Reverse:* none foreseen.
-- **D2. Signed distance, 4-voxel band, ½-voxel hit.**
-  - (a)'s case for unsigned was that a per-cell triangle gather cannot tell inside from outside.
-    Whole-mesh bakes can, and the minimum of signed fields is their union.
-  - What the sign buys: relocation pushes probes out from inside, back faces are a gradient test, and
-    no triangle orientation is stored.
-  - The ½-voxel hit keeps walls thinner than a voxel, as UE's expand does.
-  - *Reverse:* if measured sign failures on real assets cost more than this.
-- **D3. Allocate iff a staged texel has |d| under one voxel.** Fewer bricks than UE's
-  within-R-of-the-page-radius rule; the occupancy skip covers the cells left out.
-  *Reverse:* if trace steps measure high beside surfaces.
-- **D4. Two-level occupancy (HDDA) instead of UE's coarse eikonal mip.** Incremental, toroidal, no
-  propagation passes. *Reverse:* if sky rays exhaust 64 steps in measurement.
-- **D5. Material from surface cards with Lumen's payload** (Alex's answer on the card payload).
-  - Diffuse albedo and emissive are captured per (geometry, material) pair and recaptured when the
-    material's version moves.
-  - A hit does no material work.
-  - *Reverse:* none of mine; Alex chose it over cards that hold uvs.
-- **D6. No triangle is read per frame.** Meshes are read at bakes (the SDF, per geometry) and at
-  captures (the cards, per pair and per material change). A virtual geometry's cut is read once, for
-  its proxy's bake (S8), never per frame. *Reverse:* none; it is the review's rule.
-- **D7. Hits are diffuse only: `L = emissive + ρ_d·E/π`.**
-  - That is what Lumen's payload holds, and Lumen's surface cache lights diffusely too.
-  - (b) first had the full BRDF's directional albedo at the hit's NoV (`tSplitSum`), which needed
-    roughness and metalness at every hit.
-  - What is lost: a metal bounces only its emissive.
-  - *Reverse:* if metals measure dark in the bounce, capture the BRDF's hemispherical albedo in place
-    of the diffuse one. That needs the same storage and no hit-side change.
-- **D8. Radiance `rgba16float`, two-pass update.** Hardware bilinear for every consumer.
-  *Reverse:* if the stall bias measures visible, f32 history in a buffer.
-- **D9. Depth moments normalised by spacing, clamped at (1 + 0.45)·√3·s.**
-  - Chebyshev's bound asks only how many samples lie past the point, which a clamp past every point the
-    cage tests leaves as it was, and a larger clamp only loosens it. The clamp is one constant, so a
-    reader de-normalises with the spacing alone.
-  - **Corrected 2026-10-30**: it was √3·s, the cage diagonal, which holds only for a probe on its
-    lattice point. Relocation (§8.4) moves a probe up to 0.45 of a spacing on each axis, so a biased
-    point can be (1 + 0.45)·√3 ≈ 2.51 spacings from a corner probe. A direction that sees nothing read as
-    occluded past √3: visibility ≤ 0.41 at 1.8 spacings, 0.043 at 2.0. Over a cell, a corner moved 0.45
-    on every axis away from it lost up to 0.70% of the cage's trilinear weight; 0.25 on each, 0.013%.
-  - RTXGI clamps at `1.5·|spacing|` (`ProbeBlendingCS.hlsl`), the same reach over DDGI 2021's
-    half-spacing relocation bound; neither DDGI paper's text gives a value. RTXGI's own relocation is a
-    sphere of 0.45, so its clamp has headroom.
-- **D10. SH2 projected from blended radiance, not blended separately.**
-- **D11. Radiance by a multi-scale mean whose short mean follows a response time in seconds; depth
-  by an exponential blend; jittered stratified rays.**
-  - Lumen overwrites without jitter, but its screen probes filter downstream. Here consumers read
-    the probes directly.
-  - DDGI 2021's per-texel change boost is left out. A texel here sees one ray an update, so a change
-    test on it is a noise test.
-  - **Reversed for the radiance, 2026-10-29**: Alex judged the noise visible, and Enshrouded's
-    estimator (RT Gems ch. 25) was built (§8.8, as built). Measured on Sponza at τ = 0.5 s: a texel
-    moves 1.0% an update against 10.8%, the SH's band 0 0.27% against 1.54%; a doubled sun is half
-    taken in 55 frames against 29, and 90% in 389 against 105.
-  - A variant testing the means' gap against the short mean's own deviation, as SSR's accumulation
-    does, was modelled on the CPU and followed a step on a noisy texel more slowly still; not built.
-  - **The rays' half reversed too (2026-10-29).** Alex found the probes' noise visible, and asked for
-    Enshrouded's importance-sampled rays, rotating corner and all (§8.6, as built). The estimator's short
-    mean now takes a texel's period from its share of the updates that reach it (§8.8).
-- **D12. Schedule: NEW first, then a slot-hashed phase with a period from the live count.**
-- **D13. Pixels pick 2 of 8 by WRS after visibility-only weights** (the review). Brick4's sampler and
-  noise. *Reverse:* if the measured noise under TAA is visible, then a screen-space reservoir resolve,
-  argued from that measurement.
-- **D14. Sun shadows at hits by shadow rays traced in the bricks**, toward a point of the disk.
-  Shadow maps read lit off screen; the cone soft shadow S3e built leaked through gaps narrower than
-  the disk, and was replaced on 2026-10-30 (§8.7).
-- **D15. Local lights from the world clusters, one picked by WRS over the chance of its pick, its
-  shadow a ray traced in the bricks** (2026-10-30, §8.7). Until then every light of the cell, each
-  through its shadow map, a light with a cleared map unshadowed at hits.
-- **D16. Settings sub-object, rebuild on mismatch.**
-- **D17. Capacity learned from reported failures, never shrinks.**
-- **D18. The mode is named `ProbeClipmap`**, after what shading samples, as Brick4 and LPV are.
-- **D19. No bounce attenuation factor.**
-- **D20. Specular blends a radiance tap with GGX-convolved SH2 by `roughness_to_mip_ratio`** (the
-  review), LPV's blend in Metro form. *Reverse:* none of mine; the review set it.
-- **D21. One object per 2³-texel cell, written by the providers' own minimum.**
-  - UE's object grid has the same 4³ cells a page but keeps the 4 nearest objects per cell, 1 KiB a
-    page. It is filled by its own pass, and a hit blends their cards up to a weight of 0.9.
-  - Here the cell costs 256 B, and the argmin falls out of the minimum the providers compute anyway.
-  - Where two objects meet inside one cell, a hit can name the wrong one. Its card depth test then
-    fails, and the hit takes the material mean.
-  - *Reverse:* if seams measure visible, then UE's four candidates.
-- **D22. Providers merge by a min of encoded bytes, objects by the cell minimum.** The order of
-  providers cannot change a distance.
-- **D23. Cards per depth slab, placed by UE's clustering rule at brick granularity, ≤ 32 per
-  geometry.**
-  - Six bounds cards would miss every interior surface of a single-mesh room or atrium.
-  - UE places its near planes from 10 cm surfels with 32 rays a column. The brick occupancy the bake
-    already holds gives the same rule (m ≤ N ≤ Z) at 7-voxel granularity, with no rays.
-  - *Reverse:* if coverage measures short on real assets, then surfels from the capture rays.
-- **D24. Card texels are two `rgba8unorm` planes, 8 B in all.**
-  - Diffuse albedo is stored as its square root, as UE stores it.
-  - Emissive is stored under the pair's scale s_e, which loses nothing that 8-bit resident textures
-    had.
-  - Depth is 8 bits over the slab, under 0.5 voxel at the 18-brick cap. That is well inside the depth
-    tolerance of 1.5 cascade voxels.
-  - *Reverse:* an emissive that measures banded; then `rgba16float` for that plane, 4 B more a texel.
-- **D25. SDF membership is a `ShadedGeometryFlags` bit, on by default, mirrored into the row.**
-  - It is the entity's data, carried as `Skinned` is, and transparent materials stay out by rule.
-  - UE has a per-primitive distance-field lighting switch and leaves translucent sections out
-    too.
-- **D26. A cascade samples the coarsest mesh level no coarser than itself.**
-  - Its voxel is within a factor of two of the cascade's, and its band reaches at least half the
-    cascade's. Past that band a sample under-estimates, which is safe.
-  - UE instead walks the resident mips from coarse to fine per sample, with mips streamed by distance.
-    Choosing per cascade is one decision per instance and cell, and it needs no residency.
-  - *Reverse:* if steps measure slow beside surfaces at the band's edge, then the next level up.
-- **D27. The bake drops the open-mesh wrap.** The band stores nothing past R, which is what the wrap
-  was for.
-- **D28. The caches live on the geometry manager, not on the GI instance.** They survive a mode switch
-  and serve any later SDF reader. The GI keeps only the bookkeeping that requests them.
-- **D29. Recapture keys on `ShadeMaterial.version`, through the resident context's repack.**
-  - It is the change signal every material consumer already uses, and the repack is the one place it
-    is read. Nothing polls.
-  - UE tracks no material change at all; there a primitive is recaptured on an explicit
-    surface-cache invalidation or by the slow refresh of its oldest pages (§2.3).
-  - *Reverse:* none foreseen.
-- **D30. Each passing card gives one texel, blended across cards by n².**
-  - UE also blends four depth-weighted taps per card.
-  - Here a probe's many rays do that averaging, and one texel per card halves the loads.
-  - *Reverse:* if card seams measure visible in the bounce, then UE's four taps.
-- **D31. Probes are a sparse cache from the screen, not a dense lattice** (Alex, as recommended).
-  - "Also a 3D clipmap" holds either way.
-  - At the defaults the dense form is 10× the memory and 10× the update period (§11).
-  - The cost of sparse: no probes where nothing visible needs them, so off-screen bounces see only the
-    probes that exist.
-  - *Reverse:* if the off-screen bounce measures short, Enshrouded's world-cache probes (§17).
-  - **Reversed in part at S5a (Alex, 2026-10-28)**: the multi-bounce furnace measured the off-screen
-    bounce short (§8.7), so hits want the probes they read as well, one step from the screen, as the one
-    probe kind (§8.3). "If we get no indirect bounce, it is better to lose energy than to invent energy":
-    where no probe has data yet the bounce stays zero, and no other probe stands in.
-- **D32. The mover pass moves from VSM to scene level, with a skinned bit** (Alex, as recommended).
-  - The kernels and the list stay the same. The scene context owns them and produces the list once a
-    frame for any reader.
-  - The skinned bit lets this mode skip boxes that only animation moved (§7.4).
-  - VSM's lifetime coupling goes away.
-  - *Reverse:* none foreseen.
-
-## 15. Forks for Alex
-
-None is open. How each was settled:
-- **(a)'s fork 1**, vgeo and DynamicMesh invisible to rays: by the geometry caches and the providers
-  of the review (§6, §7.6–7.8).
-- **(a)'s fork 2**, unsigned distance: dissolved, because a whole-mesh bake knows the sign (D2).
-- **(a)'s fork 3**, a sparse probe cache: taken as recommended (D31).
-- **(a)'s fork 4**, the mover pass at scene level: taken as recommended, with the skinned bit (D32).
-- **(b)'s card payload**: Lumen's, diffuse albedo and emissive captured per (geometry, material) and
-  recaptured on a material change (D5).
-
-## 16. Duplication ledger
-
-Found during the audit. Items marked *(here)* are resolved by this proposal; the rest are listed,
-not fixed.
-
-**Resolved here**
-- *(here)* `GPUGeometrySDFManager`'s dense tiles, readers and all → sparse bricks in place.
-- *(here)* The probe weighting lives only inside LPV's tetrahedral sampler → extracted.
-- *(here)* Brick4's pick and its forward hash, private to Brick4 → extracted.
-- *(here)* An SDF penumbra estimator buried in a dense-volume shader → not extracted: the brick
-  clipmap's estimate is the two-sided one (§4.2).
-- *(here)* GPU slot stacks: particles' own → extracted and shared.
-- *(here)* World clusters keyed to one consumer's struct → keyed by `CLIPMAP_LEVEL_ARRAY`.
-- *(here)* The mover list owned by VSM → scene level.
-
-**Listed**
-- `CascadedSceneSDF` duplicates what the brick clipmap does once S3 lands, and is a candidate for
-  deletion. Alex's call; the lightmap tree is the precedent for keeping things. The Brixelizer port
-  stays as a reference.
-- Toroidal wrap in five places, and cascade placement in two (`IrradianceCascadePlacement` beside
-  `ClipmapWindowSet`).
-- Finest-cascade selection in two forms (box, sphere), and cascade tables in four forms. The unused
-  `global_illumination/clipmap/CLIPMAP_METADATA.js` and `CLIPMAP_CASCADE_METADATA.js` are kept
-  surface.
-- Eight radiance → SH projections; `sh2_color_get_irradiance_at` ≡ `sh2_color_irradiance` apart
-  from a clamp.
-- Three manual octahedral bilinear samplers; two border painters (LPV's perimeter walk, whose
-  radiance border is never read, and the environment skirt).
-- Two 64-ray volume-sign votes plus a CPU twin; three SDF-gradient variants; three ray-AABB slab
-  tests. S3 deleted the BLAS vote, with the bake's move to UE's.
-- `chunk_lpv_mask_weights_by_visibility` and its `_no_depth` twin define the same WGSL function name.
-- The irradiance clipmap cites a "Decision 6.3" document that exists nowhere in the tree or its
-  history.
-
-## 17. Not in this proposal
-
-Each item is added only if a measurement asks for it, or, where marked, when Alex schedules it:
-- **Skinned meshes as a dense animated patch** (Alex: later). The hooks are the clone's header alias
-  (§6.3), the mesh provider's accept (§7.7) and the skinned movers the GI skips today (§7.4).
-- **DynamicMesh in the SDF world.** It has no row and changes every frame; a provider writing per-frame
-  patches is the same mechanism as the skinned one.
-- **Cards for virtual geometry**, its own plan; until then vgeo hits take the material mean.
-- **Lighting in the surface cache** (Lumen's direct lighting and radiosity per card texel). Here the
-  probes carry the bounce.
-- **Specular at secondary hits.** Hits are diffuse only (D7), so a metal bounces nothing but its
-  emissive. The measured fix is the BRDF's hemispherical albedo captured in place of the diffuse
-  one.
-- **Caches persisted across sessions**, an offline bake format.
-- Ray and history reprojection between probes, if long-range propagation into enclosed spaces
-  measures short. History re-sampling is built as a switch, off, and measured quieter but no faster to
-  converge; weighed by the neighbour's confidence and age it is unbiased, blurred, and slower still (§8.8, as
-  built 2026-10-30); reprojecting the frame's own rays is not built.
-- Foliage and translucency in the field, Enshrouded's open problem too.
-  - Alpha-tested geometry is in the SDF as its triangles, so canopies over-occlude. The `SDFWorld`
-    bit is the authored way out.
-  - UE marks voxels within the band of only two-sided meshes with zero coverage. There its trace
-    shrinks the surface expand from 1.0 to 0.6 and lengthens the minimum step fourfold. That is the
-    shape of the fix if it measures necessary: a coverage bit per brick cell beside the object.
-- Ambient probes for fog. Fog has no GI in any mode.
-- Sharing one clipmap between views.
-
-## 18. Sources
-
-- J. Kolesik, *Realtime Global Illumination in Enshrouded*, GPC 2024 —
-  https://www.youtube.com/watch?v=57F1ezwH7Mk
-- Unreal Engine 5.4 Lumen and Global Distance Field documentation:
-  https://dev.epicgames.com/documentation/en-us/unreal-engine/lumen-technical-details-in-unreal-engine
-- Z. Majercik et al., *Dynamic Diffuse Global Illumination with Ray-Traced Irradiance Fields*,
-  JCGT 8(2), 2019 — https://jcgt.org/published/0008/02/01/ ; *Scaling Probe-Based Real-Time Dynamic
-  Global Illumination for Production*, JCGT 10(2), 2021 — https://jcgt.org/published/0010/02/01/
-- NVIDIA RTXGI-DDGI, `rtxgi-sdk/include/rtxgi/ddgi/DDGIVolume.h` and `docs/DDGIVolume.md` —
-  https://github.com/NVIDIAGameWorks/RTXGI-DDGI
-- AMD FidelityFX Brixelizer and Brixelizer GI —
-  https://gpuopen.com/manuals/fidelityfx_sdk/fidelityfx_sdk-page_techniques_brixelizer/ ,
-  https://gpuopen.com/manuals/fidelityfx_sdk/techniques/brixelizer-gi/ , FidelityFX-SDK v1.1.4
-  `sdk/include/FidelityFX/gpu/brixelizer/`, and
-  https://gpuopen.com/gdc-presentations/2024/GDC2024_GI_with_AMD_FidelityFX_Brixelizer.pdf
-- Godot 4.3 SDFGI — https://docs.godotengine.org/en/stable/tutorials/3d/global_illumination/using_sdfgi.html ,
-  `servers/rendering/renderer_rd/environment/gi.cpp` and `shaders/environment/sdfgi_*.glsl`;
-  HDDAGI — https://github.com/godotengine/godot/pull/86267 , https://github.com/godotengine/godot/pull/119869
-- kajiya GI overview — https://github.com/EmbarkStudios/kajiya/blob/main/docs/gi-overview.md
-- K. Museth, *NanoVDB: A GPU-Friendly and Portable VDB Data Structure for Real-Time Rendering and
-  Simulation*, SIGGRAPH 2021 Talks.
-- M. Fajardo et al., *Stochastic Texture Filtering*, 2023 — the WRS of `sample_discrete_wrs_mat2x4`.
-- M. Pettineo, *SHforHLSL* — https://github.com/TheRealMJP/SHforHLSL (the GGX zonal fit).
-- S. Lagarde and C. de Rousiers, *Moving Frostbite to Physically Based Rendering 3.0*, SIGGRAPH 2014
-  course notes (the dominant direction; the roughness-to-mip curve).
-- *Exploring Ray-Traced Future in Metro Exodus*, GTC 2019 (the L1 YCoCg encoding; in-tree
-  `l1i/NOTES.md`).
-- I. Quílez, distance-field gradients (the tetrahedral 4-tap form) and soft shadows.
-- In-tree: `SHADER_SWITCH_PROPOSAL_2026_10_16.md`, `engine/physics/fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md`,
-  `shadow/vsm/PLAN.md`, `volumetrics/NOTES.md`, `geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md`.