@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/shader/compiler/CodeChunkChoice.js

@@ -2,6 +2,7 @@ import { assert } from "../../../../core/assert.js";
 import { CodeChunk } from "./CodeChunk.js";
 
 /**
+ * @typedef {import("../resource/ShaderResourceDescriptor.js").ShaderResourceDescriptor} ShaderResourceDescriptor
  * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
  * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
  */
@@ -104,6 +105,15 @@ export class CodeChunkChoice extends CodeChunk {
         return false;
     }
 
+    /**
+     * A choice has no text of its own to read anything: the alternative that reads a binding declares it.
+     * @param {ShaderResourceDescriptor} resource
+     * @returns {boolean}
+     */
+    requireResource(resource) {
+        throw new Error(`${this} has no text of its own; declare '${resource.name}' on the alternative that reads it`);
+    }
+
     /**
      * A choice is linked as the alternative it stands for; see {@link CodeChunk#specialize}.
      */

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

@@ -1,10 +1,9 @@
-# Shader switches: a proposal (2026-10-16, revision c; stage 1 landed)
+# Shader switches: a proposal (2026-10-16, revision c; stages 1 and 2 landed)
 
-**Status: stage 1 is on master (2026-10-16; §12). Stages 2 and 3 are open (§6, §11).**
+**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 stage 1 contains and how it was checked:
-the shade suite (879 files, 6,744 tests), `check-types` at the base's 18, and a device run. Revisions (a) and (b) are
-superseded by your answers.
+§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
 
@@ -340,8 +339,11 @@ A few things fall out of variants being whole static objects:
 
 - **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. Distinct variants are distinct pipelines. Sets that produce the same text share one: LPV and
-  IBL on the transparent paths, or any set differing only in switches a shader does not have.
+  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.
@@ -373,10 +375,15 @@ A few things fall out of variants being whole static objects:
 |---|---|---|
 | 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` + 3 textures, 3 buffers | Brick4 and STBN yes; LPV's only when LPV runs |
-| froxel GI (a module per mode) | Brick4 `brick4`; LPV its atlas and buffers | Brick4 yes; LPV's only when LPV runs |
+| 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).
@@ -395,10 +402,22 @@ never the interface (D4 holds forever, not just in stage 1). It follows that:
   - 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.
-
-**Unmeasured:** whether an unread binding in a layout costs anything at draw time. I know of no reason it would, and
-`SHADING_LIGHT_RESOURCE_GROUP` is already shared by shaders that do not read all of it. Stage 2 would measure the
-transparent pass before and after.
+  - *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
 
@@ -466,13 +485,13 @@ Every step below is "one definition, one choice, bind by name".
   `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.
+- **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.
+"expects" in prose. *Built for every chunk the switched shaders link (§12.3).*
 
 ### What goes away, in total
 
@@ -598,11 +617,26 @@ four one-concern commits:
 3. `TemplatePassDescriptor`'s;
 4. the shadow switch with the renderer's set and its plumbing.
 
-Open: whether stage 2 (§6) follows next, `INDIRECT_LIGHTING` and `LOCAL_LIGHT_SHADING` with the bindings union.
+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.
 
-## 12. Stage 1, as landed (2026-10-16)
+Also open from stage 3: how the sky reaches water's optics chunks, so they can list the GI they call (§12.3).
 
-### What it contains
+## 12. As built
+
+### 12.1 Stage 1, as landed (2026-10-16)
+
+#### What it contains
 
 - **The mechanism:**
   - `ShaderSwitch` (`enum` / `bool`), `ShaderSwitchSet` and `CodeChunkChoice`;
@@ -629,7 +663,7 @@ Open: whether stage 2 (§6) follows next, `INDIRECT_LIGHTING` and `LOCAL_LIGHT_S
 - **Water:** `create_water_finalize_pipeline_ibl/brick4(switches)`, and `GPUWaterRenderer` caches the result per GI mode
   and set.
 
-### Tests
+#### 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
@@ -645,7 +679,7 @@ Open: whether stage 2 (§6) follows next, `INDIRECT_LIGHTING` and `LOCAL_LIGHT_S
   - 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)
+#### Device check (one-off, headless Chrome, RTX 4090)
 
 The stage-1 tree and its base (`03d5816bd`) were served side by side.
 
@@ -678,3 +712,221 @@ 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.

package/src/shade/renderer/shader/compiler/ShaderSwitch.d.ts

@@ -26,7 +26,7 @@ export class ShaderSwitch {
      * @param {number|boolean} default_value
      * @returns {ShaderSwitch}
      */
-    static "__#69@#make"(label: string, values: ReadonlyArray<number | boolean>, names: ReadonlyArray<string>, default_value: number | boolean): ShaderSwitch;
+    static "__#75@#make"(label: string, values: ReadonlyArray<number | boolean>, names: ReadonlyArray<string>, default_value: number | boolean): ShaderSwitch;
     /**
      * A switch over the members of an engine enum: a plain object of names to distinct integers, one of
      * which is `0` — the value every switch has until a set says otherwise.

package/src/shade/renderer/shader/compiler/ShaderSwitchSet.d.ts

@@ -17,7 +17,7 @@ export class ShaderSwitchSet {
      * @param {Array<number|boolean>} values none of them its switch's default
      * @returns {ShaderSwitchSet}
      */
-    static "__#70@#intern"(switches: ShaderSwitch[], values: Array<number | boolean>): ShaderSwitchSet;
+    static "__#76@#intern"(switches: ShaderSwitch[], values: Array<number | boolean>): ShaderSwitchSet;
     /**
      * The values as one string, the same for the same values. What interning is keyed by.
      * @returns {string}

package/src/shade/renderer/shader/compiler/ShaderSwitchSet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderSwitchSet.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/ShaderSwitchSet.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH;IA0BI;;;OAGG;IACH,cAFU,eAAe,CAEsB;IA0H/C;;;;OAIG;IACH,iCAJW,YAAY,EAAE,UACd,MAAM,MAAM,GAAC,OAAO,CAAC,GACnB,eAAe,CAsB3B;IA/JD;;;OAGG;IACH,kBAEC;IAQD;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,YAAY,CAIxB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,GAAC,OAAO,CAI1B;IAED;;;OAGG;IACH,mBAHW,YAAY,GACV,MAAM,GAAC,OAAO,CAM1B;IAED;;;;OAIG;IACH,oBAJW,YAAY,SACZ,MAAM,GAAC,OAAO,GACZ,eAAe,CA0C3B;IAED;;;;OAIG;IACH,wBAJW,YAAY,EAAE,GACZ,eAAe,CAqB3B;IAED,mBAYC;IA8BL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BAnMY,OAAO,mBAAmB,EAAE,YAAY"}
+{"version":3,"file":"ShaderSwitchSet.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/ShaderSwitchSet.js"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH;IAiCI;;;OAGG;IACH,cAFU,eAAe,CAEsB;IA2I/C;;;;OAIG;IACH,iCAJW,YAAY,EAAE,UACd,MAAM,MAAM,GAAC,OAAO,CAAC,GACnB,eAAe,CAsB3B;IAhLD;;;OAGG;IACH,kBAEC;IAQD;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,YAAY,CAIxB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,GAAC,OAAO,CAI1B;IAED;;;OAGG;IACH,mBAHW,YAAY,GACV,MAAM,GAAC,OAAO,CAM1B;IAED;;;;OAIG;IACH,oBAJW,YAAY,SACZ,MAAM,GAAC,OAAO,GACZ,eAAe,CA2D3B;IAED;;;;OAIG;IACH,wBAJW,YAAY,EAAE,GACZ,eAAe,CAqB3B;IAED,mBAYC;IA8BL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BA3NY,OAAO,mBAAmB,EAAE,YAAY"}

package/src/shade/renderer/shader/compiler/ShaderSwitchSet.js

@@ -36,6 +36,13 @@ export class ShaderSwitchSet {
      */
     #key = '';
 
+    /**
+     * The sets {@link with} has handed out from this one: by switch, then by the position of the
+     * value in its values. What lets a pass that derives a set every frame allocate nothing.
+     * @type {Map<ShaderSwitch, ShaderSwitchSet[]>}
+     */
+    #derived = new Map();
+
     /**
      * The values as one string, the same for the same values. What interning is keyed by.
      * @returns {string}
@@ -92,12 +99,25 @@ export class ShaderSwitchSet {
     with(shader_switch, value) {
         assert.defined(shader_switch, 'shader_switch');
         assert.equal(shader_switch.isShaderSwitch, true, 'shader_switch.isShaderSwitch !== true');
-        assert.ok(shader_switch.is_value(value), `${value} is not a value of shader switch '${shader_switch.label}'`);
+        // a message built only when it fails: a frame that asks again allocates nothing, asserts and all
+        assert.isOneOf(value, shader_switch.values, shader_switch.label);
 
         if (this.get(shader_switch) === value) {
             return this;
         }
 
+        const index = shader_switch.index_of(value);
+
+        let derived = this.#derived.get(shader_switch);
+
+        if (derived === undefined) {
+            derived = new Array(shader_switch.values.length);
+
+            this.#derived.set(shader_switch, derived);
+        } else if (derived[index] !== undefined) {
+            return derived[index];
+        }
+
         const switches = [];
         const values = [];
 
@@ -128,7 +148,11 @@ export class ShaderSwitchSet {
             values.push(value);
         }
 
-        return ShaderSwitchSet.#intern(switches, values);
+        const r = ShaderSwitchSet.#intern(switches, values);
+
+        derived[index] = r;
+
+        return r;
     }
 
     /**

package/src/shade/renderer/shader/graph/graph_prepare_bindings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_prepare_bindings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/graph/graph_prepare_bindings.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,yFANW,MAAM,EAAE,oFA0DlB"}
+{"version":3,"file":"graph_prepare_bindings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/graph/graph_prepare_bindings.js"],"names":[],"mappings":"AAkEA;;;;;;;;GAQG;AACH,yFANW,MAAM,EAAE,oFAgElB"}

package/src/shade/renderer/shader/graph/graph_prepare_bindings.js

@@ -1,6 +1,69 @@
+import { assert } from "../../../../core/assert.js";
 import { encoder_prepare_shader_binding } from "../resource/encoder_prepare_shader_binding.js";
 import { encoder_prepare_shader_bindings_defaults } from "../resource/encoder_prepare_shader_bindings_defaults.js";
 
+/**
+ * Per shader, whether its module reads a binding beyond declaring it, by name; filled as asked.
+ * @type {WeakMap<ShaderDescriptor, Map<string, boolean>>}
+ */
+const shader_reads = new WeakMap();
+
+/**
+ * @param {ShaderDescriptor} shader_descriptor
+ * @param {string} name
+ * @returns {boolean} whether the module names the binding anywhere but its declaration, comments aside
+ */
+function shader_reads_binding(shader_descriptor, name) {
+    let known = shader_reads.get(shader_descriptor);
+
+    if (known === undefined) {
+        known = new Map();
+        shader_reads.set(shader_descriptor, known);
+    }
+
+    let read = known.get(name);
+
+    if (read === undefined) {
+        const code = shader_descriptor.source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+
+        read = (code.match(new RegExp(`\\b${name}\\b`, 'g'))?.length ?? 0) > 1;
+
+        known.set(name, read);
+    }
+
+    return read;
+}
+
+/**
+ * A transient default holds whatever its pooled buffer last held, so it may only stand in for a binding
+ * the shader does not read.
+ *
+ * @param {ShaderDescriptor} shader_descriptor
+ * @param {string[]} input_names the bindings the pass was given
+ * @returns {string|null} the first binding left to its transient default that the shader reads
+ */
+function transient_default_read(shader_descriptor, input_names) {
+    const groups = shader_descriptor.resources.groups;
+
+    for (let i = 0; i < groups.length; i++) {
+        const resources = groups[i].resources;
+
+        for (let j = 0; j < resources.length; j++) {
+            const resource = resources[j];
+
+            if (
+                resource.transient_default
+                && !input_names.includes(resource.name)
+                && shader_reads_binding(shader_descriptor, resource.name)
+            ) {
+                return resource.name;
+            }
+        }
+    }
+
+    return null;
+}
+
 /**
  *
  * @param {ShaderDescriptor} shader_descriptor
@@ -61,5 +124,11 @@ export function graph_prepare_bindings(
     // process defaults
     encoder_prepare_shader_bindings_defaults(bindings, context, resources_descriptor);
 
+    assert.equal(
+        transient_default_read(shader_descriptor, input_names),
+        null,
+        'a storage buffer left to its transient default is read by the shader'
+    );
+
     return bindings;
 }