@woosh/meep-engine 3.60.4 → 3.60.5

package/src/shade/device/IMMEDIATE_DATA_PLAN_2026_08_28.md

@@ -1,569 +0,0 @@
-# WGSL immediate data in Shade — landing plan, 2026-08-28
-
-How to bring the WGSL `immediate` address space (`var<immediate>` + `GPUBindingCommandsMixin.setImmediates`)
-into Shade, starting from `ShadeGPUCommandContext.allocateTransientBuffer` and the call sites that
-feed it.
-
-**Verdict:** worth landing. Shade already models this exact concept, under this exact name, on top of
-uniform buffers — nineteen of the twenty structs literally called `PUSH_CONSTANTS` fit inside the
-64-byte budget unmodified. With no fallback in scope the remaining work is small and almost entirely
-additive.
-
-> **Scope decision (rev 2).** An earlier revision of this plan carried a dual-lowering fallback:
-> `var<immediate>` where supported, `@group(N) @binding(0) var<uniform>` where not, chosen by a
-> capability probe. That is now **out of scope**, and it should never have been in it —
-> [`RENDERER_CONTRACT.md` §2](../RENDERER_CONTRACT.md) already states the rule it violated: *"Shade
-> requires a WebGPU device that meets a fixed floor. There is no feature detection beyond it and no
-> branch that produces a lesser frame."* `ShadeDeviceFailureReason` says the same thing in its header
-> comment, citing D6/I-8: no degradation tiers, no fallbacks, no feature-detection branches.
->
-> Immediates therefore join the floor rather than getting a compatibility path. That deletes: the
-> import-time capability probe and its unrecoverable failure mode, the extra bind group the fallback
-> lowering needed, the resulting exclusion of the 7 shaders already at `maxBindGroups: 4`, and the
-> `vi.resetModules()` dance every dual-lowering spec would have required. If a fallback is ever
-> genuinely wanted, §9 shows why it belongs in a shader variant rather than in the binding machinery.
->
-> **Scope decision (rev 3).** Immediates are also *not* a device floor. `Renderer.initialize()` does
-> not check for them and the contract's §2 is unchanged; a browser without immediates starts and
-> renders as before. Detection is exported instead (§4), so a shader author decides between refusing
-> and reaching for a variant. This keeps the engine's floor where it was while the feature lands.
-
----
-
-## 1. What the feature is, restricted to what matters here
-
-Immediates are WebGPU's portable spelling of Vulkan push constants / D3D12 root constants / Metal
-`setBytes`. The parts that constrain this plan:
-
-| | Value |
-|---|---|
-| WGSL gate | `requires immediate_address_space;` — a **language extension**, not a `GPUFeatureName` |
-| Detection | `navigator.gpu.wgslLanguageFeatures.has('immediate_address_space')` — synchronous, no adapter needed |
-| Size budget | `maxImmediateSize`, default **64 bytes**, multiple of 4, **no separate Compatibility Mode default** |
-| Declaration | Module scope, immutable, **no `@group` / `@binding`** |
-| Store type | Host-shareable constructible, **arrays and structs containing arrays are disallowed** |
-| Count | **At most one** immediate variable statically accessed per entry point |
-| Layout rules | Storage-space (natural alignment), **not** uniform-space |
-| API | `pass.setImmediates(rangeOffset, data, dataOffset, dataSize)`, on render pass, compute pass and bundle encoders |
-| Pipeline layout | `GPUPipelineLayoutDescriptor.immediateSize` (default 0, ≤ `maxImmediateSize`, multiple of 4) |
-| Init | Bytes start zeroed but **slots start unset**; a draw reading an unset 4-byte slot is a validation error |
-| Reset | Per-encoder; survives `setPipeline`, cleared by a new pass and by `executeBundles` |
-
-Because `maxImmediateSize` is a `maximum`-class limit with a default of 64 and no compat-mode
-reduction, **any adapter that exposes the WGSL extension reports at least 64 bytes**. There is no
-device where the language feature is present and the budget is not. That is what makes a floor check
-sufficient and a runtime branch unnecessary.
-
-Availability is a browser-version question, not a hardware one: Vulkan's `maxPushConstantsSize` is
-core-1.0 with a 128-byte required minimum and no feature bit, and no device in the
-`vulkan.gpuinfo.org` corpus reports below 128. Chrome ships immediates in 149–150.
-
----
-
-## 2. The current path, traced
-
-Shade already has this pattern, three layers deep.
-
-**Declaration** — `ShaderResourceGroupDescriptor.addUniform` (`ShaderResourceGroupDescriptor.js:335`):
-
-```js
-const PUSH_CONSTANTS = WebGPUStruct.from({
-    probe_index_offset: u32,
-    probe_update_count: u32,
-    probe_resolution: u32,
-    probe_count: u32
-});
-
-resources.createGroup()
-    .addUniform("settings", PUSH_CONSTANTS)
-    .addTexture("tAtlas_radiance");
-```
-
-**Codegen** — `ShaderResourceSetDescriptor.generateCodeChunk` (`ShaderResourceSetDescriptor.js:305`)
-emits `@group(0) @binding(0) var<uniform> settings : PUSH_CONSTANTS;`.
-
-**Upload, per dispatch** — `ShadeGPUCommandContext.allocateTransientValueBuffer` (`:598`):
-
-```js
-const settings = context.encoder.allocateTransientValueBuffer(PUSH_CONSTANTS, { … });
-
-shader.dispatch({ encoder: context.encoder, bindings: { settings, … } });
-```
-
-which lands in `allocateTransientBuffer` (`:538`) → `GPUBufferAllocator.get` (pooled), then
-`writeValueBuffer` (`:620`) → staging buffer → `copyBufferToBuffer`, then a `BindGroupDescriptor` hash
-lookup in `GraphicsContext.setPipelineBindings` (`GraphicsContext.js:211`) and finally
-`pass.setBindGroup(i, bind_group)`.
-
-The FrameGraph route reaches the same place: `graph_compute_pass` → `graph_prepare_bindings` →
-`encoder_prepare_shader_binding` (`:34`), which turns a raw value or `ArrayBuffer` into a transient
-uniform buffer on the spot.
-
-**Scale of the surface:**
-
-- 67 `allocateTransientValueBuffer` call sites, 11 `allocateTransientBufferAndLoad`, 21 `graph_import_typed_buffer`
-- 300 `addUniform` declarations; 22 of those *call sites* name a `*PUSH_CONSTANTS*` type, across
-  **20 distinct struct definitions** (`LPV_ACCUMULATION_PUSH_CONSTANTS` is shared by four shaders).
-  The table in §6 is per-struct, so it has 20 rows, not 22
-- The single most common transient value type is a bare `u32` (12 sites)
-
----
-
-## 3. What the win actually is
-
-Not bandwidth. 64 bytes at a few hundred dispatches a frame is noise on any bus.
-
-The win is the machinery each of those 20-byte structs currently drags behind it:
-
-1. **A pooled `GPUBuffer` acquire/release per value.** `GPUBufferAllocator.get` plus the transient
-   tracking array in `ShadeGPUCommandContext`, per dispatch, per frame.
-2. **A staging buffer, a `getMappedRange`, an `unmap` and a `copyBufferToBuffer` per value** —
-   `writeValueBuffer` does all four for what is often four bytes.
-3. **A `BindGroupDescriptor` construction plus a `HashMap` lookup per value**, and a cache entry
-   whose key changes every time the value changes — so the small-uniform bind groups are the ones
-   least likely to hit the cache.
-4. **Two JS allocations per value, in the serialiser.** `writeValueBuffer` reaches
-   `write_gpu_typed_buffer`, which calls `scratch_buffer.fromArrayBuffer(data)`, which constructs a
-   fresh `DataView` and `Uint8Array` over the target every single call. Per dispatch, per frame, in a
-   codebase that advertises "zero-allocation" in its own package keywords. The immediate path writes
-   into a persistent `BinaryBuffer` and allocates nothing (§6, L3).
-5. **A `@binding` slot** in the group the settings share.
-
-Point 5 is *only* a binding, not a group. Measured across all twenty candidates: the settings uniform
-shares its group with textures and storage buffers in every case, at a median of about four resources
-per group. No bind group slot is recovered anywhere in the current codebase. (An earlier revision
-claimed otherwise and built an argument on it; that argument is withdrawn.)
-
-**The strongest case is `graph_import_typed_buffer`** (`renderer/shader/graph/graph_import_typed_buffer.js`,
-21 call sites). It does not use the transient pool at all — per execution it calls `device.createBuffer`
-with `mappedAtCreation`, `getMappedRange`, `unmap`, `copyBufferToBuffer`, then `destroy` on
-`encoder.onFinished`. A full buffer create-and-destroy per frame per value, carrying things like
-`LPV_ACCUMULATION_PUSH_CONSTANTS` at 20 bytes. The source carries a standing TODO ("this is pretty
-inefficient, figure out a way to skip needing 2 buffers") and a 2025-09-13 note that the obvious fix —
-transient buffer plus `queue.writeBuffer` — produced garbage for reasons never tracked down.
-Immediates make the two-buffer dance unnecessary by construction for the ≤64-byte cases rather than
-requiring that bug to be found first.
-
-Caveat: converting a `graph_import_typed_buffer` site is *not* a drop-in. It returns a graph resource
-id that passes consume as an ordinary binding, so the consuming pass stops declaring a graph input.
-Higher payoff per site, higher cost per site.
-
-Honest counterweight: on hardware, a 64-byte immediate may well land in a driver-managed constant
-bank rather than in registers, so do not promise a shader-side speedup. Promise the removal of
-CPU-side per-draw allocation, and measure the rest.
-
----
-
-## 4. Capability, not a floor
-
-**Built as optional.** `Renderer.initialize()` does not consult it and nothing was added to
-`RENDERER_CONTRACT.md` §2 — a browser without immediates still starts and still renders. It simply
-cannot run a shader that declares one, and deciding what to do about that belongs to whoever wrote
-the shader.
-
-`device/immediate_data_supported.js` answers the two separate questions:
-
-```js
-immediate_data_supported()                      // does this browser's WGSL have the address space?
-device_supports_immediate_size(device, bytes)   // does this adapter have the budget?
-```
-
-The first is synchronous and needs no adapter — `wgslLanguageFeatures` hangs off `navigator.gpu` —
-so it can be asked at module scope, where shader descriptors are built. That is what makes the
-shader-variant approach in §9 workable: one `if` at the point a shader is chosen.
-
-Nothing goes in `requiredFeatures`: `immediate_address_space` is a WGSL *language* extension, not a
-`GPUFeatureName`, and putting it there would make `requestDevice` reject on every device. Nothing
-goes in `requiredLimits` either — 64 is the spec default, granted without asking.
-
-`ShaderDescriptor.validate_against_device` does check the budget, and throws naming the shader and
-the shortfall. That is a per-draw guard against a device that disagrees with the language extension,
-not a startup gate; it fires only for a shader that actually declares immediate data.
-
-## 5. The one structural obstacle
-
-`ShaderResourceSetDescriptor` is a list of groups; a group is a list of resources; a resource has a
-`binding_index`. Everything downstream — `generateBindings` returning `GPUBindingResource[][]`,
-`generatePipelineLayoutDescriptor` producing one `BindGroupLayoutDescriptor` per group,
-`generateCodeChunk` prefixing every declaration with `@group(g) @binding(b)` — assumes that shape.
-
-An immediate has no group, no binding, and there is at most one per entry point. It has to live
-*beside* the groups, and its value needs a second route to the pass encoder that ends in
-`setImmediates` rather than `setBindGroup`.
-
-Nothing about that requires a device, so the whole thing stays where Shade already does its work:
-in descriptors built at module scope. `PipelineLayoutDescriptor` is device-free by design and stays
-that way.
-
----
-
-## 6. The landing plan
-
-**L1 — declaration + codegen**
-
-- `ShaderResourceSetDescriptor`: an `#immediate` slot beside `#groups`, a `setImmediate(name, type)`
-  that rejects a second call, plus validation at declaration time: `type.size <= 64`, no arrays
-  anywhere in the type (walk it — `WebGPUArray` members and nested structs both), no atomics, size a
-  multiple of 4.
-- `generateCodeChunk` (`ShaderResourceSetDescriptor.js:305`): emit `var<immediate> name : Type;`
-  first, with no `@group`/`@binding` prefix.
-- `ShaderDescriptor.compile` (`ShaderDescriptor.js:53`): the existing mechanism emits
-  `enable ${extension};`. Language extensions use **`requires`**. That needs a second channel on
-  `CodeChunk` — `addLanguageExtension` beside `addExtension` — and a `requires` line in the prelude.
-  Do not overload `addExtension`; its assert is against `WebGPUExtensionType`, which is the
-  `GPUFeatureName` namespace.
-
-**L2 — pipeline layout**
-
-- `PipelineLayoutDescriptor`: an `immediateSize = 0` field, threaded through `from`, `forStage`,
-  `fromJSON`, `hash`, `equals`, `copy`, `clone`. Missing it from `hash`/`equals` would silently alias
-  two layouts that differ only in immediate size — cheap mistake, expensive symptom.
-- `PipelineLayoutManager.#create_pipeline_layout` (`PipelineLayoutManager.js:85`): pass it to
-  `createPipelineLayout`.
-- `generatePipelineLayoutDescriptor` / `generatePipelineLayout`: set it from `roundUp(4, type.size)`.
-
-**L3 — binding resolution and the call**
-
-**Do not change the return shape of `generateBindings`.** Returning `{ groups, immediate }` would
-break all **10** external callers (`GPUParticularRenderer`, `GPUDynamicMeshResidency`,
-`graph_draw_lightmap_viz_buffer`, `prototypeParticleSystem`, `graph_atorus_denoise_luma`,
-`graph_rasterize_meshes_transparent_oit`, `ComputeShader`, `ImageShader`, `RenderPassDescriptor`,
-`GPUWaterRenderer`) and force the new field through the **22** external
-`constructRenderPass`/`constructComputePass` call sites. Purely additive instead:
-
-- `ShaderResourceSetDescriptor.writeImmediate(map, buffer)` — a *new* method that **allocates
-  nothing**. It writes the immediate value into a caller-owned `BinaryBuffer` at that buffer's
-  current `position`, advances `position` by the type's size, and returns `false` when the shader
-  declares no immediate. Every existing `generateBindings` caller is untouched.
-
-  Use the already-exported `write_wgsl_type_value(value, buffer, type)`
-  (`serde/write_gpu_typed_buffer.js:114`), which takes a `BinaryBuffer` directly. **Do not** route
-  this through `write_gpu_typed_buffer` (`:188`): that wrapper calls
-  `scratch_buffer.fromArrayBuffer(data)`, and `fromArrayBuffer` constructs `new DataView(data)` and
-  `new Uint8Array(data)` on every call — two allocations per write, and it resets `position` to 0.
-  The zero-allocation entry point already exists and is public; the wrapper is the thing to avoid.
-
-- `GraphicsContext.setPipelineBindings` (`GraphicsContext.js:211`) gains an optional fourth
-  parameter — the `BinaryBuffer`, plus the byte offset and length written. After the `setBindGroup`
-  loop: `pass.setImmediates(0, buffer.data, byte_offset, byte_length)`. `setImmediates` takes
-  `AllowSharedBufferSource`, and for a plain `ArrayBuffer` the offset and size arguments are in
-  **bytes**, so the backing store is passed through with no copy on our side. All four existing
-  callers keep working.
-
-- `ImageShader.draw` and `ComputeShader.constructPass`/`dispatch` set `position`, call
-  `writeImmediate`, and thread the buffer plus range through as optional fields.
-
-Three properties of `BinaryBuffer` that this design has to respect:
-
-1. **`data` is not stable.** `setCapacity` (and therefore `ensureCapacity`) reallocates the backing
-   `ArrayBuffer` and rebinds `dataView` / `__data_uint8`. Read `buffer.data` at the point of the
-   `setImmediates` call, never cache it — and size the buffer once at construction so it never grows
-   mid-frame.
-2. **Endianness is not the default.** `BinaryBuffer` defaults to `EndianType.LittleEndian`, but the
-   serde module's own scratch sets `endianness = platform_compute_endianness()` (`:179`) because GPU
-   buffer contents must match the host. A caller-supplied buffer that skips this writes correct-looking
-   bytes that are wrong on a big-endian host and identical on the one you test on. Set it at
-   construction, and assert it in `writeImmediate`.
-3. **Ownership.** One long-lived buffer on `ShadeGPUCommandContext`, sized to `maxImmediateSize` at
-   construction, is enough — `setImmediates` copies the bytes at call time, so the region is free for
-   reuse immediately after. The API is still parameterised on `position` rather than hardcoding 0,
-   because that costs nothing and leaves room for a caller that wants to stage several values or keep
-   a frame log of them.
-- `encoder_prepare_shader_binding` (`:34`): in the immediate case, return the raw value rather than
-  allocating a transient buffer.
-
-**The eight bypass paths.** `setPipelineBindings` does not cover everything. Eight files drive
-`pass.setBindGroup` directly and never touch it — `GPUMaterialManager`, `prototypeParticleSystem`,
-`graph_build_depth_mipmap`, `render_copy_texture`, `graph_rasterize_meshes_alpha_tested`,
-`graph_rasterize_meshes_transparent_oit`, `draw_texture_as_rgba`, `WebGPUMipmapGenerator`. A shader
-migrated in one of those needs its own `setImmediates` call at the right point in the loop. None of
-the twenty candidates lives there, so this constrains future migration rather than this landing — but
-it must not be assumed away.
-
-**L4 — the test tiers**
-
-Without a fallback these are not optional: they are the only way immediates get exercised outside a
-browser.
-
-- **WGSL validation** (`wgsl/validate_wgsl_source.js`) — teach it that `var<immediate>` is legal and
-  `requires immediate_address_space;` is a valid directive, so the new declaration does not trip the
-  foreign-token or undeclared-call rules.
-- **JS emulator** — a real trap. `collectGlobalVariable`
-  (`wgsl/emulator/WGSLJavaScriptCompiler.js:825`) only pushes to `globalBindings` when *both* `group`
-  and `binding` are non-null (`:862`). A `var<immediate>` has neither, is not `workgroup`, and falls
-  through to the `privateGlobals` branch, where it is **silently default-initialised**. Every emulator
-  spec for an immediate-using chunk would pass while reading zeros. Route
-  `address_space === 'immediate'` into `globalBindings` with a null group/binding so
-  `emu.bindings.settings = {…}` keeps working by name.
-- **SoftwareGPUDevice** — `DEFAULT_LIMITS.maxImmediateSize` (`mock/SoftwareGPUDevice.js:67`) is
-  already present, set to `0`. Raise it to 64, add `setImmediates` to `SoftwareGPURenderPassEncoder`
-  (`:130`) and `SoftwareGPUComputePassEncoder` (`:108`) with the spec's `[[immediate_data]]` /
-  `[[immediate_slots_set]]` state, validate `rangeOffset % 4`, size `% 4` and the range bound, and
-  snapshot the bytes into each recorded draw/dispatch the way `#snapshot_bindings` already snapshots
-  bind groups. Follow the folder's stated policy in `mock/IMPLEMENTATION_PLAN.md` §2: validation
-  errors go through `generate_error`, they do not throw. `createPipelineLayout` (`:766`) gains the
-  `immediateSize ≤ maxImmediateSize` and `% 4` checks. Emulate the unset-slot rule too — it is the
-  mock's chance to catch a missing `setImmediates` before a browser does.
-- **Playground** — one pass converted end to end and run in Chrome before any bulk migration.
-
-**L5 — migration**
-
-Smallest first. `shader_read_out_bucket` (4 bytes, one `u32`) is the ideal first patient;
-`shader_generate_rays` and `shader_shadow_upscale` are the same shape.
-
-**It is not one line per shader.** Only 5 of the 20 candidates supply their settings implicitly, by
-passing a plain object in `bindings` and letting `encoder_prepare_shader_binding` allocate. The other
-~15 have an explicit `allocateTransientValueBuffer` or `graph_import_typed_buffer` call that
-pre-builds the buffer and passes the `GPUBuffer`. Those need two edits: the declaration, and the call
-site that stops pre-allocating.
-
----
-
-## 7. Candidate inventory
-
-Every struct named `*PUSH_CONSTANTS*`, sized by `WebGPUStruct` (the same natural-alignment layout the
-`immediate` address space uses). Sizes were re-derived programmatically — field lists extracted from
-source and fed back through the real `WebGPUStruct.from`, not computed by hand.
-
-| Struct | Size | Verdict |
-|---|---:|---|
-| `shader_read_out_bucket` | 4 | fits |
-| `shader_generate_rays` | 4 | fits |
-| `shader_shadow_upscale` | 4 | fits |
-| `shader_sharc_evict` | 8 | fits |
-| `shader_lightmap_accummulate_tile` | 8 | fits |
-| `shader_lightmap_tile_composit` | 8 | fits |
-| `graph_lpv_store_sh` | 16 | fits |
-| `shader_perfect_perspective` | 16 | fits, see note |
-| `graph_lvp_atlas_to_sh` | 20 | fits |
-| `LPV_ACCUMULATION_PUSH_CONSTANTS` | 20 | fits |
-| `shader_lpv_accumulate_depth` | 20 | fits |
-| `graph_sample_light_probes` | 20 | fits |
-| `graph_reduce_atlas_to_sh` | 24 | fits |
-| `shader_lpv_build_gbuffer` | 24 | fits |
-| `shader_update_clipmap_cascade` | 32 | fits |
-| `graph_lpv_shade` | 32 | fits |
-| `shader_build_scene_sdf_f32` | 32 | fits |
-| `shader_scene_sdf_debug_viz` | 32 | fits |
-| `shader_scene_sdf_soft_shadows` | 48 | fits |
-| `LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS` | 128 | **cannot move** |
-
-`LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS` fails twice: 128 bytes against a 64-byte budget, and
-`frustum: WebGPUArray.from(vec4f, 6)` is an array, which the `immediate` address space disallows
-outright. It stays a uniform buffer. If the rest is worth moving later, the split is
-`{cluster_params, screen_resolution, distance_min, distance_max}` at 32 bytes as an immediate with the
-frustum left in a buffer — a follow-up, not part of this landing.
-
-Note on `shader_perfect_perspective`: its `use_vignette` member is typed `bool`, and Shade's `bool`
-primitive (`WEBGPU_WGSL_PRIMITIVE_TYPES.js:8`) is a 4-byte type. WGSL's host-shareable set is numeric
-scalars, vectors, matrices, atomics, arrays and structs of those — `bool` is in none of them, in *any*
-address space, uniform included. So this is a pre-existing condition rather than something immediates
-introduce, but the member needs to become `u32` before this struct can move. Worth checking whether
-that shader is reachable at all; grep finds no importer.
-
-Beyond the named ones, the 12 bare-`u32` `allocateTransientValueBuffer` sites are the same pattern
-without the naming, and are equally good candidates.
-
-### What must not move
-
-`CAMERA_UNIFORM_STRUCT` (~640 bytes: eight `mat4x4f`, a six-element `vec4f` frustum array, and more)
-and `VIEW_UNIFORM_STRUCT` account for 116 of the 300 `addUniform` calls. They are per-view, written
-once, read by everything — over budget, containing arrays, and not per-draw data. They stay. Same for
-anything reached through `GPUDatabase` or `GPUSingleTypeTable`.
-
----
-
-## 8. What was built
-
-Landed in one pass, all against a green suite (14,873 tests). Deviations from the plan above are
-noted where they occurred.
-
-**Mock device** — `SoftwareGPUImmediateData.js` holds WebGPU's `[[immediate_data]]` /
-`[[immediate_slots_set]]`; `setImmediates` on both pass encoders, with content-timeline failures
-throwing `OperationError` and device-timeline failures invalidating the encoder through a new
-`SoftwareGPUCommandEncoder#notify_pass_validation_error`; `maxImmediateSize` raised 0 → 64;
-`createPipelineLayout` validates `immediateSize`. Draws and dispatches now run WebGPU's *Validate
-immediate data*, so a forgotten `setImmediates` is caught here rather than in a browser.
-
-**Emulator** — `WGSLJavaScriptCompiler` routes `var<immediate>` into `globalBindings` instead of
-letting it fall through to `privateGlobals`, where it was silently default-initialised. Pinned by a
-spec that fails without the fix.
-
-**Validator** — *no change needed.* The plan assumed `validate_wgsl_source` would have to learn about
-`requires` and `var<immediate>`; it already accepts both. A regression test pins that so a future
-rule cannot start false-positiving on them.
-
-**Pipeline layout** — `PipelineLayoutDescriptor.immediateSize`, through `from`/`forStage`/`fromJSON`/
-`hash`/`equals`/`copy`, and passed to `createPipelineLayout` by the manager.
-
-**Codegen** — `CodeChunk#addLanguageExtension` as a separate channel from `addExtension`, emitted as
-`requires` rather than `enable` and deliberately not folded into `#features` (a different namespace
-from `GPUFeatureName`). `ShaderResourceSetDescriptor#setImmediate` validates size, arrays at any
-depth, atomics and runtime sizing at declaration time.
-
-**Binding** — `writeImmediate(map, buffer)` writes into a caller-owned `BinaryBuffer` at its
-`position` via the already-public `write_wgsl_type_value`, allocating nothing.
-`ShadeGPUCommandContext` owns one such buffer for the life of the context.
-`GraphicsContext#setPipelineBindings` took an optional fourth parameter, so all four existing callers
-are untouched — `generateBindings` kept its return shape and its 10 callers were not disturbed.
-
-**FrameGraph** — the plan missed this entirely. `getResourceByName` only searches groups, so the
-graph path threw for any immediate; and worse, `graph_prepare_pass_input_data` and
-`graph_prepare_bindings` read a numeric input as a graph resource id, which would have silently
-misread a bare `u32` immediate as a handle. `isImmediateName` now short-circuits all three helpers.
-Pinned by a spec that fails without it.
-
-**Detection** — `immediate_data_supported()` / `device_supports_immediate_size()`, plus a budget
-check in `ShaderDescriptor.validate_against_device`.
-
-### Not done
-
-- **No production shader migrated.** The 19 candidates in §7 are unchanged; this is the machinery
-  only. `shader_read_out_bucket` remains the right first patient.
-- **`shader_perfect_perspective`'s `bool` member** is still a `bool` (§7's note). Pre-existing, and
-  it blocks only that one struct.
-- **The eight `setBindGroup` bypass paths** (§6, L3) are untouched. No candidate lives there.
-
-## 9. Transition candidates, proved
-
-Every candidate below was **actually transitioned** — declaration and call site edited in the working
-tree — then proved, then reverted. This section records what the proof showed, not what inspection
-suggested. The tier-1 entries were carried all the way through; the rest were assessed against the
-same checks without being applied.
-
-### What "proved" means here
-
-The six checks each applied transition had to pass:
-
-1. **Module imports.** These shaders build at module scope, so a rejected type, a broken declaration
-   or bad codegen throws at import.
-2. **`immediateSize` is what the struct says.**
-3. **Generated WGSL declares `var<immediate>` with no `@group`/`@binding`, and emits `requires`.**
-4. **`validate_wgsl_source` returns no diagnostics** on the generated source.
-5. **`pipeline.layout.immediateSize` matches**, so a device would accept the pipeline.
-6. **A value round-trips** through `writeImmediate` into the expected words.
-
-Plus, across the whole set: the settings name must no longer resolve through `getResourceByName` or
-appear in any group — a stale uniform left beside a new immediate would bind twice.
-
-**What the proof does not cover, and why the scores are not higher.** *None of these shaders has any
-spec coverage* — `grep -rl <name> --include=*.spec.js` returns zero for every one, and for their call
-sites too. The full suite passing with all five applied (14,887 tests) therefore says only that
-nothing *else* broke. Nothing executes these passes outside a browser, so the call-site edit is
-verified by inspection and by the diff being a verbatim move, not by running it.
-
-**The one silent failure mode.** A misspelled *field* inside the value object is not an error:
-`write_gpu_typed_buffer` writes 0 for a member it cannot find. Probed and confirmed —
-`{bucket_ID: 11, frame: 2}` against `{bucket_id, frame}` yields words `[0, 2]`, no throw. This is
-pre-existing behaviour that immediates inherit rather than introduce (the same is true of
-`allocateTransientValueBuffer` today), but it is why every transition below moves the object literal
-**verbatim** rather than retyping it, and why the diffs are worth reading rather than trusting.
-
-### Tier 1 — transitioned and proved end to end
-
-| Shader | Bytes | Call-site change | Group effect | Net lines | Confidence |
-|---|---:|---|---|---:|---:|
-| `shader_sharc_evict` | 8 | **none** — already passes a plain object | leads a group of 4; siblings shift down one | −0 | **95%** |
-| `shader_shadow_upscale` | 4 | **none** — already passes a plain object | leads a group of 5; siblings shift down one | −0 | **95%** |
-| `shader_read_out_bucket` | 4 | 2 sites, inline `{ bucket_id }` | **owns group 0 outright** — group disappears, later groups renumber | −8 | **90%** |
-| `shader_generate_rays` | 4 | 1 site, inline `{ frame_index }` | **last in its group** — no sibling index moves | −4 | **92%** |
-| `graph_lvp_atlas_to_sh` | 20 | 1 site, inline 5-field object | owns group 0 outright — group disappears | −5 | **85%** |
-
-The two at 95% need *no call-site edit at all*: they already pass `settings: { … }` as a plain
-object, because the immediate path accepts a value where the uniform path demands a bindable buffer.
-Their entire diff is one line in the declaration. The residual 5% is that no test executes them.
-
-`shader_read_out_bucket` scores lower than `shader_generate_rays` despite being smaller: removing its
-uniform empties group 0, so every later group renumbers. That is consistent between the WGSL and the
-layout because both regenerate from the same descriptor, and it is why it still scores 90 — but it is
-a larger blast radius than a declaration that sits last in a shared group and moves nothing.
-
-`graph_lvp_atlas_to_sh` is the lowest of the tier because its value object has five fields drawn from
-four different sources, which is the most surface for the silent-misspelling failure above.
-
-### Tier 2 — same shape, not yet applied
-
-Assessed against the same checks by inspection. All are live (one importer each), all fit, none
-contains an array.
-
-| Shader | Bytes | Notes | Confidence |
-|---|---:|---|---:|
-| `graph_lpv_store_sh` | 16 | leads a group of 3 | 80% |
-| `graph_reduce_atlas_to_sh` | 24 | owns its group | 80% |
-| `shader_lpv_build_gbuffer` | 24 | ImageShader | 75% |
-| `shader_lpv_accumulate_depth` | 20 | ImageShader, group of 5 | 75% |
-| `graph_lpv_shade` | 32 | group of 3 | 75% |
-| `graph_sample_light_probes` | 20 | ImageShader, group of 7 | 70% |
-| `shader_build_scene_sdf_f32` | 32 | **two** resource sets (f32 and f16) share one struct; both must move together | 65% |
-
-`LPV_ACCUMULATION_PUSH_CONSTANTS` (20 bytes, 5 importers) is deliberately absent. It is shared across
-four shaders and supplied through `graph_import_typed_buffer`, so it is not a per-shader edit — it is
-the `graph_import_typed_buffer` conversion described in §3, which changes how the consuming pass
-declares its input. Higher payoff, different job.
-
-### Not worth doing
-
-Six candidates have **zero importers** — nothing in the tree constructs them:
-`shader_lightmap_tile_composit`, `shader_lightmap_accummulate_tile`, `shader_update_clipmap_cascade`,
-`shader_perfect_perspective`, `shader_scene_sdf_debug_viz`, `shader_scene_sdf_soft_shadows`.
-
-They would transition trivially and change nothing that runs. `shader_perfect_perspective` also still
-carries the `bool` member from §7. Migrating dead shaders would inflate the count and prove nothing;
-they are listed so nobody spends a morning on them.
-
-`LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS` remains excluded on both counts — 128 bytes and an array.
-
-### Recommended order
-
-`shader_sharc_evict` first, then `shader_shadow_upscale`: one line each, no call site, and they
-establish the pattern with the smallest possible diff. `shader_generate_rays` next, as the first with
-a call-site edit. Then `shader_read_out_bucket`, which is the first to renumber groups and therefore
-the first worth looking at in a browser before moving on.
-
-Before any of them lands in a build anyone plays: run one in Chrome 149+. Nothing in the suite
-executes these passes, and that gap is the whole of the residual risk.
-
----
-
-## 10. If a fallback is ever wanted anyway
-
-It belongs in a shader variant, not in the binding machinery — and Shade already supports that with
-no new mechanism. `ShaderDescriptor.compile()` clones the body chunk and adds the resource set's
-generated chunk as a dependency:
-
-```js
-const chunk = this.#body.clone();
-chunk.addDependency(this.#resources.generateCodeChunk());
-```
-
-So one `CodeChunk` body pairs with two different `ShaderResourceSetDescriptor`s to produce two
-`ShaderDescriptor`s — immediate and uniform — from a single source of shader text, selected by
-whoever constructs them. The body never changes: `settings.probe_count` reads identically either way.
-
-That is a per-shader, opt-in decision made by the shader's author, which is a very different thing
-from a capability branch threaded through codegen, pipeline layout, binding resolution and the test
-harness. Keeping the door open costs nothing; walking through it preemptively cost a great deal.
-
----
-
-## 11. Open questions
-
-- **Which shader migrates first, and when?** Answered in §9: `shader_sharc_evict` and
-  `shader_shadow_upscale` need no call-site edit at all. The machinery is inert until one lands.
-- **Do these passes get a spec before or after they migrate?** None of the twelve live candidates has
-  any test coverage, which is the entire residual risk in §9. A spec that drives one through the
-  software device would convert several 75s into 90s, and is probably worth more than the next three
-  migrations.
-- **Is 64 bytes worth revisiting later?** `maxImmediateSize` is raisable, but D3D12's root signature
-  budget means no browser is likely to expose more. `IMMEDIATE_SIZE_FLOOR` refuses more than 64 at
-  declaration; if a project ever knows its device offers more, that constant is the single place to
-  relax.
-- **Should `graph_import_typed_buffer`'s two-buffer dance be fixed independently?** §3 argues its 21
-  call sites are the strongest case for immediates, but the standing TODO there is a separate bug —
-  the 2025-09-13 note says the obvious fix produced garbage and was never chased down. Immediates
-  route around it for the ≤64-byte cases without explaining it.
-  Answered 2026-09-26: fixed independently. The garbage was frame-graph aliasing — a `queue.writeBuffer`
-  into a pooled buffer lands ahead of the whole submission, and a pass earlier in it had written that
-  buffer for another resource. The import now writes with `writeValueBuffer`, in order, and creates no
-  buffer per frame; `graph_import_typed_buffer.spec.js` pins both. Immediates would still drop the
-  buffer altogether for the ≤64-byte cases.