@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/shader/compiler/SHADER_SWITCH_PROPOSAL_2026_10_16.md

@@ -0,0 +1,932 @@
+# Shader switches: a proposal (2026-10-16, revision c; stages 1 and 2 landed)
+
+**Status: stages 1 and 2 are on master (2026-10-16). Stage 3, declared bindings, is built in a worktree, uncommitted
+(§12.3).**
+
+§0 records your decisions, §4–§6 the design and its stages, and §12 what each stage contains and how it was checked. Revisions (a) and (b) are superseded by your answers.
+
+## 0. Decided so far
+
+From your answers of 2026-10-16:
+
+- **D1 — a switch is an integer.** A boolean is a switch of two values. A shader depends on several switches. A
+  switch is a value, not a chunk, and one switch may be decided at several places in the graph. (Confirmed.)
+- **D2 — a switched shader specializes to a static graph.** A switched shader and an immutable set of switch values
+  become an ordinary, fully static `CodeChunk` graph. The shader object caches its variants by the set.
+  `GraphicsContext` knows nothing of switches.
+- **D3 — every switch defaults to 0.**
+- **D4 — code first, the kludges fixed after.** In the first stage, alternatives differ in code only. The long-term
+  design still has to remove the existing kludges, resources included, and a refactor is fine.
+
+From your answers to revision (b):
+
+- **D5 — resources: one interface per definition (§5.2).** It is the union of its alternatives' bindings, bound by
+  name, with defaults for what a mode lacks. Stage 3's declared bindings are wanted later; they will change the shape
+  of a shader class a little.
+- **D6 — no flip machinery.** Pipelines made on first use compile synchronously, as they do today. A flip compiles the
+  new variants then, and nothing extra is built for it.
+- **D7 — a variant's label carries its set:** `Shade From G-Buffer [shadow directional technique=Virtual]`.
+- **D8 — no interface declaration.** A choice never inspects its alternatives, and the parent never white-boxes what
+  sits behind a switch. The per-value specs are what link every alternative into its real shaders.
+- **D9 — the API is `ShaderSwitch.enum(label, Enum)` and `ShaderSwitch.bool(label)`,** one mechanism underneath. A
+  switch's values are its own: the enum's members, or `false`/`true`. Sets, choices, labels and errors use them, and
+  errors and labels name the member.
+  - *My call, inside D3:* an enum must have a member equal to 0, the default, and one without is refused at
+    `enum()`. A bool's default is `false`. If you would rather the first-declared member be the default, it is a
+    one-line change.
+
+What follows from those:
+
+- **Pins are gone.** Their only use was a pair of exports with different bindings. §5 makes one definition serve every
+  value, and a pipeline that wants another value passes another set.
+- **The linker is untouched.** `compile()` links static graphs only, and refuses a graph that still holds a choice.
+  Revision (a) threaded the set through `compile()`; this revision does not.
+
+## 1. Summary
+
+```js
+// a switch over an engine enum, 0 by default; or ShaderSwitch.bool(label), false by default
+export const ShadowDirectionalTechnique = { Cascades: 0, Virtual: 1 };
+export const SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique);
+
+// where a graph decides it: the export every importer already uses
+export const chunk_shadowmap_sample_directional = CodeChunkChoice.from(SHADOW_DIRECTIONAL_TECHNIQUE);
+chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Cascades, chunk_shadowmap_sample_directional_cascades);
+chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Virtual, chunk_shadowmap_sample_directional_virtual);
+
+// an immutable, interned set of values; a switch it does not name is at its default
+const switches = ShaderSwitchSet.EMPTY.with(SHADOW_DIRECTIONAL_TECHNIQUE, ShadowDirectionalTechnique.Virtual);
+
+// the graph, specialized: every choice replaced by its selected alternative, so no choice is left
+const static_body = body.specialize(switches);
+
+// the shader caches its variants by the set; a variant is an ordinary static shader
+shader_deferred_main.variant(switches).draw({ /* … */ });
+shader_deferred_main.descriptor.switches; // [SHADOW_DIRECTIONAL_TECHNIQUE]
+```
+
+For the case that prompted this, `chunk_shadowmap_sample_directional` becomes a choice between `_cascades` and
+`_virtual`. None of the chunks above it changes, and none of the nine shaders that reach it changes its chunk code.
+
+Measured on the real `Shade From G-Buffer` module (§7):
+
+- **Cascades** drops exactly the 14 VSM functions and 4 VSM declarations: 96 → 82 functions, 69,917 → 59,892
+  characters.
+- **Virtual** drops the 2-function cascade walk: 94 functions.
+- In both, only `shadowmap_sample_directional` changes body.
+- **Tint** (Chrome, RTX 4090) compiles all three with no messages.
+- **Pipeline creation** in Chrome takes 0.81–0.83× (cascades) and 0.66–0.70× (virtual) of the shipped shader's.
+- **Cost of a variant:** specializing plus linking takes 0.075–0.083 ms across runs, the same as linking the shipped
+  shader today.
+  A repeat `variant(set)` lookup takes 0.1 µs and allocates nothing.
+
+The deferred GPU time measured earlier on the same variants (as hand-made twins) was 0.936× for cascades and 0.957×
+for virtual, with byte-identical images.
+
+**The long-term shape (§5–§6).** Each switched shader is one definition. It declares every binding any of its
+alternatives reads, and a binding a mode does not have falls back to a declared default. Owners bind by name and
+hand the renderer's set to `variant()`. That removes, in three stages:
+
+- the two IBL/Brick4 forward-fragment twins;
+- the paired AVBOIT/MBOIT/water exports and the `use_brick4 ? […] : […]` bind-entry arrays;
+- the `build_deferred_main_shader` and `build_ssr_resolve_shader` factories;
+- the per-mode froxel GI shaders;
+- water's hidden GI dependency;
+- the five owners' branches on `indirect_lighting_mode`.
+
+Open questions are in §11.
+
+## 2. What the engine does today
+
+There are four ways a shader chooses an implementation today. None of them can be seen in the chunk graph.
+
+1. **A runtime branch on a global choice.** `shadowmap_sample_directional` branches per light on
+   `shadowmap.virtual_map != NULL`, though the technique is per renderer (`Renderer.feature_virtual_shadow_maps` →
+   `GPUSceneShadowmapContext.use_virtual_shadow_maps`). Both paths are linked into nine shader definitions:
+   - deferred heavy and deferred ReSTIR (`shader_deferred_main.js`);
+   - AVBOIT draw IBL and Brick4 (`TemplatePassDescriptor`, one pipeline per material template);
+   - MBOIT resolve IBL and Brick4;
+   - volumetrics build-lighting and build-irradiance;
+   - water finalize.
+
+   The chain is `chunk_shadowmap_sample_directional` → `chunk_shadowmap_get_light_visibility` →
+   `chunk_shade_directional_lights` → `chunk_shade_standard_material_direct` (and `_restir`) → the shader bodies.
+   Volumetrics and water optics reach it from `chunk_shadowmap_get_light_visibility` directly.
+2. **A factory parameter at the root.** `build_deferred_main_shader({ label, shading_chunk, with_restir })` builds heavy
+   and ReSTIR, and the Renderer picks the export by `feature_restir_di_enabled`. This is the `make_shader({ flag })`
+   shape that `no-nested-shader-codegen` rules out. ReSTIR also adds a binding, `tRestirRadiance`.
+3. **A twin of an intermediate chunk.** `chunk_forward_shade_standard_fragment_ibl` and `_brick4` are 178 and 185 lines
+   that differ in 46 lines: the indirect-lighting block, plus comments that have already drifted apart. They feed
+   `shader_avboit_draw_ibl` / `_brick4` and `shader_oit_resolve_moments_ibl` / `shader_oit_resolve_moments`.
+   The owners pick by `indirect_lighting_mode` (`graph_rasterize_meshes_transparent_avboit.js:538`,
+   `graph_rasterize_meshes_transparent_oit.js:150`) and build different bind groups, because Brick4 adds a `brick4`
+   storage buffer to the view group.
+4. **A function filled in at the root.** Water's `finalize_body` calls `water_gi_specular` and `water_gi_irradiance`
+   without listing a dependency that defines them. `water_finalize_shader_ibl` / `_brick4` add `chunk_water_gi_ibl` or
+   `_brick4` beside it (`shader_water.js:593-597`). Nothing needs a twin, but the dependency is invisible.
+
+A switch with its choices gives all four one declared form: pattern 1 in stage 1 (shadows), and patterns 2, 3 and 4
+in stage 2, once one definition can carry every alternative's bindings (§5).
+
+The engine already has an *open* interface of the same shape. A material template supplies `material_surface` and
+`material_opacity` to every pass by function name (`ShadeMaterialTemplate.surface` / `.opacity`), as Unreal's materials
+and vertex factories do. Switches are the *closed* counterpart: an engine-owned choice whose values the engine knows.
+Neither replaces the other.
+
+## 3. What other engines do
+
+Read from source or primary docs. Unreal was read in the installed UE 5.4 tree. The rest comes from the research brief
+`shader-switch-prior-art.md` in the side-notes folder of this session group, which has the URLs and identifiers; its
+Bevy and gpuweb claims were re-checked against the pages.
+
+**Unreal: permutation domains.** `RenderCore/Public/ShaderPermutation.h`. A dimension is a C++ type made by
+`SHADER_PERMUTATION_BOOL` / `_INT` / `_RANGE_INT` / `_SPARSE_INT` / `_ENUM_CLASS`, each carrying a `DefineName`.
+`TShaderPermutationDomain<…>` is their product, and its permutation id is mixed-radix over the dimensions
+(`ToDimensionValueId`). A shader class lists its dimensions. `FDeferredLightPS` (`Renderer/Private/LightRendering.cpp:816`)
+has 14 of them, including `FVirtualShadowMapMask`.
+
+- `ShouldCompilePermutation` culls combinations: a directional light × the VSM mask is never compiled.
+- `RemapPermutation` folds combinations together: visualize-culling forces the others off.
+- `ModifyCompilationEnvironment` adds the VSM defines only when that dimension is on.
+- The draw site sets every dimension by hand (`LightRendering.cpp:2804-2833`), then asks the shader map for
+  `(shader type, permutation id)`. **The owner knows every dimension.** Nothing derives the domain: the shader class lists it
+  and the draw site sets it.
+- Dimensions select `#if` blocks. Dependencies are `#include`s, which can sit inside an `#if`, but nothing declares
+  what each value pulls in.
+
+**Unreal: vertex factories and materials.** These are the other half of Unreal's answer, and they are an *interface
+slot*. `FVertexFactoryType::ModifyCompilationEnvironment` maps the virtual include path
+`/Engine/Generated/VertexFactory.ush` to `#include "<this factory's file>"` (`RenderCore/Public/VertexFactory.h:418-420`).
+`/Engine/Generated/Material.ush` is mapped to the generated material code (`Engine/Private/Materials/MaterialShared.cpp:3357`).
+Every shader that includes the path gets the implementation the compile supplies, and nothing in between is twinned.
+The shader map is keyed by material × vertex factory × shader type × permutation.
+
+Note that Unreal's deferred light shader does not choose its *shadow technique* this way. VSM is projected into a
+screen-space mask beforehand, and the light shader only chooses whether to read the mask.
+
+**Unity: keywords.** A pass declares its keyword sets by hand with `#pragma multi_compile` / `shader_feature`
+(`_local`, `_vertex`/`_fragment` suffixes). A plain `#include` drops the pragmas of the file it includes, so a library's
+switches do not reach the shader that uses it. `#include_with_pragmas` exists to let them, and URP's `Lit.shader` uses
+it to pull in whole keyword bundles. That is Unity working its way toward a domain derived from the includes.
+
+- Since 2021.2 every declared keyword is local to the shader's `LocalKeywordSpace`. A `GlobalKeyword` is mapped into
+  each shader's space by name.
+- Setting a keyword the shader does not declare does nothing. This design does the same: values for other switches
+  are ignored.
+- Variants are looked up by closest match, and a missing one falls back silently. We should not copy that.
+
+**Bevy and naga_oil.** naga_oil passes one global map of shader defs to every module. Each module's `effective_defs`
+are collected by syntax: every name in an `#if`/`#ifdef`, whether or not its branch is taken, plus the effective defs of
+every import. So a module's domain is derived and transitive. The module is cached by a key made only of those defs
+(`ModuleKey::from_members`). That is this design's `descriptor.switches` and its key, arrived at independently.
+
+The code itself is chosen by `#ifdef` inside the text, the conditional-template shape this engine rejects.
+
+naga_oil's other route is `virtual fn` in a base module and `override fn base::f` in the top-level shader. A
+`Redirector` then rewrites every call in the final module, so no intermediate module is twinned. But the redirect is
+global, so two call sites cannot get different implementations. That is candidate B (§10).
+
+**Bevy 0.20 (released 2026-10-08) has since moved all its shaders to WESL** and removed its own WGSL dialect (checked
+against the release post). The release says nothing about what replaces `virtual fn`/`override fn`.
+
+**WESL.** `@if`/`@elif`/`@else` attributes go on declarations, statements, struct members and imports. The conditions
+are names joined with `! && ||`; they carry no values. Features are one flat set for the whole link.
+
+- The spec makes an unset feature that is used a link error. wesl-js treats it as false. wesl-rs offers
+  `Enable/Disable/Keep/Error` and defaults to `Disable`.
+- A removed branch need not be valid, and only declarations reachable from the root are emitted.
+- A module-parameters proposal (#222, unimplemented) would fork only the declarations that depend on a parameter.
+
+**gpuweb / WGSL.** WGSL itself has no conditional compilation, shipped or accepted. The only thread is gpuweb#5140,
+"@if for conditions", which is open in Milestone 3 with no decision (checked). Reviewers there asked for *declared*
+conditions, so that a library can say which conditions it reads. That is the same requirement as here.
+
+`override` is pipeline-overridable, but the spec defines a shader as the call closure from the entry point *whatever the
+constants' values*. A function reached only through a false `if` on an override is part of the shader, its bindings stay
+in the shader's interface, and nothing requires the dead branch to be removed. Chrome's Tint keeps it as `if (false)`
+(measured 2026-10-16), and DXC then drops it.
+
+This is a second reason an override is the wrong mechanism, beyond hiding the dependency. A Brick4-or-IBL override would
+still need the `brick4` buffer bound in IBL mode.
+
+**Slang: link-time `extern`/`export`.** A module declares `extern struct S : IFoo;` or `extern static const int k;`. A
+provider module declares `export struct S : IFoo = Impl;`. The program is composed from the modules chosen
+(`createCompositeComponentType`) and then `link()`ed. Unselected providers never enter the program, and intermediate
+modules compile once.
+
+This is the cleanest prior art for choosing deep in a graph without duplication, and it is open, like B. Whether any
+API lists a module's unresolved externs is unverified.
+
+**Filament** chooses the shadow technique per View at *run time*. Only the sampler type is a variant; PCF, VSM and
+EVSM are a uniform (`frameUniforms.shadowSamplingType`). That is today's meep, the runtime branch, which costs 4–6 % of
+the deferred pass here.
+
+**Godot** reads each specialization constant through an accessor that falls back to a push constant when built as an
+"ubershader". One source then serves both the specialized pipeline and a fallback compiled in the background. We do not
+need that, because `PipelineEnquiry` already compiles off the main thread.
+
+**What this design takes, and what it leaves.**
+
+- **From Unreal:** a dimension as an object with a closed value set, and a key per shader made of its values. But not
+  the owner listing every dimension; here the graph lists them.
+- **From naga_oil:** deriving the domain transitively from the graph, and keying only on it.
+- **From Unity:** values a shader does not use are ignored.
+- **From WESL's spec:** an unset value is an error, not false.
+- **From Slang and vertex factories:** the implementation is linked in *beside* the code that calls it, so nothing in
+  between is twinned or rebuilt.
+- **Left out:** conditional text inside a chunk (Unreal's and naga_oil's `#if`, WESL's `@if` on statements), which is
+  what `CodeChunk` exists to avoid. Also left out: global redirects (naga_oil overrides) and closest-match fallback
+  (Unity).
+
+An alternative here is a whole chunk with its own dependencies, which is WESL's `@if` on a declaration, raised to a
+declared, typed choice.
+
+## 4. The design
+
+### 4.1 Pieces
+
+| piece | is | API |
+|---|---|---|
+| `ShaderSwitch` | a named choice over an engine enum's members (default: the member equal to 0) or over `false`/`true` (default `false`) | `ShaderSwitch.enum(label, Enum)`, `ShaderSwitch.bool(label)`; `label`, `values`, `default_value`, `is_value(v)`, `name_of(v)` |
+| `ShaderSwitchSet` | immutable, **interned** values for some switches; a switch it does not name is at its default | `EMPTY`, `with(switch, value)`, `get(switch)`, `restricted_to(switches)` |
+| `CodeChunkChoice` | a chunk standing for one alternative per value of one switch | `CodeChunkChoice.from(switch)`, `add(value, chunk)`, `alternative_for(set)` |
+| `CodeChunk.specialize(set)` | the graph with every choice replaced by its selected alternative | returns a static `CodeChunk` |
+| `CodeChunk.collectSwitches()` | every switch the graph decides, through every alternative | `ShaderSwitch[]` |
+| `variant(set)` | on `ShaderDescriptor`, `ImageShader`, `ComputeShader`, and (designed) `TemplatePassDescriptor` | a static shader of the same class |
+
+**Interning** makes a set a value: two sets that give every switch the same value are one object, and a switch set to
+0 is not stored. So:
+
+- `a.with(X, 1).with(Y, 2) === a.with(Y, 2).with(X, 1)`;
+- `EMPTY.with(X, X.default_value) === EMPTY`;
+- every cache keys by identity;
+- `toString()` names the members, `shadow directional technique=Virtual`, which is what labels carry (D7);
+- `with` returns `this` when the value is already that, so a renderer re-deriving its set every frame allocates
+  nothing until a flag changes.
+
+Each set is made once, on first use, and kept for the process, so the table only grows by sets actually used.
+
+### 4.2 Specialization: a switched graph becomes a static one
+
+`specialize(set)` walks the graph once, depth-first, with a memo from source chunk to result:
+
+- A **choice** becomes the specialization of the alternative `set` selects. An alternative may itself be a choice of
+  another switch.
+- A **chunk whose dependencies all come back as themselves** is returned as it is. Everything not above a choice is
+  shared with the source graph, and a graph with no choice specializes to itself.
+- **Any other chunk** becomes a new `CodeChunk`: the same text and extensions, with specialized dependencies. If two
+  dependencies resolve to the same chunk, it is kept once.
+- **The memo** keeps what two chunks share in the source shared in the result, so a diamond stays a diamond.
+
+`compile()` is unchanged, except that it throws, naming the choice, if a choice reaches it. The linker only ever sees
+static graphs.
+
+`collectSwitches()` walks every alternative, selected or not, so a switch nested inside one alternative is still in
+the shader's domain.
+
+Errors:
+
+- a value with no alternative at a choice names the switch and the value;
+- a cycle through any alternative is refused at `add()`;
+- a choice equals only itself, since every choice has the same empty text.
+
+### 4.3 Variants on the shader classes
+
+"The shader" caches its variants by the set, as you asked. Every class has the same shape, `variant(set)`:
+
+1. Look `set` up by identity. A frame asking again stops here: 0.1 µs, no allocation.
+2. Restrict it to the descriptor's `switches`. Sets that agree on this shader's switches get the same variant.
+3. If the restricted set is `EMPTY`, return `this`. The object a module exports *is* the all-defaults variant, so
+   `shader.pipeline` and `descriptor.source` keep meaning what they mean today.
+4. Otherwise build, once, a static object of the same class from the specialized descriptor.
+
+| class | status | variant is |
+|---|---|---|
+| `ShaderDescriptor` | prototyped | `ShaderDescriptor.from({ label: '<label> [<set>]', resources: same object, body: body.specialize(set) })`. `switches` = `body.collectSwitches()`. `source` = the all-zeros variant. |
+| `ImageShader` | prototyped | `new ImageShader({ descriptor: descriptor.variant(set), targets, depthStencil })`, the same targets and depth state as the original. |
+| `ComputeShader` | prototyped | `new ComputeShader(descriptor.variant(set))`. Refused if its `@workgroup_size` differs from the original's: a switch changes what a pass computes, never how it is dispatched. |
+| `TemplatePassDescriptor` | designed | a sibling sharing `label`, `build` and the attachments. `build(template, set)` gets the set and returns `….variant(set).source`; existing builds that ignore the second argument keep working. Its own per-manager × template × cull-mode cache is unchanged. The reads of `.pipeline` for its layout (`graph_rasterize_meshes_transparent_avboit.js:287`, `:593`; `graph_rasterize_meshes_transparent_oit.js:205`, `:353`) becomes a `pipeline_layout` getter, so a sibling needs no pipeline of its own. |
+| water's finalize pipeline | designed | `create_water_finalize_pipeline(set)`, cached the same way. |
+
+A few things fall out of variants being whole static objects:
+
+- `features` (the `enable` list) and `validate_against_device` are per variant, with no extra work.
+- Labels carry the set, so profiler entries and validation errors name the variant they came from.
+
+### 4.4 Where the set comes from
+
+- **Who builds it.** The Renderer, from its feature flags, at the start of `render()`:
+
+  ```js
+  this.#shader_switches = this.#shader_switches
+      .with(SHADOW_DIRECTIONAL_TECHNIQUE, this.feature_virtual_shadow_maps ? ShadowDirectionalTechnique.Virtual : ShadowDirectionalTechnique.Cascades)
+      .with(INDIRECT_LIGHTING, this.indirect_lighting_mode)                                   // stage 2
+      .with(LOCAL_LIGHT_SHADING, this.feature_restir_di_enabled ? LocalLightShading.ReSTIR : LocalLightShading.Clustered); // stage 2
+  ```
+
+  This allocates nothing while the flags are unchanged.
+- **How it reaches owners.** Each owner is handed it the way it is handed `indirect_lighting_mode` today: the deferred
+  pass in the Renderer, the volumetrics and transparency graph functions through their options, water through its
+  draw call. An owner passes the set opaquely to `variant()`. It never learns which switches its shaders contain, and
+  in stage 2 the set replaces the `indirect_lighting_mode` parameter it carries today.
+- **A per-pipeline choice.** An owner asks for it explicitly, with `shader.variant(switches.with(X, v))`, for example a
+  debug view that forces cascades.
+- **A forgotten set.** With D3 an owner that forgets to pass the set draws the all-defaults variant, silently. That is the price of
+  defaults. The domain is enumerable, so a review can list every shader with non-empty `switches` and check that its
+  owner calls `variant`.
+
+### 4.5 Caching and keys
+
+- **Shader level:** by set identity, then by the restricted set (§4.3).
+- **GPU pipeline managers: unchanged.** `RenderPipelineManager` and `ComputePipelineManager` key by descriptor, which
+  includes the WGSL text and the label. Distinct variants are distinct pipelines. Sets differing only in switches a
+  shader does not have share one, because the variant is restricted to the shader's own switches first.
+  - *Corrected in stage 2:* sets that produce the same text through different values do not share. LPV and IBL on
+    the transparent paths and water link the same code, but D7 puts the set in the label and descriptor equality
+    compares labels, so LPV gets its own pipeline: one extra compile when LPV is switched on.
+- **What affects what.** `descriptor.switches` lists a shader's switches, and `TemplatePassDescriptor.switches_of(template)`
+  does the same per template, since a template's own chunks may hold a choice. "Which pipelines does flipping X
+  recompile" is the set of shaders whose `switches` include X.
+
+### 4.6 Preparation, and a flip
+
+- **Offers.** The Renderer offers `shader.variant(this.#shader_switches).pipeline` and hands the set to the `enquire_*`
+  functions, so only the selected variants are prepared.
+- **When the set changes**, nothing extra happens (D6). The first frame that draws with the new set makes its
+  variants through `obtain`, synchronously, as a feature turned on after `initialize()` does today. That is about 1 s
+  cold for the deferred shader. The shadow records and the shaders flip in that same frame.
+- **Speculative offers.** The domain is enumerable, so a settings screen can offer the other value in the background to
+  make flips instant.
+
+### 4.7 Specs
+
+- **Existing specs keep passing.** With D3 they test the all-defaults variant, and the whole shade suite (877 files) passes on the
+  prototype unchanged.
+- **New specs per switched shader:** "every value validates as WGSL", a plain `for` over `switch.values` inside one test,
+  not `.each`.
+- **Chunk-level harnesses** that compile a graph containing a choice call `specialize(set)` first. The linker refuses
+  one that does not.
+
+## 5. Resources: the long-term half
+
+### 5.1 What differs between alternatives today
+
+| fork | bindings only one mode has | does the resource exist in the other modes? |
+|---|---|---|
+| AVBOIT draw, MBOIT resolve | `brick4` (in the view group) | yes: `Brick4LightMap` creates its buffer in its constructor, per scene |
+| water finalize | `brick4`, `view` (an extra group) | yes |
+| SSR resolve (`build_ssr_resolve_shader` factory) | IBL `tEnvironment`; Brick4 `brick4`, `tSTBN_vec2`; LPV `tEnvironment` + 2 textures, 3 buffers + 1 uniform | Brick4, STBN and LPV's buffers yes; LPV's atlas textures only once LPV runs |
+| froxel GI (a module per mode) | IBL `environment_sh`; Brick4 `brick4`; LPV 3 buffers + 1 uniform | yes |
+| deferred heavy/ReSTIR (factory) | `tRestirRadiance` | only when ReSTIR runs |
+
+*Corrected in stage 2:* LPV's buffers exist in every mode. `GPUSceneContext`'s constructor makes the
+`GPULightProbeVolume` beside the `Brick4LightMap`, and its buffers are created there at a reserved minimum (one probe,
+one tetrahedron, a BVH root). Only the atlas textures wait: a `GPUTextureContext` allocates on first use, and nothing
+uses them outside LPV.
+
+Mode-specific bindings cannot simply get a group of their own. The raster passes already use groups 0–3 (material,
+scene, view, lights), which is all WebGPU guarantees (`maxBindGroups` defaults to 4, and the device floor does not
+raise it).
+
+### 5.2 Recommended: one interface per definition, the union of its alternatives'
+
+A switched shader's resource set declares every binding any of its alternatives reads. Switches then change code only,
+never the interface (D4 holds forever, not just in stage 1). It follows that:
+
+- **Layouts don't depend on the set.** The shared groups (`SHADING_LIGHT_RESOURCE_GROUP`, `FORWARD_LIGHT_LAYOUT`) and the
+  bind groups built from them stay shared across variants and passes. A layout may list a binding the selected variant
+  does not read; WebGPU allows that.
+- **Owners bind by name.** `group.generateBindings(map, encoder)` already does this, and every pass becomes
+  "pass what you have". The positional `use_brick4 ? [ … ] : [ … ]` arrays in the AVBOIT and MBOIT owners go.
+- **A binding a mode lacks falls back to its declared default.**
+  - Textures already take one: `addTexture(…, BLACK_PIXEL_TEXTURE)` is in use. `tRestirRadiance` defaults to black.
+  - Storage buffers have no default parameter today. One convention would be added: `addStorageBuffer(name, type,
+    write, default_value)`, with the engine's zero buffer of the type's minimum size. LPV's three buffers need it.
+  - *As built in stage 2, your option B on the frame graph path only:* `addStorageBuffer(name, type, write,
+    transient_default)`. The declaration says only whether the convention applies. A frame graph pass given nothing
+    for such a binding binds a transient storage buffer of the type's minimum binding size from the frame's pool, so
+    there is no buffer to keep and no lifecycle. Its contents are whatever the pooled buffer last held, so it may
+    only stand in for a binding the selected variant does not read, and an assert checks exactly that: the module
+    names the binding nowhere but its declaration, comments aside. A pass that binds by hand (`generateBindings`)
+    gets no default and is told so.
+  - Owners pass only what the running mode has. The Renderer hands SSR and froxel GI Brick4's map, or the light
+    probe volume, only while that mode runs. AVBOIT, MBOIT and water bind by hand and pass Brick4's buffer, which
+    exists in every mode (§5.1).
+  - Textures: `tRestirRadiance` and LPV's `lpv_atlas_depth` default to `BLACK_PIXEL_TEXTURE`, and
+    `lpv_atlas_radiance`, a `uint` binding, to a new one-texel `r32uint` zero, `ZERO_UINT_PIXEL_TEXTURE`. LPV's
+    `lpv_metadata` uniform defaults to a volume of no probes.
+
+**Measured in stage 2 (§12.2):** an unread binding in a layout costs nothing measurable at draw time. The AVBOIT draw
+and the SSR resolve take the same GPU time with the union of bindings as with their own mode's.
+
+### 5.3 Later, and optional: chunks declare the bindings they read
+
+Today `chunk_shade_directional_lights` says in prose that it "relies on the `light_data` storage binding and the shadow
+atlas bindings being present". `chunk_water_gi_brick4` says "Expects `brick4` and `view`". These are implicit
+dependencies, of the same kind as water's hidden GI function.
+
+A chunk would declare them through a channel beside `addExtension`: `chunk.requireResource(RESOURCE_BRICK4)`, with the
+resource descriptor exported once. `compile()` collects them over the static graph as it collects extensions, and
+`ShaderDescriptor` checks each against its resource set by name and type. The error names both: "`chunk_brick4_sample_*`
+reads `brick4`, which `AVBOIT / draw` does not bind".
+
+With switches, a variant's required set is then known exactly. Migration is chunk by chunk, since an undeclared read
+works as it does today.
+
+### 5.4 Considered and not recommended
+
+- **Resources chosen by switch, per variant.** A group, or entries within one, would change with the set, so each
+  variant binds only what it reads. Shared groups would stop being shared whenever a variant read less than all of
+  one, and owners would build a bind group per variant. It buys nothing measured.
+- **A group per mode.** It does not fit in 4 groups.
+
+## 6. Migration, in three stages
+
+Each stage is a set of one-concern commits, red-then-green where it fixes something.
+
+### Stage 1: the mechanism and shadows (code-only)
+
+1. The compiler layer as prototyped: `ShaderSwitch`, `ShaderSwitchSet`, `CodeChunkChoice`, `specialize`,
+   `collectSwitches`, and `variant` on `ShaderDescriptor`, `ImageShader` and `ComputeShader`.
+2. `TemplatePassDescriptor.variant` and `build(template, set)`. `.pipeline` reads for layout become `pipeline_layout`.
+   Water's finalize builder takes a set.
+3. Shadows:
+   - add `ShadowDirectionalTechnique { Cascades: 0, Virtual: 1 }` and
+     `SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique)`;
+   - split `_cascades` (today's function without the virtual branch) from `_virtual` (record read; NULL → 1.0; else
+     `shadowmap_sample_virtual`);
+   - make `chunk_shadowmap_sample_directional` the choice. Nothing above it changes.
+4. The Renderer builds `#shader_switches` and hands it to:
+   - the deferred pass;
+   - volumetrics build-lighting and build-irradiance;
+   - AVBOIT and MBOIT;
+   - water;
+   - the `enquire_*` functions.
+
+5. Specs: about a dozen that compile these shaders directly gain a loop over the technique.
+
+### Stage 2: resources, and the forks that needed them
+
+Every step below is "one definition, one choice, bind by name".
+
+- **`INDIRECT_LIGHTING = ShaderSwitch.enum('indirect lighting', ShadeIndirectLightingMode)`**, the enum as it is, with IBL
+  as 0.
+  - **Forward fragment:** one `chunk_forward_shade_standard_fragment` calling `forward_sample_indirect(…)`. A choice
+    provides it: IBL → environment, Brick4 → `brick4_sample_forward_indirect`, LPV → environment. This replaces the
+    178/185-line twins.
+  - **AVBOIT and MBOIT:** one draw and one resolve, each with `brick4` in the view group. The `_ibl`/`_brick4` exports and
+    the branch on `indirect_lighting_mode` in both owners go.
+  - **Water:** one finalize shader. `chunk_water_gi` is a choice, and `finalize_body` lists it as a dependency, so the
+    hidden dependency becomes explicit.
+  - **SSR resolve:** one shader. `ssr_sample_radiance` (and `ssr_sample_hit_irradiance`) are choices, and
+    `build_ssr_resolve_shader` goes.
+  - **Froxel GI:** one shader whose per-froxel radiance lookup is a choice; the three modules become three alternatives.
+- **`LOCAL_LIGHT_SHADING = ShaderSwitch.enum('local light shading', LocalLightShading)`**, `{ Clustered: 0, ReSTIR: 1 }`. The deferred body depends on a choice between
+  `chunk_shade_standard_material_direct` and `_restir`. `tRestirRadiance` defaults to black.
+  `build_deferred_main_shader` and `shader_deferred_main_restir` go. The forward paths keep linking the clustered chunk
+  directly, so they never depend on the switch.
+- **The storage-buffer default convention** (§5.2), for LPV's buffers. *Built on the frame graph path only (§5.2).*
+- **Measure:** the transparent pass and SSR before and after, by the paired method.
+
+### Stage 3 (optional): declared bindings
+
+`requireResource` and the link-time check (§5.3), then chunk by chunk, starting with the ones that say "relies on" or
+"expects" in prose. *Built for every chunk the switched shaders link (§12.3).*
+
+### What goes away, in total
+
+- **Duplicate code:**
+  - the forward fragment twins;
+  - the AVBOIT and MBOIT export pairs;
+  - the water finalize pair;
+  - two per-mode SSR wrappers and three froxel GI modules, which become alternatives;
+  - `shader_deferred_main_restir`.
+- **Factories:** `build_deferred_main_shader` and `build_ssr_resolve_shader`.
+- **Owner branches:** five `switch`/`?:` on `indirect_lighting_mode`, two positional bind-entry pairs, and the
+  `indirect_lighting_mode` parameter threaded through those owners.
+- **A runtime branch:** the per-light shadow technique branch, worth 4–6 % of the deferred pass.
+
+## 7. Prototype and measurements
+
+### Specs, 33 new tests
+
+- `compiler/ShaderSwitch.spec.js`, 4 tests: an enum's members in declaration order with default 0; a bool's
+  `false`/`true` with default `false`; an enum without a 0 member refused; repeated values refused.
+- `compiler/CodeChunkChoice.spec.js`, 16 tests:
+  - only the selected closure is linked;
+  - an unnamed enum switch is 0, an unnamed bool `false`;
+  - an enum with gaps between its values;
+  - a choice three chunks deep needs one copy of each chunk above it;
+  - a shared chunk stays one chunk;
+  - topological order;
+  - a static graph is its own specialization;
+  - the linker refuses a choice;
+  - discovery from above;
+  - a switch nested in one alternative, and one with 3 values;
+  - an alternative that is a choice;
+  - one switch at two places;
+  - a missing alternative names the switch and the member;
+  - cycles;
+  - identity.
+- `compiler/ShaderSwitchSet.spec.js`, 5 tests: interning regardless of order; a default is not stored; a changed
+  value; restriction; `toString` names the members.
+- `ShaderDescriptor.spec.js`, 4 tests: domain found two chunks down; `source` is the all-defaults variant; a variant
+  links one alternative, has no switches and is labelled `… technique=Virtual`; sets that agree share a variant, and
+  the empty set gives the descriptor itself.
+- `ImageShader.spec.js`, 2 tests, and `ComputeShader.spec.js`, 2 tests: the variant's pipeline code and targets, caching,
+  `this` for all-defaults, and a variant with another `@workgroup_size` refused.
+
+### The real deferred shader
+
+A scratch probe (`scratchpad/probe/shadow_choice.probe.js`, not in the tree) rebuilds the four chunks above
+`chunk_shadowmap_sample_directional` from their real `.text` and dependency lists, with the choice in its place. In the
+engine they would not change at all.
+
+| | characters | functions | engine validator | Tint (Chrome, RTX 4090) | vs shipped |
+|---|---|---|---|---|---|
+| shipped (both paths) | 69,917 | 96 | pass | 0 messages | |
+| cascades | 59,892 | 82 | pass | 0 messages | −14 VSM functions, −4 VSM structs/consts; only `shadowmap_sample_directional` changed |
+| virtual | 62,682 | 94 | pass | 0 messages | −`shadowmap_csm_compute_cascade_blended` and its row read, −2 structs; only `shadowmap_sample_directional` changed |
+
+- **Link time**, median of 200 interleaved runs: today's `compile()` 0.079 / 0.083 ms in two runs; `specialize` +
+  `compile()` of a variant 0.075 / 0.083 ms.
+- **`variant(set)` with a set already seen:** 0.1 µs.
+- **Pipeline creation** (`tint_check.mjs`):
+  - **Method.** `createRenderPipelineAsync` with the deferred pass's vertex stage, target and depth state, and
+    `layout: 'auto'`. One at a time, rotating order, 8 rounds. A fresh seed constant per compile, so neither Dawn's
+    nor the driver's cache serves it.
+  - **Results.** Two runs: shipped 1251 / 1225 ms, cascades 1009 / 1017 ms (0.81× / 0.83×), virtual 877 / 810 ms
+    (0.70× / 0.66×).
+  - **Caveat.** This is wall time on a busy box, not the trace's `InitializeImpl`, so it compares with the earlier
+    twins (0.78× / 0.66×) by ratio only.
+- **GPU time was not re-measured.** The 0.936× / 0.957× were measured on twins built by the same removals. The cascades
+  variant is that twin. The virtual variant is the twin's branch inverted (`== NULL → 1.0` first).
+
+## 8. Costs
+
+| part | size |
+|---|---|
+| prototype as it stands | 3 classes (540 lines with docs); `CodeChunk` +135; `ShaderDescriptor` +67/−1; `ImageShader` +51; `ComputeShader` +49; 6 spec files (504 lines) |
+| rest of stage 1 (estimate) | `TemplatePassDescriptor` (~50), water builder, Renderer set + plumbing to the owners and the enquiries (~100), shadow split (1 file into 3), ~12 specs |
+| stage 2 (estimate) | the steps of §6 stage 2, each mostly deletion. Expected net negative in lines, not counted. |
+
+Runtime:
+
+- No per-frame allocation once the set is steady.
+- A lookup is 0.1 µs, and a variant costs 0.075–0.083 ms to specialize and link.
+- A flip compiles the affected variants on first use (D6). The old ones stay cached.
+
+Risks:
+
+- **A forgotten set draws the all-defaults variant silently (§4.4).**
+- **Errors move to first use.** A broken non-zero alternative only shows when a pipeline is made. The per-value specs
+  catch it.
+
+## 9. Reuse map
+
+| piece | reuses / generalises |
+|---|---|
+| specialization | `CodeChunk`'s own graph and private fields, with the same identity-based dedup the linker relies on. No second linker; `compile()` is untouched. |
+| values | engine enums as they are (`ShadeIndirectLightingMode` unchanged), or a bool. The shape of Unreal's `SHADER_PERMUTATION_ENUM_CLASS`/`_BOOL`, and like its `SPARSE_INT` an enum need not be contiguous. |
+| variant objects | `ShaderDescriptor`, `ImageShader`, `ComputeShader` and `TemplatePassDescriptor` themselves. A variant is one of them, so draw, dispatch, validation and the profiler need nothing new. |
+| GPU pipeline cache | `RenderPipelineManager` / `ComputePipelineManager` unchanged. Text equality separates and shares variants. |
+| preparation | `PipelineEnquiry` and `prepare()` at start-up, offering the selected variants. A flip uses `obtain` as anything made on first use does. |
+| bind by name | `ShaderResourceGroupDescriptor.generateBindings`, and texture `default_value` (`BLACK_PIXEL_TEXTURE`). One new default convention, for storage buffers. |
+| declared bindings (stage 3) | the `addExtension` / `addLanguageExtension` channel: collected at link, the same way. |
+| `ProgrammableStage.constants` | left for what `override` is for: numbers. Not for choosing code. |
+
+## 10. Candidates considered (revision a)
+
+- **A: a switch is the choice.** The value is an alternative chunk, and each place where the graph chooses is its own
+  switch. It would make the renderer name every place a decision is made. Superseded by D1.
+- **B: open slots filled by whoever builds the shader.** This is Unreal's vertex-factory include, naga_oil's
+  `override fn`, Slang's `extern`/`export`, and today's water GI. Nothing can enumerate a slot's implementations, so
+  preparation and specs cannot loop over variants. Material templates already are the engine's open interface.
+- **C: a switch decided at choices in the graph.** This is the design above, now with enum and bool values (D1, D9), a
+  static graph per variant (D2) and a default (D3).
+- **Rejected before this proposal:** WGSL `override` constants. They hide the dependency, and the spec keeps a function
+  reached through a false override `if` in the shader, its bindings included.
+
+## 11. Open questions for Alex
+
+The design questions are closed (D1–D9). An enum must have a member equal to 0, a rule Alex kept. Stage 1 landed as
+four one-concern commits:
+
+1. the compiler layer;
+2. the shader classes' `variant`;
+3. `TemplatePassDescriptor`'s;
+4. the shadow switch with the renderer's set and its plumbing.
+
+Stage 2 landed as seven, with the storage-buffer default as you chose it: option B, on the frame graph path only
+(§5.2).
+
+Stage 3 is built and checked (§12.3), uncommitted. Open: landing, proposed as five one-concern commits,
+master-direct:
+
+1. a resource's declaration apart from its placement (`ShaderResourceDescriptor`'s factories, `group.add`,
+   `isSatisfiedBy`);
+2. chunks declare the bindings they read, and a shader's link checks them (`requireResource`);
+3. six shaders bind what their chunks read: the SDF build, screen-space shadows, the four lightmap debug views;
+4. the switched shaders' chunks declare their bindings, with the audit spec;
+5. this document.
+
+Also open from stage 3: how the sky reaches water's optics chunks, so they can list the GI they call (§12.3).
+
+## 12. As built
+
+### 12.1 Stage 1, as landed (2026-10-16)
+
+#### What it contains
+
+- **The mechanism:**
+  - `ShaderSwitch` (`enum` / `bool`), `ShaderSwitchSet` and `CodeChunkChoice`;
+  - `CodeChunk.specialize` and `collectSwitches`;
+  - `variant(set)` on `ShaderDescriptor`, `ImageShader`, `ComputeShader` and `TemplatePassDescriptor`.
+
+  A `TemplatePassDescriptor` build is now `(template, switches)`. The four transparent passes that light fragments
+  build `….variant(switches)`, and their pipeline labels carry the set. Owners read a template pass's layout through
+  `pipeline_layout`, so a variant needs no pipeline of its own.
+- **The shadow switch:**
+  - `ShadowDirectionalTechnique { Cascades: 0, Virtual: 1 }`;
+  - `SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique)`;
+  - `chunk_shadowmap_sample_directional_cascades` and `chunk_shadowmap_sample_directional_virtual`.
+
+  `chunk_shadowmap_sample_directional` is now the choice between those two alternatives. No chunk above it changed.
+- **The renderer:**
+  - `Renderer.#shader_switches` follows `feature_virtual_shadow_maps`. It is updated in `#draw_to_target`, beside the
+    shadow context's own flag, and in `enquirePipelines`, and readable as `renderer.shader_switches`.
+  - It is handed to:
+    - the deferred pass;
+    - `GPUViewVolumetrics.graph_update`, which passes it to froxel irradiance and light scattering;
+    - the AVBOIT orchestrator, which passes it to the draw pass and to each side channel's `avboit_prepare` (water);
+    - the MBOIT orchestrator, for its resolve pass.
+- **Water:** `create_water_finalize_pipeline_ibl/brick4(switches)`, and `GPUWaterRenderer` caches the result per GI mode
+  and set.
+
+#### Tests
+
+- **`shadow_directional_technique_consumers.spec.js`** covers all nine shaders under both techniques. In each, exactly
+  the selected technique's sampling is linked, the other's is absent, and the module passes the WGSL checks. With every
+  switch at its default, the result is cascades.
+- **`TemplatePassDescriptor.spec.js`** (3 tests): a variant builds each template for its set; one variant per set, and
+  the pass itself for the empty set; a variant shares its original's attachments and layout.
+- **The AVBOIT orchestrator spec** gained a test on the software device: water's optics pipeline, as recorded on the
+  device, links the technique of the set the orchestrator was handed. It fails if the orchestrator stops passing the set
+  to side channels (checked).
+- **Five chunk-level harnesses now specialize before linking**, which the linker requires:
+  - the cascades harness to Cascades;
+  - the VSM harness to Virtual — 4 of its 6 tests fail if it is built for Cascades instead (checked);
+  - the normal-decode harness and the two water-optics harnesses to the default.
+- **Gates:** the shade suite passes, 879 files and 6,744 tests. `check-types` reads 18 against the base's 18.
+
+#### Device check (one-off, headless Chrome, RTX 4090)
+
+The stage-1 tree and its base (`03d5816bd`) were served side by side.
+
+- **VSM playground (deferred lighting).**
+  - Stage 1 makes two shadow-sampling pipelines: `Shade From G-Buffer`, cascades only, offered at start-up; and
+    `Shade From G-Buffer [shadow directional technique=Virtual]`, virtual only. No pipeline links both.
+  - The base makes one pipeline that links both.
+- **Images.** Stage 1 against the base differs in no more pixels than the base against itself, with the playground's
+  movers animating and the filter jittered per frame:
+
+  | technique | stage 1 vs base | base vs base |
+  |---|---|---|
+  | cascades | 6.3 % of pixels | 7.4 % |
+  | virtual | 5.5 % of pixels | 7.8 % |
+
+- **The same playground with a fog volume added from the page (deferred + volumetric lighting).**
+  - Stage 1 adds `Volumetrics / build lighting`, cascades only, and `Volumetrics / build lighting [shadow directional
+    technique=Virtual]`, virtual only. The base has one, which links both.
+  - The fog's per-frame jitter moves most pixels by a level or two, in both comparisons alike:
+
+    | technique | stage 1 vs base: pixels off by > 8 levels (mean max-channel difference) | base vs base |
+    |---|---|---|
+    | cascades | 5.97 % (4.32) | 5.70 % (4.33) |
+    | virtual | 6.00 % (4.38) | 5.81 % (4.44) |
+- **Console errors.** `vsm: feedback readback failed` appears only after a tab is closed, on the base as on stage 1.
+  It is a readback cut short by the close.
+
+Not checked on the device:
+
+- **water and MBOIT,** whose playground does not expose its renderer for the flip. They are covered on the software
+  device and by the consumer spec.
+- **GPU time of the variants.** The 0.936× / 0.957× of revision (a) were measured on equivalent twins.
+
+### 12.2 Stage 2, as landed (2026-10-16, `6e263855d`..`e354def85`)
+
+#### What it contains
+
+- **Two switches,** set by the Renderer's `#update_shader_switches` beside the shadow technique:
+  - `INDIRECT_LIGHTING = ShaderSwitch.enum('indirect lighting', ShadeIndirectLightingMode)`, from
+    `indirect_lighting_mode`;
+  - `LOCAL_LIGHT_SHADING = ShaderSwitch.enum('local light shading', LocalLightShading)`, `{ Clustered: 0, ReSTIR: 1 }`,
+    from `feature_restir_di_enabled`.
+- **Six choices,** each where a graph asks for the light:
+
+  | choice | IBL | Brick4 | LPV |
+  |---|---|---|---|
+  | `chunk_forward_sample_indirect` | environment | `brick4_sample_forward_indirect` | environment |
+  | `chunk_water_gi` (now listed by `finalize_body`) | `chunk_water_gi_ibl` | `chunk_water_gi_brick4` | `chunk_water_gi_ibl` |
+  | `chunk_ssr_sample_radiance` | environment | `brick4_sample_specular` | `lpv_sample_radiance` |
+  | `chunk_ssr_add_hit_irradiance` | nothing | nothing | the LPV bounce at the hit |
+  | `chunk_volumetrics_gi_sample` | `environment_sh` | `brick4_sample_sh` | the LPV mesh |
+
+  and `chunk_shade_standard_material_direct_deferred` on `LOCAL_LIGHT_SHADING`: the clustered chunk, or `_restir`.
+- **One definition each:** `chunk_forward_shade_standard_fragment`, `shader_avboit_draw`, `shader_oit_resolve_moments`,
+  `water_finalize_shader` (`create_water_finalize_pipeline(switches)`), `ssr_resolve_shader`, `shader_volumetrics_gi`,
+  `shader_deferred_main`. Each declares the union of its alternatives' bindings.
+- **Gone:** the forward twins; `shader_avboit_draw_ibl`/`_brick4`; `shader_oit_resolve_moments_ibl`; water's `_ibl`/
+  `_brick4` shaders, pipelines and resource sets; `build_ssr_resolve_shader` and the three per-mode resolves; the
+  three froxel GI modules; `build_deferred_main_shader` and `shader_deferred_main_restir`.
+- **Owners:** no pass below the Renderer takes `indirect_lighting_mode` any more. The AVBOIT orchestrator, its side
+  channels' `avboit_prepare`, the MBOIT orchestrator, `GPUViewVolumetrics.graph_update` and `SSR.graph_pass` take the
+  set alone.
+  - AVBOIT and MBOIT bind their view group by name (`AVBOIT_DRAW_VIEW_GROUP`, `OIT_RESOLVE_VIEW_GROUP`, through
+    `generateBindings`). The positional pairs are gone.
+  - SSR and froxel GI take Brick4's map and the light probe volume as optional sources, and the Renderer hands them
+    the running mode's alone. Another mode's bindings are the shader's defaults (§5.2).
+  - Water binds Brick4's buffer and the view in every mode, by hand: both exist in every mode.
+  - SSR restarts its history when its resolve variant changes, where it used to compare modes.
+  - The Renderer's own branches on the mode stay: they pick passes, not shaders (the diffuse/specular pair, Brick4's
+    fused pass, the enquiry, the LPV update).
+- **Defaults** (§5.2): storage buffers with a transient default (`brick4` in SSR and froxel GI, and the LPV's three
+  buffers through `LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS`, a twin of the shared group that the passes which always
+  bind the volume keep using); `lpv_metadata` a volume of no probes; `tRestirRadiance` and `lpv_atlas_depth`
+  `BLACK_PIXEL_TEXTURE`; `lpv_atlas_radiance` the new `ZERO_UINT_PIXEL_TEXTURE`.
+
+#### What changed in the code
+
+Every variant was diffed against the shader it replaces, declaration by declaration, with the order-dependent
+`Struct_N` names normalised:
+
+- **Same code:** water's optics under Brick4, the AVBOIT Brick4 vertex stage, and deferred ReSTIR.
+- **One wrapper function more** (`forward_sample_indirect`, `volumetrics_gi_sample`, `ssr_add_hit_irradiance`), which
+  the caller now calls in place of the code it wrapped: the transparent passes, SSR and froxel GI.
+- **Declarations only:** the union's bindings, and binding numbers shifted to make room for them. Deferred
+  (clustered) gains `tRestirRadiance`.
+
+#### Tests
+
+- **`indirect_lighting_consumers.spec.js`** (5 tests): the AVBOIT draw and MBOIT resolve for the standard template,
+  water's optics, SSR's resolve and froxel GI, under every mode. Each variant links only its mode's sampling, passes
+  the WGSL checks, and has the same layout or resources as every other mode's; with every switch at its default the
+  result is IBL.
+- **`shader_deferred_main.spec.js`** (3 tests): each way of shading local lights links its own code, and the two bind
+  alike with `tRestirRadiance` black by default.
+- **`storage_buffer_transient_default.spec.js`** (4 tests, software device): a pass given nothing binds a transient
+  buffer of the minimum binding size; a pass given the buffer binds it; a shader that reads a binding left to its
+  default is refused; binding by hand, the default is no default. Each fails with its piece of the mechanism
+  disabled (checked).
+- **Owners pass the running mode's source alone:** `SSR.spec.js` and `graph_build_froxel_gi.spec.js` check, per mode,
+  that the pass binds that mode's source and no other's, and that the frame then submits on the software device.
+  An owner binding another mode's source, as option A would have, fails them (checked).
+- **Water's dependency is pinned:** taking `chunk_water_gi` back out of `finalize_body` fails the consumer spec's water
+  test and both water optics rows of `water_shaders_wgsl_validity.spec.js` (checked).
+- **The AVBOIT orchestrator spec** gained a test on the software device: water's optics are drawn with the mode of the
+  set the orchestrator is handed, and bind every mode's resources by name without an error.
+- **`shadow_directional_technique_consumers.spec.js`** now crosses the shadow technique with every indirect lighting
+  mode and both ways of shading local lights. Fifteen other specs follow the renames.
+- **Gates:** the shade suite passes, 894 files and 6,787 tests. `check-types` reads 18, the same as the base.
+
+#### Device checks (one-off, headless Chrome, RTX 4090)
+
+- **One mode per pipeline.** A probe recorded every pipeline's WGSL while the avboit, water_refraction and
+  particle_ecs playgrounds were switched through IBL, Brick4 and LPV, AVBOIT and MBOIT, with SSR and then ReSTIR on.
+  Every pipeline of a switched shader links exactly one mode's sampling:
+
+  | shader | pipelines |
+  |---|---|
+  | AVBOIT draw, MBOIT resolve, water optics | the default (environment), `[indirect lighting=Brick4]` (Brick4), `[indirect lighting=LPV]` (environment) |
+  | SSR resolve | one per mode, each linking only its own |
+  | Volumetrics / GI | one per mode, each linking only its own |
+  | Shade From G-Buffer | the default (clustered), `[local light shading=ReSTIR]` (ReSTIR) |
+
+  No compilation or validation errors came from these shaders, with option B's defaults standing in for the other
+  modes' sources in SSR and froxel GI (run again after B).
+- **GPU time, before and after.** A bench copy of the tree held both paths, the old per-mode shader with its own
+  bindings and the new one with the union, and its owners picked one per frame. Arms alternated in blocks of four
+  frames inside one capture, the first frame of each block dropped, with four captures per setting in alternating
+  order (`ab_drive`). Frames were checked to have drawn the arm's own pass. Spans are quantised to 1.024 µs, so the
+  medians are what can be read:
+
+  | pass | setting | median, old / new | captures |
+  |---|---|---|---|
+  | AVBOIT draw | IBL, avboit playground | 1.000 | 4 of 4 |
+  | AVBOIT draw | Brick4 | 1.000 | 4 of 4 |
+  | SSR resolve | IBL, ssr_reprojection, lateral and still, 1280 | 1.000 | 7 of 8; the eighth 0.976, one quantum |
+  | SSR resolve | Brick4, lateral | 1.000 in one capture, 1.018 (one quantum) in three | 4 |
+
+  Pass times were about 59 µs (AVBOIT IBL), 66–69 µs (AVBOIT Brick4), 42 µs (SSR IBL) and 56–57 µs (SSR Brick4).
+  The avboit playground found no environment map on this machine and lit the scene by its own lights alone.
+  These were taken before option B, with the scene's buffers in the entries the variant does not read; B puts
+  transient buffers there instead, which changes nothing the shader reads.
+
+#### Found along the way, not changed
+
+- **ReSTIR DI's resample and spatial passes do not compile in Chrome.** `WEIGHT_LIMIT = 3.4028235e38` in
+  `restir/reservoir/shader.js` rounds above the largest f32, and Tint refuses it. This predates stage 2 (`57e2f80b2`).
+  The deferred pass's ReSTIR variant itself compiles.
+- **`chunk_water_inscatter` and `chunk_water_receiver_downwelling`** still call `water_gi_irradiance` without listing
+  a dependency. Their spec harnesses supply a stub. `finalize_body` lists `chunk_water_gi`, so the shader's graph
+  is explicit.
+- **LPV's transparent and water variants** are separate pipelines with the same code as IBL's (§4.5's correction).
+
+### 12.3 Stage 3, as built (2026-10-16, uncommitted)
+
+#### What it contains
+
+- **A declaration apart from its placement.** `ShaderResourceDescriptor.uniform`, `.storageBuffer`, `.texture`,
+  `.storageTexture` and `.sampler` make a declaration alone: name, kind, type, default. The group's `addX` methods call
+  them, and `group.add(declaration)` places a copy (`clone_declaration`), so one declaration sits in any number of
+  groups at their own binding indices and visibilities.
+- **What satisfies a declaration** (`isSatisfiedBy`): a binding of the same name and WGSL type with at least the
+  declared access. A read-only storage buffer is satisfied by a read-write one, a `float` texture by an
+  `unfilterable-float` one; `depth` is a type of its own; a sampler is a comparison sampler or not; a storage texture
+  keeps its format and dimension, with its access a subset. Placement, visibility and defaults do not count.
+- **The channel,** beside `addExtension`: `CodeChunk.requireResource(declaration)`, read back through
+  `required_resources`. `specialize` and `copy` carry it, and a choice refuses one, since it has no text to read
+  with. `compile()` returns `resources`: each declaration once, with the first chunk in link order that declared it.
+- **The check.** `ShaderDescriptor.compile()` looks each declaration up in its resource set by name:
+  - unbound: `'light_count' reads 'light_data', which 'test unbound' does not bind`;
+  - mistyped: `… reads 'light_data' as a read-only-storage buffer of array< u32 >, which 'test mistyped' binds as a
+    2d unfilterable-float texture`.
+  
+  Image, compute and template shaders all compile through it, so a variant checks only what its selected
+  alternatives declare. It throws rather than asserts: it runs once per variant, at link.
+- **`ShaderDescriptor.body`,** the graph a shader links, choices still in it.
+- **Declarations, exported where the data lives:**
+
+  | file | declarations |
+  |---|---|
+  | `camera/CAMERA_RESOURCE.js`, `view/VIEW_RESOURCE.js` | `camera`, `view` |
+  | `light/LIGHT_DATA_RESOURCE.js`, `light/cluster/LIGHT_CLUSTER_RESOURCES.js` | `light_data`; `cluster_parameters`, `cluster_lookup`, `cluster_data` |
+  | `light/environment/ENVIRONMENT_MAP_RESOURCE.js`, `ENVIRONMENT_SH_RESOURCE.js` | `tEnvironment`, `environment_sh` |
+  | `shadow/map/SHADOWMAP_RESOURCES.js` | `shadowmapAtlas`, `sCompareLinear` |
+  | `global_illumination/brick4/gpu/BRICK4_RESOURCE.js`, `…/octahedral/LPV_SHADER_RESOURCE_GROUP.js` | `brick4`; the light probe volume's six |
+  | `STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js`, `texture/SAMPLER_LINEAR_RESOURCE.js` | `tSTBN_vec2`, `tSTBN_vec3`, `tSplitSum`; `sLinear` |
+  | `deferred/GBUFFER_RESOURCES.js`, `restir/di/RESTIR_RADIANCE_RESOURCE.js` | `gBufferPBR`, `gBufferAlbedo`, `gBufferEmissive`, `tAlbedoAO`; `tRestirRadiance` |
+  | `volumetrics/VOLUMETRICS_RESOURCES.js`, `…/gi/volumetrics_gi_resources.js`, `chunk_volumetrics_sun_optical_depth.js` | `volumetrics_metadata`, `tVolumetrics`, `tParticipatingMedia1`; `tGIY`, `tGICoCg`; the sun's cascades |
+  | `shader/chunk/screen_space/SCREEN_SPACE_RESOURCES.js` | `tDepth`, `tHZB`, `tNormal` |
+  | `geometry/GEOMETRY_ATTRIBUTE_DATA_RESOURCE.js`, `geometry/meshlet/MESHLET_METADATA_RESOURCE.js`, `scene/SCENE_DATABASE_RESOURCE.js` | `meshlet_data`, `meshlet_metadata`, `scene_database` |
+  | `material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js`, `water/surface/WATER_SURFACE_RESOURCES.js`, `water/shader_water.js` | the standard material's nine; the surface interface's five; water's trace and LOD |
+
+- **Migrated:** every chunk the eight switched shaders link in any variant declares what its own functions read,
+  and so do the sibling chunks in the same files: 56 chunks in 52 files. The prose lists of bindings they replace are gone ("relies on the `light_data` storage
+  binding…", "Bindings it reads: …").
+- **Groups built from the declarations:** `SHADING_LIGHT_RESOURCE_GROUP`, `LPV_SHADER_RESOURCE_GROUP`,
+  `SHADING_MATERIAL_RESOURCE_GROUP`, the froxel GI group, water's resources and the sun's cascades in the lighting pass.
+  Every other group keeps its `addX` calls, which satisfy the declarations by name and type.
+
+#### What changed in the code
+
+Every exported shader and every variant of the switched ones, 406 modules, was linked on the base and on stage 3
+and compared with the `Struct_N` names normalised. 399 are identical. The rest are the six shaders below, which gain
+the bindings their chunks read, and one script's error message (a path).
+
+#### Found and fixed: six shaders that could not compile
+
+A migrated chunk is checked wherever it is linked, and six shaders link one that reads a binding they never bound.
+Tint (headless Chrome, RTX 4090) refuses master's sources for all six: `unresolved value 'meshlet_data'` in the
+geometry SDF build and the four lightmap debug views (`density`, `uv_checker`, `view_flat`, `view_sh`), and
+`unresolved value 'tHZB'` in screen-space shadows. Until now they failed at `createShaderModule`; the check fails
+them at link, and their modules threw on import. None is reached in-tree: `GPUGeometryManager.sdf` throws "Not
+implemented", and nothing imports the other five. Each now binds what its chunks read, appended to its group:
+
+- **Screen-space shadows:** `tHZB`. Compiles on Tint.
+- **Geometry SDF build:** `meshlet_metadata` and `meshlet_data`, and `GPUGeometrySDFManager` passes
+  `geometries.meshlets`' buffers as every other dispatch does. Compiles on Tint.
+- **The lightmap debug views:** the same two buffers, so they import again. On Tint they now stop at `struct member
+  lightmap_uvs not found`: the mesh struct no longer has the field. Not changed.
+
+#### Tests
+
+- **`ShaderResourceDescriptor.spec.js`** (6 tests): what satisfies a declaration, per kind.
+- **`ShaderResourceGroupDescriptor.spec.js`** (+1): one declaration in two groups sits at each group's index, and
+  visibility is the group's.
+- **`CodeChunk.spec.js`** (+1) and **`CodeChunkChoice.spec.js`** (+1): collection at link; a choice refuses a
+  declaration.
+- **`ShaderDescriptor.spec.js`** (+4): unbound and mistyped name the chunk, the binding and the shader; a binding read
+  as declared, or read-write, links the same source as no declaration; a variant checks only its selected alternative.
+- **`switched_shaders_declare_bindings.spec.js`** (7 tests), the audit: every chunk of the eight switched shaders,
+  in every variant, declares exactly the module-scope bindings its own functions read, parsed, with parameters and
+  locals excluded. The shader's body is where its bindings are written, and declares nothing. It failed with 106
+  findings over 50 chunks before the migration.
+- **`GPUGeometrySDFManager.spec.js`:** its geometry manager stand-in gains the meshlet buffers.
+- **Gates:** the shade suite passes, 901 files and 6,833 tests. `check-types` reads 18, the same as the base.
+
+#### Device check (one-off, in-app browser)
+
+The modules are the same text, so the check is that the renderer's pipelines still link and run. The avboit
+playground compiled its nine AVBOIT modules and drew AVBOIT and MBOIT, under IBL and Brick4 each, for 2,038 frames;
+the vsm playground drew cascades and then virtual shadow maps. No uncaptured device error came from either.
+
+#### Found along the way, not changed
+
+- **Water's optics still call `water_gi_irradiance` without a dependency.** Making `chunk_water_gi` their dependency
+  was tried: the shader is unchanged, but the in-scatter oracle and the downwelling spec harnesses supply their own
+  stub through that name, and would then link two definitions, which the emulator tolerates and WGSL does not.
+  Fixing it means a choice of how the sky reaches these chunks: an argument, or a stub chunk the harness specializes in.
+- **The lightmap debug views' `lightmap_uvs`,** above.
+- **Placement derived from the declarations,** the larger change to the shader class this stage anticipated (§5.3):
+  not built. Groups still place their bindings by hand, and declarations only check them.