@woosh/meep-engine 3.56.0 → 3.58.0

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

@@ -0,0 +1,2677 @@
+# 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
+   is served by one (§7.6, §7.8).
+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 through an SDF soft shadow, local lights 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, one level each, sampled by
+  `indirect_sample_texture` with each sampler's wrap mode and a stochastic bilinear tap.
+- 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 written by its provider (§7.8);
+- 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 | one jittered ray per texel (stratified), always | no starvation, no second schedule; revisit only on a measured noise problem (§17) |
+| moving-average estimator, 5 u32 per texel | exponential blend over a response time in seconds (§8.8) | DDGI's form; one history; a physical knob |
+| 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 | not in v1 (§17) | a second probe kind; added only if off-screen bounce measures short |
+| 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
+
+From the local source (`H:/Program Files/Epic Games/UE_5.4/Engine`). 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
+
+From the local source. The production reference for §6 and §7.7. Paths are under `Engine/`.
+
+**Mesh distance fields** (`Source/Runtime/Engine/Public/DistanceFieldAtlas.h`,
+`Source/Developer/MeshUtilities/Private/MeshDistanceFieldUtilities.cpp`)
+- 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 `bAffectDistanceFieldLighting` off, are left out: the
+  precedent for the membership bit (D25).
+
+**Composition** (`Source/Runtime/Renderer/Private/GlobalDistanceField.cpp`,
+`Shaders/Private/DistanceField/GlobalDistanceFieldCompositeObjects.usf`,
+`Shaders/Private/MeshDistanceFieldCommon.ush`)
+- 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** (`Shaders/Private/DistanceField/GlobalDistanceFieldObjectGrid.ush`,
+`Shaders/Private/Lumen/LumenSoftwareRayTracing.ush`)
+- 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** (`Source/Developer/MeshUtilities/Private/MeshCardRepresentationUtilities.cpp`)
+- 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 "MinRayZ" 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 MinRayZ ≤ 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** (`Source/Runtime/Renderer/Private/Lumen/LumenSurfaceCache.cpp`,
+`LumenSceneRendering.cpp`, `LumenSceneCardCapture.cpp`)
+- 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 `InvalidateLumenSurfaceCache` on the
+    primitive, or a slow refresh of the oldest pages;
+  - a material change is not tracked.
+
+**Sampling at a hit** (`Shaders/Private/Lumen/SurfaceCache/LumenSurfaceCacheSampling.ush`)
+- 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). By the CVar's own description, 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 | one jittered ray per texel | importance sampling | no starvation, no extra schedule, no CDF |
+| 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_…`, `volumetrics_point_light_shadow` / `_spot_…` | **GENERALISE** the cluster keying from `IRRADIANCE_CLIPMAP_STRUCT` to a `CLIPMAP_LEVEL_ARRAY`; the light and shadow chunks **REUSE** |
+| 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 is Quílez's two-sided one (§7.9) |
+| 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 soft shadow) ─► shade ─► 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 and it is not virtual.
+- Virtual geometry has its own provider (§7.8).
+- 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), which is UE's MinRayZ.
+- 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).
+   - Its random state is seeded from (pair, texel), which fixes its stochastic bilinear tap 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.
+
+**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.
+
+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
+
+`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.
+
+**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
+
+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.
+
+### 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.
+
+**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, √3·s_c)/s_c`: normalised by spacing, so every cascade has the same precision, and clamped at the cage diagonal, 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.
+
+### 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).
+
+   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. **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.
+
+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.
+
+### 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.
+
+### 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 28 B (`PROBE_RAY_STRUCT`) since S4d: `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, three half floats. Trace writes the
+  direct irradiance there and shade writes the radiance over it. The hit's position is the probe's
+  origin plus `t` along the direction, which shading recomputes. (S4c's record held the two suns'
+  visibility in place of the light; S4d moved E_dir into the trace, below.)
+- **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, 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.
+
+### 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`, with shadow
+    from `volumetrics_{point,spot}_light_shadow`.
+  - A light whose shadow map is cleared lights hits unshadowed, which is a stated limit.
+- **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.
+  - 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**, three half floats: 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.
+
+### 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.
+- **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 √3),
+  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 α.
+  - **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 (√3, 3).
+  - Depth samples, in spacings: a miss √3, a back face 0.2·t, a hit t, each held to √3. A depth texel
+    gathers R/n_d² rays, so the GI refuses R > 64·n_d².
+- **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.
+
+## 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.
+
+   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.
+
+### 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.
+
+### 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.
+
+### 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)` | LPV's body with §9.2: albedo·E/π at the hit when confidence > 0.05 |
+| `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).
+
+### 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.
+
+### 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_time`, `retention_time`): 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_time` | 0.5 s | > 0 | temporal time constant τ |
+| `retention_time` | 1 s | > 0 | how long an unwanted probe keeps its slot |
+
+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;
+- 64 instances per cell in the mesh provider, 256 triangles per cell in the vgeo provider;
+- 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.
+  - `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, soft-shadow estimator, 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.**
+
+## 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 | measured follow-ups only (§17) | — |
+
+## 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). The vgeo provider reads its cut per
+  requested cell, 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 √3·s.**
+- **D10. SH2 projected from blended radiance, not blended separately.**
+- **D11. Exponential blend over a response time in seconds; 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.
+  - *Reverse:* if noise or lag measures visible at the defaults, Enshrouded's moving-average
+    estimator, which is the variance-aware form of that boost.
+- **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 SDF soft-shadow rays.** Shadow maps read lit off screen.
+- **D15. Local lights from the world clusters with the shadow-atlas lookups.** A light with a
+  cleared map is 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 (MinRayZ ≤ 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's `bAffectDistanceFieldLighting` is the same switch, and UE 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
+    `InvalidateLumenSurfaceCache` 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).
+- **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.
+- World-cache probes at ray hits (Enshrouded's second kind), if the off-screen bounce measures short.
+- Importance-sampled ray directions, if noise at the defaults measures visible.
+- Ray and history reprojection between probes, if long-range propagation into enclosed spaces
+  measures short.
+- 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 source, under `Engine/`:
+  - the global field: `Source/Runtime/Renderer/Private/GlobalDistanceField.cpp`,
+    `Shaders/Private/DistanceField/GlobalDistanceField*.usf/.ush`, `GlobalDistanceFieldObjectGrid.ush`;
+  - mesh distance fields: `Source/Runtime/Engine/Public/DistanceFieldAtlas.h`,
+    `Source/Developer/MeshUtilities/Private/MeshDistanceFieldUtilities.cpp`,
+    `Shaders/Private/MeshDistanceFieldCommon.ush`, `Shaders/Private/DistanceFieldLightingShared.ush`;
+  - mesh cards and the surface cache: `Source/Developer/MeshUtilities/Private/MeshCardRepresentationUtilities.cpp`,
+    `Source/Runtime/Renderer/Private/Lumen/LumenSurfaceCache.cpp`, `LumenSceneRendering.cpp`,
+    `LumenSceneCardCapture.cpp`, `Shaders/Private/Lumen/SurfaceCache/LumenSurfaceCacheSampling.ush`,
+    `Shaders/Private/Lumen/LumenSoftwareRayTracing.ush`;
+  - the radiance cache: `Source/Runtime/Renderer/Private/Lumen/LumenRadianceCache*.cpp`,
+    `Shaders/Private/Lumen/LumenRadianceCache*.usf/.ush`.
+- 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`.