@woosh/meep-engine 3.11.1 → 3.11.3

package/src/shade/device/IMMEDIATE_DATA_PLAN_2026_08_28.md

@@ -1,451 +1,564 @@
-# 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.
-
----
-
-## 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. The floor
-
-Immediates become a floor requirement, stated in `RENDERER_CONTRACT.md` §2 next to
-`indirect-first-instance` and `maxStorageBuffersPerShaderStage ≥ 10`, and checked in `Renderer.js`
-using the idiom already there (`Renderer.js:1123`).
-
-Two checks, both before the device is requested, so the failure names what was missing:
-
-```js
-// earliest — wgslLanguageFeatures lives on navigator.gpu, no adapter required
-if (!gpu.wgslLanguageFeatures.has('immediate_address_space')) {
-    throw ShadeDeviceFailure.below_floor(
-        "requires WGSL immediate data (Chrome 149+); this browser does not support it"
-    );
-}
-
-// beside the existing maxStorageBuffersPerShaderStage check, on the adapter
-const maxImmediateSize = adapter.limits.maxImmediateSize;
-if (maxImmediateSize < 64) {
-    throw ShadeDeviceFailure.below_floor(
-        `requires 64 bytes of immediate data, adapter offers ${maxImmediateSize}`
-    );
-}
-```
-
-`below_floor` is the right reason code: an adapter that does not meet §2, with the detail. Nothing
-goes in `requiredFeatures` — `immediate_address_space` is a WGSL language extension, not a
-`GPUFeatureName`, and adding it there would make `requestDevice` reject on every device. Nothing goes
-in `requiredLimits` either: 64 is the spec default, so a device gets it without asking.
-
-**When the floor rises.** Not in the plumbing commits — a shader that declares no immediate emits no
-`requires` directive and needs nothing. The floor and the checks land in the same commit as the
-**first migrated shader** (§8 step 6), so the engine keeps running on older Chrome for as long as it
-still can. That is one commit where the browser support statement changes, and it should say so in
-its message.
-
----
-
-## 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. Commit sequence
-
-Steps 1–5 are inert without a shader that declares an immediate, so the engine still runs on older
-Chrome throughout. Step 6 is where the floor rises.
-
-1. `feat(shade): the software device carries immediate data` — L4's mock work alone. Raises
-   `maxImmediateSize` to 64, adds `setImmediates` to both pass encoders with spec state and
-   validation, `immediateSize` validation on `createPipelineLayout`.
-   Note while doing this: the `DEFAULT_LIMITS` doc comment claims the table was "verified field by
-   field against a Dawn default device (`webgpu` package, already a dependency)". **That package is
-   not a dependency** — `webgpu` appears in `package.json` only as a `keywords` entry, and is absent
-   from `node_modules`. So `maxImmediateSize: 0` cannot be re-verified from this repo, and raising it
-   to 64 rests on the spec's `maximum`-class default rather than a Dawn reading. Say that in the
-   comment instead of repeating an unverifiable citation.
-2. `fix(shade): the emulator does not silently zero an immediate` — the `WGSLJavaScriptCompiler`
-   fall-through at `:862`, plus the `validate_wgsl_source` rules. A spec that fails before and passes
-   after.
-3. `feat(shade): pipeline layouts carry an immediate size` — L2, pinned by a `SoftwareGPUDevice` spec.
-4. `feat(shade): shaders can declare immediate data` — L1. The `requires` channel on `CodeChunk`,
-   `setImmediate` on the set descriptor, the declaration-time validation.
-5. `feat(shade): immediate data reaches the pass encoder` — L3. `generateImmediateBytes`, the optional
-   `setPipelineBindings` parameter, `encoder_prepare_shader_binding` stops allocating for immediates.
-6. `feat(shade): immediate data joins the device floor` — the two `Renderer.js` checks, the
-   `RENDERER_CONTRACT.md` §2 amendment, **and** the first migrated shader
-   (`shader_read_out_bucket`), together. This is the commit that raises the browser requirement to
-   Chrome 149+; its message should say so plainly.
-7. `refactor(shade): <pass> passes its settings as immediate data` — one per shader thereafter.
-
-Measure between 6 and 7, and again after the first handful of 7s: transient buffer acquisitions per
-frame and bind-group cache misses per frame are the two numbers that should move. If they do not,
-stop migrating the `allocateTransientValueBuffer` sites and spend the effort on the
-`graph_import_typed_buffer` consumers instead, where the per-frame cost is a whole buffer rather than
-a pool hit.
-
----
-
-## 9. 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.
-
----
-
-## 10. Open questions
-
-- **Is Chrome 149+ acceptable as the engine floor, and when?** This is now the only gating question
-  in the plan. Steps 1–5 can land regardless; step 6 needs an answer. Immediates are in Chrome
-  149–150, so the answer is partly a calendar question about how far behind the target audience runs.
-- **Should `setImmediate` live on `ShaderResourceSetDescriptor` or on `ShaderDescriptor`?** The set
-  descriptor is where every other resource is declared; but an immediate is not a bound resource —
-  the spec is explicit that it is part of the *shader interface*, not the *resource interface*.
-  Recommendation: the set descriptor, because that is what `generateCodeChunk` and the binding path
-  already walk, and splitting across two objects buys nothing.
-- **Is 64 bytes worth revisiting later?** `maxImmediateSize` is raisable, but D3D12's root signature
-  budget means no browser is likely to expose more. Plan around 64 permanently.
+# 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.