@woosh/meep-engine 3.14.6 → 3.16.0

package/src/engine/graphics/render/frame_graph/CORRECTNESS_FIXES_2026_09_04.md

@@ -0,0 +1,659 @@
+# FrameGraph — correctness and invariant fixes, 2026-09-04
+
+Working ledger for the confirmed **correctness** and **invariant** findings of the FrameGraph audit
+of 2026-09-04. The allocation and performance findings from the same audit are **out of scope here**
+— they have their own plan and their own numbers.
+
+Companion to `FRAME_GRAPH_RECOMMENDATIONS.md`, which records the earlier round; nothing marked DONE
+or WITHDRAWN there is re-litigated below.
+
+**Why these matter more than the assert count suggests.** meep ships raw source and the consuming
+project strips assertions (`README.md:249`, "Shipping a build" — `@rollup/plugin-strip`'s defaults
+already cover `assert.*`). So in a shipped game `validate()` never runs, `FramePassResources.get()`'s
+declaration check never runs, and every defect below is **silent**. That is the reason to fix them
+rather than leave them to the asserts.
+
+**The constraint that shapes every fix here.** The strip matcher is
+`^(?:console\.\w+|assert\.\w+)$` and it deletes the whole `ExpressionStatement`, arguments included.
+A check moved out of `assert.*` into a differently-named helper or an inline `if (…) throw` stops
+being stripped and becomes permanent production cost. So: new checks go in as `assert.*` calls, or
+as plain `if`-throws only where the check must survive stripping and the cost is deliberate.
+
+---
+
+## Every finding, and where it went
+
+The audit's 28 correctness/invariant findings, against the sections below. Two of the audit's own IDs
+collapse into one section where they are the same defect seen from two ends.
+
+| audit finding | § | status |
+| --- | --- | --- |
+| `lifetime-ignores-side-effect-passes` (+ its 3 duplicates) | 2 | DONE |
+| `resource-entry-destroy-never-nulls` | 3 | DONE |
+| `execute-leaks-transients-when-a-pass-throws` | 4 | DONE |
+| `void-context-cannot-hold-two-transients` | 1 | DONE |
+| `bare-assert-ships-to-production` | 7 | DONE |
+| `sky-lut-superseded-read` | 18 | DONE (module not wired) |
+| `probe-atlas-drops-versioned-handles` | 19 | DONE |
+| `paint-border-depth-returns-void` | 19 | DONE |
+| `rasterize-handles-dropped-at-call-site` | 22 | DONE |
+| `gbuffer-albedo-superseded-not-republished` | 23 | DONE |
+| `import-aliasing-defeats-validate` | 15 | DONE, as detection |
+| `unparented-transient-never-allocated` | 5 | DONE |
+| `resources-get-checks-declaration-not-allocation` | 6 | DONE |
+| `validate-runs-as-an-assert-argument` | 13 | **WITHDRAWN** |
+| `signal-swallow-defeats-one-shot-guards` | 14 | DOCUMENTED |
+| `resource-manager-identity-keyed` | 1 | DONE |
+| `pool-drops-resource-on-perkey-overflow` | 9 | DONE |
+| `texture-equals-missing-type-check` | 8 | DONE |
+| `graph-read-buffer-defaults-to-pooled-size` | 16 | DONE |
+| `atlas-to-sh-undeclared-read` | 19 | DONE |
+| `side-door-resource-access` | 20 | DONE at the named site |
+| `profiler-recorder-leaked-on-pass-throw` | 21 | DONE, unpinned |
+| `dot-html-label-unescaped-names` | 10 | DONE |
+| `dot-tooltip-wrong-escaper` | 10 | DONE |
+| `dot-fill-colours-are-linear-light` | 10 | DONE |
+| `double-write-same-handle-mints-orphan-version` | 11 | DONE |
+| `frame-context-describe-skips-open-guard` | 12 | DONE |
+| `debug-reprojection-spurious-read` | 17 | DONE (module dead) |
+| `shadow-atlas-imported-per-cascade-job` | 24 | **DEFERRED** |
+
+One withdrawn, one deferred, three fixed without a test that can pin them — each says why in its own
+section rather than here.
+
+---
+
+## 1. The void backend cannot hold two live transients — **DONE**
+
+`VoidRenderContext.createResource` returned `null` for every descriptor while
+`RenderResourceManager` keys its live-descriptor table by resource *identity*
+(`RenderResourceManager.js:50`), so the second concurrently-live transient in any graph collided
+with the first and threw `Resource is already associated with a live descriptor` from the allocation
+preamble at `FrameGraph.js:624` — before any pass callback, so the error was not even decorated with
+a pass name.
+
+That is why `FrameGraph.spec.js` hand-rolls its own `DummyRenderer` for every test that allocates and
+uses `VoidRenderContext.INSTANCE` only for the empty graph: the shipped device-free backend could not
+execute the one graph shape a resource-lifetime test needs. It is the cause of which "no spec pins
+lifetimes" is the symptom, so it had to land first.
+
+Fixed by handing back a distinct token per call — `{ void_resource: <n> }` from a per-context
+counter. `INSTANCE` is kept: with distinct tokens there is no poisoned entry to survive into a later
+test, and two specs already import it.
+
+`RenderResourceManager.get` now rejects a `null`/`undefined` from `createResource` explicitly, naming
+the backend class and the descriptor, so a backend that forgets fails at the point of the mistake
+rather than on the next allocation with a message about corruption. This is deliberately a plain
+`if`-throw and not an `assert.*`: it guards the manager's own identity-keyed invariant against a
+third-party backend, and it must survive stripping.
+
+Also covers the `resource-manager-identity-keyed` finding, which named the same pair of files.
+Re-keying the live table by descriptor rather than by identity was **not** done: identity keying is
+what makes the double-release guard possible, and with the backend fixed there is no live case that
+needs it.
+
+Pinned by `backend/void/VoidRenderContext.spec.js` — three tests, all red before the change: a
+two-transient graph executing against a fresh context, distinct tokens per call, and the named-backend
+failure message.
+
+Commit: `9a9483bcb`
+
+## 2. `compile()` and `execute()` disagreed about which passes exist — **DONE**
+
+The headline defect, raised independently by four reviewers. `compile()`'s lifetime loop skipped any
+pass with `ref_count === 0` (`FrameGraph.js:576`); `execute()` ran a pass whenever `can_execute()`
+said so (`ref_count > 0 || has_side_effects`, `FramePassNode.js:116`). A pass that only reads and
+calls `make_side_effect()` — the shape of *every* readback helper in the tree — therefore never
+became any resource's `entry.last`, so the transients it reads went back to the pool after an
+earlier pass. The pool re-issues within the frame, matching on approximate size and a usage
+superset, so a later pass could be handed the same buffer and write into it before the reader
+encoded.
+
+Live on the readback path: `graph_read_buffer.js:110-113` and `graph_inspect_gpu_buffer.js:130-134`
+are both `read` + `make_side_effect` with no write.
+
+Fixed as **one shared survivor predicate**, not the one-word change the audit suggested.
+`compile()` now builds `#surviving_passes` from `can_execute()` and computes lifetimes over exactly
+that array; `execute()` iterates the same array and no longer asks the question a second time. The
+two cannot drift apart again because there is only one answer.
+
+Pinned by `FrameGraph.lifetimes.spec.js` — "a side-effect pass that only reads keeps the transient
+it reads alive" (asserts both `entry.last` and that a later same-shape allocation does *not* get
+handed the producer's resource), and "compile() and execute() agree on which passes run".
+
+Commit: `3983273c9`
+
+## 3. `ResourceEntry.destroy()` never cleared the handle — **DONE**
+
+`destroy()` called `resources.release(this.resource)` and left the field pointing at a resource the
+pool had taken back, so any sweep filtered on `resource !== null` — which is the obvious filter for
+item 4 below — would release each already-released entry a second time. The pool hands the same
+object straight back out, so by then the stale handle may belong to a live entry, and
+`TransientResourcePool.release` checks `bound.has(resource)`, which is **true** for the new owner.
+The sweep would pool a resource still in use, silently, with no assert left in a shipped build to
+notice.
+
+`destroy()` now nulls the field, and `create()` asserts the entry is empty before allocating.
+
+Landed in the same commit as item 2, as it had to be: on its own, nulling the field turns a
+stale-but-live handle into a null dereference inside a pass.
+
+Note on the production path: the manager the renderer actually uses is
+`shade/renderer/ResourceManager.js` (`GraphicsExecutionContext.js:30` overwrites the base), **not**
+`frame_graph/resource/RenderResourceManager.js`. Its `release` returns false silently for an
+unbound resource, so the real hazard here is aliasing, not a thrown error.
+
+Pinned by "a transient holds no resource handle once the graph has released it".
+
+Commit: `3983273c9`
+
+## 4. `execute()` leaked every live transient when a pass threw — **DONE**
+
+No cleanup path at all: the failure was decorated and rethrown, so the per-pass release scan never
+ran for the failing pass or any pass after it. A render loop that catches and carries on — the usual
+shape — leaks a full set of the graph's transients per failing frame.
+
+`execute()`'s pass loop is now wrapped, and on the way out `#release_live_transients` walks the
+registry once, releasing every `isTransient() && resource !== null` entry before re-raising.
+
+Two placement decisions, both deliberate:
+
+- The sweep is in a `catch` around the whole loop, **not** in a `finally` around the pass body. That
+  inner `finally` belongs to the `onPassBegin`/`onPassEnd` bracket and runs once per pass; a release
+  scan there would run on the success path too.
+- `onExecuted` stays success-only, and now says so on the field. It means "the frame's work is
+  recorded", which a failed frame has not done. It has no subscribers anywhere in the tree, so the
+  contract was still free to choose.
+
+Pinned by "a pass that throws does not leak the transients allocated before it" (asserts the pool
+re-issues both objects afterwards) and "the leak sweep does not release a transient twice", which is
+the regression guard for item 3.
+
+Commit: `b0ee342de`
+
+## 5. A transient created outside a pass was allocated by nobody — **DONE**
+
+`FrameGraph.create_resource()` is public, and a transient created through it rather than through
+`FramePassBuilder.create` appears in no pass's `resource_creates`, so nothing allocated it: the pass
+was handed `null`, and — once item 2 made lifetimes cover the passes that actually run — the release
+scan then tried to hand `null` back to the pool.
+
+Item 2 is what surfaced it. Before that fix the shape was masked by the very defect being fixed: the
+side-effect reader had `ref_count === 0`, so `entry.last` was never set and the release scan never
+reached the entry. `RenderExtensionRegistry.spec.js:448` went red the moment lifetimes were correct,
+which is why this had to land in the same commit rather than after it.
+
+Fixed by allocating such an entry at its **first surviving user**. `compile()` fills a new
+`FramePassNode.resource_allocates` — the pass's own creates, plus any unparented transient it is the
+first survivor to touch — and `execute()` allocates from that list instead of from `resource_creates`.
+The entry then has the same lifetime any other transient has.
+
+Refusing the shape instead was rejected: `validate()` already blesses reading a transient no pass
+writes ("the reader is then the pass about to fill it"), the extension surface hands the graph out
+through `FrameContext.graph`, and three specs already record this way.
+
+`ResourceEntry.producer` changes meaning from "pass that created this" to "surviving pass that
+allocates this", which is the definition the audit's own note asked for and is documented on the
+field. It was previously a dead write.
+
+Pinned by "a transient created on the graph rather than by a pass is allocated by its first user",
+which also asserts it is allocated exactly once and released at the end.
+
+Commit: `3983273c9`
+
+## 6. `FramePassResources.get()` checked declaration, never allocation — **DONE**
+
+`get()` asserted the pass had declared a read/write/create of the handle, and never that anything
+had put a resource behind it, so a pass could be handed `null` and the failure would surface later
+inside a bind-group build, naming the consumer rather than the missing producer.
+
+`get()` now also asserts `entry.resource` is non-null, naming the resource and the pass. Kept as an
+`assert.*` so it strips: with item 5 landed there is no reachable way to hit it, and it is a
+development-time diagnostic rather than a production guard.
+
+The audit's second half — build a per-pass `Map<id, ResourceEntry>` in `compile()` and replace the
+three `includes()` scans — is an **allocation/performance** change and belongs to that plan, not
+here.
+
+Commit: `3983273c9`
+
+## 7. Seventeen bare `assert(` calls shipped past the strip — **DONE**
+
+`assert.ok === assert` (`assert.js`), so `assert(cond, msg)` is a legal spelling that behaves
+identically in development. Its callee is an **Identifier** rather than a MemberExpression, so
+`@rollup/plugin-strip`'s default matcher `^(?:console\.\w+|assert\.\w+)$` never matched it and every
+one of them survived into a shipped build.
+
+The worst was `gpu_vertex_buffer_layout_from_spec.js:45` —
+`assert(layout.validate(console.error), 'layout invalid')`, which is `FrameGraph.js:505`'s exact
+shape on the wrong side of the matcher: a whole validator running on every vertex-buffer layout
+build in a shipped game, and still able to throw there.
+
+Seventeen one-character edits, `assert(` → `assert.ok(`, across `geometry_stripify.js` (6), the
+MikkT files (8), `StateNode.js`, `GPUTypedTable.js` and the layout builder. The census matched the
+audit's exactly.
+
+**The rule inverts inside `assert.js` itself**, and that half landed too. Its own
+`assert.isNumber` / `assert.defined` / `assert.ok` calls are the implementation, not a development
+check, so stripping them leaves a module that still exports functions which no longer check
+anything — silently, in any bundle that retains it. Nineteen internal calls now go through the
+helpers' local names, which is what the top half of the file already did (`notEqual` calls `assert`,
+not `assert.ok`); `isNumber`, `isString`, `isInteger` and `defined` were converted from anonymous
+property assignments to named declarations so the rest could reach them.
+
+Pinned by `core/assert_strip_contract.spec.js`, in the house style of `teardown_contract.spec.js`:
+an acorn parse rather than a text match, because a bare `assert(` in a comment is not a call and a
+file with its own local `assert` (`meshopt_clusterizer.js`, 37 of them) is not calling this one. Two
+tests — no file importing `core/assert.js` calls it as a bare identifier, and `assert.js` contains no
+`assert.*` call of its own.
+
+Commit: `3ddc6745e`
+
+## 8. A cross-type hash collision crashed the descriptor pool — **DONE**
+
+`RenderResourceManager` holds textures and buffers in **one** `ImmutableObjectPool`, so the two
+descriptor types share a hash table and a probe of one can land in a bucket holding the other.
+`shade/device/graph/TextureResourceDescriptor.equals` never called `super.equals`, and its first act
+was `isArrayEqualStrict(this.resolution, other.resolution)` — so a texture stored and then probed
+with a buffer dereferenced `other.resolution.length` on undefined and threw a `TypeError` out of the
+lookup instead of missing the cache. `BufferResourceDescriptor.equals` already got this right, so
+only one direction was unsafe.
+
+`equals` now starts with the identity shortcut and `super.equals(other)`.
+
+`BufferResourceDescriptor.hash` made that collision far likelier than it had to be: `size ^ usage` is
+symmetric, so `(x, y)` and `(y, x)` land on one value, and it omitted `ensure_cleared` entirely
+although `equals` compares it — two descriptors that are *not* equal sharing every bucket. Replaced
+with `combine_hash(size, usage, ensure_cleared[0], ensure_cleared[1])`.
+
+Pinned by `shade/device/graph/resource_descriptor_equality.spec.js`, four tests, all red before: the
+cross-type comparison in both directions, a real collision driven through an `ImmutableObjectPool`,
+the clear-range hash, and the size/usage swap.
+
+Verified against the suites outside `frame_graph` that read these classes:
+`graph_radix_sort.spec.js`, `graph_bvh_build_lbvh.spec.js`,
+`graph_rasterize_meshes_transparent_avboit.spec.js` and `sgpt_topology.spec.js`.
+
+Commit: `19356c711`
+
+## 9. `release()` dropped a resource the pool would not keep — **DONE**
+
+`RenderResourceManager.release` removed the resource from the live-descriptor table and then ignored
+the return of `ImmutableObjectPool.add`. `add` returns false **without firing `onRemoved`** when the
+per-key bucket is full — unlike the global-capacity eviction path, which routes through `onRemoved`
+to `destroyResource`. So the resource was neither pooled, nor destroyed, nor tracked. Leaked, and
+leaked exactly under the pressure where leaking hurts: more same-shape transients alive at once than
+the bucket holds, every frame.
+
+`release` now destroys what the pool refuses. Of the two remedies the audit offered, this is the one
+that keeps responsibilities straight: the pool's answer is "not mine", and deciding a GPU resource's
+fate belongs to its owner.
+
+Pinned by `resource/RenderResourceManager.spec.js` — over-subscribe one descriptor, release
+everything, and assert that every resource is either handed back out again or destroyed. Red before
+with 22 of 32 unaccounted for. The spec deliberately does not name the pool's capacity.
+
+Commit: `614bc3a84`
+
+## 10. The DOT export escaped for the wrong syntax, three ways — **DONE**
+
+Three low-severity findings, one commit, because they are the same mistake: `exportToDot` writes
+**HTML-like** labels (`label=<...>`) and treated them as quoted strings.
+
+- **Names went in raw.** `graph.add("shadow & vsm")` makes graphviz refuse the *whole file*, not
+  just that node — so the debugging tool fails exactly when someone names a pass descriptively.
+- **The one escaper present was the wrong one.** `graphviz_escape_string` was applied to the
+  descriptor `type` sitting inches away in the same template: a record-label escaper whose
+  backslashes are not processed inside markup at all, and which leaves `&`, `<` and `>` alone.
+- **Every tooltip was mangled.** `tooltip` is a plain quoted attribute where `{`, `}` and `|` are
+  ordinary characters, so the size/format/usage line — the reason to hover — rendered its
+  backslashes literally in 100% of dumps.
+
+Added `graphviz_escape_html_label` (`&`, `<`, `>`) and `graphviz_escape_quoted` (`\`, `"`, newline)
+beside the existing record-label escaper, each with its own spec, and pointed each call site at the
+one for the syntax it writes. `graphviz_escape_string` is unchanged: it *is* the record-label
+escaper, and `convert_graph_to_dot_string.js` still uses it.
+
+**Fill colours** were the third: `okhsv_to_linear_srgb` quantized straight to bytes into a field
+GraphViz reads as gamma-encoded sRGB. Read back the way GraphViz reads it, an imported resource's
+saturation measured **0.46** against the **0.2** the code chose — so the deliberately quiet
+imported-vs-transient distinction read as a large colour difference. The transfer function is now
+applied before quantizing.
+
+Pinned by `FrameGraph.dot.spec.js`, four tests, all red before. The colour one asserts through the
+inverse — decode the emitted hex as sRGB, convert back to OkHSV, and check the saturation is the one
+the code asked for — rather than re-implementing the forward path.
+
+The audit also flagged `csm_debug_draw_preview.js:111,138` as the same bug. **Not a defect there**:
+that output goes into a `Color` handed to the engine's own debug draw, which works in linear light.
+The DOT case is different only because GraphViz reads its input as sRGB.
+
+Commit: `020269b17`
+
+## 11. A double write minted an orphan version — **DONE**
+
+`FramePassBuilder.write` branched on `node.creates(resource)` rather than on whether this pass had
+already produced a version of that entry, so a second `write()` of the same original handle — or of
+the handle the first write just handed back — took the clone path again. The first clone is a node
+nobody can read (the caller only kept the last) and `resource_writes` is one longer than the pass's
+logical writes.
+
+Nothing reported it. The orphan is unreferenced by construction, so the cull loop reaches it and
+cancels the extra reference count, and `validate()` sees a well-formed graph.
+
+`write()` now returns the version this pass already produced for that entry, checked by resource ID
+across `resource_writes`. That subsumes the `creates` branch — a created resource is already in
+`resource_writes` — so the two cases became one. Skipping the second implicit `read()` is part of the
+fix rather than a side effect: the pass is not reading two versions.
+
+Idempotent rather than asserting, of the audit's two options: no recorded caller intends a second
+write, and returning the version they already have is what they meant.
+
+Pinned by `FramePassBuilder.spec.js`, four tests: the double write, re-writing the returned handle,
+a created resource written again, and — the guard against over-correcting — two *different* passes
+writing one resource still producing a version each.
+
+Commit: `2ba63294b`
+
+## 12. `FrameContext.describe()` skipped the open guard — **DONE**
+
+`FrameRecord.read` and `publish` both assert `frame.is_open`, and `FrameContext.is_open` documents
+why. `describe(handle)` took a raw handle rather than going through a record, which was the one way
+around the check — and it answers from a graph that may already have executed and released its
+transients. An extension calling it from an async continuation got a descriptor from last frame:
+plausible, wrong, and silent.
+
+Now asserts the same thing, in the same words.
+
+Pinned in `FrameContext.spec.js`.
+
+Commit: `2ba63294b`
+
+## 13. `validate()` runs as an `assert.ok` argument — **DOCUMENTED, deliberate**
+
+The audit read this as a hazard: either the gate always runs, or it silently disappears. The second
+is the intent, and it is load-bearing.
+
+`@rollup/plugin-strip` deletes a matched call *together with its arguments*, so under the strip the
+consuming project applies, the whole gate — the O(passes × reads) walk, the two
+`Int32Array(registry.length)` allocations, and the retained `console.error` — leaves the build. That
+is what makes a development-only check over five-plus graphs a frame affordable.
+
+The audit's suggested fix — hoist to `const valid = this.validate(problem_consumer)` — would be a
+**regression**: it leaves the walk running in every shipped build and strips only the assert that
+reads the result.
+
+A comment now says so at the call site, so the next reader does not "complete" it. No code change.
+
+**WITHDRAWN** as a defect.
+
+## 14. Signal swallows a listener's exception — **DOCUMENTED**
+
+`onPassBegin` / `onPassEnd` / `onExecuted` hand every listener the live graph, and `Signal` catches
+whatever a handler throws (`Signal.js:511-514`). So the one-shot state assertions protect callers but
+not listeners — the one place the graph actively invites third-party code in — and an `expect()`
+inside a listener can never fail a test.
+
+Not a live defect: no in-tree listener misbehaves, and the verifier majority called it a hardening
+point rather than a bug. Changing the signature to withhold the graph would break the signal
+convention for a hazard nobody has hit.
+
+Recorded on all three fields instead: a listener is a read-only observer, its exceptions are
+swallowed, and an assertion inside one cannot fail a test — assert after the dispatch, as
+`FrameGraph.pass_signals.spec.js` already does.
+
+Commit: `2ba63294b`
+
+## 15. Import aliasing defeats `validate()` — **DONE, as detection**
+
+`import_resource` has no identity check, so importing one `GPUTexture` twice gives it two
+independent `ResourceEntry` version chains. Everything `validate()` reasons about — versions,
+supersession, `producer` ordering — is scoped to a single entry, so every read/write hazard between
+them is invisible, and `is_valid_resource` answers about the wrong chain. Live: `view_ctx.camera.
+buffer.buffer` is imported seven times and `hierarchical_z_buffer.texture` three times into one
+`Shading` graph.
+
+Landed exactly as the brief scopes it: a new `FrameGraph.report_resource_aliasing(problem_consumer)`
+that names each physical resource held under more than one entry, and **changes no entry
+allocation**.
+
+It is deliberately **not** wired into `compile()`. None of the live duplicate imports produces an
+incorrect frame today — the sites happen to be ordered safely, and their passes write imported
+resources, so they are side-effect passes that never cull — and failing `compile()` on them would
+break the renderer over a hazard that is structural rather than live. Collapsing them into one entry
+is the other half of the audit's fix, and it changes which handle every one of those callers gets
+back; both are decisions of their own, and this reports the shape so either can be taken with the
+numbers in hand.
+
+Pinned by `FrameGraph.aliasing.spec.js`, four tests. One of them is the argument for the whole
+finding: two entries for one texture, a genuine stale read across them, `validate()` returning true
+with no problems, and the aliasing report naming it.
+
+The camera-7×/HZB-3× counts are the audit's; they are not re-measured here, because building the
+live `Shading` graph needs a device.
+
+Commit: `0c5f37541`
+
+## 16. `graph_read_buffer` defaulted its size from the pooled allocation — **DONE**
+
+With `size` omitted, the readback read `source.size` off the concrete `GPUBuffer` the transient pool
+handed back. The pool matches **approximately** — any pooled buffer at least as large as the request,
+within a slack bound — so the number of bytes copied out was a function of pool state rather than of
+the resource the caller named. The same call reads a different number of bytes run to run, and
+everything past the descriptor's size is the previous tenant's data.
+
+The VT feedback path (`VirtualTextureManager.js:1226`, no `size`) stays correct today only because
+the pass hand-clears the whole physical buffer first and the walk treats 0 as empty. Remove either
+and it is reading somebody else's bytes.
+
+Now `resources.getDescriptor(buffer).size - offset`. `FramePassResources.getDescriptor` already
+existed for exactly this.
+
+Pinned by `graph_read_buffer.spec.js` — a device-free context whose `createResource` deliberately
+over-allocates 4×, plus the explicit-size and offset cases. Red at 1024 bytes for a 256-byte
+resource.
+
+Commit: `a8fc3770b`
+
+## 17. The debug reprojection pass read something it never binds — **DONE**
+
+`graph_pass_debug_reprojection` recorded `read(input)` for a resource `execute_reproject` never
+touches, which pins that resource's whole producing chain into the frame through culling. Enabling a
+debug overlay therefore changed what the rest of the frame executed — the opposite of what a debug
+overlay is for.
+
+The module is **dead**: no call sites anywhere, and already recorded as such in
+`shade/device/PASS_ENCODER_PROPOSAL_2026_08_31.md`. Fixed rather than deleted, because deleting it is
+a call for whoever owns the denoiser; the `input` parameter and its read are gone, so reviving the
+module does not revive the defect.
+
+One thing left alone deliberately: `create("fake history", ...)` at the same site allocates a
+full-resolution `rgba8unorm` texture nothing ever binds. It is equally dead, but it is also a *write*,
+so removing it changes whether the pass can be culled — a decision for whoever revives this, and it
+is not one of the audit's findings.
+
+Pinned by `graph_pass_debug_reprojection.spec.js`, which asserts the recorded read set.
+
+Commit: `a8fc3770b`
+
+## 18. The sky LUT was read at the version the image pass had superseded — **DONE**
+
+`GPUSky.update()` imported the transmittance LUT, wrote it through `graph_image_pass` while
+discarding the versioned handle that pass returns, and then bound the original v0 handle to the
+multiscatter compute pass. That is the superseded read `validate()` was built to reject, so
+`compile()` throws in a dev build; with assertions stripped, the multiscatter dispatch samples a
+texture with no recorded dependency on the pass that filled it, leaving the graph free to reorder or
+cull the producer.
+
+**The module is not wired.** Nothing constructs `GPUSky`, and its only reference —
+`GPUViewSkyContext` — has no callers either. Confirmed before spending time on it, as the brief
+asked. Fixed anyway, because it was one line and a revival should not revive the defect.
+
+Pinned by `GPUSky.spec.js` on `SoftwareGPUDevice` (with `subgroups` required, which the mock grants
+because it runs no WGSL): `update()` must not throw, and before the fix it threw
+`FrameGraph 'sky update': the recorded graph is invalid`.
+
+Commit: `ec4773428`
+
+## 19. The probe atlas dropped every versioned handle — **DONE**
+
+`GPUProbeAtlas.graph_update` imported the depth and radiance atlases once each, wrote them through
+helpers whose renamed handles it discarded, and then handed the **original v0** handles to the
+border paints and the convolution — at least three superseded reads per bake. Same defect as item 3
+of `FRAME_GRAPH_RECOMMENDATIONS`, unfixed here.
+
+Two helpers made it unfixable at the call site, so both changed first:
+
+- `graph_lpv_paint_border_depth` wrote the atlas through a `graph_compute_pass` and **returned
+  nothing** (its own medium finding, `paint-border-depth-returns-void`). It now returns the handle.
+- `graph_lpv_shade` did not merely discard its result — it returned `radiance: atlas_radiance`, the
+  handle it was *given*, so even a caller that threaded it got the pre-write version. It now returns
+  what its compute pass produced.
+
+`GPUProbeAtlas` then threads both atlases through the whole chain, including the returned
+`t_radiance`, which callers were previously handed at v0.
+
+**`graph_lvp_atlas_to_sh` landed with it**, because it is the reader at the end of that chain. It
+bound the radiance atlas by reaching into the captured `GPUProbeAtlas` inside `execute` rather than
+through a declared handle, so the graph contained no edge from the fill passes to the convolution:
+culling was free to elide them (they survive today only because they write an imported resource),
+`validate()` could not check the read, `FramePassResources.get`'s declaration assertion was bypassed
+rather than enforced, and the DOT/JSON exports and the profiler's topology showed no dependency. It
+now takes `atlas_radiance` and declares `pass.read`.
+
+Pinned by `lpv_atlas_handles.spec.js`, four tests, three red before: the helper returns a handle, a
+reader threaded onto it validates, a reader left on the pre-border handle is reported as a
+superseded read, and the convolution declares its read.
+
+**What is not pinned:** the composition inside `graph_update` itself. It needs a live scene with
+materials, geometry and a BVH, which is out of reach device-free — so the spec pins each helper's
+contract instead. Saying so rather than pretending, as the brief asks.
+
+Commit: `4dc41ed6f`
+
+## 20. Passes bound buffers through captured objects — **DONE at the named site**
+
+`graph_cull_lights` bound the camera uniform and the light database off the JS objects its `execute`
+closures captured, so both culling passes appeared in the graph with **no inputs at all**: culling,
+ordering and `validate()` reason about declared handles only, and the DOT/JSON exports and the
+profiler's topology showed nothing. Both buffers are now imported once per call and threaded, which
+is the rule `graph_particles.js` already states in its header — "every persistent buffer is imported
+exactly once: two imports of one buffer are two resource entries the graph cannot tell apart".
+
+Pinned by `graph_cull_lights.spec.js` (on `SoftwareGPUDevice`): both passes declare both reads, and
+the call imports each buffer once, asserted through `report_resource_aliasing` from item 15.
+
+**The extent, as the brief asks for rather than a sweep.** A census over `src/shade` for a binding
+whose value is a property of a captured object — `x.buffer`, `.gpu_buffer`, `.buffer_data`,
+`.buffer_probes`, `.buffer_metadata`, `.scene_database_buffer` — finds **~120 sites across 52 files**
+(a handful of which are device-mock code rather than graph helpers). The verifier majority downgraded
+this from an invariant violation to an observability point, and they are right for the tree as it
+stands: insertion-order execution plus the imported-write side-effect rule make the stale read
+unreachable today, and no buffer read this way is written inside the same graph. It becomes a real
+defect the moment one of them is. The ones worth doing first are the buffers something *does* write
+in-graph — the scene database and the emitter database.
+
+Commit: `7fa65c3bc`
+
+## 21. A throwing pass stranded the profiler's frame recorder — **DONE, unpinned**
+
+The profiler's whole teardown hung off `command_ctx.finish()`, the statement after `encodeGraph`.
+A throwing pass therefore left: the recorder still subscribed to a dead graph, holding the whole
+61-pass frame graph and every pass closure in it reachable; one `GPUQuerySet` of 2048 timestamps and
+its two 16 KB resolve/readback buffers never destroyed; `profiling_absorbed` never settled; and the
+session's frame accounting silently short a frame. A render loop that catches and carries on repeats
+that every failing frame until the device complains.
+
+`render_to_target` now holds the pass failure, runs `finish()` and the `profiling_absorbed` hookup on
+both paths, and re-raises. A teardown failure does **not** replace the pass failure that caused it —
+a partial command buffer can legitimately refuse to close after an aborted pass, and the pass failure
+is what the caller needs — but a teardown failure on the success path still propagates normally.
+
+**Not pinned by a test.** `Renderer.render_to_target` needs a device, a scene with materials,
+geometry and a BVH, and a canvas; nothing in the tree constructs a `Renderer`, and building a harness
+for it is a piece of work in its own right rather than part of this fix. Saying so rather than
+pretending.
+
+Commit: `7fa65c3bc`
+
+## 22. The rasterizer's advanced handles were dropped at the call site — **DONE**
+
+`FRAME_GRAPH_RECOMMENDATIONS` item 3 threaded depth and colour through the sub-helpers, but
+`graph_rasterize_scene` still returned only the bucket buffer. So `Renderer` called
+`graph_import_texture` a *second* time on the very `GPUTextureContext` objects the job had just
+written — `#vis_render_target.color_attachments[0]/[1]` and `texture_depth_current` — giving one
+physical texture two unrelated `ResourceEntry` chains and leaving no dependency edge at all from the
+rasterization passes to their consumers.
+
+It draws correctly today only because writing an imported resource marks a pass a side-effect that
+culling may not touch, so insertion order saves the picture. `Renderer.js` carries a TODO to make
+those viz targets transient; the moment that lands, the rasterization passes lose `has_side_effects`,
+nothing in the graph reads the versions they wrote, and `compile()` culls the entire opaque +
+alpha-tested chain — an empty G-buffer with no diagnostic.
+
+`graph_rasterize_scene` now returns `{buckets, depth, color_targets}`, mirroring
+`graph_rasterize_scene_fast_raw` which has done so all along, and the Renderer destructures them
+instead of re-importing. Three imports removed from the `Shading` graph.
+
+**Not pinned by a test**, for the same reason as item 21: recording it needs a `RasterizationJob`
+with a live view context, scene, materials and render target. The contract change is small and the
+call site is the only consumer that reads the return; `execute_rasterization_jobs.js` ignores it.
+
+Commit: `5efd86114`
+
+## 23. The G-buffer record kept naming the pre-AO albedo — **DONE**
+
+The AO composite writes the albedo target and the renderer updated only its local
+`gr_texture_material_albedo_ao`, leaving `record_gbuffer.albedo` on the superseded version while
+`GBufferTextures` is declared readable at `AfterLighting`, `AfterTransparency` and `BeforePresent`.
+An extension reading it from `AfterLighting` on gets a handle an earlier pass has already replaced:
+`validate()` rejects it in a dev build, and a stripped build reads it silently.
+
+Latent rather than live — both shipped consumers (`GPUDecalRenderer`, `GPUTerrainSplatRenderer`)
+publish back into the record and therefore run at `AfterGBuffer`, before the composite — but a record
+must always name the handle that currently *is* the G-buffer, the same way `record_scene_color.color`
+is re-stated three times through the frame.
+
+The audit's suggested one-line reassignment does not work: `GBufferTextures.is_writable_at` restricts
+publication to `AfterGBuffer`, and the composite runs well after it. **Relaxing that would have been
+the wrong fix** — the freeze is deliberate and documented, and it is about *extensions*: publishing
+into the G-buffer record once shading has run is meaningless. So the renderer got an internal path
+instead: `FrameRecord.republish()`, everything `publish()` checks except the phase, and
+`GBufferTextures.republish_albedo()` on top of it. The superseded-handle check is kept, which is the
+one that matters here.
+
+Pinned in `FrameContext.spec.js`: extension publication into the frozen record still throws,
+`republish_albedo` succeeds and the record then reads back the new handle, and re-stating with a
+superseded handle is refused.
+
+Commit: `5efd86114`
+
+## 24. The shadow atlas is imported once per cascade job — **DEFERRED**
+
+A directional map's cascades are recorded into one graph, but each job runs `graph_rasterize_scene`,
+which imports `job.render_target.depth_attachment` for itself. All the cascades share
+`GPUSceneShadowmapContext`'s single `#render_target`, so N cascades produce N independent
+`ResourceEntry` chains for one physical atlas and the graph records no relationship between the
+cascade writes at all.
+
+Correct today, and explicitly rather than accidentally: the cascades are viewport-scissored, and
+`graph_meshlets_rasterize.js` detects the restricted viewport and replaces the full-attachment depth
+clear with a `texture_fill_rectangle` over the cascade rect. Every write is to an imported resource,
+so every pass side-effects and survives culling.
+
+**What blocks it.** The audit says this depends on item 22, and item 22 has landed — but landing it
+was only half of what this needs. `graph_rasterize_scene` now *returns* the depth handle; it still
+cannot *accept* one. Threading the atlas in means `RasterizationJob` carrying graph handles instead
+of `GPUTextureContext` objects, and that is the job model all four rasterization entry points share.
+That is a design change, not a local fix, and the brief for this pass rules out a refactor of that
+size.
+
+What is available in the meantime: `FrameGraph.report_resource_aliasing` (item 15) names exactly this
+condition, so the N-entries-per-atlas shape can be measured before anyone decides to change the job
+model.
+
+One correction to the finding's own tail, worth recording so the next reader does not act on it: if
+the atlas were made transient the breakage would **not** be "only the last cascade is sampled". The
+atlas is sampled from outside the graph entirely — the lighting shader reads `this.texture`,
+published by `#write_shadow_records` — so a transient atlas would break outright. The
+N-entries-per-atlas structure is what would let that happen quietly.