@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,255 +0,0 @@
-# `shade/device/mock` — implementation plan
-
-Execution plan for [`EXTENSION_PROPOSAL_2026_08_22.md`](./EXTENSION_PROPOSAL_2026_08_22.md). Item IDs
-(`P1`…`P9`) are the proposal's; finding IDs (`A1`, `B2`, …) are
-[`REVIEW_2026_08_22.md`](./REVIEW_2026_08_22.md)'s.
-
-Status is maintained in §5 as the work lands.
-
----
-
-## 1. Order of work
-
-The proposal's dependency graph, with one deviation noted below:
-
-```
-Step 1   P9  small change bundle + the policy comment      (sets the rule everything else follows)
-Step 2   P3  per-instance frozen limits
-Step 3   P7  instanceof recognition for views and samplers (own commit — touches vitest.setup.mjs)
-Step 4   P1  buffer mapping                                (mapAsync + sub-range getMappedRange TOGETHER)
-Step 5   P5  texture format block table                    (moved ahead of P2 — P2's texture rules need it)
-Step 6   P2  validation parity
-Step 7   P4  render pass encoder + texture copy commands
-Step 8   P6  resource lifetime + leak ledger
-Step 9   P8  timestamp queries
-```
-
-**Deviation from the proposal's sequencing.** P5 moves ahead of P2. The proposal put P2 in phase 3
-and P5 in phase 4, but P2's `createTexture` rules need to know a format's block size to validate
-anything about texture storage, and P5 is the module that knows it. Cheaper to land the table first
-than to write `createTexture` validation twice.
-
-P9 moves to the front, ahead of P3, because its policy comment is the decision every later item has
-to conform to — the proposal itself says it "arguably deserves to be its own item ahead of
-everything else".
-
----
-
-## 2. The policy this work adopts (P9's decision, made up front)
-
-Three conventions currently coexist in this folder for input the device will not honour, and every
-item below has to pick one. The decision, to be written into `SoftwareGPUDevice.js` as the folder's
-stated rule:
-
-1. **Anything the WebGPU spec calls a validation error is reported through `generate_error`, never
-   thrown.** The device hands back an invalid object where the spec hands back an invalid object.
-   This is the default and it covers every new rule in P2, P4 and P8.
-2. **A caller bug that WebGPU cannot express — using an object after `finish()`/`end()` — throws.**
-   Kept as an existing deliberate deviation, because these come from test code getting the encoder
-   protocol wrong, and a silent no-op there wastes more time than it saves.
-   `SoftwareGPUDevice.spec.js` already pins this.
-3. **A feature this mock does not emulate throws a plain `Error` naming itself.** `flipY`, non-CPU
-   image sources, multi-layer `writeTexture`. Distinct from (1) on purpose: (1) means "a real device
-   would refuse this too", (3) means "a real device would accept this and we cannot".
-
-The distinction that matters: **(1) is a statement about WebGPU, (3) is a statement about this
-mock.** A test that sees (1) has found a bug in the code under test. A test that sees (3) has found a
-limit of the harness.
-
----
-
-## 3. Per-step detail
-
-### Step 1 — P9, small change bundle
-
-`SoftwareGPUDevice.js`
-- Header comment stating §2's policy, with the two exceptions named.
-- `createCommandEncoder(descriptor)` passes the descriptor through.
-- `features`: always contains `core-features-and-limits`; constructor accepts extra ones (the hook
-  P8 uses).
-
-`SoftwareGPUCommandEncoder.js`
-- extends `SoftwareGPUObjectBase`, takes `(device, descriptor)`, so it has a `label`.
-- Encoder **locks** while a pass is open: `#open_pass`. Any encoder method while locked, or a second
-  `beginComputePass`, invalidates the encoder with a validation error surfacing at `finish()`. The
-  pass tells the encoder when it ends.
-
-`SoftwareGPUComputePassEncoder.js`
-- `setBindGroup(index, group, dynamicOffsets)` and the 5-argument
-  `(index, group, dynamicOffsetsData, start, length)` overload both record offsets; dispatches carry
-  them.
-- `end()` notifies the owning encoder.
-
-`SoftwareGPUQueue.js`
-- `onSubmittedWorkDone()` → resolved promise. Submission here is synchronous, so the work *is* done.
-- Re-submitting a command buffer is a validation error, not a throw (B5).
-
-`SoftwareGPUCommandBuffer.js`
-- expose `isExecuted` so the queue can refuse a second submission without catching an exception.
-
-**Verify:** new tests for each row; whole `shade/` suite unchanged.
-
-### Step 2 — P3, limits
-
-`SoftwareGPUDevice.js`
-- `new SoftwareGPUDevice({ label, limits, features })`.
-- `DEFAULT_LIMITS` corrected: the four stage-scoped storage limits take the values the spec derives
-  for a core device (`maxStorageBuffersPerShaderStage` = 8, `maxStorageTexturesPerShaderStage` = 4),
-  and `maxImmediateSize: 0` is added. Frozen.
-- An override is validated the way `requestDevice({requiredLimits})` validates one: an unknown limit
-  name is a `TypeError`; a value *better* than the default is an `OperationError`. "Better" is
-  larger for `max*` and smaller for `min*`.
-- Per-device frozen object.
-
-**Verify:** two devices do not share limits; assignment is a silent no-op; a lowered
-`maxTextureDimension2D` reaches a real renderer clamp (`VirtualShadowMap`).
-
-### Step 3 — P7, `instanceof`
-
-- New `SoftwareGPUSampler` class (`isSoftwareGPUSampler` on the prototype); `createSampler` returns it.
-- `shade/vitest.setup.mjs`: `Symbol.hasInstance` on the `GPUTextureView` and `GPUSampler` stubs,
-  matching the existing `GPUBuffer` treatment.
-
-**Verify:** bind groups differing only in bound view hash differently; a view and a sampler survive
-`encoder_prepare_shader_binding`. Own commit.
-
-### Step 4 — P1, buffer mapping
-
-`SoftwareGPUBuffer.js` — constructor takes the device (needed to raise validation errors).
-- State: `#map_state`, `#map_offset`, `#map_size`, `#mapped_ranges`.
-- `mapAsync(mode, offset = 0, size)` — exactly one of `READ`/`WRITE`; matching usage bit; `offset % 8`;
-  `size % 4`; in bounds; `mapState === "unmapped"`; valid; not destroyed. Failure ⇒ device validation
-  error **and** a rejected `OperationError`. Success ⇒ `"pending"` then `"mapped"`.
-- `getMappedRange(offset = 0, size)` — a **fresh `ArrayBuffer` of exactly `size`**, copied out of the
-  backing store. `offset % 8`, `size % 4`, inside the mapped range, no overlap with a live range.
-  `OperationError` otherwise, including when not mapped (A3).
-- `unmap()` — write every live range back into the backing store, then detach it with
-  `ArrayBuffer.prototype.transfer()`. `mapState` → `"unmapped"`.
-- `mappedAtCreation` maps the whole buffer, so the existing create-write-unmap pattern is unchanged.
-
-**Verify:** `inspect_via_copy` round trip with no shader; staging pool allocates 1 buffer for 5
-identical requests and serves a 64-byte request from a pooled 256-byte buffer; a range is detached
-after `unmap()` and its bytes reached `.data`; zero `Not Implemented` lines from
-`GPUMeshSkinningContext.spec.js`.
-
-### Step 5 — P5, format table
-
-New `descriptor/texture/format/gpu_texture_format_info.js` — the full WebGPU colour, depth/stencil
-and compressed format list as `{block_width, block_height, bytes_per_block, aspects, copyable}`.
-Additive: `parse_gpu_texture_format.js` is left alone.
-
-`SoftwareGPUTexture` uses it for `bytes_per_texel` and gains block-aware mip sizing.
-
-**Verify:** table-driven spec over the whole list; `depth24plus`, `stencil8`, `rgb10a2unorm`,
-`bc7-rgba-unorm` stop throwing.
-
-### Step 6 — P2, validation parity
-
-Per the proposal's rule list, landing one entry point at a time in this order: `queue.writeBuffer`
-(A1, the highest-consequence finding), `copyBufferToBuffer`, `clearBuffer`, `createBuffer`,
-`createTexture`, then the destroyed-state check every consumer honours (A2). Reading the suite output
-between each.
-
-`SoftwareGPUTexture.invalid()` mirrors `SoftwareGPUBuffer.invalid()`.
-
-**Verify:** a table-driven spec, one case per rule; the over-long `writeBuffer` regression;
-`shade/` suite reviewed for new uncaptured errors — each one triaged as a real violation or a rule
-applied too strictly.
-
-### Step 7 — P4, render pass + texture copies
-
-- `SoftwareGPURenderPassEncoder` — recording, modelled on the compute pass encoder, with the same
-  "this executes nothing" header. `setPipeline`, `setBindGroup` (both overloads), `setViewport`,
-  `setScissorRect`, `setVertexBuffer`, `setIndexBuffer`, `draw`, `drawIndexed`, `drawIndirect`,
-  `drawIndexedIndirect`, debug markers, `end`. Records `draws` and retains the attachment descriptor.
-- `encoder.beginRenderPass` — participates in the P9 lock.
-- `copyTextureToTexture`, `copyBufferToTexture`, `copyTextureToBuffer` — executing, row loops over
-  `get_mip_data`, honouring `bytesPerRow` / `rowsPerImage`.
-
-**Verify:** a two-pass frame through `ShadeGPUCommandContext` asserting pass order and attachments;
-a texel round trip `writeTexture → copyTextureToBuffer → mapAsync`.
-
-### Step 8 — P6, lifetime
-
-- `destroy()` idempotent on buffer and texture.
-- `device.destroy()`: idempotent, destroys everything the device handed out, resolves `device.lost`
-  with `"destroyed"`, and makes later work a validation error.
-- `device.lost` — a promise, present from construction.
-- A live-resource ledger the device exposes as **end state**, not a call count.
-
-**Verify:** double destroy is a no-op; `lost` resolves with the right reason; a
-`ShadeGPUCommandContext` leaves no live transient buffers behind.
-
-### Step 9 — P8, timestamp queries
-
-- `SoftwareGPUQuerySet`; `device.createQuerySet`.
-- `encoder.resolveQuerySet` — writes a deterministic monotonic `BigInt64` counter, with a header
-  saying **in terms** that these are not measurements.
-- `timestampWrites` accepted and recorded on compute and render pass descriptors.
-- `timestamp-query` available through the constructor's `features`.
-
-**Verify:** `GPUTimerArray` resolves N pairs and decodes N durations end to end; a mismatched resolve
-range is a validation error.
-
----
-
-## 4. Standing rules for this work
-
-- **Tests are black-box.** Assert observable behaviour — bytes, error scopes, `mapState`, live
-  resource counts. No call counting, no reaching into privates.
-- **No mocks inside the mock.** Tests drive real `SoftwareGPU*` objects and real renderer classes.
-- **`assert.*` is not validation.** It is stripped in production, so every spec rule uses
-  `generate_error`. Asserts stay for programming errors in test code.
-- **Every step ends green**, with the whole `shade/` suite run and any new console output triaged.
-- **One commit per step**, so a bisect lands on a single item.
-
----
-
-## 5. Status — complete
-
-All nine items landed, one commit each, in the order above.
-
-| Step | Item | Commit | Result |
-|---|---|---|---|
-| 1 | P9 small change bundle | `bf6401105` | encoder label + pass lock + dynamic offsets + resubmit-as-error |
-| 2 | P3 limits | `a10fc2d47` | per-device frozen limits; four wrong defaults corrected |
-| 3 | P7 instanceof | `b68b31c58` | two dead binding-hash branches now live |
-| 4 | P1 buffer mapping | `5278fbb45` | readback works; staging pool pools; 104 → 0 suppressed errors |
-| 5 | P5 format table | `41d64c98e` | depth, packed and compressed formats stop throwing |
-| 6 | P2 validation parity | `fe5113cdc` | found one real renderer bug (see below) |
-| 7 | P4 render pass + copies | `87b4ad3fe` | render passes and texture copies exist at all |
-| 8 | P6 lifetime | `06db0bf52` | idempotent destroy, `device.lost`, leak ledger |
-| 9 | P8 timestamp queries | `d415b378f` | `GPUTimerArray` runs end to end in node |
-
-### What the suite says
-
-`shade/` went from **338 files / 2515 tests** to **348 files / 2653 tests**, all passing, with **zero**
-uncaptured WebGPU errors. The 104 suppressed `Not Implemented` rejections in
-`GPUMeshSkinningContext.spec.js` are gone.
-
-### The one production bug this found
-
-P2's `copyBufferToBuffer` validation caught `GPUGeometryBVHManager` encoding copies out of
-`temp_metadata_buffer` while it was still mapped, unmapping only after the loop — a validation error
-on a real device, where those copies do nothing. The data buffer fifty lines above already writes,
-unmaps, and only then copies; the metadata path now does the same. Fixed in `fe5113cdc`.
-
-### Two things deliberately not done
-
-- **A pre-existing worker-pool flake.** `vitest` intermittently reports "Worker exited unexpectedly"
-  on the full `shade/` run, dropping one file's results. Measured at HEAD *before* any of this work
-  (1 of 3 runs) and after (comparable rate), and no test ever fails when it happens. Out of scope
-  and not introduced here. **Resolved on 2026-08-22**, and it was not a flake: the Dawn devices held
-  at module scope by eight specs kept their workers from terminating. Those specs are gone and the
-  `webgpu` dependency with them, so a full run now reports zero errors.
-- **`GPUDatabase.spec.js`'s skipped `full-fat` test** still cannot run against this device: its
-  upload goes through a compute dispatch, which changes no bytes here. That was established while
-  reviewing the proposal and is recorded in the review's F2. **The test was deleted on 2026-08-22**
-  — a skipped functional test is fixed or deleted, and F2 is the record of why fixing it here was
-  never available.
-
-### What is still true after all nine
-
-A dispatch still changes no bytes, and a draw still writes no pixels. Everything here makes the
-*host* side testable — allocation, lifetime, encoding, validation, upload, readback, pass structure,
-timing plumbing. Shader output remains `ComputeShaderEmulator`'s and Dawn's territory.