@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/device/mock/REVIEW_2026_08_22.md

@@ -1,527 +1,527 @@
-# `shade/device/mock` — review, 2026-08-22
-
-A review of `SoftwareGPUDevice` and the objects around it, against the WebGPU specification and
-against what the Shade renderer actually asks a device to do.
-
-> **Status: acted on.** Every finding below except the two named as out of scope has since been
-> fixed. This document describes the device *as it was on 2026-08-22*, and is kept as the record of
-> why the work was done and what the evidence for each finding was — not as a description of the
-> current code. What actually landed is in
-> [`IMPLEMENTATION_PLAN.md`](./IMPLEMENTATION_PLAN.md) §5.
->
-> Still open: **E1/E2** (inherited limitations) are only partly addressed — `bytes_per_texel` no
-> longer throws for depth, packed or compressed formats, but `writeTexture` is still single-layer
-> (E2). **F1** and **F2** were both closed on 2026-08-22, by deletion rather than by fixing:
-> `probe_instance_animation.js` was removed with the `webgpu` dependency (it was one of five
-> hand-run Dawn probes), and `GPUDatabase.spec.js`'s skipped `full-fat` test went with it — F2's
-> own finding is why it could not be re-pointed at this device instead.
-
-The companion document is [`EXTENSION_PROPOSAL_2026_08_22.md`](./EXTENSION_PROPOSAL_2026_08_22.md),
-which turns the findings here into ranked work items.
-
----
-
-## 1. Method
-
-Read every file in this folder, then established each behavioural claim below by running it. The
-probes were temporary spec files placed in this folder (vitest's `include` is `app/src/**/*.spec.js`,
-so a scratch file elsewhere is not collected) and deleted afterwards. Limit values were checked
-against a real Dawn device obtained through the `webgpu` package, which is already a dependency and
-is what `GPUDatabase.spec.js` and the `probe_*.js` tools use.
-
-Every "verified" tag below means the behaviour was observed, not inferred from reading.
-
-Baseline: `npx vitest run app/src/mir-engine/meep/src/shade/device/mock/` — 26 tests, all passing.
-
----
-
-## 2. What this mock is, and what it is good at
-
-`SoftwareGPUDevice` is a CPU-memory stand-in for `GPUDevice` that lets renderer code be constructed
-and driven under node. It is not an emulator: nothing here compiles or executes WGSL — that is
-`wgsl/emulator/ComputeShaderEmulator.js` — and nothing rasterizes.
-
-Three things in it are genuinely good and should be preserved by any extension:
-
-1. **The error model is right.** `pushErrorScope` / `popErrorScope` / `generate_error` /
-   `uncapturederror` reproduce WebGPU's scope stack faithfully, down to details that are easy to get
-   wrong: innermost-matching-scope wins, a scope keeps only its first error, a pop with no scope open
-   rejects with an `OperationError`, an unclaimed error reaches the console. `SoftwareGPUError` is
-   deliberately not an `Error` subclass, because `GPUError` is not one either. The reasoning is
-   written down in the source next to the code that depends on it.
-
-2. **A rejected descriptor does not throw.** `createBuffer` reports through the error scope and
-   returns an invalid buffer that still reads back its requested `size`, `usage` and `label`, and the
-   invalidity propagates the way WebGPU propagates it — a command naming an invalid buffer poisons
-   the *encoder*, and the error surfaces from `finish()`, not from the encoding call. Then a
-   submission holding one invalid command buffer executes *none* of its command buffers. That chain
-   is subtle and it is implemented correctly.
-
-3. **Where it declines to emulate, it says so loudly.** `SoftwareGPUComputePassEncoder`'s header
-   states in plain words that dispatches change no bytes and that asserting on shader output is
-   meaningless. `dispatchWorkgroupsIndirect` records `[-1, -1, -1]` rather than inventing a
-   workgroup count. This is the right instinct and the extensions should keep it.
-
-The findings below are about the surface *around* that core, which is much thinner than the core
-suggests.
-
-### 2.1 Inventory
-
-| File | Fidelity | Note |
-|---|---|---|
-| `SoftwareGPUDevice` | **Validating** (buffers only) | error scopes complete; `destroy`/`adapterInfo` throw |
-| `SoftwareGPUError`, `SoftwareGPUUncapturedErrorEvent` | **Complete** | — |
-| `SoftwareGPUBuffer` | **Executing** | no mapping; no destroyed-state enforcement |
-| `SoftwareGPUQueue` | **Executing** | no validation at all |
-| `SoftwareGPUCommandEncoder` | **Executing** (2 of 8 commands) | no render pass, no texture copies |
-| `SoftwareGPUCommandBuffer` | **Executing** | — |
-| `SoftwareGPUTexture` | **Storing** | lazy per-mip CPU storage, layer 0 only |
-| `SoftwareGPUComputePassEncoder` | **Recording** | by design |
-| `SoftwareGPUPipeline`, `SoftwareGPUShaderModule`, `SoftwareGPUBindGroup(Layout)`, `SoftwareGPUTextureView` | **Opaque handle** | by design |
-| `GPUQuerySet`, `GPURenderPassEncoder`, `GPURenderBundle*`, `GPUAdapter`, `GPUCanvasContext` | **Absent** | — |
-
-The ladder — *opaque handle → recording → storing → executing → validating* — is the useful axis for
-the rest of this document. The mock's problem is not that objects sit low on it. It is that **which**
-rung a given object sits on is unpredictable, and nothing tells a caller which one they got.
-
----
-
-## 3. Findings
-
-Grouped by failure mode, because the failure mode determines how much a finding costs you.
-
-### Class A — silent divergence
-
-*The mock accepts what a real device rejects. The test goes green and the GPU breaks. This is the
-expensive class: a mock that is merely incomplete wastes an afternoon, a mock that is wrong ships a
-bug.*
-
-#### A1. `queue.writeBuffer` performs no validation whatsoever — verified
-
-The spec requires `bufferOffset % 4 === 0`, the written size to be a multiple of 4, the destination
-range to lie inside the buffer, and the destination usage to include `COPY_DST`. None of these are
-checked.
-
-Observed, on an 8-byte buffer:
-
-- `writeBuffer(buffer, 0, new Uint8Array(16))` — **wrote 8 bytes, reported nothing.** No throw, no
-  error scope entry. The default-size computation at `SoftwareGPUQueue.js:84` is
-  `Math.min(buffer.size - offset, source.byteLength - dataOffset)`, which silently clamps. A real
-  device raises a validation error; the caller here is told the write succeeded.
-- `writeBuffer(buffer, 1, new Uint8Array([9,9,9]))` — **wrote 3 bytes at byte offset 1.** Both the
-  offset and the size are unaligned; both are validation errors in WebGPU.
-- With an explicit oversized `size`, the clamp does not apply and `array_buffer_copy` throws a bare
-  `RangeError: Invalid typed array length` from two frames down — an opaque crash where the spec has
-  a named, catchable error.
-
-`writeBuffer` is the single most-used queue entry point in the renderer. Silent truncation here is
-the highest-consequence finding in this document.
-
-#### A2. A destroyed buffer remains fully usable — verified
-
-```
-c = device.createBuffer({size: 16, usage: COPY_DST}); c.destroy();
-queue.writeBuffer(c, 0, new Uint8Array([1,2,3,4]));
-// error scope: null      c.data: [1, 2, 3, 4]
-```
-
-`destroy()` sets a flag and nothing reads it. `#data` is retained, `writeBuffer` writes into it,
-`copyBufferToBuffer` copies out of it, `getMappedRange` hands it out. Use-after-destroy is one of the
-easier lifetime bugs to introduce in a pooled allocator and this mock is blind to all of it.
-
-`SoftwareGPUTexture.destroy()` at least clears `#mip_data`, but `get_mip_data` will happily
-re-allocate afterwards, so the same hole exists one indirection away.
-
-#### A3. `getMappedRange()` succeeds on an unmapped buffer — verified
-
-The guard at `SoftwareGPUBuffer.js:144` tests `#data === null`, which is only true for a buffer the
-device *refused*. A valid, unmapped, never-mapped buffer returns its whole storage. The spec requires
-an `OperationError` unless `mapState` is `"mapped"`.
-
-Consequence: renderer code that forgets to map, or that reads a range after `unmap()`, works here and
-fails in a browser. `GPUBufferStagingAllocator` asserts `mapState === "mapped"` precisely because
-that discipline matters, and the mock removes the only mechanism that would catch a violation.
-
-#### A4. `createBuffer` validates one rule out of five — verified
-
-Only `size > maxBufferSize` is checked. Accepted without complaint:
-
-- `usage: 0` (spec: validation error),
-- `MAP_READ | MAP_WRITE` together, and `MAP_READ` combined with anything other than `COPY_DST`
-  (spec: validation error),
-- `mappedAtCreation: true` with a size that is not a multiple of 4 (spec: validation error).
-
-#### A5. `createTexture` validates nothing at all — verified
-
-```
-device.createTexture({size: [1<<20, 1<<20], format: 'rgba8unorm', usage: TEXTURE_BINDING});
-// error scope: null
-```
-
-`maxTextureDimension1D/2D/3D`, `maxTextureArrayLayers`, `mipLevelCount` versus size, `sampleCount`,
-`usage: 0`, format/usage compatibility — none are examined. This is a straight inconsistency with
-`createBuffer`, which is the same kind of entry point and does check its headline limit.
-
-It also leaves seven sites unexercised. The renderer clamps its own allocations against a texture
-dimension limit in `Renderer.js:1381`, `:1440`, `GPUProbeAtlas.js:112`, `:213`,
-`VirtualShadowMap.js:77` and `GPUSceneShadowmapContext.js:270` (all `maxTextureDimension2D`), and in
-`GPUGeometrySDFManager.js:71` (`maxTextureDimension3D`). The mock cannot tell you whether any of
-those clamps is correct, because it never objects to the unclamped value.
-
-#### A6. `copyBufferToBuffer` validates nothing — verified
-
-An 8-byte source and an 8-byte destination with `size = 64`:
-
-```
-encoder.copyBufferToBuffer(a, 0, b, 0, 64);
-finish()  -> error scope: null   (encoder was not invalidated)
-submit()  -> RangeError: Invalid typed array length: 16
-```
-
-The spec requires `COPY_SRC` / `COPY_DST` usage, 4-byte alignment on both offsets and the size,
-in-bounds ranges, and `source !== destination`. The encoder checks only `isValid`. Note the shape of
-the failure: the error appears at *submit* time, as a `RangeError` from inside `array_buffer_copy`,
-with a message that names neither buffer.
-
-`ShadeGPUCommandContext.copyBufferToBuffer` does assert bounds — but `assert.*` is compiled out of
-production builds, so the assertion is a development aid, not the contract, and it is the mock's job
-to be the contract.
-
-#### A7. `clearBuffer` accepts an unaligned range — verified
-
-`clearBuffer(buffer, 1, 3)` is executed. The spec requires both offset and size to be multiples of 4.
-
-#### A8. The command encoder is never locked while a pass is open — verified
-
-```
-const p1 = enc.beginComputePass(); const p2 = enc.beginComputePass();  // both succeed
-```
-
-WebGPU puts the encoder into a *locked* state for the lifetime of a pass; any encoder method called
-before `end()` is a validation error that invalidates the encoder. Here you can interleave two passes,
-or issue `copyBufferToBuffer` in the middle of one, and the mock will not object. Pass-scoping bugs
-are a real category and this makes them invisible.
-
-Related: a pass's recorded work never reaches the command buffer. `beginComputePass` pushes onto
-`encoder.compute_passes` and the pass is inspected from there; `finish()` does not fold it into
-`#commands`. That is coherent with "the pass executes nothing", but it does mean `end()` is
-unobservable and pass ordering relative to copies is not represented anywhere.
-
-#### A9. `device.limits` is one shared, mutable object — verified
-
-```
-device.limits.maxBufferSize = 4;
-new SoftwareGPUDevice().limits.maxBufferSize   // -> 4
-```
-
-`DEFAULT_LIMITS` is a module-level object returned by reference from every device. `GPUSupportedLimits`
-is declared entirely `readonly`, and a real Dawn device silently ignores the assignment (verified).
-Here one test can poison every subsequent device in the same worker.
-
-This also blocks something worth having: the clamp sites listed in A5 are only reachable today by
-actually requesting an 8192-pixel texture. A device whose limits could be *lowered* per instance
-would make them cheap to test — see the proposal, P3.
-
-#### A10. `device.features` is empty; a real core device is not — verified
-
-Dawn's default device reports `core-features-and-limits`. The spec makes that feature always present
-and always enabled on a core adapter. The mock's `NO_FEATURES` is defensible for optional features —
-the header argues the case well — but the always-on one is a factual difference, and code written as
-`device.features.has('core-features-and-limits')` would take the compatibility-mode branch here.
-
-#### A11. Four limits are wrong and one is missing — verified
-
-Against Dawn's default (spec-default) device, `DEFAULT_LIMITS` matches on every field it declares
-except:
-
-| Limit | Mock | Dawn default |
-|---|---|---|
-| `maxStorageBuffersInVertexStage` | 0 (`// unset`) | 8 |
-| `maxStorageBuffersInFragmentStage` | 0 (`// unset`) | 8 |
-| `maxStorageTexturesInVertexStage` | 0 (`// unset`) | 4 |
-| `maxStorageTexturesInFragmentStage` | 0 (`// unset`) | 4 |
-| `maxImmediateSize` | *absent* | 0 |
-
-The four zeroes are not a conservative choice — they are the *compatibility-mode* values, and they
-say "this device supports no storage bindings in the vertex or fragment stage", which is a stronger
-and less true claim than the spec default. Dawn's values are exactly
-`maxStorageBuffersPerShaderStage` and `maxStorageTexturesPerShaderStage`, which is what the spec
-derives them from for a core device.
-
-### Class B — loud divergence
-
-*The mock throws where a real device reports, or refuses what a real device allows. Nothing ships
-broken, but tests cannot be written at all — and the current suite is already paying for it.*
-
-#### B1. `mapAsync` throws `Not Implemented`, and it is costing us today — verified
-
-This is the most consequential gap in the folder, and it is not hypothetical:
-
-```
-$ npx vitest run .../GPUMeshSkinningContext.spec.js --reporter=verbose | grep -c "Not Implemented"
-104
-```
-
-**104 rejected `mapAsync` calls inside one passing spec file.** The origin is
-`GPUBufferStagingAllocator.release()`, which re-maps a released buffer to return it to the pool. The
-`mapAsync` rejection is routed to `console.error` there, so the buffer is dropped instead of pooled,
-the test still passes, and nobody notices.
-
-The measurable effect:
-
-```
-5 identical 64-byte staging requests -> 5 buffers created
-```
-
-Under a real device the pool serves the second through fifth from the first. **The staging pool does
-not pool under the mock** — which means `ShadeGPUCommandContext.writeBuffer` and `writeValueBuffer`,
-the renderer's primary upload path, run a different allocation strategy in tests than in production,
-and any test that reasons about allocation counts is reasoning about the wrong system.
-
-`mapAsync` is also the gate on every GPU→CPU readback: `inspect_gpu_buffer`,
-`inspect_gpu_buffer_typed`, `graph_read_buffer`, `download_texture_data`,
-`Uint32BufferSamplingStats`, `GPUTimer`, `GPUTimerArray`. All are unreachable under the mock.
-
-#### B2. `getMappedRange` refuses sub-ranges the spec allows — verified
-
-```
-getMappedRange(0, 32) on a 64-byte buffer -> Error('Size not supported')
-getMappedRange(offset !== 0)              -> Error('Offset not supported')
-```
-
-Six production call sites pass a sub-range: `ShadeGPUCommandContext.js:630` and `:660`
-(`getMappedRange(0, size)` on a pooled buffer that is `>=` size), `inspect_gpu_buffer.js:43`, `:85`,
-`:95`, `GPUTimerArray.js:169`, `graph_read_buffer.js:95`. The staging path only avoids this today
-*because* B1 stops the pool from ever handing back an oversized buffer — one bug is masking the other,
-and fixing B1 alone would expose B2 immediately.
-
-The spec's own constraints (`offset % 8 === 0`, `size % 4 === 0`, range inside the mapped range, no
-overlap with a range already handed out) are cheap and are the useful part.
-
-#### B3. `destroy()` is not idempotent — verified
-
-`SoftwareGPUBuffer.destroy()` throws `Already destroyed` on a second call; so does
-`SoftwareGPUTexture.destroy()`. The spec says destroy may be called multiple times. The source
-already carries `// TODO should this fail silently instead?` — the answer is yes, and it matters:
-defensive double-destroy in pool teardown is normal, correct code that this mock punishes.
-
-#### B4. `device.destroy()` and `device.adapterInfo` throw `Not Implemented`
-
-`destroy()` in particular is not exotic — it is how a renderer shuts down. Spec behaviour is well
-defined and small: idempotent, resolves `lost` with reason `"destroyed"`, and subsequent work
-becomes a validation error rather than an exception.
-
-#### B5. Re-submitting a command buffer throws — verified
-
-`submit([cb])` twice gives `Error: execute() called twice` from `SoftwareGPUCommandBuffer`. The spec
-makes a second submission a validation error. Throwing is inconsistent with this folder's own
-governing argument, stated at `SoftwareGPUDevice.js:246`: *"Throwing instead would mean renderer code
-that runs on a GPU takes a different path here, which is the one thing a software device must not
-do."*
-
-#### B6. Encode-after-`finish` throws — deliberate, and worth naming as such
-
-`#assert_encoding()` and the second `finish()` both throw. WebGPU makes these validation errors on an
-invalidated encoder. This is a *chosen* deviation — `SoftwareGPUDevice.spec.js:443` pins it — and the
-argument for it (a caller bug should be loud) is reasonable.
-
-It is listed here not as a defect but because the folder currently has **two contradictory policies**
-(A6/B5 argue "never throw, always report"; B6 argues "throw on caller bugs") and neither is written
-down as a policy. Whichever way it lands, it should be one sentence in one place, and the exceptions
-should be exceptions on purpose.
-
-#### B7. `copyExternalImageToTexture` throws for `flipY` and for non-`ImageData` sources
-
-Honest and well-documented, but it is a third policy: an unimplemented *feature* throws a plain
-`Error`. Same note as B6.
-
-### Class C — absent surface
-
-*A `TypeError: x is not a function` on contact. Cheap to diagnose, but each one is a hard stop for a
-category of test.*
-
-| # | Missing | Consequence |
-|---|---|---|
-| C1 | `device.createQuerySet` | `GPUTimer`, `GPUTimerArray` cannot be constructed |
-| C2 | `encoder.beginRenderPass` | **any** render-pass test; `ShadeGPUCommandContext.beginRenderPass`/`constructRenderPass` are dead under the mock |
-| C3 | `encoder.copyTextureToTexture` / `copyBufferToTexture` / `copyTextureToBuffer` | texture upload/readback/blit paths; `download_texture_data` |
-| C4 | `encoder.resolveQuerySet` | timing readback |
-| C5 | a render pass encoder class | see C2 |
-| C6 | `queue.onSubmittedWorkDone` | any code that waits on the queue |
-| C7 | `device.lost` | shutdown / context-loss handling |
-| C8 | `createCommandEncoder(descriptor)` — descriptor dropped | encoder has no `label` at all; `ShadeGPUCommandContext.create` passes one (`ShadeGPUCommandContext.js:198`) and it vanishes. `SoftwareGPUCommandEncoder`, `SoftwareGPUQueue` and `SoftwareGPUCommandBuffer` all skip `SoftwareGPUObjectBase`, and the compute pass encoder rolled its own `label` field instead — four objects, three answers |
-| C9 | `setBindGroup` dynamic offsets | the 5-argument overload is dropped on the floor; dynamic-offset bugs are invisible |
-| C10 | `GPUAdapter` / `navigator.gpu` stand-in | device-acquisition code cannot be driven |
-
-C2/C5 are worth a second look because of how small the real requirement is. Counting calls made
-directly on a pass across all of `shade/`: `draw` (17), `setViewport` (4), `drawIndirect` (3),
-`setVertexBuffer` (1, in a `prototype*.js` file), plus `setPipeline` / `setBindGroup` / `end` /
-debug markers. No index buffers, no bundles, no occlusion queries. And most full-screen work does not
-touch a pass directly at all — `ImageShader.draw()` funnels through `constructRenderPass` →
-`setViewport` → `draw(3)` → `end` (`renderer/shader/ImageShader.js:178-208`), with roughly two dozen
-further call sites behind it. A recording render pass encoder is about the size of the compute one
-that already exists, and it unblocks every full-screen pass in the renderer.
-
-### Class D — environment coupling
-
-#### D1. Texture views and samplers are not recognised by the `instanceof` stubs — verified
-
-```
-tex.createView()      instanceof GPUTextureView -> false
-device.createSampler() instanceof GPUSampler    -> false
-device.createBuffer()  instanceof GPUBuffer     -> true
-```
-
-`vitest.setup.mjs` gives `GPUBuffer` a `Symbol.hasInstance` that recognises `SoftwareGPUBuffer`, with
-a good comment explaining why. `GPUTextureView` and `GPUSampler` got empty stand-ins instead.
-
-The consequence is in production code:
-`BindGroupDescriptor.compute_binding_resource_hash` branches on exactly those two `instanceof` tests.
-Under the mock both are false, control falls to `resource.buffer !== undefined` (also false), and the
-function **returns 0 for every texture-view and sampler binding**. Two bind groups differing only in
-their bound textures hash identically. The correctness of the cache is saved by
-`compute_binding_resource_equality`, which falls back to identity — so this is not a live bug, but it
-does mean the texture-view and sampler branches of the renderer's bind-group hashing are *dead code
-in node*, and `BindGroupManager.spec.js` (109 lines) binds only buffers, so nothing covers them.
-
-The same two tests also gate `encoder_prepare_shader_binding.js:55`/`:66` and
-`ShaderResourceGroupDescriptor.js:132`, which take an `else { throw }` branch for an unrecognised
-resource.
-
-`SoftwareGPUSampler` is not even a class — `createSampler` returns
-`{...descriptor, isSoftwareGPUSampler: true}`, an object literal, so `a.constructor` is `Object`.
-
-### Class E — inherited limitations
-
-#### E1. `bytes_per_texel` throws for most non-colour formats — verified
-
-`SoftwareGPUTexture.bytes_per_texel` delegates to `parse_gpu_texture_format`, whose regular
-expression handles only `<channels><bits><type>`:
-
-| Format | Result |
-|---|---|
-| `rgba8unorm`, `bgra8unorm`, `rgba8unorm-srgb`, `r32float`, `rg16uint` | correct |
-| `depth32float` | correct (special case) |
-| `depth24plus`, `stencil8`, `bc7-rgba-unorm` | `Error: Failed to parse` |
-| `rgb10a2unorm`, `rg11b10ufloat` | `Error: Unsupported format` |
-
-So a texture in any depth format other than `depth32float`, any packed format, or any block-compressed
-format cannot have data written to it or read from it through this mock. Given that Shade's shadow
-maps, Hi-Z chain and G-buffer all use depth and packed formats, this bounds texture testing quite
-sharply. The fix belongs upstream of this folder, but the requirement originates here.
-
-#### E2. `writeTexture` is single-layer, single-aspect, 2D only
-
-`assert.equal(depth, 1, 'only single-layer writes are emulated')`. `rowsPerImage` is ignored, `aspect`
-is ignored, and although `get_mip_data` allocates `width × height × depthOrArrayLayers × bpt`, the
-row addressing in `writeTexture` only ever reaches layer 0 — the rest of the allocation is
-unreachable. Cube maps, texture arrays and 3D textures (the LPG volume, the SDF atlas, the probe
-atlas) are all out of reach.
-
-Also note this validation is expressed with `assert.*`, which is stripped in production builds. That
-is harmless while this folder is test-only, but it means the guard is a development aid rather than
-a contract; a mock's refusals should hold under any build.
-
-### Class F — stale documentation
-
-#### F1. `probe_instance_animation.js` states a limitation that no longer exists
-
-Its header explains that it cannot be a spec because *"`SoftwareGPUDevice` has neither
-`pushErrorScope` nor `createShaderModule`"*. Both exist now, and `GPUMeshSkinningContext.spec.js:73`
-constructs a full `GraphicsContext` over the mock. The *other* reason given there — that registration
-is only observable through GPU output — still stands, so the file should stay a probe; but the stated
-wall is gone and the comment misleads the next reader about what the mock can do.
-
-#### F2. `GPUDatabase.spec.js` carries a skipped functional test
-
-`test.skip("full-fat", ...)` is written against a real Dawn device and exercises the whole
-write → upload → read-back loop. It cannot be re-pointed at the software device: `GPUDatabase.update`
-uploads through a **compute dispatch** (`gpu_table_element_upload_shader.dispatch`,
-`GPUDatabase.js:570`), and a dispatch changes no bytes here. No amount of extension to this mock
-short of shader execution will run it.
-
-It is listed because a skipped functional test should be fixed or deleted, and because the reason it
-is skipped needs checking: the stated obstacle elsewhere in the tree is that a Dawn device "does not
-survive vitest's worker pool", but a Dawn device created inside a vitest run in this repo today does
-a full `writeBuffer → mapAsync → getMappedRange` round trip successfully (verified). Whatever is
-actually blocking that test, it is worth re-establishing rather than assuming.
-
----
-
-## 4. Summary
-
-| Class | Count | Cost of leaving it |
-|---|---|---|
-| A — silent divergence | 11 | green tests over broken GPU behaviour |
-| B — loud divergence | 7 | tests cannot be written; 104 suppressed errors in one existing spec |
-| C — absent surface | 10 | whole categories blocked (render passes, timing, texture copies) |
-| D — environment coupling | 1 | two production hashing branches dead in node |
-| E — inherited | 2 | depth/packed/compressed textures out of reach |
-| F — stale docs | 2 | — |
-
-The one-line version: **the error-reporting machinery is excellent and the validation it exists to
-report is almost entirely absent.** The scaffolding for saying "the device refused this, here is why,
-in the scope you were watching" is built, tested and correct — and `createBuffer`'s single
-`maxBufferSize` check is the only thing that ever uses it. Every extension in the companion document
-is, in one way or another, a way of giving that machinery something to report.
-
----
-
-## 5. Adversarial review of this document
-
-Challenges raised against the draft, and what they changed.
-
-**"A2, A3 and A6 are the same finding — the mock does not validate."** Partly fair, and they are now
-grouped under one heading with one shared framing. They are kept separate because the remedies are
-independent and land in different files, and because A2 (lifetime) is a different *kind* of state
-than A6 (arguments). The class heading now carries the shared argument so the individual entries do
-not repeat it.
-
-**"You claim `writeBuffer` truncation is the highest-consequence finding, but you have not shown a
-real renderer bug it would hide."** Correct, and the claim is now scoped to what was measured: the
-behaviour is verified, the consequence is argued from call-site count (`writeBuffer` is the most-used
-queue entry point), not from a caught bug. No claim of a discovered defect is made anywhere in this
-document.
-
-**"B1's `104` is a grep count of stack-trace lines, not of distinct failures."** A fair objection, and
-it was checked rather than argued: the same run yields 104 `Error: Not Implemented` lines, 104
-`at SoftwareGPUBuffer.mapAsync` frames and 104 `at GPUBufferStagingAllocator.release` frames. Each
-stack contributes exactly one of each, so the count is 104 distinct rejections. The claim stands as
-written. Independently of the count, the argument rests on the second measurement —
-`5 identical staging requests → 5 buffers created` — which is a direct behavioural observation and
-does not depend on error counting at all.
-
-**"A9's 'poisons every device in the worker' — do the current tests actually share a worker?"** Not
-asserted either way now. The verified fact is that the object is shared and mutable and that a real
-device ignores the write; whether any current test collides is unknown and the text no longer implies
-one does.
-
-**"A11 says Dawn's numbers are 'the spec defaults'. Dawn reports its *supported* limits, which may
-exceed spec defaults."** Right, and the text was corrected. The evidence is that
-`adapter.requestDevice()` with no `requiredLimits` yields the default device, and that its four
-values coincide exactly with `maxStorageBuffersPerShaderStage` / `maxStorageTexturesPerShaderStage`,
-which is how the spec derives them for a core device. The document now says that, rather than
-"Dawn is the spec".
-
-**"D1 is a bug in `vitest.setup.mjs`, not in this folder."** True; it is retained because the fix
-requires a change in this folder as well (`SoftwareGPUSampler` must become a class to be recognised)
-and because a reader of the mock has no other place to learn that view bindings hash to zero. The
-class is now explicitly named "environment coupling" rather than filed as a mock defect.
-
-**"E1/E2 are other people's code."** Yes — the class is named "inherited" and the review says the fix
-belongs upstream. They are in scope because they bound what this mock can be extended to do, which
-is the question the companion document has to answer.
-
-**"B6 is listed as a finding but you conclude it is fine."** Reworded. It is not a defect claim; it
-is a claim that three different policies for unimplemented/illegal input coexist without one being
-written down. That claim stands on its own.
-
-**"The render-pass call counts in C2 look like a raw `.draw(` grep."** They were, and they were
-wrong — 44 counted `ImageShader.draw({...})` helper calls alongside genuine `pass.draw()` calls.
-Recounted against pass-bound receivers only: 17 / 4 / 3 / 1. The correction weakens the raw numbers
-and strengthens the point, because `ImageShader.draw` turns out to funnel *into* the same tiny pass
-surface, so the helper call sites are additional beneficiaries rather than additional API.
-
-**"The fidelity ladder in §2.1 is invented vocabulary."** It is, and it is only used as a reading
-aid. The table's rungs are each defined by the concrete behaviour of the object, so a reader who
-rejects the vocabulary loses nothing.
+# `shade/device/mock` — review, 2026-08-22
+
+A review of `SoftwareGPUDevice` and the objects around it, against the WebGPU specification and
+against what the Shade renderer actually asks a device to do.
+
+> **Status: acted on.** Every finding below except the two named as out of scope has since been
+> fixed. This document describes the device *as it was on 2026-08-22*, and is kept as the record of
+> why the work was done and what the evidence for each finding was — not as a description of the
+> current code. What actually landed is in
+> [`IMPLEMENTATION_PLAN.md`](./IMPLEMENTATION_PLAN.md) §5.
+>
+> Still open: **E1/E2** (inherited limitations) are only partly addressed — `bytes_per_texel` no
+> longer throws for depth, packed or compressed formats, but `writeTexture` is still single-layer
+> (E2). **F1** and **F2** were both closed on 2026-08-22, by deletion rather than by fixing:
+> `probe_instance_animation.js` was removed with the `webgpu` dependency (it was one of five
+> hand-run Dawn probes), and `GPUDatabase.spec.js`'s skipped `full-fat` test went with it — F2's
+> own finding is why it could not be re-pointed at this device instead.
+
+The companion document is [`EXTENSION_PROPOSAL_2026_08_22.md`](./EXTENSION_PROPOSAL_2026_08_22.md),
+which turns the findings here into ranked work items.
+
+---
+
+## 1. Method
+
+Read every file in this folder, then established each behavioural claim below by running it. The
+probes were temporary spec files placed in this folder (vitest's `include` is `app/src/**/*.spec.js`,
+so a scratch file elsewhere is not collected) and deleted afterwards. Limit values were checked
+against a real Dawn device obtained through the `webgpu` package, which is already a dependency and
+is what `GPUDatabase.spec.js` and the `probe_*.js` tools use.
+
+Every "verified" tag below means the behaviour was observed, not inferred from reading.
+
+Baseline: `npx vitest run app/src/mir-engine/meep/src/shade/device/mock/` — 26 tests, all passing.
+
+---
+
+## 2. What this mock is, and what it is good at
+
+`SoftwareGPUDevice` is a CPU-memory stand-in for `GPUDevice` that lets renderer code be constructed
+and driven under node. It is not an emulator: nothing here compiles or executes WGSL — that is
+`wgsl/emulator/ComputeShaderEmulator.js` — and nothing rasterizes.
+
+Three things in it are genuinely good and should be preserved by any extension:
+
+1. **The error model is right.** `pushErrorScope` / `popErrorScope` / `generate_error` /
+   `uncapturederror` reproduce WebGPU's scope stack faithfully, down to details that are easy to get
+   wrong: innermost-matching-scope wins, a scope keeps only its first error, a pop with no scope open
+   rejects with an `OperationError`, an unclaimed error reaches the console. `SoftwareGPUError` is
+   deliberately not an `Error` subclass, because `GPUError` is not one either. The reasoning is
+   written down in the source next to the code that depends on it.
+
+2. **A rejected descriptor does not throw.** `createBuffer` reports through the error scope and
+   returns an invalid buffer that still reads back its requested `size`, `usage` and `label`, and the
+   invalidity propagates the way WebGPU propagates it — a command naming an invalid buffer poisons
+   the *encoder*, and the error surfaces from `finish()`, not from the encoding call. Then a
+   submission holding one invalid command buffer executes *none* of its command buffers. That chain
+   is subtle and it is implemented correctly.
+
+3. **Where it declines to emulate, it says so loudly.** `SoftwareGPUComputePassEncoder`'s header
+   states in plain words that dispatches change no bytes and that asserting on shader output is
+   meaningless. `dispatchWorkgroupsIndirect` records `[-1, -1, -1]` rather than inventing a
+   workgroup count. This is the right instinct and the extensions should keep it.
+
+The findings below are about the surface *around* that core, which is much thinner than the core
+suggests.
+
+### 2.1 Inventory
+
+| File | Fidelity | Note |
+|---|---|---|
+| `SoftwareGPUDevice` | **Validating** (buffers only) | error scopes complete; `destroy`/`adapterInfo` throw |
+| `SoftwareGPUError`, `SoftwareGPUUncapturedErrorEvent` | **Complete** | — |
+| `SoftwareGPUBuffer` | **Executing** | no mapping; no destroyed-state enforcement |
+| `SoftwareGPUQueue` | **Executing** | no validation at all |
+| `SoftwareGPUCommandEncoder` | **Executing** (2 of 8 commands) | no render pass, no texture copies |
+| `SoftwareGPUCommandBuffer` | **Executing** | — |
+| `SoftwareGPUTexture` | **Storing** | lazy per-mip CPU storage, layer 0 only |
+| `SoftwareGPUComputePassEncoder` | **Recording** | by design |
+| `SoftwareGPUPipeline`, `SoftwareGPUShaderModule`, `SoftwareGPUBindGroup(Layout)`, `SoftwareGPUTextureView` | **Opaque handle** | by design |
+| `GPUQuerySet`, `GPURenderPassEncoder`, `GPURenderBundle*`, `GPUAdapter`, `GPUCanvasContext` | **Absent** | — |
+
+The ladder — *opaque handle → recording → storing → executing → validating* — is the useful axis for
+the rest of this document. The mock's problem is not that objects sit low on it. It is that **which**
+rung a given object sits on is unpredictable, and nothing tells a caller which one they got.
+
+---
+
+## 3. Findings
+
+Grouped by failure mode, because the failure mode determines how much a finding costs you.
+
+### Class A — silent divergence
+
+*The mock accepts what a real device rejects. The test goes green and the GPU breaks. This is the
+expensive class: a mock that is merely incomplete wastes an afternoon, a mock that is wrong ships a
+bug.*
+
+#### A1. `queue.writeBuffer` performs no validation whatsoever — verified
+
+The spec requires `bufferOffset % 4 === 0`, the written size to be a multiple of 4, the destination
+range to lie inside the buffer, and the destination usage to include `COPY_DST`. None of these are
+checked.
+
+Observed, on an 8-byte buffer:
+
+- `writeBuffer(buffer, 0, new Uint8Array(16))` — **wrote 8 bytes, reported nothing.** No throw, no
+  error scope entry. The default-size computation at `SoftwareGPUQueue.js:84` is
+  `Math.min(buffer.size - offset, source.byteLength - dataOffset)`, which silently clamps. A real
+  device raises a validation error; the caller here is told the write succeeded.
+- `writeBuffer(buffer, 1, new Uint8Array([9,9,9]))` — **wrote 3 bytes at byte offset 1.** Both the
+  offset and the size are unaligned; both are validation errors in WebGPU.
+- With an explicit oversized `size`, the clamp does not apply and `array_buffer_copy` throws a bare
+  `RangeError: Invalid typed array length` from two frames down — an opaque crash where the spec has
+  a named, catchable error.
+
+`writeBuffer` is the single most-used queue entry point in the renderer. Silent truncation here is
+the highest-consequence finding in this document.
+
+#### A2. A destroyed buffer remains fully usable — verified
+
+```
+c = device.createBuffer({size: 16, usage: COPY_DST}); c.destroy();
+queue.writeBuffer(c, 0, new Uint8Array([1,2,3,4]));
+// error scope: null      c.data: [1, 2, 3, 4]
+```
+
+`destroy()` sets a flag and nothing reads it. `#data` is retained, `writeBuffer` writes into it,
+`copyBufferToBuffer` copies out of it, `getMappedRange` hands it out. Use-after-destroy is one of the
+easier lifetime bugs to introduce in a pooled allocator and this mock is blind to all of it.
+
+`SoftwareGPUTexture.destroy()` at least clears `#mip_data`, but `get_mip_data` will happily
+re-allocate afterwards, so the same hole exists one indirection away.
+
+#### A3. `getMappedRange()` succeeds on an unmapped buffer — verified
+
+The guard at `SoftwareGPUBuffer.js:144` tests `#data === null`, which is only true for a buffer the
+device *refused*. A valid, unmapped, never-mapped buffer returns its whole storage. The spec requires
+an `OperationError` unless `mapState` is `"mapped"`.
+
+Consequence: renderer code that forgets to map, or that reads a range after `unmap()`, works here and
+fails in a browser. `GPUBufferStagingAllocator` asserts `mapState === "mapped"` precisely because
+that discipline matters, and the mock removes the only mechanism that would catch a violation.
+
+#### A4. `createBuffer` validates one rule out of five — verified
+
+Only `size > maxBufferSize` is checked. Accepted without complaint:
+
+- `usage: 0` (spec: validation error),
+- `MAP_READ | MAP_WRITE` together, and `MAP_READ` combined with anything other than `COPY_DST`
+  (spec: validation error),
+- `mappedAtCreation: true` with a size that is not a multiple of 4 (spec: validation error).
+
+#### A5. `createTexture` validates nothing at all — verified
+
+```
+device.createTexture({size: [1<<20, 1<<20], format: 'rgba8unorm', usage: TEXTURE_BINDING});
+// error scope: null
+```
+
+`maxTextureDimension1D/2D/3D`, `maxTextureArrayLayers`, `mipLevelCount` versus size, `sampleCount`,
+`usage: 0`, format/usage compatibility — none are examined. This is a straight inconsistency with
+`createBuffer`, which is the same kind of entry point and does check its headline limit.
+
+It also leaves seven sites unexercised. The renderer clamps its own allocations against a texture
+dimension limit in `Renderer.js:1381`, `:1440`, `GPUProbeAtlas.js:112`, `:213`,
+`VirtualShadowMap.js:77` and `GPUSceneShadowmapContext.js:270` (all `maxTextureDimension2D`), and in
+`GPUGeometrySDFManager.js:71` (`maxTextureDimension3D`). The mock cannot tell you whether any of
+those clamps is correct, because it never objects to the unclamped value.
+
+#### A6. `copyBufferToBuffer` validates nothing — verified
+
+An 8-byte source and an 8-byte destination with `size = 64`:
+
+```
+encoder.copyBufferToBuffer(a, 0, b, 0, 64);
+finish()  -> error scope: null   (encoder was not invalidated)
+submit()  -> RangeError: Invalid typed array length: 16
+```
+
+The spec requires `COPY_SRC` / `COPY_DST` usage, 4-byte alignment on both offsets and the size,
+in-bounds ranges, and `source !== destination`. The encoder checks only `isValid`. Note the shape of
+the failure: the error appears at *submit* time, as a `RangeError` from inside `array_buffer_copy`,
+with a message that names neither buffer.
+
+`ShadeGPUCommandContext.copyBufferToBuffer` does assert bounds — but `assert.*` is compiled out of
+production builds, so the assertion is a development aid, not the contract, and it is the mock's job
+to be the contract.
+
+#### A7. `clearBuffer` accepts an unaligned range — verified
+
+`clearBuffer(buffer, 1, 3)` is executed. The spec requires both offset and size to be multiples of 4.
+
+#### A8. The command encoder is never locked while a pass is open — verified
+
+```
+const p1 = enc.beginComputePass(); const p2 = enc.beginComputePass();  // both succeed
+```
+
+WebGPU puts the encoder into a *locked* state for the lifetime of a pass; any encoder method called
+before `end()` is a validation error that invalidates the encoder. Here you can interleave two passes,
+or issue `copyBufferToBuffer` in the middle of one, and the mock will not object. Pass-scoping bugs
+are a real category and this makes them invisible.
+
+Related: a pass's recorded work never reaches the command buffer. `beginComputePass` pushes onto
+`encoder.compute_passes` and the pass is inspected from there; `finish()` does not fold it into
+`#commands`. That is coherent with "the pass executes nothing", but it does mean `end()` is
+unobservable and pass ordering relative to copies is not represented anywhere.
+
+#### A9. `device.limits` is one shared, mutable object — verified
+
+```
+device.limits.maxBufferSize = 4;
+new SoftwareGPUDevice().limits.maxBufferSize   // -> 4
+```
+
+`DEFAULT_LIMITS` is a module-level object returned by reference from every device. `GPUSupportedLimits`
+is declared entirely `readonly`, and a real Dawn device silently ignores the assignment (verified).
+Here one test can poison every subsequent device in the same worker.
+
+This also blocks something worth having: the clamp sites listed in A5 are only reachable today by
+actually requesting an 8192-pixel texture. A device whose limits could be *lowered* per instance
+would make them cheap to test — see the proposal, P3.
+
+#### A10. `device.features` is empty; a real core device is not — verified
+
+Dawn's default device reports `core-features-and-limits`. The spec makes that feature always present
+and always enabled on a core adapter. The mock's `NO_FEATURES` is defensible for optional features —
+the header argues the case well — but the always-on one is a factual difference, and code written as
+`device.features.has('core-features-and-limits')` would take the compatibility-mode branch here.
+
+#### A11. Four limits are wrong and one is missing — verified
+
+Against Dawn's default (spec-default) device, `DEFAULT_LIMITS` matches on every field it declares
+except:
+
+| Limit | Mock | Dawn default |
+|---|---|---|
+| `maxStorageBuffersInVertexStage` | 0 (`// unset`) | 8 |
+| `maxStorageBuffersInFragmentStage` | 0 (`// unset`) | 8 |
+| `maxStorageTexturesInVertexStage` | 0 (`// unset`) | 4 |
+| `maxStorageTexturesInFragmentStage` | 0 (`// unset`) | 4 |
+| `maxImmediateSize` | *absent* | 0 |
+
+The four zeroes are not a conservative choice — they are the *compatibility-mode* values, and they
+say "this device supports no storage bindings in the vertex or fragment stage", which is a stronger
+and less true claim than the spec default. Dawn's values are exactly
+`maxStorageBuffersPerShaderStage` and `maxStorageTexturesPerShaderStage`, which is what the spec
+derives them from for a core device.
+
+### Class B — loud divergence
+
+*The mock throws where a real device reports, or refuses what a real device allows. Nothing ships
+broken, but tests cannot be written at all — and the current suite is already paying for it.*
+
+#### B1. `mapAsync` throws `Not Implemented`, and it is costing us today — verified
+
+This is the most consequential gap in the folder, and it is not hypothetical:
+
+```
+$ npx vitest run .../GPUMeshSkinningContext.spec.js --reporter=verbose | grep -c "Not Implemented"
+104
+```
+
+**104 rejected `mapAsync` calls inside one passing spec file.** The origin is
+`GPUBufferStagingAllocator.release()`, which re-maps a released buffer to return it to the pool. The
+`mapAsync` rejection is routed to `console.error` there, so the buffer is dropped instead of pooled,
+the test still passes, and nobody notices.
+
+The measurable effect:
+
+```
+5 identical 64-byte staging requests -> 5 buffers created
+```
+
+Under a real device the pool serves the second through fifth from the first. **The staging pool does
+not pool under the mock** — which means `ShadeGPUCommandContext.writeBuffer` and `writeValueBuffer`,
+the renderer's primary upload path, run a different allocation strategy in tests than in production,
+and any test that reasons about allocation counts is reasoning about the wrong system.
+
+`mapAsync` is also the gate on every GPU→CPU readback: `inspect_gpu_buffer`,
+`inspect_gpu_buffer_typed`, `graph_read_buffer`, `download_texture_data`,
+`Uint32BufferSamplingStats`, `GPUTimer`, `GPUTimerArray`. All are unreachable under the mock.
+
+#### B2. `getMappedRange` refuses sub-ranges the spec allows — verified
+
+```
+getMappedRange(0, 32) on a 64-byte buffer -> Error('Size not supported')
+getMappedRange(offset !== 0)              -> Error('Offset not supported')
+```
+
+Six production call sites pass a sub-range: `ShadeGPUCommandContext.js:630` and `:660`
+(`getMappedRange(0, size)` on a pooled buffer that is `>=` size), `inspect_gpu_buffer.js:43`, `:85`,
+`:95`, `GPUTimerArray.js:169`, `graph_read_buffer.js:95`. The staging path only avoids this today
+*because* B1 stops the pool from ever handing back an oversized buffer — one bug is masking the other,
+and fixing B1 alone would expose B2 immediately.
+
+The spec's own constraints (`offset % 8 === 0`, `size % 4 === 0`, range inside the mapped range, no
+overlap with a range already handed out) are cheap and are the useful part.
+
+#### B3. `destroy()` is not idempotent — verified
+
+`SoftwareGPUBuffer.destroy()` throws `Already destroyed` on a second call; so does
+`SoftwareGPUTexture.destroy()`. The spec says destroy may be called multiple times. The source
+already carries `// TODO should this fail silently instead?` — the answer is yes, and it matters:
+defensive double-destroy in pool teardown is normal, correct code that this mock punishes.
+
+#### B4. `device.destroy()` and `device.adapterInfo` throw `Not Implemented`
+
+`destroy()` in particular is not exotic — it is how a renderer shuts down. Spec behaviour is well
+defined and small: idempotent, resolves `lost` with reason `"destroyed"`, and subsequent work
+becomes a validation error rather than an exception.
+
+#### B5. Re-submitting a command buffer throws — verified
+
+`submit([cb])` twice gives `Error: execute() called twice` from `SoftwareGPUCommandBuffer`. The spec
+makes a second submission a validation error. Throwing is inconsistent with this folder's own
+governing argument, stated at `SoftwareGPUDevice.js:246`: *"Throwing instead would mean renderer code
+that runs on a GPU takes a different path here, which is the one thing a software device must not
+do."*
+
+#### B6. Encode-after-`finish` throws — deliberate, and worth naming as such
+
+`#assert_encoding()` and the second `finish()` both throw. WebGPU makes these validation errors on an
+invalidated encoder. This is a *chosen* deviation — `SoftwareGPUDevice.spec.js:443` pins it — and the
+argument for it (a caller bug should be loud) is reasonable.
+
+It is listed here not as a defect but because the folder currently has **two contradictory policies**
+(A6/B5 argue "never throw, always report"; B6 argues "throw on caller bugs") and neither is written
+down as a policy. Whichever way it lands, it should be one sentence in one place, and the exceptions
+should be exceptions on purpose.
+
+#### B7. `copyExternalImageToTexture` throws for `flipY` and for non-`ImageData` sources
+
+Honest and well-documented, but it is a third policy: an unimplemented *feature* throws a plain
+`Error`. Same note as B6.
+
+### Class C — absent surface
+
+*A `TypeError: x is not a function` on contact. Cheap to diagnose, but each one is a hard stop for a
+category of test.*
+
+| # | Missing | Consequence |
+|---|---|---|
+| C1 | `device.createQuerySet` | `GPUTimer`, `GPUTimerArray` cannot be constructed |
+| C2 | `encoder.beginRenderPass` | **any** render-pass test; `ShadeGPUCommandContext.beginRenderPass`/`constructRenderPass` are dead under the mock |
+| C3 | `encoder.copyTextureToTexture` / `copyBufferToTexture` / `copyTextureToBuffer` | texture upload/readback/blit paths; `download_texture_data` |
+| C4 | `encoder.resolveQuerySet` | timing readback |
+| C5 | a render pass encoder class | see C2 |
+| C6 | `queue.onSubmittedWorkDone` | any code that waits on the queue |
+| C7 | `device.lost` | shutdown / context-loss handling |
+| C8 | `createCommandEncoder(descriptor)` — descriptor dropped | encoder has no `label` at all; `ShadeGPUCommandContext.create` passes one (`ShadeGPUCommandContext.js:198`) and it vanishes. `SoftwareGPUCommandEncoder`, `SoftwareGPUQueue` and `SoftwareGPUCommandBuffer` all skip `SoftwareGPUObjectBase`, and the compute pass encoder rolled its own `label` field instead — four objects, three answers |
+| C9 | `setBindGroup` dynamic offsets | the 5-argument overload is dropped on the floor; dynamic-offset bugs are invisible |
+| C10 | `GPUAdapter` / `navigator.gpu` stand-in | device-acquisition code cannot be driven |
+
+C2/C5 are worth a second look because of how small the real requirement is. Counting calls made
+directly on a pass across all of `shade/`: `draw` (17), `setViewport` (4), `drawIndirect` (3),
+`setVertexBuffer` (1, in a `prototype*.js` file), plus `setPipeline` / `setBindGroup` / `end` /
+debug markers. No index buffers, no bundles, no occlusion queries. And most full-screen work does not
+touch a pass directly at all — `ImageShader.draw()` funnels through `constructRenderPass` →
+`setViewport` → `draw(3)` → `end` (`renderer/shader/ImageShader.js:178-208`), with roughly two dozen
+further call sites behind it. A recording render pass encoder is about the size of the compute one
+that already exists, and it unblocks every full-screen pass in the renderer.
+
+### Class D — environment coupling
+
+#### D1. Texture views and samplers are not recognised by the `instanceof` stubs — verified
+
+```
+tex.createView()      instanceof GPUTextureView -> false
+device.createSampler() instanceof GPUSampler    -> false
+device.createBuffer()  instanceof GPUBuffer     -> true
+```
+
+`vitest.setup.mjs` gives `GPUBuffer` a `Symbol.hasInstance` that recognises `SoftwareGPUBuffer`, with
+a good comment explaining why. `GPUTextureView` and `GPUSampler` got empty stand-ins instead.
+
+The consequence is in production code:
+`BindGroupDescriptor.compute_binding_resource_hash` branches on exactly those two `instanceof` tests.
+Under the mock both are false, control falls to `resource.buffer !== undefined` (also false), and the
+function **returns 0 for every texture-view and sampler binding**. Two bind groups differing only in
+their bound textures hash identically. The correctness of the cache is saved by
+`compute_binding_resource_equality`, which falls back to identity — so this is not a live bug, but it
+does mean the texture-view and sampler branches of the renderer's bind-group hashing are *dead code
+in node*, and `BindGroupManager.spec.js` (109 lines) binds only buffers, so nothing covers them.
+
+The same two tests also gate `encoder_prepare_shader_binding.js:55`/`:66` and
+`ShaderResourceGroupDescriptor.js:132`, which take an `else { throw }` branch for an unrecognised
+resource.
+
+`SoftwareGPUSampler` is not even a class — `createSampler` returns
+`{...descriptor, isSoftwareGPUSampler: true}`, an object literal, so `a.constructor` is `Object`.
+
+### Class E — inherited limitations
+
+#### E1. `bytes_per_texel` throws for most non-colour formats — verified
+
+`SoftwareGPUTexture.bytes_per_texel` delegates to `parse_gpu_texture_format`, whose regular
+expression handles only `<channels><bits><type>`:
+
+| Format | Result |
+|---|---|
+| `rgba8unorm`, `bgra8unorm`, `rgba8unorm-srgb`, `r32float`, `rg16uint` | correct |
+| `depth32float` | correct (special case) |
+| `depth24plus`, `stencil8`, `bc7-rgba-unorm` | `Error: Failed to parse` |
+| `rgb10a2unorm`, `rg11b10ufloat` | `Error: Unsupported format` |
+
+So a texture in any depth format other than `depth32float`, any packed format, or any block-compressed
+format cannot have data written to it or read from it through this mock. Given that Shade's shadow
+maps, Hi-Z chain and G-buffer all use depth and packed formats, this bounds texture testing quite
+sharply. The fix belongs upstream of this folder, but the requirement originates here.
+
+#### E2. `writeTexture` is single-layer, single-aspect, 2D only
+
+`assert.equal(depth, 1, 'only single-layer writes are emulated')`. `rowsPerImage` is ignored, `aspect`
+is ignored, and although `get_mip_data` allocates `width × height × depthOrArrayLayers × bpt`, the
+row addressing in `writeTexture` only ever reaches layer 0 — the rest of the allocation is
+unreachable. Cube maps, texture arrays and 3D textures (the LPG volume, the SDF atlas, the probe
+atlas) are all out of reach.
+
+Also note this validation is expressed with `assert.*`, which is stripped in production builds. That
+is harmless while this folder is test-only, but it means the guard is a development aid rather than
+a contract; a mock's refusals should hold under any build.
+
+### Class F — stale documentation
+
+#### F1. `probe_instance_animation.js` states a limitation that no longer exists
+
+Its header explains that it cannot be a spec because *"`SoftwareGPUDevice` has neither
+`pushErrorScope` nor `createShaderModule`"*. Both exist now, and `GPUMeshSkinningContext.spec.js:73`
+constructs a full `GraphicsContext` over the mock. The *other* reason given there — that registration
+is only observable through GPU output — still stands, so the file should stay a probe; but the stated
+wall is gone and the comment misleads the next reader about what the mock can do.
+
+#### F2. `GPUDatabase.spec.js` carries a skipped functional test
+
+`test.skip("full-fat", ...)` is written against a real Dawn device and exercises the whole
+write → upload → read-back loop. It cannot be re-pointed at the software device: `GPUDatabase.update`
+uploads through a **compute dispatch** (`gpu_table_element_upload_shader.dispatch`,
+`GPUDatabase.js:570`), and a dispatch changes no bytes here. No amount of extension to this mock
+short of shader execution will run it.
+
+It is listed because a skipped functional test should be fixed or deleted, and because the reason it
+is skipped needs checking: the stated obstacle elsewhere in the tree is that a Dawn device "does not
+survive vitest's worker pool", but a Dawn device created inside a vitest run in this repo today does
+a full `writeBuffer → mapAsync → getMappedRange` round trip successfully (verified). Whatever is
+actually blocking that test, it is worth re-establishing rather than assuming.
+
+---
+
+## 4. Summary
+
+| Class | Count | Cost of leaving it |
+|---|---|---|
+| A — silent divergence | 11 | green tests over broken GPU behaviour |
+| B — loud divergence | 7 | tests cannot be written; 104 suppressed errors in one existing spec |
+| C — absent surface | 10 | whole categories blocked (render passes, timing, texture copies) |
+| D — environment coupling | 1 | two production hashing branches dead in node |
+| E — inherited | 2 | depth/packed/compressed textures out of reach |
+| F — stale docs | 2 | — |
+
+The one-line version: **the error-reporting machinery is excellent and the validation it exists to
+report is almost entirely absent.** The scaffolding for saying "the device refused this, here is why,
+in the scope you were watching" is built, tested and correct — and `createBuffer`'s single
+`maxBufferSize` check is the only thing that ever uses it. Every extension in the companion document
+is, in one way or another, a way of giving that machinery something to report.
+
+---
+
+## 5. Adversarial review of this document
+
+Challenges raised against the draft, and what they changed.
+
+**"A2, A3 and A6 are the same finding — the mock does not validate."** Partly fair, and they are now
+grouped under one heading with one shared framing. They are kept separate because the remedies are
+independent and land in different files, and because A2 (lifetime) is a different *kind* of state
+than A6 (arguments). The class heading now carries the shared argument so the individual entries do
+not repeat it.
+
+**"You claim `writeBuffer` truncation is the highest-consequence finding, but you have not shown a
+real renderer bug it would hide."** Correct, and the claim is now scoped to what was measured: the
+behaviour is verified, the consequence is argued from call-site count (`writeBuffer` is the most-used
+queue entry point), not from a caught bug. No claim of a discovered defect is made anywhere in this
+document.
+
+**"B1's `104` is a grep count of stack-trace lines, not of distinct failures."** A fair objection, and
+it was checked rather than argued: the same run yields 104 `Error: Not Implemented` lines, 104
+`at SoftwareGPUBuffer.mapAsync` frames and 104 `at GPUBufferStagingAllocator.release` frames. Each
+stack contributes exactly one of each, so the count is 104 distinct rejections. The claim stands as
+written. Independently of the count, the argument rests on the second measurement —
+`5 identical staging requests → 5 buffers created` — which is a direct behavioural observation and
+does not depend on error counting at all.
+
+**"A9's 'poisons every device in the worker' — do the current tests actually share a worker?"** Not
+asserted either way now. The verified fact is that the object is shared and mutable and that a real
+device ignores the write; whether any current test collides is unknown and the text no longer implies
+one does.
+
+**"A11 says Dawn's numbers are 'the spec defaults'. Dawn reports its *supported* limits, which may
+exceed spec defaults."** Right, and the text was corrected. The evidence is that
+`adapter.requestDevice()` with no `requiredLimits` yields the default device, and that its four
+values coincide exactly with `maxStorageBuffersPerShaderStage` / `maxStorageTexturesPerShaderStage`,
+which is how the spec derives them for a core device. The document now says that, rather than
+"Dawn is the spec".
+
+**"D1 is a bug in `vitest.setup.mjs`, not in this folder."** True; it is retained because the fix
+requires a change in this folder as well (`SoftwareGPUSampler` must become a class to be recognised)
+and because a reader of the mock has no other place to learn that view bindings hash to zero. The
+class is now explicitly named "environment coupling" rather than filed as a mock defect.
+
+**"E1/E2 are other people's code."** Yes — the class is named "inherited" and the review says the fix
+belongs upstream. They are in scope because they bound what this mock can be extended to do, which
+is the question the companion document has to answer.
+
+**"B6 is listed as a finding but you conclude it is fine."** Reworded. It is not a defect claim; it
+is a claim that three different policies for unimplemented/illegal input coexist without one being
+written down. That claim stands on its own.
+
+**"The render-pass call counts in C2 look like a raw `.draw(` grep."** They were, and they were
+wrong — 44 counted `ImageShader.draw({...})` helper calls alongside genuine `pass.draw()` calls.
+Recounted against pass-bound receivers only: 17 / 4 / 3 / 1. The correction weakens the raw numbers
+and strengthens the point, because `ImageShader.draw` turns out to funnel *into* the same tiny pass
+surface, so the helper call sites are additional beneficiaries rather than additional API.
+
+**"The fidelity ladder in §2.1 is invented vocabulary."** It is, and it is only used as a reading
+aid. The table's rungs are each defined by the concrete behaviour of the object, so a reader who
+rejects the vocabulary loses nothing.