@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,458 +0,0 @@
-# `shade/device/mock` — extension proposal, 2026-08-22
-
-Ranked work items for `SoftwareGPUDevice`, derived from
-[`REVIEW_2026_08_22.md`](./REVIEW_2026_08_22.md).
-
-Two ID spaces, kept distinct on purpose: `P1`…`P9` are the proposed items in this document, and
-`A1`, `B2`, `C7`, … are findings in the review.
-
-> **Status: all nine items built.** See [`IMPLEMENTATION_PLAN.md`](./IMPLEMENTATION_PLAN.md) for the
-> order they landed in, the commit for each, and what changed against the estimates here. This
-> document is kept as the record of why each item was chosen and what it was expected to cost.
-
----
-
-## 0. What this proposal optimises for
-
-Three constraints, all of which an item must satisfy:
-
-1. **It has to make the graphics engine testable.** Every item names the production code it unblocks
-   and the test that proves it. An item that only makes the mock more complete is not on this list.
-2. **It has to be low-hanging.** Nothing here needs a WGSL execution engine, a rasterizer, or a new
-   architecture. The largest single item is roughly two hundred lines.
-3. **It has to follow the spec.** Where the spec and convenience disagree, the spec wins — a mock
-   that is convenient and wrong is worse than no mock, because the test that passes against it is
-   evidence of nothing.
-
-A fourth constraint is implicit and worth stating: **it must not require touching Shade's
-architecture.** Every item below is additive inside this folder, with exactly two named exceptions:
-P7 adds two `Symbol.hasInstance` stubs to `shade/vitest.setup.mjs`, and P5 adds a *new* module beside
-`descriptor/texture/format/parse_gpu_texture_format.js` without rewriting it. No existing renderer
-module is restructured by anything here.
-
-### The organising idea
-
-The review's conclusion is that the error-reporting machinery in this folder is complete and correct,
-and almost nothing uses it. `createBuffer`'s `maxBufferSize` check is the only validation the device
-performs, out of dozens the spec requires. Most of what follows is filling in the reports that
-machinery was built to carry.
-
----
-
-## 1. Ranked items
-
-### P1 — Buffer mapping · **highest value**
-
-*Addresses B1, B2, A3. Enables: readback, staging-pool parity.*
-
-Implement the mapping lifecycle on `SoftwareGPUBuffer`:
-
-- `mapAsync(mode, offset = 0, size)` — validates `mode` against `usage` (`GPUMapMode.READ` needs
-  `MAP_READ`, `WRITE` needs `MAP_WRITE`), `offset % 8 === 0`, `size % 4 === 0`, range inside the
-  buffer, `mapState === "unmapped"`, buffer valid and not destroyed. Sets `mapState` to `"pending"`,
-  then `"mapped"`, and resolves. Rejects with an `OperationError` on a validation failure and raises
-  a validation error on the device, which is what the spec does — both, not one.
-- `getMappedRange(offset = 0, size)` — returns a **distinct `ArrayBuffer` of exactly `size` bytes**,
-  a copy of the mapped region. Validates `offset % 8`, `size % 4`, containment inside the mapped
-  range, and non-overlap with a range already handed out. `OperationError` otherwise, including when
-  `mapState !== "mapped"` — which is A3.
-- `unmap()` — copies every outstanding range back into the backing store (this is what makes
-  `mappedAtCreation` and `MAP_WRITE` uploads real), then **detaches** them via
-  `ArrayBuffer.prototype.transfer()`, which is available and behaves correctly on the Node in use
-  (verified on v24). Sets `mapState` to `"unmapped"`.
-
-**Why copies rather than the current alias.** Today `getMappedRange` hands out the storage itself,
-so a range survives `unmap()` and keeps working — the source documents this as deliberate, and it is
-what makes `mappedAtCreation` readback convenient. It also makes use-after-unmap invisible, which is
-a real bug class in pooled-buffer code, and it makes the non-overlap and detach rules unimplementable.
-The copy-and-write-back model is what a driver actually does, costs one memcpy per mapped range in
-tests, and preserves the convenience for the case that motivated the alias: a `mappedAtCreation`
-buffer written and unmapped still reads back correctly through `.data`.
-
-**Blocked-on-this, today:** `inspect_gpu_buffer`, `inspect_gpu_buffer_typed`, `graph_read_buffer`,
-`download_texture_data`, `Uint32BufferSamplingStats`, `GPUTimer`, `GPUTimerArray`, and — the one that
-is actively distorting the suite — `GPUBufferStagingAllocator` recycling, and with it
-`ShadeGPUCommandContext.writeBuffer` / `writeValueBuffer`.
-
-**Acceptance:**
-- A host-side round trip with no shader in it: `queue.writeBuffer` → `copyBufferToBuffer` into a
-  `MAP_READ | COPY_DST` buffer → `mapAsync` → `getMappedRange` returns the bytes. That is
-  `inspect_gpu_buffer`'s `inspect_via_copy` path exactly, so the spec can call the production
-  function rather than reimplement it.
-- Five identical staging requests through `GPUBufferStagingAllocator` allocate **one** buffer, not
-  five, and the pool serves a 64-byte request from a pooled 256-byte buffer — the sub-range case
-  that B2 currently refuses.
-- `GPUMeshSkinningContext.spec.js` produces zero `Not Implemented` lines (currently 104).
-- A range handed out by `getMappedRange` is detached after `unmap()`, and its contents reached the
-  backing store.
-
-**Cost:** ~120 lines plus spec. **Risk:** low, but see §3 — fixing B1 exposes B2, so the two land
-together.
-
----
-
-### P2 — Validation parity on the queue and the encoder
-
-*Addresses A1, A2, A4, A5, A6, A7.*
-
-Give the error machinery something to report. Each rule is a spec bullet and two to four lines:
-
-`queue.writeBuffer` — `COPY_DST` in usage; `bufferOffset % 4`; written size `% 4`;
-`bufferOffset + size <= buffer.size`; source range inside `data`; buffer valid, unmapped, not
-destroyed. **Remove the `Math.min` clamp on the default size** (`SoftwareGPUQueue.js:84`): the spec's
-default is `data.byteLength - dataOffset`, and a value that overruns the destination is a validation
-error, not something to quietly shorten (A1).
-
-`encoder.copyBufferToBuffer` — `COPY_SRC` / `COPY_DST`; all three of offset/offset/size `% 4`; both
-ranges in bounds; `source !== destination`; neither destroyed. Failures invalidate the encoder and
-surface from `finish()`, which is the path the encoder already implements.
-
-`encoder.clearBuffer` — `COPY_DST`; offset and size `% 4`; in bounds.
-
-`device.createBuffer` — `usage !== 0`; `MAP_READ` only with `COPY_DST`, `MAP_WRITE` only with
-`COPY_SRC`, never both; `mappedAtCreation` requires `size % 4`.
-
-`device.createTexture` — dimension against `maxTextureDimension1D/2D/3D`, layers against
-`maxTextureArrayLayers`, `mipLevelCount` against `floor(log2(max(w,h,d))) + 1`, `usage !== 0`,
-`sampleCount ∈ {1, 4}`. Returns an invalid texture on refusal, mirroring `SoftwareGPUBuffer.invalid`.
-
-`GPUBuffer` gains a destroyed-state check that every consumer honours, so A2 stops being possible.
-
-**Why this is safe to land:** a refused operation calls `generate_error`, and an error nobody is
-scoped for goes to `console.error` — it does not fail a vitest run. So the blast radius is console
-noise plus any test that explicitly opens a scope, not a red suite. That is also the argument for
-landing it *after* P1: P1 removes 104 lines of existing console noise, so new noise is legible.
-
-**Acceptance:** a `SoftwareGPUValidationError` for each rule, in a table-driven spec; plus a
-regression test that an over-long `writeBuffer` reports instead of truncating.
-
-**Cost:** ~200 lines, mostly a checklist. **Risk:** medium — see §3.
-
----
-
-### P3 — Per-instance, frozen, overridable limits · **best value-to-cost ratio**
-
-*Addresses A9, A11, and unlocks the clamp paths behind A5.*
-
-```js
-new SoftwareGPUDevice({ limits: { maxTextureDimension2D: 256 } })
-```
-
-- Each device gets its own object; `Object.freeze` it, so an assignment is a no-op the way it is on a
-  real device rather than a mutation everyone else sees (A9).
-- Correct the four stage-scoped storage limits to mirror `maxStorageBuffersPerShaderStage` (8) and
-  `maxStorageTexturesPerShaderStage` (4), and add `maxImmediateSize: 0` (A11).
-- Reject an override that *exceeds* a real adapter's default, since that is what
-  `requestDevice({requiredLimits})` does — a mock that grants a limit no hardware offers is a
-  liability.
-
-**Why it earns its place:** Shade has at least seven sites that clamp an allocation against a texture
-dimension limit — `Renderer.js:1381`, `:1440`, `GPUProbeAtlas.js:112`, `:213`,
-`VirtualShadowMap.js:77`, `GPUSceneShadowmapContext.js:270` against `maxTextureDimension2D`, and
-`GPUGeometrySDFManager.js:71` against `maxTextureDimension3D`. Today the only way to reach the
-clamped branch is to actually request an 8192-pixel texture. With a lowered limit, each becomes a
-three-line test.
-
-**Acceptance:** a spec that lowers `maxTextureDimension2D` and asserts `VirtualShadowMap` clamps its
-resolution; a spec that two devices do not share limits.
-
-**Cost:** ~30 lines. **Risk:** none — additive, with a default that changes only the five values
-named in A11.
-
----
-
-### P4 — Recording render pass encoder, and the missing copy commands
-
-*Addresses C2, C3, C5.*
-
-`SoftwareGPURenderPassEncoder`, modelled directly on the existing compute pass encoder: record, do
-not execute, and say so in the header the way that file already does.
-
-The surface is small because Shade is a vertex-pulling meshlet renderer. Counting calls made directly
-on a pass across all of `shade/`: `draw` (17), `setViewport` (4), `drawIndirect` (3),
-`setVertexBuffer` (1, and that one is in a `prototype*.js` file), plus `setPipeline`, `setBindGroup`,
-`end` and the debug markers. **No index buffers, no render bundles, no occlusion queries.**
-
-The leverage is better than those counts suggest: `ImageShader.draw()` funnels through
-`constructRenderPass` → `setViewport` → `draw(3)` → `end` (`renderer/shader/ImageShader.js:178-208`),
-and roughly two dozen further call sites go through *it*. One recording pass encoder therefore
-unblocks every full-screen pass in the renderer.
-
-Record `draws` the way the compute encoder records `dispatches`, and retain the descriptor's
-`colorAttachments` / `depthStencilAttachment` so a test can assert what a pass was pointed at — which
-is the actual question the frame graph raises.
-
-Alongside it, the three copy commands that execute against the texture storage that already exists:
-`copyTextureToTexture`, `copyBufferToTexture`, `copyTextureToBuffer`. These are row loops over
-`get_mip_data`, structurally identical to `queue.writeTexture`.
-
-**Unblocks:** any test of `ShadeGPUCommandContext.beginRenderPass` / `constructRenderPass`, the frame
-graph's pass wiring, attachment load/store configuration, and — with P1 — `download_texture_data`
-end to end.
-
-**Acceptance:** a spec that builds a two-pass frame through `ShadeGPUCommandContext` and asserts the
-passes, their order, and their attachments; a spec that round-trips texels through
-`writeTexture → copyTextureToBuffer → mapAsync`.
-
-**Cost:** ~150 lines for the pass encoder, ~80 for the copies. **Risk:** low; nothing existing calls
-these, so there is no behaviour to regress. Bounded by P5 below for depth formats.
-
----
-
-### P5 — Texture format block table
-
-*Addresses the review's E1 (inherited).*
-
-A `gpu_texture_format_info(format) -> {blockWidth, blockHeight, bytesPerBlock, aspects}` table
-covering the spec's format list, as a **new module** in `descriptor/texture/format/` beside
-`parse_gpu_texture_format.js` rather than a rewrite of it. `SoftwareGPUTexture.bytes_per_texel` (and
-its block-aware successor) reads the table.
-
-`parse_gpu_texture_format`'s regular expression cannot express depth, stencil, packed or
-block-compressed formats — `depth24plus`, `stencil8`, `bc7-rgba-unorm` fail to parse and
-`rgb10a2unorm`, `rg11b10ufloat` parse into nonsense and throw. A table is the right shape for this
-data and a regex is not; and leaving the existing function alone keeps the change additive, which is
-how Shade prefers changes.
-
-**Unblocks:** every texture test involving a shadow map, the Hi-Z chain, the G-buffer, or any
-compressed asset — currently all of them throw at first write.
-
-**Acceptance:** a table-driven spec over the full format list asserting the block descriptor, checked
-against Dawn where Dawn exposes it.
-
-**Cost:** mechanical, ~90 rows plus ~40 lines. **Risk:** low, additive. The tedium is the cost.
-
----
-
-### P6 — Resource lifetime, spec-shaped
-
-*Addresses B3, B4, A2's other half.*
-
-- `destroy()` becomes idempotent on `SoftwareGPUBuffer` and `SoftwareGPUTexture` — the source's own
-  `// TODO should this fail silently instead?` answered in the spec's favour (B3).
-- `device.destroy()` implemented: idempotent, releases every resource the device handed out, resolves
-  `device.lost` with reason `"destroyed"`, and makes subsequent work a validation error rather than
-  an exception (B4, C7).
-- The device keeps a ledger of live resources so a test can assert **end state**: *"after this pass
-  tore down, the device is holding nothing."*
-
-On that last point: the ledger is deliberately an end-state assertion and not a call counter.
-`GPUBufferAllocator.spec.js` currently monkey-patches `createBuffer` and `buffer.destroy` to count
-calls, which is the kind of white-box assertion the house style rejects; a leak check asks an
-observable question about the device instead.
-
-**Acceptance:** double-destroy is a no-op; a spec that a `ShadeGPUCommandContext` releases every
-transient buffer it took.
-
-**Cost:** ~80 lines. **Risk:** low.
-
----
-
-### P7 — `instanceof` recognition for views and samplers
-
-*Addresses D1.*
-
-Two changes:
-
-1. `createSampler` returns a `SoftwareGPUSampler` **class** instance rather than an object literal
-   (it is the only resource here that is not a class, and `a.constructor` equality in
-   `BindGroupDescriptor` therefore sees `Object`).
-2. `vitest.setup.mjs` gives `GPUTextureView` and `GPUSampler` the same `Symbol.hasInstance` treatment
-   `GPUBuffer` already has, recognising `isSoftwareGPUTextureView` / `isSoftwareGPUSampler`.
-
-Today both `instanceof` tests are false under the mock, so
-`BindGroupDescriptor.compute_binding_resource_hash` returns **0 for every texture-view and sampler
-binding** and its two dedicated branches are dead code in node. `BindGroupManager.spec.js` binds only
-buffers, so nothing covers them. The same two globals also gate
-`encoder_prepare_shader_binding.js:55`/`:66` and `ShaderResourceGroupDescriptor.js:132`.
-
-**Acceptance:** a spec that two bind groups differing only in bound texture view hash differently,
-and that a texture-view binding survives `encoder_prepare_shader_binding`.
-
-**Cost:** ~20 lines across two files. **Risk:** bind-group hash values change under the mock. Since
-no current test binds a view or a sampler, the measured blast radius is zero — but this is the one
-item that changes the behaviour of code paths outside this folder, so it lands on its own commit.
-
----
-
-### P8 — Timestamp queries
-
-*Addresses C1, C4.*
-
-`createQuerySet`, `resolveQuerySet`, and acceptance of `timestampWrites` on pass descriptors — plus
-an opt-in `new SoftwareGPUDevice({ features: ['timestamp-query'] })` so `device.features.has(...)`
-answers truthfully for a device that has it. (`ShadeGPUCommandContext` already gates its timer
-plumbing on exactly that call, at `:344` and `:483`.)
-
-`resolveQuerySet` writes a deterministic, monotonically increasing `BigInt64` counter into the
-destination buffer, and the source **says in its header, unmissably, that these are not
-measurements.** The precedent is `dispatchWorkgroupsIndirect` recording `[-1, -1, -1]` rather than
-inventing a workgroup count: state the fiction rather than dress it up.
-
-What this actually tests is not timing but the plumbing that breaks: query-set sizing, resolve
-ranges, buffer offsets, the `BigInt64Array` decode in `GPUTimer` / `GPUTimerArray`, and pairing of
-begin/end writes. Combined with P1 the whole timing readback path runs in node.
-
-**Acceptance:** `GPUTimerArray` resolves N pairs and decodes N durations; a spec that a mismatched
-resolve range is a validation error.
-
-**Cost:** ~100 lines. **Risk:** low. Weighed against P4/P5 it is worth less, hence the position.
-
----
-
-### P9 — The small change bundle
-
-*Addresses C6, C8, C9, A8, A10, B5, B6/B7.*
-
-Individually trivial, collectively the difference between a mock you can lean on and one you
-constantly work around:
-
-| Change | Finding |
-|---|---|
-| `createCommandEncoder(descriptor)` honours its descriptor; `SoftwareGPUCommandEncoder` extends `SoftwareGPUObjectBase` so it has a `label` | C8 |
-| `queue.onSubmittedWorkDone()` → a resolved promise (submission is synchronous here) | C6 |
-| `setBindGroup` records dynamic offsets, both overloads | C9 |
-| The encoder locks while a pass is open; a second `beginComputePass` or an encoder command before `end()` is a validation error | A8 |
-| `features` reports `core-features-and-limits`, which every core device has | A10 |
-| Re-submitting a command buffer is a validation error rather than `throw new Error('execute() called twice')` | B5 |
-| One header comment stating the folder's policy for illegal input, and naming its deliberate exceptions | B6, B7 |
-
-That last row is the one that matters beyond its size. The folder currently runs three policies —
-*report through the error scope* (A6, B5), *throw on a caller bug* (encode-after-finish), *throw for
-an unimplemented feature* (`copyExternalImageToTexture`) — and none is written down. Any of the three
-is defensible; not choosing is not.
-
-**Cost:** ~90 lines total. **Risk:** the encoder lock could surface existing pass-scoping violations
-in Shade. That is the point, and it is a validation error, not a thrown exception, so it will appear
-as console output rather than a red suite.
-
----
-
-## 2. Considered and not proposed
-
-| | Why not |
-|---|---|
-| WGSL execution / a software rasterizer | The mock's value is that it is *not* one. Shader execution is `ComputeShaderEmulator`'s job and real execution is Dawn's; a third half-implementation would be the least trustworthy of the three. The compute pass encoder's header already makes this argument and it is correct. |
-| WebGPU CTS conformance | Wrong target. The engine needs the ~15% of the API it uses to be right, not the whole surface to be 60% right. |
-| `SoftwareGPUAdapter` / `navigator.gpu` (C10) | Only `ShadeDeviceFailure` cares about acquisition, and `ShadeDeviceFailure.spec.js` already covers the failure objects directly. Revisit if acquisition grows logic. |
-| Render bundles, occlusion queries, external textures, canvas context | Zero call sites in Shade. |
-| Multi-layer / 3D `writeTexture` (review E2) | Genuinely useful for the LPG volume and the SDF atlas, but it is a real generalisation of the addressing rather than a checklist, and it should follow P5 — there is no point generalising layers while depth formats still throw. |
-| Making `assert.*`-based refusals throw in production builds | The mock is test-only, so the stripped assertions cost nothing today. Worth one line in the policy comment from P9 rather than a code change. |
-| Fixing `probe_instance_animation.js`'s stale header (F1) | A one-line doc fix outside this folder; noted so it is not lost, not tracked here. |
-
----
-
-## 3. Sequencing, and the risks that drive it
-
-```
-P3 ─┐
-P7 ─┼─► (independent, land first: additive, near-zero risk)
-P9 ─┘
-       P1 ──► P2 ──► P6
-        │
-        └───► P5 ──► P4 ──► P8
-```
-
-**Phase 1 — P3, P7, P9.** Additive, no behaviour to regress, and P9's policy comment sets the rule
-every later item follows. P7 lands on its own commit because it is the only item that changes the
-behaviour of code outside this folder.
-
-**Phase 2 — P1.** The single biggest unlock, and it retires 104 lines of existing console noise,
-which is a precondition for reading the noise P2 creates.
-
-**Phase 3 — P2.** After P1, because of the coupling below.
-
-**Phase 4 — P5, then P4.** Formats before texture commands; there is no point implementing
-`copyTextureToBuffer` while `bytes_per_texel` throws for depth.
-
-**Phase 5 — P6, P8.**
-
-### Risks worth naming before starting
-
-**P1 and P2 are coupled through a masking bug.** B2 (`getMappedRange` refuses sub-ranges) is
-invisible today only because B1 (`mapAsync` throws) stops `GPUBufferStagingAllocator` from ever
-recycling an oversized buffer. Implement `mapAsync` alone and the pool starts working, immediately
-hands back a buffer larger than requested, and `ShadeGPUCommandContext.writeBuffer` throws
-`Size not supported` on the next frame. **The two halves of P1 must land in one commit**, and the
-staging-pool spec is the test that proves it.
-
-**P2 will surface latent violations in Shade.** That is the purpose, but it is also a scope risk: an
-unknown number of existing call sites may be doing something the spec forbids. Two mitigations. First,
-the failure mode is a `console.error` from an unscoped validation error, not a test failure, so the
-suite does not go red on landing. Second, land the rules one entry point at a time —
-`writeBuffer` first, since A1 is the highest-consequence finding — and read the output before adding
-the next.
-
-**P7 changes hash values.** Only under the mock, and only for bindings no current test creates.
-Own commit, so a bisect lands cleanly on it if this is wrong.
-
-**Nothing here helps with what a shader computes.** Worth restating because it bounds every claim in
-this document: after all nine items, a dispatch still changes no bytes. These extensions make the
-*host* side of the renderer testable — allocation, lifetime, encoding, validation, upload, readback,
-pass structure. Shader output remains `ComputeShaderEmulator`'s and Dawn's territory, and a test that
-asserts on it against this device is meaningless regardless of how much of this proposal is built.
-
----
-
-## 4. Adversarial review of this document
-
-Challenges raised against the draft, and what they changed.
-
-**"P1 is described as low-hanging but it changes the memory model of every mapped buffer."** Fair, and
-the item now argues the change rather than asserting it. The current alias-the-storage design is
-*documented as deliberate* in the source, so replacing it needs a reason: it makes use-after-unmap
-invisible and makes the spec's non-overlap and detach rules unimplementable. The convenience it was
-protecting (`mappedAtCreation` readback through `.data`) is preserved by the write-back. P1 is the
-largest item here and the ordering reflects that; "low-hanging" is claimed for the proposal as a
-whole against the alternative of a real emulator, not for P1 individually.
-
-**"P2 will break the suite and you have not measured how badly."** Correct — that is unmeasured and
-the document now says so plainly instead of implying safety. Two things were added: the mechanical
-reason a validation error cannot fail vitest (unscoped errors reach `console.error`, not the
-reporter), and a per-entry-point rollout so the unknown is discovered incrementally. The honest
-statement is that the size of the latent-violation set is unknown until `writeBuffer` validation
-lands.
-
-**"P8 fabricates timing data — the review's own standard rejects that."** The strongest objection
-raised. The item was rewritten to be explicit that the numbers are fiction, to require the header to
-say so, and to relocate the claimed value: what P8 tests is the *plumbing* (query-set sizing, resolve
-offsets, `BigInt64Array` decode, begin/end pairing), which is real and is what actually breaks. It
-was also moved down the ranking. If the fiction is still unacceptable, dropping P8 costs the least of
-any item here.
-
-**"P1's acceptance criterion — un-skipping `GPUDatabase.spec.js`'s `full-fat` test — assumes that
-test only needs mapping."** It does not, and the criterion was wrong. `GPUDatabase.update` uploads
-through a compute dispatch (`GPUDatabase.js:570`), which changes no bytes under this device, so no
-extension short of shader execution runs that test. It was replaced with three criteria that contain
-no shader at all — a host-side `writeBuffer → copy → mapAsync → getMappedRange` round trip through
-`inspect_via_copy`, the staging-pool allocation count, and detach-on-unmap. This is a good
-illustration of the trap the whole proposal has to avoid: *"the mock nearly runs this test"* is easy
-to believe and needs checking against what the code path actually does.
-
-**"The P1↔B2 coupling is asserted, not demonstrated."** Half true. That `getMappedRange` refuses
-`(0, 32)` on a 64-byte buffer is verified; that `GPUBufferStagingAllocator.get` returns a buffer with
-`size >= min_size_bytes` is read from its source and its own assertion; that
-`ShadeGPUCommandContext.writeBuffer` then calls `getMappedRange(0, size)` is read from `:660`. The
-conjunction is inference from three verified facts, not an observed failure — because the failure
-cannot be observed until `mapAsync` exists. That is precisely why it is called out as a sequencing
-risk with a named test rather than left to be discovered.
-
-**"Why is P3 not first if it is the best ratio?"** It is in Phase 1. The list is ranked by value, the
-diagram by dependency, and the two orderings differ; the document now states which is which rather
-than leaving a reader to reconcile them.
-
-**"P5 is 90 rows of table — that is not low-hanging."** It is mechanical rather than small, which is
-a different thing, and the item now says so. It stays because P4 is worth much less without it: today
-every depth, packed and block-compressed format throws at first write, which covers the shadow maps,
-the Hi-Z chain and the G-buffer.
-
-**"P9 bundles seven unrelated changes to look cheap."** True of the first six rows, which are genuinely
-independent one-liners and are listed as a table so they can be split. The seventh — the policy
-comment — is not filler: three contradictory conventions for illegal input currently coexist in this
-folder, and every later item has to pick one. It arguably deserves to be its own item ahead of
-everything else.
-
-**"'Zero call sites in Shade' is a weak reason to exclude render bundles."** Accepted as a limit on
-the argument. The exclusions in §2 are scoped to *this engine's current usage*, which is the stated
-optimisation target, and would need revisiting if the renderer's shape changes. The table says
-"Zero call sites in Shade" rather than "not useful" for that reason.