@woosh/meep-engine 3.11.3 → 3.13.0

package/src/shade/device/PASS_ENCODER_PROPOSAL_2026_08_31.md

@@ -0,0 +1,750 @@
+# Pass encoder decorators, and the end of the debug-timer path
+
+**Status:** implemented — revision 3
+**Date:** 2026-08-31
+**Scope:** `src/shade/device/ShadeGPUCommandContext.js`, `src/shade/device/timing/`, `src/shade/descriptor/pipeline/compute/`, `src/shade/renderer/Renderer.js`
+**Supersedes:** [GPU_PROFILER_PROPOSAL_2026_08_28.md](timing/GPU_PROFILER_PROPOSAL_2026_08_28.md) §6.1 (last paragraph) and §6.2 hook 3
+
+> **Revision 2** carried the workgroup size rather than re-parsing it (§3.5), dropped the pretence
+> of WebGPU overload compatibility (§3.2), removed the scratch-object side channel revision 1
+> introduced (§3.4), and added an adversarial pass (§8) that changed four decisions.
+>
+> **Revision 3** records what shipped. The §9 decisions were taken (§9), the error-carrying
+> `workgroup_size_error` of revision 2 was rejected in favour of throwing at construction (§3.5),
+> and the code landed in three commits (§10).
+
+---
+
+## 1. What is there now
+
+Profiling reaches a GPU pass through four private members of `ShadeGPUCommandContext` and one `Proxy`.
+
+| Piece | Where | What it does |
+|---|---|---|
+| `#with_timestamp_writes(descriptor, kind)` | [ShadeGPUCommandContext.js:461](ShadeGPUCommandContext.js:461) | Branches on the string `'compute'`/`'render'`, asks `GPUTimerArray` for a slot, shallow-copies the descriptor to add `timestampWrites`, and **as a side effect** writes `#pending_work`. |
+| `#pending_work` | [:128](ShadeGPUCommandContext.js:128) | A one-slot channel between `#with_timestamp_writes` and `#instrument_pass`. |
+| `#instrument_pass(encoder)` | [:136](ShadeGPUCommandContext.js:136) | Reads `#pending_work`, clears it, writes `#last_work`, and returns either the raw encoder or a `Proxy`. |
+| `#last_work` | [:577](ShadeGPUCommandContext.js:577) | A second one-slot channel, this time between `begin*Pass` and `#note_pipeline`. |
+| `make_profiling_pass_encoder` | [timing/profile/make_profiling_pass_encoder.js](timing/profile/make_profiling_pass_encoder.js) | A `Proxy` whose `get` trap switches on the method **name as a string**, wraps six of them, memoises bound closures in a `Map`, and forwards the rest by `Reflect`. |
+| `parse_workgroup_size` | [timing/profile/parse_workgroup_size.js](timing/profile/parse_workgroup_size.js) | Re-parses WGSL per pass to recover `@workgroup_size`. Already marked `@deprecated`: it duplicates `compute_infer_workgroup_size_from_source`, badly. |
+
+So `beginComputePass` reads:
+
+```js
+const _descriptor = this.#with_timestamp_writes(descriptor, 'compute');
+
+return this.#instrument_pass(encoder.beginComputePass(_descriptor))
+```
+
+Two calls, neither of which names what it produced, coupled through two private fields that neither
+signature mentions.
+
+Alongside it, a second entry point into the same machinery:
+
+| Piece | Where | What it does |
+|---|---|---|
+| `enable_debug_timers(cb)` | [:93](ShadeGPUCommandContext.js:93) | Allocates the `GPUTimerArray`, and at `finish()` hands `results_to_console_table()` to a callback. |
+| `Renderer.add_debug_frame(n)` / `Renderer.onFrameDebug` | [Renderer.js:671](../renderer/Renderer.js:671), [:431](../renderer/Renderer.js:431) | Arms N frames, fires the table. |
+
+## 2. What is wrong with it
+
+**The two hidden channels.** `#pending_work` and `#last_work` are the whole objection. Neither
+appears in a signature. `#with_timestamp_writes` is a *getter-shaped* method that mutates; the only
+thing keeping it correct is that the very next statement consumes what it left behind. Insert a line
+between them, reach `beginComputePass` from inside its call tree, or throw part way, and the next
+pass silently inherits the previous pass's work record. Nothing would catch it.
+
+**`kind` as a string.** `#with_timestamp_writes(descriptor, 'compute')` re-derives, by string
+comparison, a fact the call site already knew statically — it is *literally inside*
+`beginComputePass`.
+
+**Reflection where a method call belongs.** `make_profiling_pass_encoder` switches on
+`'dispatchWorkgroups'`, `'draw'`, `'drawIndexed'` as strings, in a `Proxy` `get` trap, on the hot
+encoding path. `work.dispatch_count++` is three characters of real logic wrapped in a dispatch
+mechanism.
+
+**The Proxy's own justification does not survive contact with the fix.** The file argues a
+hand-written forwarder is dangerous because a missed method "does not fail loudly, it silently drops
+a call … and only while profiling". That is true *only because the wrapper is conditional*. Make the
+decorator the one and only pass type Shade hands out, and the failure mode inverts: a missing method
+is `pass.setScissorRect is not a function`, on the first frame, in every build, profiling or not. The
+argument for the Proxy is an argument against *conditional* wrapping, not against hand-writing the
+forwarder.
+
+**Three silent returns.** `#with_timestamp_writes` returns the descriptor unchanged for three
+different reasons (timers off, device lacks `timestamp-query`, array full) and the caller cannot tell
+which — nor that the pass ended up untimed.
+
+**A second, worse WGSL parser, run per pass.** `parse_workgroup_size` reads a bare decimal literal
+and returns `[0,0,0]` for anything else — while `compute_infer_workgroup_size_from_source`, twenty
+metres away, resolves `const` references, strips comments, handles hex and `i`/`u` suffixes, and
+throws with a specific message when it genuinely cannot tell. `ComputeShader` already calls the good
+one **once, at construction**, and keeps the answer. The profiler re-derives a worse answer at encode
+time, for a value that has not changed since the pipeline was created.
+
+**`enable_debug_timers` is a redundant second face.** It shares the `GPUTimerArray` with
+`enable_profiling`, either may allocate it, and `finish()` runs both drains. It produces a
+slot-shaped console table with no graph-pass attribution, no workload, no pipeline identity — a
+strictly worse view than the profiler's, reached through a separate API. Its consumers:
+
+- `Renderer.add_debug_frame` / `Renderer.onFrameDebug` — **zero subscribers anywhere in the tree**
+  (grep across all packages; the 2026-08-28 proposal noted the same and left them in).
+- [verify_gpu_bvh_build.js:316](../renderer/gpu_primitive/bvh/verify_gpu_bvh_build.js:316) — one
+  developer verification tool that wants a console table.
+
+That is the entire public surface. It is the cheapest moment this will ever be to remove it.
+
+---
+
+## 3. Proposed design
+
+### 3.1 `ShadeGPUComputePassEncoder` / `ShadeGPURenderPassEncoder`
+
+Two concrete decorator classes, in `src/shade/device/pass/`. **Every** pass Shade opens is one of
+these; there is no unwrapped path and no conditional wrapping. They hold a nullable
+`GPUProfileWork` and tally into it.
+
+They import **nothing** from `timing/profile/`. `work` is a bag of counters, `null` is the ordinary
+case, and the classes do not know what a capture is — which preserves (in fact improves) the
+tree-shaking property `GPUProfileSession`'s header promises.
+
+### 3.2 Forward exactly the arity you received
+
+These are not a compatibility shim. Following WebGPU's method names removes friction for anyone who
+already knows the API; it is not a promise of substitutability.
+
+**The rule, learnt the hard way (§8.9): a forwarder passes exactly the arity it was given, and never
+reasons about what a binding layer will do with a trailing `undefined`.** Three shapes satisfy it,
+and every method in both classes uses one of them:
+
+```js
+// 1. Only forwards, and has trailing optionals → rest arguments. Arity is preserved by
+//    construction, which is the property that matters and the one a reader should not have to
+//    verify branch by branch. `size` here means "the rest of the buffer" and has no default to
+//    stand in for at all, so an absent argument and an `undefined` one are different requests.
+setVertexBuffer(...args) {
+    this.#pass.setVertexBuffer(...args);
+}
+
+// 2. One trailing optional → branch on it. Cheap, and it also means this form can never select
+//    the five-argument overload by accident, which is what makes `setBindGroupRange` an honest
+//    name rather than only a convention.
+setBindGroup(index, bind_group, dynamic_offsets) {
+    if (dynamic_offsets === undefined) {
+        this.#pass.setBindGroup(index, bind_group);
+    } else {
+        this.#pass.setBindGroup(index, bind_group, dynamic_offsets);
+    }
+}
+
+// 3. Has to read its arguments in order to count them → named parameters, with WebGPU's own
+//    defaults spelled out. Those defaults are 1 and 0, so materialising them passes four defined
+//    values rather than a trailing `undefined`, and is equivalent to omitting them.
+draw(vertex_count, instance_count = 1, first_vertex = 0, first_instance = 0) { /* ... */ }
+```
+
+Where WebGPU resolves an overload by arity, Shade gives each form its own name: `setBindGroup` for
+the `sequence` form and `setBindGroupRange` for the `Uint32Array`-slice form. Nothing in the
+renderer uses the slice form today; it exists because `SoftwareGPUComputePassEncoder` models it.
+
+> Revision 2 got this exactly half right. It identified `setBindGroup` as the one forward that could
+> be *wrong* rather than merely incomplete, then guarded the wrong end of it — see §8.9.
+
+### 3.3 The compute decorator in full
+
+```js
+export class ShadeGPUComputePassEncoder {
+
+    /** @type {GPUComputePassEncoder} */
+    #pass;
+
+    /**
+     * Where this pass's encoded work is tallied, or null when nothing is profiling.
+     * @type {GPUProfileWork|null}
+     */
+    #work;
+
+    #ended = false;
+
+    /**
+     * @param {GPUComputePassEncoder} pass
+     * @param {GPUProfileWork|null} work
+     */
+    constructor(pass, work) {
+        assert.defined(pass, 'pass');
+
+        this.#pass = pass;
+        this.#work = work;
+    }
+
+    /** @returns {string} */
+    get label() { return this.#pass.label; }
+
+    /** @param {string} value */
+    set label(value) { this.#pass.label = value; }
+
+    // --- GPUComputePassEncoder ------------------------------------------------
+
+    setPipeline(pipeline) {
+        this.#pass.setPipeline(pipeline);
+    }
+
+    dispatchWorkgroups(x, y = 1, z = 1) {
+        const work = this.#work;
+
+        if (work !== null) {
+            work.dispatch_count++;
+            work.workgroups[0] += x;
+            work.workgroups[1] += y;
+            work.workgroups[2] += z;
+        }
+
+        this.#pass.dispatchWorkgroups(x, y, z);
+    }
+
+    dispatchWorkgroupsIndirect(indirect_buffer, indirect_offset) {
+        const work = this.#work;
+
+        if (work !== null) {
+            // Size lives in a GPU buffer, so there is nothing to add to `workgroups`. Counted
+            // apart so the totals are not read as covering this.
+            work.indirect_dispatch_count++;
+        }
+
+        this.#pass.dispatchWorkgroupsIndirect(indirect_buffer, indirect_offset);
+    }
+
+    end() {
+        assert.notOk(this.#ended, 'pass already ended');
+
+        this.#ended = true;
+
+        this.#pass.end();
+    }
+
+    // --- GPUBindingCommandsMixin ----------------------------------------------
+
+    setBindGroup(index, bind_group, dynamic_offsets) { /* §3.2 */ }
+
+    setBindGroupRange(index, bind_group, data, data_start, data_length) { /* §3.2 */ }
+
+    setImmediates(range_offset, data, data_offset, data_size) {
+        this.#pass.setImmediates(range_offset, data, data_offset, data_size);
+    }
+
+    // --- GPUDebugCommandsMixin ------------------------------------------------
+
+    pushDebugGroup(label) { this.#pass.pushDebugGroup(label); }
+
+    popDebugGroup() { this.#pass.popDebugGroup(); }
+
+    insertDebugMarker(label) { this.#pass.insertDebugMarker(label); }
+
+    // --- Shade ----------------------------------------------------------------
+
+    /**
+     * Record which pipeline descriptor this pass ran.
+     *
+     * Separate from `setPipeline` because `setPipeline` receives the compiled
+     * {@link GPUComputePipeline}, and neither the label the descriptor was given nor its workgroup
+     * size is on it. Only `constructComputePass` holds the descriptor, so a pass begun the long way
+     * records its counts but not what ran them — which the model represents as an unknown rather
+     * than a zero.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {void}
+     */
+    record_pipeline(descriptor) {
+        const work = this.#work;
+
+        if (work === null) {
+            return;
+        }
+
+        work.pipeline = descriptor.label ?? "";
+        work.workgroup_size = descriptor.workgroup_size;
+    }
+}
+```
+
+`ShadeGPURenderPassEncoder` is the mirror image over the render surface: `setViewport`,
+`setScissorRect`, `setBlendConstant`, `setStencilReference`, `setIndexBuffer`, `setVertexBuffer`,
+`beginOcclusionQuery`, `endOcclusionQuery`, `executeBundles`, `draw`, `drawIndexed`, `drawIndirect`,
+`drawIndexedIndirect`, plus the same two mixins, `end` and `record_pipeline`. Only the four `draw*`
+methods carry a tally; the rest forward.
+
+**Only six methods branch** — four `draw*` and two `dispatch*`. Everything else is a one-line
+forward. Both classes come to roughly 130 lines and read top to bottom as a complete statement of the
+interface they decorate, which is the entire point.
+
+> **Known blind spot, inherited:** draws inside a `GPURenderBundle` passed to `executeBundles` are
+> not counted — the bundle was encoded elsewhere. The Proxy had the same gap and nothing in Shade
+> uses bundles today. It belongs in `GPUProfileWork`'s documentation rather than being left implicit.
+
+### 3.4 The context's profiling state, in one object
+
+`ShadeGPUCommandContext` currently carries six fields for a feature that is off by default:
+`#debug_timers`, `#debug_timers_callback`, `#profile_recorder`, `#profile_query_set_id`,
+`#pending_work`, `#last_work`, plus `#profiling_absorbed` and its resolver. Collapse them into one
+nullable `#profiler`.
+
+The profiler **opens the pass itself**. Two values are needed at two different instants —
+`timestampWrites` before the encoder exists, the `GPUProfileWork` after — and any design that returns
+them to the caller has to carry them across that gap somehow. Handing the profiler the encoder
+collapses the gap: both values are produced and consumed inside one method, and there is nothing to
+carry. (Revision 1 returned a reused `{writes, work}` struct, which was `#pending_work` again in
+better clothes. See §8.3.)
+
+```js
+/**
+ * Everything one command context needs in order to be profiled: its timer array, the recorder the
+ * timings go to, and which query set it is within the frame.
+ */
+export class ShadeGPUContextProfiler {
+
+    #timers;
+    #recorder;
+    #query_set_id;
+
+    #absorbed;
+    #absorbed_resolve;
+
+    constructor(device, recorder, query_set_id) {
+        this.#timers = new GPUTimerArray(device);
+        this.#recorder = recorder;
+        this.#query_set_id = query_set_id;
+
+        this.#absorbed = new Promise(resolve => { this.#absorbed_resolve = resolve; });
+    }
+
+    get absorbed() { return this.#absorbed; }
+
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @param {GPUComputePassDescriptor} [descriptor]
+     * @returns {ShadeGPUComputePassEncoder}
+     */
+    begin_compute_pass(encoder, descriptor) {
+        const writes = this.#timers.getComputeWrites(descriptor?.label);
+
+        if (writes === undefined) {
+            /*
+             No slot left, or the device withheld `timestamp-query`. An untimed pass is the correct
+             degradation in both; a pass carrying query indices the set does not have is a
+             validation error blamed on a pass that did nothing wrong.
+            */
+            return new ShadeGPUComputePassEncoder(encoder.beginComputePass(descriptor), null);
+        }
+
+        /*
+         Copied, never written through. Several call sites reuse one descriptor across passes, and
+         stamping `timestampWrites` onto it left the next pass carrying the previous pass's query
+         indices. `{...undefined}` is `{}`, which is also how the no-descriptor form stays legal.
+        */
+        const gpu_pass = encoder.beginComputePass({ ...descriptor, timestampWrites: writes });
+
+        return new ShadeGPUComputePassEncoder(gpu_pass, this.#note_slot(writes));
+    }
+
+    /** The render mirror of {@link begin_compute_pass}. */
+    begin_render_pass(encoder, descriptor) { /* getRenderWrites, ShadeGPURenderPassEncoder */ }
+
+    /**
+     * @param {GPUComputePassTimestampWrites|GPURenderPassTimestampWrites} writes
+     * @returns {GPUProfileWork|null}
+     */
+    #note_slot(writes) {
+        /*
+         The one moment the join can be made. The recorder knows which frame graph pass is
+         executing right now; the slot is what the timings will come back keyed by. Neither fact is
+         recoverable later — see GPUFrameRecorder.
+        */
+        return this.#recorder.note_pass_slot(
+            this.#query_set_id,
+            writes.beginningOfPassWriteIndex / 2
+        );
+    }
+
+    /** @param {GPUCommandEncoder} encoder */
+    resolve(encoder) { this.#timers.resolve(encoder); }
+
+    /**
+     * Read the timings back and hand them to the recorder. Resolves {@link absorbed} either way.
+     * @returns {void}
+     */
+    absorb() {
+        const timers = this.#timers;
+
+        timers.download_results()
+            .then(() => { this.#recorder.absorb(timers, this.#query_set_id); })
+            .finally(() => {
+                timers.destroy();
+
+                // In `finally` so a failed readback still releases whoever is waiting on the frame.
+                // A profile session that hangs because one download rejected is worse than one
+                // missing a frame.
+                this.#absorbed_resolve();
+            });
+    }
+}
+```
+
+`beginComputePass` on the context becomes five lines with two named outcomes:
+
+```js
+/**
+ * @param {GPUComputePassDescriptor} [descriptor]
+ * @returns {ShadeGPUComputePassEncoder}
+ */
+beginComputePass(descriptor) {
+    const profiler = this.#profiler;
+
+    if (profiler === null) {
+        return new ShadeGPUComputePassEncoder(this.#gpu_encoder.beginComputePass(descriptor), null);
+    }
+
+    return profiler.begin_compute_pass(this.#gpu_encoder, descriptor);
+}
+```
+
+No `kind` string. No hidden field. `beginRenderPass` is the same five lines.
+
+`constructComputePass` loses `#note_pipeline` and `#last_work` entirely:
+
+```js
+const pass = this.beginComputePass(pass_descriptor);
+
+pass.setPipeline(gpu_pipeline);
+pass.record_pipeline(pipeline);
+
+graphics.setPipelineBindings(pass, pipeline, bindings, immediate);
+```
+
+### 3.5 The workgroup size is carried, not re-parsed
+
+`ComputePipelineDescriptor` reads `@workgroup_size` out of its code **as the code is set**, in
+`from`, `simplified` and `fromJSON`, and becomes the single owner of the answer:
+
+```js
+/**
+ * `[x, y, z]` of this pipeline's `@workgroup_size`.
+ *
+ * Read once, when the code is set, and kept — the source cannot change under a descriptor without
+ * going back through one of the factories, each of which reads it again.
+ *
+ * Frozen, because it is handed out by reference to per-pass profile records and a descriptor that
+ * outlives a whole capture must not be mutable through one of them.
+ *
+ * Takes no part in `equals`/`hash`: it is derived from `compute.module`, which both already cover,
+ * and a cache key computed two ways is a cache that can disagree with itself.
+ *
+ * @returns {readonly number[]}
+ */
+get workgroup_size()
+```
+
+Backed by `compute_infer_workgroup_size_from_source`. **Source it cannot read throws, at
+construction.** Revision 2 proposed a `workgroup_size_error` companion so the descriptor could
+report rather than throw, on the grounds that a capture must not take a frame down. That was
+rejected, and rightly:
+
+> The user can't construct a ComputeShader because their source is messed up — that's preferred to
+> them constructing an invalid shader that we then have to recognize and deal with.
+
+Every consumer of this number divides a thread count by it. A descriptor that cannot state its own
+workgroup size is one nobody downstream can use correctly, so `[0, 0, 0]` would only defer the
+failure to somewhere with less context to explain it. The only `[0, 0, 0]` left is a bare
+`new ComputePipelineDescriptor()` that has no code yet — not a fallback, a state `new` alone
+produces.
+
+`ComputeShader` reads the descriptor instead of parsing separately. Its message keeps the shader's
+label because the pipeline is given the same one, so nothing is wrapped and nothing is lost.
+
+This is strictly better than what either side did before:
+
+- **One parse**, at pipeline-descriptor construction, by the parser that actually handles WGSL.
+- The nine `ComputePipelineDescriptor` sites that do **not** go through `ComputeShader` — VSM
+  residence, tile allocation, coarse bounds, probe dering, indirect command build ×2, irradiance
+  lookup, debug reprojection, virtual shadow residence — get correct workgroup sizes in profiles
+  for the first time. `parse_workgroup_size` returned `[0,0,0]` for any of them stating the size
+  through a `const`.
+- `parse_workgroup_size.js` is deleted, resolving the `@deprecated` note already on it.
+- `timing/profile/` loses its last unconditionally-linked module, so the whole profiler directory
+  is now unreachable from any engine entry point — which is what `GPUProfileSession`'s header
+  claims and, before this, was not quite true.
+
+**`fromJSON` re-reads it.** `ComputePipelineDescriptor.fromJSON` replaces `compute` in place, so a
+size read for whatever was there before would be the wrong shader's — and wrong here means a wrong
+*divisor*. Covered by a spec.
+
+Verified before landing that eager reading breaks nothing: every compute pipeline reachable in the
+tree parses. Two modules would not, and both are unreferenced — `GPUVirtualShadowTextureResidence`
+(which already throws on import today, for an unrelated missing default export) and
+`graph_pass_debug_reprojection`.
+
+### 3.6 A check the device already does, dropped
+
+`#with_timestamp_writes` guards on `this.#graphics.device.features.has('timestamp-query')`. This is
+redundant: `GPUTimerArray`'s constructor returns early without the feature, leaving `#query_set`
+undefined, and `#get_writes` already returns `undefined` in that case
+([GPUTimerArray.js:97](timing/GPUTimerArray.js:97)). One fewer place that has to know the feature
+exists.
+
+---
+
+## 4. Removing the debug-timer path
+
+| File | Change |
+|---|---|
+| `ShadeGPUCommandContext.js` | Delete `enable_debug_timers` (:93), `#debug_timers_callback` (:87), and the `results_to_console_table` branch in `finish()` (:975). The `noop` import becomes unused — its only two uses are `#debug_timers_callback` and `#profiling_absorbed_resolve`, and both leave. |
+| `renderer/Renderer.js` | Delete `onFrameDebug` (:431), `#debug_frame_count` (:606), `add_debug_frame` (:671), and the arming block (:1736–1744). **Zero subscribers repo-wide.** |
+| `renderer/gpu_primitive/bvh/verify_gpu_bvh_build.js` | Move onto the profiler (below). |
+| `RENDERER_CONTRACT.md:544` | Drop `add_debug_frame(n)` from the surface table. |
+| `timing/GPU_PROFILER_PROPOSAL_2026_08_28.md` | §6.1 last ¶, §6.2 hook 3, and table rows 57/59/60 describe things that no longer exist. |
+| `gpu_primitive/bvh/GPU_BVH_BUILD_PLAN.md:235`, `PHASE1_HANDOVER.md:148` | Same. |
+
+The replacement for the one real consumer is *better* than what it replaces — it gains dispatch and
+invocation counts, which is what a BVH build verification actually wants:
+
+```js
+let recorder = null;
+
+if (test_case.count >= 100000) {
+    recorder = new GPUFrameRecorder(0, performance.now());
+    recorder.enable_work_capture();
+
+    cmd.enable_profiling(recorder, 0);
+}
+
+// ... build the graph ...
+
+if (recorder !== null) {
+    recorder.attach_graph(graph);
+}
+
+cmd.encodeGraph(graph);
+cmd.finish();
+
+if (recorder !== null) {
+    const captured = recorder;
+
+    cmd.profiling_absorbed.then(() => {
+        const frame = captured.close(performance.now());
+
+        console.log(`[BVH] GPU timings — ${test_case.name}`);
+        console.table(frame.spans.map(span => ({
+            label: span.label,
+            duration_ms: span.duration_ns * 1e-6,
+            dispatches: span.work?.dispatch_count ?? 0,
+            invocations: span.work?.invocation_count ?? 0
+        })));
+    });
+}
+```
+
+"Profile the next N frames" — what `add_debug_frame` was for — is already
+`new GPUProfileSession({ frame_limit: N })`.
+
+---
+
+## 5. One migration hazard, worth stating plainly
+
+**Do not null `#profiler` inside `finish()`.** The renderer reads `profiling_absorbed` *after*
+`finish()` ([Renderer.js:2520, then :2531](../renderer/Renderer.js:2531)). If `profiling_absorbed`
+becomes a getter that returns `Promise.resolve()` when `#profiler === null`, nulling the field in
+`finish()` hands the renderer an already-resolved promise and it commits an empty frame — every
+frame, silently, with no error anywhere. The current code survives this only because
+`#profiling_absorbed` is a separate cached field.
+
+The profiler holds no GPU resources after `absorb()` — it destroys the timer array itself — so
+leaving the reference in place is correct and costs nothing.
+
+---
+
+## 6. Testing
+
+| Tier | What |
+|---|---|
+| **Unit, node** | Port `sgpt_workload.spec.js` off `make_profiling_pass_encoder` onto the two classes: counting *and* forwarding, which it already tests. Its "a method the proxy has never heard of still works" test is deleted — that behaviour is gone deliberately. |
+| **Unit, node** | `ComputePipelineDescriptor.workgroup_size`: the size for a literal, for a `const`, `[0,0,0]` plus a populated `workgroup_size_error` for an override expression, the memo invalidated by `fromJSON`/`copy`, and the returned array frozen. |
+| **Unit, node** | `ComputeShader` still throws the same message for an unreadable size — a spec that pins the wrapping, since §3.5 rewrites how it gets there. |
+| **Unit, node** | Drift guard: every method name on `SoftwareGPUComputePassEncoder.prototype` / `SoftwareGPURenderPassEncoder.prototype` has a counterpart on the decorator, modulo the §3.2 rename. This catches the decorator falling behind **the mock**, which is what breaks node-tier specs. It is *not* a completeness check against WebGPU — see §8.2. |
+| **`SoftwareGPUDevice`** | `ShadeGPUCommandContextFrame.spec.js` already drives `setViewport`/`draw`/`dispatchWorkgroups`/`end` through the context and asserts on the underlying mock encoder — it passes unchanged if the forwarding is right, which makes it the integration check for free. `GPUFrameRecorder.spec.js` and `GPUProfileSession.spec.js` cover the join end to end. |
+| **Browser playground** | The **only** real completeness check: diff each decorator against the live `GPUComputePassEncoder.prototype` / `GPURenderPassEncoder.prototype` and **throw**, not warn. A console warning in a playground page is a warning nobody reads. |
+| **Measurement** | `shade/playground/volumetrics_froxel/measure.js`, before and after, profiling **off**. |
+
+---
+
+## 7. Cost, honestly
+
+**Not profiling** — per pass: one object allocation, one `assert.defined`, one `assert.notOk`; per
+encoder method: one call frame. Asserts in this codebase are **not** stripped in production
+([core/assert.js](../../core/assert.js) has no build-time gate), so those two are real work on every
+pass, not a debug-build cost.
+
+How many passes per frame is **not known** — the 2026-08-28 proposal lists it as an open question
+(§734 there) and `GPUTimerArray`'s 1024-slot default is a ceiling, not a measurement. So the total is
+unquantified by construction and §6's measurement is the answer, not this paragraph.
+
+**Profiling** — strictly faster. A `Proxy` `get` trap plus a `Map` lookup on every property access
+becomes a direct method call. Plus one WGSL parse removed per profiled compute pass (§3.5).
+
+**Correctness** — the two hidden fields go, and with them any defect that could only manifest while
+profiling.
+
+---
+
+## 8. Adversarial pass
+
+Attacking the above. Four findings changed the design; the rest are recorded because they are the
+things most likely to be wrong.
+
+### 8.1 `label` was write-only-broken *(fixed above)*
+
+Revision 1 gave the decorators a `label` getter and no setter. `GPUObjectBase.label` is a read-write
+attribute, ES modules are always strict mode, and assigning to an accessor with no setter throws
+`TypeError`. Nothing writes `pass.label` today (checked), so this would have sat dormant until
+someone tried — and the §6 drift guard compares *method* names and would never have caught a missing
+accessor. Fixed: `get`/`set` pair. The general lesson is that the drift guard's scope is narrower
+than it looks, which is §8.2.
+
+### 8.2 The node conformance test was oversold *(claim corrected above)*
+
+Revision 1 called the node-tier test "the completeness guarantee … which the Proxy could not do".
+That is wrong twice over. It compares meep's decorator against meep's own hand-written mock, so it
+cannot possibly catch a method Chrome adds — both sides would be missing it. And `toHaveProperty`
+walks the prototype chain, so `Object.prototype` members pass vacuously. It is a **drift guard**
+between two files in this repo, which is worth having and is not the same claim. Only the browser
+check tests completeness, and it has to *throw*. §6 now says so.
+
+This weakens — but does not overturn — the §2 argument. The Proxy's real advantage was forwarding
+methods **nobody had heard of yet**; that advantage is real and this proposal gives it up on purpose,
+in exchange for a failure that is loud and immediate instead of silent and capture-only. Worth being
+explicit that it is a trade, not a free win.
+
+### 8.3 Revision 1 reintroduced the bug it was removing *(design changed above)*
+
+Revision 1 replaced `#pending_work` with a reused `ShadeGPUPassProfile` scratch object returned from
+`open_compute_pass`, "valid until the next call". That is the same coupling — a mutable value whose
+correctness depends on the caller consuming it before anything else runs — moved one class down and
+given a name. Having just written two pages about why that pattern is bad, shipping it would have
+been indefensible. §3.4 now has the profiler open the pass, so both values are produced and consumed
+inside one method and there is nothing to carry.
+
+### 8.4 The commit sequence was not actually independently green *(fixed above, see §9)*
+
+Revision 1 ordered "decorators first, profiler-state consolidation second". But the decorators need
+the work record to come from *somewhere*, so step 1 would have had to build `begin*Pass` against the
+old `#pending_work` channel and then immediately rewrite it. Reordered.
+
+### 8.5 Sharing the workgroup-size array is a real aliasing hazard *(mitigated above)*
+
+`work.workgroup_size = descriptor.workgroup_size` hands a per-pass profile record a reference to an
+array owned by a descriptor that outlives the whole capture. Nothing mutates it today —
+`GPUProfileWork` assigns it and never writes through it, unlike `workgroups`, which is mutated in
+place three lines away in the same class. That is close enough to be worth removing as a possibility
+rather than as a bug: §3.5 freezes it.
+
+### 8.6 The memo has two invalidation paths and I nearly missed both *(covered above)*
+
+`ComputePipelineDescriptor.fromJSON` mutates `this.compute` in place and `PipelineDescriptorBase` has
+a `copy`. A memoised `workgroup_size` read before either would be silently stale afterwards — and
+stale in the worst way, since the number is used as a *divisor* for thread counts. §3.5 and §6 both
+call it out. This is the single most likely place for this change to introduce a real bug.
+
+### 8.7 Claims I softened rather than defended
+
+- **"Perfectly predicted branch."** The `#work !== null` check is uniform within a frame but flips
+  when a capture starts or stops. Predictable, not free, and not worth a sentence of advocacy.
+- **"~200 passes/frame, ~1200 calls/frame."** Invented. The number is unknown and is listed as an
+  open question in the profiler proposal itself. §7 now says so instead of quoting a fabricated
+  figure at two decimal places of confidence.
+- **"Both classes ~120 lines."** Now ~130 with the `label` setter and the split `setBindGroup`.
+  Immaterial, but the earlier number was a guess presented as a measurement.
+
+### 8.9 It shipped broken anyway — the arity bug *(found in a browser, after landing)*
+
+`setBindGroup(0, bind_group)` forwarded `setBindGroup(0, bind_group, undefined)`, and the renderer
+died on its first bind group with "the provided value cannot be converted to a sequence".
+
+The failure is worth recording in full, because every safeguard in this document was pointed at it
+and it got through anyway.
+
+**§3.2 named the right method and guarded the wrong end of it.** It identified `setBindGroup` as the
+one forward that could be actively wrong, correctly diagnosed *why* — an overload resolved by
+counting arguments — and then wrote a three-argument forwarder whose whole purpose was to avoid the
+five-argument one. The hazard was never the arity it might reach; it was the `undefined` it would
+hand over on the way. The proposal even asserted the opposite in as many words: "Every other method
+has all-optional trailing parameters with WebIDL defaults, for which forwarding `undefined` is
+correct." That sentence was reasoning about a specification, presented as a fact about a browser,
+and it was load-bearing for seven methods.
+
+**Six more had the same defect waiting.** `setImmediates`, `setIndexBuffer`, `setVertexBuffer` and
+the render-side `setBindGroup`. `setVertexBuffer(0, buffer)` — from `prototypeParticleSystem` — was
+next in line, and worse: `size` there has no default to stand in for, it means "the rest of the
+buffer", so an absent argument and an `undefined` one are genuinely different requests.
+
+**The node tier could not have caught it.** The mock encoders are plain JS functions and take a
+trailing `undefined` happily, so the mock and the browser disagree in exactly the place the design
+depended on. §6's drift guard compared method *names*, which was never going to help — §8.2 already
+observed the node tier was weaker than it looked, and still put a name-comparison in the plan.
+
+**What replaced it:** specs that assert arity preservation against a recording fake, which is
+mock-independent and would have failed on the first run; and the fix verified against real WebGPU
+in a browser rather than against the mock.
+
+**Not fully explained.** The in-app browser (Chrome 148) *accepts* the explicit `undefined`; the
+build that crashed does not. So the fix is verified correct on both, but the exact behavioural
+difference was not reproduced, and the code comment says "some builds accept it, others do not"
+rather than claiming a mechanism it cannot demonstrate.
+
+**The standing lesson.** The browser-tier check §9 leaves open is not a nice-to-have. Two of the
+three tiers in §6 are blind to the mock/browser boundary by construction, and this change has now
+been wrong at that boundary twice.
+
+### 8.8 Residual risks, accepted
+
+- **A WebGPU method Chrome ships that Shade has not modelled** is now a hard failure rather than a
+  silent forward. That is the intended trade (§8.2), but it means the browser check is load-bearing
+  and needs to actually run in CI or a pre-release checklist, not just exist.
+- **`executeBundles` work is uncounted** (§3.3). Pre-existing, documented, nothing uses bundles.
+- **99 call sites change type.** No reflection over pass objects exists anywhere in the tree
+  (`typeof pass.x`, `Object.keys(pass)`, spread, `instanceof` — all checked, all absent), so the
+  surface is method calls only. If one is missed it throws at that call; it cannot silently misbehave.
+
+---
+
+## 9. Decisions taken
+
+| # | Question | Decision |
+|---|---|---|
+| 1 | Location | **`device/pass/`**, with `ShadeGPUContextProfiler` in `device/timing/` beside the timer array it owns. |
+| 2 | `GPUTimerArray.results_to_console_table` | **Deleted** — "a crude tool, no longer required". Its two specs moved onto `traverse_results`. |
+| 3 | `setBindGroupRange` | **Kept.** The mock models the slice form, and naming it is the whole point of §3.2. |
+| 4 | A `gpu_pass` escape hatch | **Omitted.** Nothing needs one and it invites bypass. |
+| 5 | `end()` double-end assert | **In.** Tracking open passes on the context stays a separate change. |
+| 6 | `workgroup_size_error` | **Rejected — throw instead.** See §3.5. |
+
+Still open, and deliberately not done here:
+
+- **The browser-tier completeness check** against the live `GPUComputePassEncoder.prototype` /
+  `GPURenderPassEncoder.prototype`. It is the only real completeness check (§8.2) and it is now
+  load-bearing, since a method Chrome ships that Shade has not modelled throws rather than being
+  forwarded blind.
+- **The measurement.** `shade/playground/volumetrics_froxel/measure.js`, profiling off, before and
+  after. §7 says why the numbers are not guessed at here.
+- **Two unreferenced modules** found on the way: `GPUVirtualShadowTextureResidence.js` imports a
+  default export that does not exist and throws on import; `graph_pass_debug_reprojection.js` is
+  dead. Both predate this change and neither was touched.
+
+---
+
+## 10. Commits
+
+1. `refactor(shade): pipeline descriptors carry their workgroup size` — §3.5.
+2. `refactor(shade): pass encoders become explicit decorator classes` — §§3.1–3.4 and 3.6, plus the
+   BVH verification tool moved onto a `GPUFrameRecorder`.
+3. `refactor(shade): remove the debug-timer path, the profiler is the only one` — §4.
+
+Revision 2 ordered these decorators-first; that was wrong (§8.4) and the workgroup size went first
+instead. Full suite green after each: 15,012 tests.