@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/light/cluster/PROPOSAL_ALGORITHM_2026_10_16.md

@@ -0,0 +1,524 @@
+# Cluster light assignment: the algorithm (proposal, 2026-10-16)
+
+Status: **proposal, nothing built for landing.** This is the algorithmic half of the investigation. The
+structural half (grid dimensioning, output format, pass chain, lights/decals builder merge) belongs to the
+sibling session "cluster-structural". Where an option depends on its choices, both formats are evaluated:
+
+- **Format A**: today's per-cell `{counts, offset}` into a compact list, points then spots.
+- **Format B**: a z-binned format (Drobot 2017): per 2D tile, a bitmask over a depth-sorted light list;
+  per z-bin, the `[min, max]` sorted index.
+
+Every number is labelled **measured** or **predicted**.
+
+- **Measured** means a paired A/B: all arms are interleaved in one process, every arm runs in its own
+  timestamped compute pass, the arm order alternates every iteration, and a fixed ballast pass runs in
+  front.
+- **4090 numbers are relative on that device only.** For modest hardware there are **measured** numbers
+  from this machine's **AMD Radeon iGPU** (RDNA2, 2 CUs, shared DDR5), reached from headless Chrome with
+  `--use-adapter-luid=0,120673`. The register, occupancy and scratch figures come from the NVIDIA 610.88
+  and AMD 2.0.302 Vulkan drivers, compiling Tint's own SPIR-V.
+
+## 0. Summary
+
+1. **At zero lights, 89–98% of today's cost is zeroing the private list.** That list is
+   `var local_lights = array<u32, 256>()`: 1 KiB of local memory per thread, written before any light is
+   tested. Removing it takes 4K on the 4090 from 237 µs to 5.7 µs, and 1898×982 on the iGPU from 951 µs to
+   101 µs. Rebuilding the frustum and mapping the slice costs 2–3 µs on the 4090 and 80–390 µs on the iGPU,
+   but only becomes visible once the array is gone. The global atomic costs 0–7%.
+2. **Defect: the last z-slice takes every spot light.** That slice's far plane sits at FLT_MAX, so the
+   cell's corner bounding sphere stops being finite and the cone test can no longer reject anything. This
+   accounts for 85% of all pairs with 16 lights, and 42% with 1,024, where it fills those 1,860 cells to the
+   cap of 128. The fix (`A0fix`) is local, and is measured below.
+3. **Today's pass does not survive many lights on modest hardware.** At 1898×982 with 1,024 lights it
+   takes 0.95–1.5 ms on the 4090 and **61 ms on the iGPU**.
+4. **Recommended Format A path: A2, cooperative coarse-to-fine, cell-centric.** A small O(L) light prepass
+   sorts the culled list by (type, id) and writes a view-space record and a cell-space box per light. Each
+   4×4×4 workgroup then culls the list against its own box, 64 lights at a time, compacts the survivors in
+   order into workgroup memory, and every thread fine-tests only those.
+   - Zero lights cost the per-cell floor plus the prepass: 5–6 µs on the 4090, 5–78 µs on the iGPU.
+   - 1,024 lights cost 56–75 µs on the 4090 and 0.12–2.4 ms on the iGPU.
+   - All dispatches are direct, and the output is deterministic in both set and order.
+5. **Light-centric assignment (L1) scales best on the 4090 but loses on the iGPU.** On the 4090 it takes
+   41 µs at 1,024 lights and 85 µs at 4,096 (1898×982). On the iGPU it costs 0.9–4 ms, because the cost of
+   its per-cell atomics dominates there. It also needs three indirect dispatches, which Chrome prices at
+   about 105 kcyc each on its GPU process.
+6. **If cluster-structural picks Format B, its build is the cheapest measured, and its zero-light cost
+   does not scale with resolution at all.** The build takes 5–9 µs at zero lights on both GPUs and at every
+   resolution, and 27–93 µs on the 4090 at 1,024–4,096 lights. Which way to build the tile masks depends on
+   the device (§3.5).
+7. **Test tightness:** at 1,024 lights the shipped tests admit 3.0× the exact pairs, and 16× for spots.
+   The light-box pretest brings that to 1.66×. On a ground-plane G-buffer, light evaluations per pixel go
+   from 31.4 (today, slice fixed) to 19.1 (pretest) and 17.3 (pretest plus UE's cone plane), against 10.3
+   exact.
+
+## 1. The measured baseline, by term
+
+**The pass as built.** One thread per cell in 4×4×4 groups: 32 px tiles × 24 exponential slices,
+5,760 / 44,640 / 195,840 cells at 640×360 / 1898×982 / 3840×2160.
+
+Correction to the brief: **the per-cell frustum is not built from corners.** `frustum_slice` blends the
+camera's normalized planes pairwise (`frustum_plane_pair_lerp`) and normalizes six planes. The corner chain
+does run, but **per spot light, per cell**:
+
+> `spot_light_intersects_frustum` → `cone_intersects_frustum` → `frustum_to_bounding_sphere` →
+> `frustum_to_corners`, which is 8 three-plane intersections.
+
+`frustum_from_corners`, `plane_from_triangle` and `cluster_slice_frustum` are linked but never called.
+Every pair also re-reads and re-marshals the light record from the paged database (12 words for a point
+light, 17 for a spot).
+
+### 1.1 Zero lights: ablation arms (p10, µs)
+
+Arms are cumulative or single removals from the shipped WGSL, by string edit. All of them produce identical
+output at zero lights.
+
+| arm | 4090 640×360 | 4090 1898×982 | 4090 4K | iGPU 640×360 | iGPU 1898×982 | iGPU 4K |
+|---|---:|---:|---:|---:|---:|---:|
+| A0 shipped | 4.1 | 36.9 | 236.5 | 132.1 | 950.7 | 3,769 |
+| − atomic (taken only when the cell has lights) | 3.1 | 38.9 | 220.2 | 132.6 | 969.3 | 3,801 |
+| − slice mapping (exp2 + inverse lerp) | 4.1 | 38.9 | 221.2 | 127.6 | 945.2 | 3,658 |
+| − frustum rebuild and slice mapping | 4.1 | 34.8 | 229.4 | 124.4 | 951.4 | 3,780 |
+| − private array (256 → 2 entries) | 2.0 | 4.1 | 5.7 | 17.4 | 101.0 | 468.9 |
+| − array − atomic − frustum | 1.0 | 2.0 | 3.1 | 9.8 | 21.3 | 78.5 |
+| floor (bounds, index, write `{0,1}`) | 1.0 | 1.0 | 2.0 | 1.6 | 9.8 | 31.9 |
+
+**Terms at 1898×982**, rounded: 4090 37 µs and iGPU 951 µs in total.
+
+| term | 4090 | iGPU |
+|---|---:|---:|
+| array zero-init | 33 µs (89%) | 850 µs (89%) |
+| frustum rebuild and slice mapping, after the array is gone | 2 µs | 80 µs |
+| atomic | ≤ 3% (noise) | ≤ 3% (noise) |
+| floor | 1 µs | 10 µs |
+
+At 4K the array is 98% of the 4090 time and 88% of the iGPU time.
+
+**Why the array costs this much.** It is pure memory traffic: 195,840 threads × 1 KiB = 200 MB of stores
+at 4K, and 237 µs is about 0.85 TB/s, the 4090's DRAM rate.
+
+The private list adds no registers, it adds scratch:
+
+| | 4090 regs | 4090 local mem | 4090 occupancy | AMD VGPRs | AMD scratch |
+|---|---:|---:|---:|---:|---:|
+| A0 with the list | 72 | 1,024 B | 58% | 72 | 1,344 B |
+| A0 with a 2-entry list | 80 | 0 | 50% | 88 | 0 |
+
+The rest of the register pressure comes from the light loop. The spot test's corner rebuild sits inside
+it.
+
+### 1.2 With lights (p10)
+
+| | 4090 640×360 | 4090 1898×982 | 4090 4K | iGPU 640×360 | iGPU 1898×982 | iGPU 4K |
+|---|---:|---:|---:|---:|---:|---:|
+| A0, 16 lights | 11.3 µs | 45.1 µs | 232 µs | 156 µs | 1.11 ms | 4.0 ms |
+| A0, 1,024 lights | 1.17 ms | 0.95–1.49 ms ¹ | 3.81 ms | 8.2 ms | 61.3 ms | 257 ms |
+| A0, 4,096 lights | 2.90 ms | 3.86 ms | 11.65 ms | 36.4 ms | 276 ms | — |
+| A0fix, 1,024 lights | 1.03 ms | 0.62–1.42 ms ¹ | 3.49 ms | 6.7 ms | 51.7 ms | 218 ms |
+
+¹ The p10 moved between runs. Another GPU client was time-slicing with these runs (§6), so p10–p50 is
+given.
+
+### 1.3 The last-slice spot defect (measured)
+
+**Mechanism.** Slice 23's far depth is `cluster_depth_from_z_slice(24)`, which is FLOAT32_MAX. Its corners
+come out non-finite, `cone_intersects_sphere` then compares against NaN, and every rejection is false. So
+every spot light lands in all 1,860 cells of slice 23 at 1898×982:
+
+| | spot pairs from this alone | share of all pairs |
+|---|---:|---:|
+| 8 point + 8 spot lights | 14,880 | 85% (of 17,476) |
+| 512 point + 512 spot lights | 238,080 | 42% (of 572,545) |
+
+At 1,024 lights every one of those cells sits at the cap of 128 spot lights, so a far pixel shades up to
+128 spot lights that cannot reach it.
+
+**The fix (`A0fix`).** For an unbounded cell, test the cone's own bounding sphere against the cell's
+planes. This removes exactly those pairs (0 other cells change) and is 4–20% faster.
+
+## 2. Survey
+
+Every entry below is **VERIFIED**, read at a pinned commit, unless tagged **SECONDARY**. The raw copies are
+in the scratchpad `src/`.
+
+### 2.1 Unreal Engine 5.4 (`LightGridInjection.usf/.cpp`, read in the installed source)
+
+- **Thread mapping:** one thread per cell, `THREADGROUP_SIZE` 4, so 4×4×4 groups. The grid is 64 px tiles ×
+  32 slices.
+- **No parent or coarse grid in 5.4.**
+- **Cell bounds:** the view-space AABB of the cell's 8 corners (`ComputeCellViewAABB`). Lights are moved to
+  view space on the CPU.
+- **Test:** `ComputeSquaredDistanceFromBoxToPoint` < r². For spot lights, one separating plane through the
+  apex facing the AABB centre (`IsAabbOutsideInfiniteAcuteConeApprox`).
+- **Iteration:** brute force over every local light, per cell.
+- **Default output, the linked list** (`r.Forward.LightLinkedListCulling=1`):
+  - per hit pair: an `InterlockedAdd` on one global counter, plus an `InterlockedExchange` on the cell's head;
+  - then `LightGridCompactCS`, on the same grid, walks each list, allocates with one global
+    `InterlockedAdd` (the LDS pre-aggregation is off by default), and writes the list reversed to restore
+    list order.
+- **Non-linked mode:** per-cell `InterlockedAdd` into 32 fixed slots.
+- **Zero lights:** no gate beyond the whole-feature one.
+- **The far end of the z distribution is the furthest light,** computed on the CPU.
+
+### 2.2 The other engines
+
+| | iteration order | hierarchy | test | output, allocation, overflow | order | zero lights |
+|---|---|---|---|---|---|---|
+| Bevy (GPU path, now the default) | Light-centric by **rasterisation**: one quad per (light, z-slice), so one fragment per (cluster, light) | none | sphere vs cluster AABB; spot: Wronski cone | per cluster offset + per-type counts; Hillis–Steele scan, then a single workgroup walks the chunks; fill by `atomicAdd`. Global list grows after a CPU readback | non-deterministic | allocation passes still run over every cluster |
+| Filament (CPU, 8 jobs) | per light; private per-froxel bitsets, no atomics | none | projected AABB → froxel ranges, refined per slice and row; spot: cone vs froxel sphere | `offset<<16 \| count`, u8 records, neighbour dedup; on overflow, **over-inclusive** "all lights" record; cap 255 lights | deterministic, not ascending | skipped |
+| Godot 4 | Light-centric by **rasterising proxy meshes** at 1/4 res with 4×MSAA, `atomicOr`, subgroup-elected writer | none | the proxy mesh | per 32 px tile: element bitmask + **32 linear z-bins of `[min, max)`**, i.e. Drobot's scheme per tile; cap 512 per type, farthest dropped | deterministic, distance-sorted | skipped |
+| Unity HDRP | Big tile, then per 32 px tile: 64 threads build the coarse list; then **thread i = z-cluster i** loops over the coarse lights | **64 px big-tile list (≤ 511)** feeds 32 px clusters | screen AABB, sphere vs tile cone, exact edge tests; per cluster, 6 hull planes vs 8 corners | compact list via global `InterlockedAdd`; 26-bit offset + 6-bit count (63); caps 511 / 128 | **sorted to keep the lowest 128** ("prevent unpredictable light list"); big-tile overflow is racy | gated |
+| Wicked | per 32 px tile workgroup, threads take different entities, groupshared `InterlockedOr` | none | sphere vs tile frustum and AABB; 2.5D 32-slice depth mask | per-tile flat bitmask (256 entities); no allocation | racy at the cap | dispatch skipped, UAV cleared |
+| Drobot 2017, CoD:IW (**SECONDARY**, slides) | z-binning; tile masks by rasterising proxies with MSAA as conservative raster | — | — | sort lights by z; uniform bins with a 2×16-bit min/max LUT; 8×8 px tiles with 256-bit masks; the shader restricts its words to the bin range | — | — |
+
+Frostbite/BF3 tiled deferred (Andersson 2011) was **not checked**.
+
+**What the survey says for this decision:**
+
+- Nobody ships today's shape *plus* a 1 KiB private list.
+- The engines whose cost follows the lights do it by **light-centric scatter**. Bevy and Godot get the
+  scatter from the rasteriser, Filament from CPU bitsets.
+- HDRP keeps cell-centric threads but makes them **hierarchical**, and deliberately sorts so it keeps the
+  lowest indices. That is meep's keep-smallest rule.
+
+## 3. Proposals, ranked
+
+### 3.0 Shared prepass (O(L), used by A1/A2/A3/L1/Z1/Z2)
+
+Three dispatches, all direct. They are sized by the CPU-known clusterable light count, and every thread past
+the culled count read on the GPU exits.
+
+1. **mark:** each culled tuple ORs one bit into a per-type visibility bitmask sized by the table extent.
+2. **compact:** one 256-thread workgroup scans the popcounts with a subgroup scan, giving a list **sorted by
+   (type, id)**. Per-thread budget: 2 words = 64 bits. The 16,384 lights this covers are exactly the cull
+   list's own limit, so one workgroup always suffices. It self-clears the mask.
+3. **lights:** per sorted light:
+   - reads the database record **once**;
+   - writes a view-space record (sphere, apex/height, direction/cos, source radius);
+   - writes a packed cell-space box: tile x/y from the exact tangent extents of the bound sphere, z from
+     `cluster_depth_to_z_slice`.
+
+   The spot bound is the bounding sphere of the flat-capped cone that the shipped test uses.
+
+**Measured cost:** 3.1 µs at zero lights to 8.2 µs at 4,096 lights (4090), and 1.8–24 µs (iGPU), at any
+resolution.
+
+**Why sort.** Sorting turns keep-smallest into "the first CAP hits in list order", and makes the written
+order deterministic. Today the *order* within a cell follows the cull pass's `atomicAdd`, and only the
+overflow *set* is deterministic.
+
+### 3.1 Recommended for Format A — A2: cooperative coarse-to-fine, cell-centric
+
+**Mechanism.** The workgroup is a 4×4×4 coarse cell. For each chunk of 64 sorted lights:
+
+1. thread i tests light i's cell box against the group's box;
+2. the survivors are compacted **in order** into `surv[64]` (subgroup exclusive add plus per-subgroup
+   offsets) — 520 B to 1 KiB of workgroup memory;
+3. every thread runs box + precise tests on the survivors only, counting against the per-type cap of 128.
+
+Then the subgroup-aggregated allocation (one atomic per subgroup, skipped when the subgroup total is 0),
+then a second sweep that writes. There is no private array.
+
+**Scaling.**
+
+- O(C/64 · L) cheap integer box tests, plus O(C · survivors) precise tests.
+- Zero lights: O(C) floor plus the prepass.
+- Per-thread loops: L/64 chunks (≤ 256 at the cull limit) × ≤ 64 survivors.
+- **Doc line for the budget:** past the per-type cap the largest sorted indices are dropped, exactly as
+  today.
+
+**Cost (measured, p10).**
+
+| | 4090 640×360 | 4090 1898×982 | 4090 4K | iGPU 640×360 | iGPU 1898×982 | iGPU 4K |
+|---|---:|---:|---:|---:|---:|---:|
+| 0 lights | 5.1 µs | 5.1 µs | 6.1 µs | 5.3 µs | 21.8 µs | 77.8 µs |
+| 16 lights | 9.2 µs | 9.2 µs | 10.2 µs | 14.1 µs | 70.8 µs | 271 µs |
+| 1,024 lights | 74.8 µs | 56.3 µs | 58.4 µs | 119 µs | 621 µs | 2.43 ms |
+| 4,096 lights | 303 µs | 222 µs | 239 µs | 511 µs | 2.68 ms | — |
+
+**Against the shipped pass at 1,024 lights:** 15–66× faster on the 4090 and 69–106× on the iGPU.
+
+**Registers:**
+
+| | regs | local mem | shared mem | occupancy |
+|---|---:|---:|---:|---:|
+| 4090 | 48 | 0 | 520 B | 83% |
+| AMD | 41 VGPR | 0 scratch | 1 KiB LDS | 10 waves (predicted, wave64) |
+
+**Output** is **identical** to A1 and to L1 in every cell (§4). It is a strict subset of `A0fix`: the box
+pretest only removes pairs.
+
+**Reuse map.**
+
+| piece | existing machinery | duplication found |
+|---|---|---|
+| sorted culled list | the prepass mark/compact replaces the cull's append order; it could be written by `shader_cull_lights_hzb` directly (pass chain → structural); the general n scan is `graph_prefix_scan_csdldf` | `NOTES.md` TODO "sort lights by type" |
+| per-light record + box | `chunk_point_light_to_aabb3` / `chunk_spot_light_to_aabb3`, `chunk_cone_to_bounding_box`, `chunk_cluster_depth_to_z_slice`, `chunk_sphere_screen_extents` (exists; one caller; written for +z forward) | today every cell re-marshals every record |
+| cell planes | replaces `frustum_slice` + `plane_normalize`: four eye-plane normals from the tile's NDC edges, two depths from `chunk_cluster_depth_from_z_slice` | `frustum_to_corners` per spot *pair* goes |
+| precise tests | `chunk_sphere_intersects_frustum` semantics; `chunk_cone_intersects_sphere` verbatim, with the cell's bounding sphere computed **once per cell**, not per pair | `frustum_to_bounding_sphere` per pair |
+| ordered compaction | subgroup ballot / exclusive add, the pattern of `chunk_subgroup_active_count_bits`; `workgroupUniformLoad` | — |
+| allocation | `chunk_vsm_append_mover` (subgroup exclusive add + elect + broadcast) | — |
+| decals | `shader_cluster_assign_decals` is the same shape, with a sorted 32-entry private array and keep-largest | the cell setup is duplicated line for line |
+
+**Risks.**
+
+- **Determinism:** the set and the order are both a function of the scene.
+  - One measured caveat: at the cap, A2/A3 can keep a near-smallest set instead of the smallest (A1 vs A3
+    differed in one cell, stable across runs). Corrected in round 3: the 4×4×4 workgroup's subgroup lanes
+    are permuted against `local_invocation_index`, so the subgroup-scan compaction is deterministic but not
+    ascending within 32-light windows. It is not codegen. Fix and measurements: `PROPOSAL_HIERARCHICAL_2026_10_16.md` R3.1.
+- **Overflow:** keep-smallest per type, unchanged.
+- **Consumers:** none change.
+- **Weak spot:** the O(L/64) coarse loop. At 4,096 lights A2 is 220–300 µs (4090) and 2.7 ms (iGPU,
+  1898×982), and the cull limit of 16,384 would be about 4× that (**predicted**). At low resolution there
+  are few groups, so it is latency-bound: 303 µs at 640×360 vs 222 µs at 1898×982.
+
+**Known cheap refinement (unmeasured).** Build the cell's bounding sphere lazily, on the first spot
+survivor. On the iGPU, A2 with 16 lights is 71 µs against a 22 µs zero-light cost, and that difference is
+mostly per-cell setup.
+
+### 3.2 A1 — the minimal Format A fix
+
+**Mechanism.** A0's single loop over the sorted list, with the box pretest, count-then-write, and no private
+array.
+
+**Measured.**
+
+- Zero lights: 5–6 µs (4090) and 6–65 µs (iGPU).
+- 1,024 lights: 173–252 µs (4090) and 0.65–19 ms (iGPU).
+- 4,096 lights: 1.3–2.0 ms (4090).
+
+Registers 46 (83%) on NVIDIA; 34 VGPR, 12 waves on AMD.
+
+It fixes the zero-light term and nothing else. **It keeps a per-thread loop over all L, which has no
+budget.** A2 beats or ties it everywhere except zero lights on the iGPU (18.5 vs 21.8 µs at 1898×982, 65 vs 78 µs at 4K). It is listed only as the smallest diff.
+
+### 3.3 A3 — light-centric coarse bitmask plus A2's fine pass (measured negative on the 4090)
+
+**Mechanism.** One workgroup per light ORs its bit into a per-coarse-cell mask (direct dispatch; budget
+coarse cells/64, which is 48 at 4K). The fine pass skips empty word pairs.
+
+**Measured.**
+
+- 4090: matches A2 or loses — 935 vs 303 µs at 640×360 with 4,096 lights. Only 90 coarse cells means
+  heavy `atomicOr` contention.
+- iGPU: **beats** A2 — 468 vs 621 µs (1898×982, 1,024 lights), 1.67 vs 2.43 ms (4K, 1,024), 2.11 vs 2.68 ms
+  (1898×982, 4,096).
+
+So it is device-dependent, and not recommended as the default.
+
+### 3.4 L1 — light-centric pairs (Format A, exact allocation)
+
+**Mechanism.**
+
+1. Scan the per-light candidate cell counts. One workgroup at the cull limit.
+2. **pairs** (indirect): one thread per (light, cell) candidate. A binary search finds the light. Precise
+   test; per-cell `atomicAdd` count; first-hit cell appended to an occupied list; hit appended. Both
+   appends are subgroup-aggregated.
+3. A one-thread args pass.
+4. **alloc** (indirect, over occupied cells only).
+5. **fill** (indirect, over hits).
+6. The metadata is cleared first: O(C), 8 B per cell.
+
+**Scaling.** O(L + candidates + occupied + hits), plus the O(C) clear. No per-thread loop over L. Candidates
+at 1,024 lights: 194k at 1898×982 and 857k at 4K, of which 95% hit. Today's cell-centric pass does 45.7M
+and 200M tests for the same.
+
+**Measured (p10).**
+
+| | 4090 640×360 | 4090 1898×982 | 4090 4K | iGPU 1898×982 | iGPU 4K |
+|---|---:|---:|---:|---:|---:|
+| 0 lights | 17.4 µs | 17.4 µs | 18.4 µs | 23.0 µs | 44.8 µs |
+| 1,024 lights | 31.7 µs | 41.0 µs | 77.8 µs | 923 µs | 4.05 ms |
+| 4,096 lights | 46.1 µs | 85.0 µs | 246 µs | 3.96 ms | — |
+
+**Its zero-light floor is Chrome's.** Every indirect dispatch gets Dawn's validation pass (see
+`gpu_primitive/indirect/NOTES.md`).
+
+**On the iGPU,** pairs and fill cost 381 + 502 µs at 1898×982 with 1,024 lights. Global atomics are the
+iGPU's weakness.
+
+**CPU price (predicted from the measured frame-anatomy prices):** 3 indirect dispatches × ~105 kcyc plus
+5 extra dispatches × ~4 kcyc, about **335 kcyc of Chrome's GPU-process thread per frame**. That is about
+2.5% of the 13.6 Mcyc simple-cube frame. For comparison, A2 adds about 12 kcyc.
+
+**Engine-wide lesson (measured).** On D3D12, Tint lowers `atomicLoad` to `InterlockedOr(x, 0)`, a
+read-modify-write. Every thread reading a shared counter that way serializes on one address:
+
+| | `atomicLoad` | plain read-only view |
+|---|---:|---:|
+| fill, 819k threads | 411 µs | 31 µs |
+| alloc | 34 µs | 6 µs |
+
+Read counters through a plain read-only view.
+
+**Risks.**
+
+- **Overflow:** a cell past the per-type cap keeps whichever hits arrive first. That is non-deterministic;
+  37 cells at 640×360 with 4,096 lights differed from A1. Keeping keep-smallest needs a fix-up pass for
+  overflowing cells only (rare path, unmeasured).
+- **Order** within a cell is non-deterministic. Today's order already is.
+
+### 3.5 Format B build — Z1 (atomic scatter) / Z2 (tile-centric ballot)
+
+**Mechanism.**
+
+- Depth sort of the culled lights (single-workgroup bitonic of ≤ 4,096 keys in 16 KiB, as the small-n path;
+  `graph_radix_sort` beyond).
+- 1,024 linear z-bins, written by `atomicMin`/`atomicMax` per (light, bin), budget bins/64.
+- Per-tile masks:
+  - **Z1:** one workgroup per light ORs its tiles (budget tiles/64, 128 at 4K).
+  - **Z2:** one thread per (tile, light); the subgroup ballot is the word. No atomics.
+- Z1 and Z2 produce **bit-identical masks**.
+
+**Measured build (p10).**
+
+| | 4090 1898×982 Z1 | 4090 1898×982 Z2 | 4090 4K Z1 | 4090 4K Z2 | iGPU 1898×982 Z1 | iGPU 1898×982 Z2 | iGPU 4K Z1 | iGPU 4K Z2 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| 0 lights | 8.2 µs | — | 7.2 µs | — | 5.3 µs | — | 5.9 µs | — |
+| 1,024 lights | 29.7 µs | 41.0 µs | 39.9 µs | 87.0 µs | 183 µs | 452 µs | 2.97 ms | 1.78 ms |
+| 4,096 lights | 65.5 µs | 115 µs | 93.2 µs | 302 µs | 4.0 ms | 1.89 ms | — | — |
+
+**Scaling.** O(L log L + Σ tiles per light + Σ bins per light). **The zero-light cost has no cell or tile
+term at all:** W = 0 words, and only the bins are cleared.
+
+**The consumer side** (shading reads the bin range, then the masked words) is **not measured here**. That
+is cluster-structural's.
+
+**Risks.**
+
+- **Overflow:** none in the format. The mask holds all lights up to the cull limit.
+- **What a shading-loop budget drops:** the **farthest in depth order**, deterministically. That replaces
+  keep-smallest-id: keep-nearest is a different rule (fork F3).
+- **Z1 vs Z2 is not a light-count threshold.** It follows atomic throughput (4090: Z1 always; iGPU: crossover
+  between 1,024 and 4,096 at 1898×982). That makes it a per-device choice, not something derivable from
+  workgroup size or LDS.
+
+### 3.6 Write-out options, measured where it mattered
+
+- **Per-thread global `atomicAdd` → subgroup-aggregated** (one per subgroup, skipped at a zero total):
+  ≤ 3% of today's pass. The driver path already copes. It is the default in A1/A2/A3/L1 because it is free.
+- **Fixed per-cell slots** (UE non-linked) would delete the allocation entirely. **Predicted** memory:
+  today's `cluster_data` is already about 64.5 entries per cell (50 MB at 4K), but 2 × 128 slots per cell
+  would be 200 MB. Not pursued.
+- **Prefix-scan compaction** (CSDLDF) is needed only for L1's candidate offsets. One workgroup covers the
+  cull limit.
+
+## 4. Test tightness (counting arm, 1898×982, 512 point + 512 spot lights)
+
+**How "exact" was computed.**
+
+- **Points:** Dykstra projection of the centre onto the cell's six half-spaces, distance < r.
+- **Spots:** sampling 7³ points of the cell against the spherical sector plus the source sphere. This is a
+  **lower bound**.
+
+**Validation.** The JS planes test reproduces the GPU's `A0fix` count exactly (334,465), and A1 contains
+**every exact pair** (0 missing).
+
+| test | point pairs | spot pairs | total | × exact | light evals / shaded pixel (ground plane) |
+|---|---:|---:|---:|---:|---:|
+| A0 shipped (with the last-slice defect) | — | — | 572,545 | 5.1 | 32.3 |
+| A0fix: sphere vs 6 planes; spot cone vs cell bounding sphere | 131,096 | 203,369 | 334,465 | 3.0 | 31.4 |
+| UE 5.4: range sphere vs cell view-AABB + one-plane cone | 145,327 | 71,023 | 216,350 | 1.9 | 18.7 |
+| A1/A2/L1: A0fix ∧ light cell box | 131,096 | 53,837 | 184,933 | 1.66 | 19.1 |
+| A1 + UE's one-plane cone on spots | 131,096 | 39,361 | 170,457 | 1.53 | 17.3 |
+| exact (points) / sampled (spots) | 99,143 | ≥ 12,555 | ≥ 111,698 | 1 | 10.3 |
+
+**Reading it.**
+
+- For points, the box pretest adds nothing (131,096 both ways). The remaining 32% are 6-plane corner false
+  positives, and the cell AABB is *looser* than the planes (145k).
+- For spots, the corner bounding sphere of a long cell is the problem: 16× exact. The box cuts it 3.8×, and
+  the cone plane another 27%.
+
+**Shading cost.** Counted only: −45% light evaluations per pixel (31.4 → 17.3). The time is **unmeasured**:
+it needs the real deferred pass. With 16 lights the evaluations go 0.23 → 0.13 (exact 0.08).
+
+## 5. Forks for Alex
+
+- **F1. Format A path: A2 alone (recommended), or A2 plus L1 as a large-n path.** The crossover is
+  device-specific: on the 4090, L1 overtakes A2 between 16 and 1,024 lights; on the iGPU A2 stays ahead to
+  4,096 or more. So a threshold cannot be derived from workgroup size or LDS. Running both would mean
+  dispatching both every frame (the count lives on the GPU) and paying L1's indirect price on the CPU every
+  frame. *Recommendation:* A2 as the single Format A path. Its budget is stated (L/64 chunks, ≤ 256 at the
+  cull limit); beyond that, Format B is the scalable answer.
+- **F2. Land the two local fixes ahead of either redesign?** Both are small and measured:
+  - the last-slice spot fix, `A0fix`: −42% of pairs at 1,024 lights, up to 128 spot evaluations less per far
+    pixel;
+  - removing the private list (A1's count-then-write over a sorted list): zero-light 237 → 6 µs on the 4090
+    at 4K, 3.8 → 0.07 ms on the iGPU.
+
+  *Recommendation:* yes, the slice fix now. The list removal ships as part of A2 rather than as A1, because
+  A1's own loop is unbudgeted.
+- **F3. If Format B: keep-nearest instead of keep-smallest-id.** Under a loop budget, z-binning drops the
+  farthest by depth rank, deterministically. *Recommendation:* accept. It is deterministic, and it is the
+  better visual loss. This needs cluster-structural's format call first.
+- **F4. Spot test.** Add UE's one-plane cone refinement to the precise spot test (−27% spot pairs, cheap),
+  and drop the per-pair corner rebuild in any case. *Recommendation:* yes. Leave the points' 6-plane test
+  as is: the AABB is looser and exact distance costs too much per pair.
+- **F5. Who sorts the culled list.** The prepass mark/compact can be folded into `shader_cull_lights_hzb`,
+  which would write visibility bits instead of appending. That is cluster-structural's pass chain.
+  *Recommendation:* fold it, so the bench's 3 prepass dispatches become 1.
+
+## 6. Method, data, caveats
+
+- **Arms.** One bench page on this worktree's vite (:5317). It uses:
+  - the **shipped** WGSL (`shader_cluster_assign_lights.pipeline`, the same module the frame-anatomy report
+    dumped, SPIR-V bound 1188);
+  - the real `GPUDatabase` + `LIGHT_DATABASE_SPEC` records;
+  - the engine's `PerspectiveCamera` (fov 45°, near 0.1, far 2000, reverse-Z infinite);
+  - `update_frustum_far_plane` and `build_light_cluster_parameters`.
+
+  The culled list is shuffled to mimic the cull's append order.
+- **Scene.** Lights at view depth 2–120 m, NDC xy ±1.1, range 1.5–6 m. Spots point within 60° of down, with
+  half-angles of 15–45°. The scene is synthetic, so the numbers are relative between arms, not a forecast for
+  a game.
+- **Correctness checks.**
+  - A1 ≡ A2 ≡ L1 per cell at every configuration checked.
+  - A3 ≡ A1 except the one lane-order cell noted in §3.1.
+  - Z1 ≡ Z2 masks (one bin word differed).
+  - Every prototype's set is a subset of `A0fix`'s.
+- **Timing.**
+  - 200 iterations on the 4090, 30 on the iGPU (one submit per iteration there, for TDR safety).
+  - Statistic: p10 of per-iteration pass durations. p50, p90, means and paired ratios are in the JSON.
+  - Timestamps are unquantized but come in 1.024 µs steps on the 4090.
+  - **Caveat:** a peer session's headless Chrome (`H:\tmp\vrsp-*`) was time-slicing the 4090 through most
+    runs (50–98% utilization). The ballast's own time varied 300–1,000 µs, and the long arms show bimodal
+    p50/p90. The p10 values reproduced across 2–3 runs, within the 1 µs quantum for small arms and about 10%
+    for large ones, except A0 at 1898×982 with 1,024 lights (0.95–1.49 ms). The iGPU had no other client.
+- **Offline compilers.** Dawn `dump_shaders` on SwiftShader, binaries recovered from `DawnWebGPUCache`
+  (28/28 matched), then `vkstats.py` on both drivers. Robust buffer access is on, as in Chrome.
+
+### Register / scratch table (NVIDIA 610.88 Vulkan; AMD 2.0.302 Vulkan)
+
+| pipeline | threads | NV regs | NV local | NV shared | Ada occupancy | AMD VGPR | AMD SGPR | AMD scratch | AMD LDS |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| A0 shipped | 64 | 72 | 1,024 | 1,792 | 58% | 72 | 48 | 1,344 | 0 |
+| A0fix | 64 | 72 | 1,024 | 1,792 | 58% | 73 | 48 | 1,344 | 0 |
+| A0 − array | 64 | 80 | 0 | 0 | 50% | 88 | 48 | 0 | 0 |
+| A1 | 64 | 46 | 0 | 0 | 83% | 34 | 62 | 0 | 0 |
+| A2 | 64 | 48 | 0 | 520 | 83% | 41 | 68 | 0 | 1,024 |
+| A3 fine | 64 | 48 | 0 | 528 | 83% | 41 | 70 | 0 | 1,024 |
+| prep_lights / compact / mark | 64 / 256 / 64 | 27 / 20 / 16 | 0 | 0 / 512 / 0 | 100% | 30 / 18 / 3 | — | 0 | 0 / 512 / 0 |
+| L1 pairs / alloc / fill / scan | 256 / 64 / 256 / 256 | 36 / 16 / 16 / 20 | 0 | — | 100% | 34 / 10 / 5 / 72 | — | 0 | — |
+| Z1 sort / scatter; Z2 tiles | 256 / 64; 64 | 25 / 21; 16 | 0 | 16,384 / 0; 0 | 83% / 100% | 26 / 8; 4 | — | 0 | 16,384 / 0 |
+
+Ada occupancy uses the frame-anatomy report's formula. AMD waves per SIMD are **predicted** for wave64:
+A0 7, A1 12, A2 10.
+
+**Cross-check with cluster-structural** (its numbers, from its notes; different scene and harness).
+
+- **Zero-light private-array finding: agrees.** The shipped pass goes 49.2 → 4.1 µs at 1080p and
+  221 → 6.1 µs at 4K with the array shrunk.
+- **Its R1 on the same iGPU, 512 lights:** about 0.6 ms at 1080p and 2.7 ms at 4K. The per-cell expansion
+  into Format A takes 520 / 2,345 µs of that.
+- **That is the same range as A2 here at 1,024 lights:** 0.62 ms at 1898×982 and 2.43 ms at 4K.
+- **On a 2-CU iGPU, writing Format A per cell is the dominant term of both designs.** Only a format whose
+  consumers read tile/bin data directly removes it.
+
+**Data and scripts** (scratchpad copies, never in the repo): `H:/tmp/clusteralgo/bench/`.
+
+- `bench.js`, `arms.js`, `a3.wgsl.js`, `patch_z2.cjs`: the arms;
+- `drive.mjs`, `job_*.js`: the drivers;
+- `results/{nv_full,amd_full,z2_nv,z2_amd,steps*,amd_steps,count_*}.json`;
+- SPIR-V dumps and stats in `H:/tmp/clusteralgo/{dumps,vkstats.json}`;
+- the iGPU is selected with `--use-adapter-luid=0,120673`; `luid.py` lists the LUIDs.