@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -10,6 +10,10 @@ it was wrong, not merely unbuilt. Nothing on this list is open, and the extensio
 `FrameGraph` for nothing further. The "noted, not now" list at the bottom is performance and naming,
 untouched on purpose — functionality and design first.
 
+A later deep audit (2026-09-04) found defects this round did not cover, and its correctness and
+invariant fixes are recorded in `CORRECTNESS_FIXES_2026_09_04.md`. Four of them change the standing
+picture here and are noted in place below.
+
 ---
 
 ## 1. Make the lifecycle one-shot and assert it — **DONE**
@@ -93,6 +97,13 @@ v3→v4 (double). The fast path's cube-shadow faces chain the same way. All four
 records — `Shading` plus three `shadows` — validate clean **with the accumulation exemption removed**,
 which is what item 2 above records.
 
+**The threading stopped at the entry point, and the 2026-09-04 audit found where.**
+`graph_rasterize_scene` returned only the bucket buffer, so `Renderer` re-imported the same
+`GPUTextureContext` objects to read what the rasterizer had written — one physical texture, two
+unrelated entry chains, no edge. Fixed in `CORRECTNESS_FIXES_2026_09_04.md` §22: the entry point now
+returns `{buckets, depth, color_targets}`. The same defect was still unfixed in `GPUProbeAtlas` (§19)
+and `GPUSky` (§18).
+
 ## 4. Recording scopes — **DONE** (supersedes §13.1's `pass_count`)
 
 §13.1 asks for a `pass_count` getter so the cull diagnostic can recover "the node range extension X
@@ -203,16 +214,21 @@ into.
 
 - §3.2 `frame.describe(handle)` → `FrameGraph.getDescriptor(handle)` exists and returns the entry's
   descriptor. Transient and imported resources both carry a real descriptor with absolute pixels, so
-  a derived `frame.resolution` works today.
+  a derived `frame.resolution` works today. (`FrameContext.describe` skipped the `is_open` guard that
+  `read` and `publish` enforce until `CORRECTNESS_FIXES_2026_09_04.md` §12.)
 - §3.4 publication check → `is_valid_resource(handle)` exists and does exactly the version compare
-  the design describes.
+  the design describes. It answers about one `ResourceEntry`, so it is blind to a resource imported
+  twice; `FrameGraph.report_resource_aliasing` names that condition
+  (`CORRECTNESS_FIXES_2026_09_04.md` §15).
 - §5 post-execute hook → `onExecuted` exists.
 
 ## Noted, not now
 
-- `execute()` rescans **every** resource entry after **every** pass to find lifetime ends
-  (`FrameGraph.js:621`) — O(passes × resources) per frame. `compile()` already knows `entry.last`;
-  it should build a per-pass destroy list.
+- `execute()` rescans **every** resource entry after **every** pass to find lifetime ends —
+  O(executed passes × registry entries) per frame. `compile()` already knows `entry.last`; it should
+  build a per-pass destroy list, in the shape `FramePassNode.resource_allocates` already has for the
+  other direction. Write it against the survivor set `compile()` now computes
+  (`CORRECTNESS_FIXES_2026_09_04.md` §2), not against `ref_count`.
 - `resource_creates` / `reads` / `writes` are arrays searched with `includes()`, and
   `FramePassResources.get` hits them per resource per pass.
 - The class mixes conventions: `create_resource` / `is_valid_resource` beside `getResourceEntry` /

package/src/engine/graphics/render/frame_graph/FrameGraph.d.ts

@@ -58,6 +58,15 @@ export class FrameGraph {
      */
     name: string;
     /**
+     * Every pass that survived culling has run, successfully.
+     *
+     * **Success-only.** A pass that throws takes the failure out of {@link execute} without sending
+     * this — the graph hands its transients back and re-raises, and a listener waiting on this one
+     * is left waiting. Anything that must settle on both paths belongs in the caller's own
+     * `finally`, not here. Deliberate rather than incidental: this says "the frame's work is
+     * recorded", which a failed frame has not done.
+     *
+     * Read-only, and swallowing, on the same terms as {@link onPassBegin}.
      *
      * @type {Signal<IFrameGraphContext,this>}
      */
@@ -75,6 +84,14 @@ export class FrameGraph {
      * Fires only for passes that survive culling, in execution order, and never nests: {@link
      * execute} runs one pass at a time.
      *
+     * **A listener is a read-only observer.** The graph is handed over for symmetry with the signal
+     * convention, not as an invitation: recording or compiling from a listener corrupts the counts
+     * and lifetimes `execute()` is in the middle of using. The one-shot state assertions guard
+     * against that, but they cannot stop a listener — `Signal` catches whatever a handler throws
+     * and logs it — so a misbehaving listener produces two console lines and the frame carries on.
+     * By the same token an `expect()` inside a listener can never fail a test; assert after the
+     * dispatch, as `FrameGraph.pass_signals.spec.js` does.
+     *
      * @type {Signal<FramePassNode,this>}
      */
     onPassBegin: any;
@@ -85,6 +102,8 @@ export class FrameGraph {
      * something on begin is not left holding it open by an exception. A listener must therefore
      * treat this as "that pass is over" rather than "that pass succeeded".
      *
+     * Read-only, and swallowing, on the same terms as {@link onPassBegin}.
+     *
      * @type {Signal<FramePassNode,this>}
      */
     onPassEnd: any;
@@ -229,6 +248,32 @@ export class FrameGraph {
      * @returns {boolean} whether the graph is free of problems
      */
     validate(problem_consumer?: (arg0: string) => any): boolean;
+    /**
+     * Report physical resources this graph holds under more than one {@link ResourceEntry}.
+     *
+     * Everything {@link validate} reasons about — versions, supersession, `producer` ordering — is
+     * scoped to a single entry, and {@link import_resource} has no identity check, so importing one
+     * `GPUTexture` twice gives it two independent version chains that the checker treats as
+     * unrelated resources. Every read/write hazard between them is invisible, and
+     * {@link is_valid_resource} answers about the wrong chain.
+     *
+     * **Detection only, and not wired into {@link compile}.** The live `Shading` graph imports the
+     * camera buffer seven times and the hierarchical-Z buffer three, and none of those produces an
+     * incorrect frame today: the duplicate sites happen to be ordered safely, and their passes write
+     * imported resources, so they are side-effect passes that never cull. Failing `compile()` on
+     * them would break the renderer over a hazard that is structural rather than live, and
+     * collapsing them into one entry changes which handle every one of those callers gets back.
+     * Both are decisions of their own; this reports the shape so that either can be taken with the
+     * numbers in hand.
+     *
+     * Only entries that hold a resource are considered, so a transient is reported only if the
+     * backend handed the same object out twice while both were live — which is itself the bug
+     * {@link RenderResourceManager} guards against.
+     *
+     * @param {function(string):*} [problem_consumer] invoked once per aliased resource
+     * @returns {number} how many physical resources are held under more than one entry
+     */
+    report_resource_aliasing(problem_consumer?: (arg0: string) => any): number;
     compile(): void;
     /**
      *

package/src/engine/graphics/render/frame_graph/FrameGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/frame_graph/FrameGraph.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IAkFI;;;OAGG;IACH,mBAFW,MAAM,EAOhB;IA1FD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,gBAA0B;IAE1B;;;;;;;;;;;;;;OAcG;IACH,iBAA2B;IAE3B;;;;;;;;OAQG;IACH,eAAyB;IAEzB;;;;OAIG;IACH,qBAAkB;IAElB;;;;OAIG;IACH,yBAAsB;IAEtB;;;;OAIG;IACH,4BAAyB;IAgCzB;;;;;OAKG;IACH,oBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;;;;;;;;OAWG;IACH,iBAHW,MAAM,GACJ,eAAe,CAe3B;IAED;;OAEG;IACH,kBAKC;IAED;;;;OAIG;IACH,qBAHW,MAAM,sBAehB;IAED;;;;OAIG;IACH,oBAHW,MAAM,qBAehB;IAED;;;;OAIG;IACH,qBAHW,MAAM,KAKhB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,oBAEJ,MAAM,CAYlB;IAED;;;;;OAKG;IACH,6BAYC;IAED;;;;;;OAMG;IACH,4BAgBC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CAqBlB;IAED;;;;;;OAMG;IACH,2BALW,MAAM,wDAGJ,MAAM,CAYlB;IAED;;;OAGG;IACH,4BAHa,OAAO,CAQnB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,6CAEe,kBAAkB,kCAAkC,IAAI,GAC3E,gBAAgB,CA6B5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,mCAHoB,MAAM,WACb,OAAO,CA2DnB;IAED,gBA8FC;IAED;;;OAGG;IACH,2CA6EC;IAED;;;;;;;;;;;;OAYG;IACH;gBAFqB,EAAE;mBAAa,EAAE;MA6DrC;IAED;;;;;OAKG;IACH,eAFY,MAAM,CAsLjB;IAGL;;;;OAIG;IACH,uBAFU,OAAO,CAEgB;;CAPhC;gCAl6B+B,sBAAsB;8BAKxB,oBAAoB;6BACrB,mBAAmB;mCAFb,yBAAyB;iCAF3B,uBAAuB"}
+{"version":3,"file":"FrameGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/frame_graph/FrameGraph.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IAoHI;;;OAGG;IACH,mBAFW,MAAM,EAOhB;IA5HD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;OAYG;IACH,gBAA0B;IAE1B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAA2B;IAE3B;;;;;;;;;;OAUG;IACH,eAAyB;IAEzB;;;;OAIG;IACH,qBAAkB;IAElB;;;;OAIG;IACH,yBAAsB;IAEtB;;;;OAIG;IACH,4BAAyB;IA+CzB;;;;;OAKG;IACH,oBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;;;;;;;;OAWG;IACH,iBAHW,MAAM,GACJ,eAAe,CAe3B;IAED;;OAEG;IACH,kBAKC;IAED;;;;OAIG;IACH,qBAHW,MAAM,sBAehB;IAED;;;;OAIG;IACH,oBAHW,MAAM,qBAehB;IAED;;;;OAIG;IACH,qBAHW,MAAM,KAKhB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,oBAEJ,MAAM,CAYlB;IAED;;;;;OAKG;IACH,6BAYC;IAED;;;;;;OAMG;IACH,4BAgBC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CAqBlB;IAED;;;;;;OAMG;IACH,2BALW,MAAM,wDAGJ,MAAM,CAYlB;IAED;;;OAGG;IACH,4BAHa,OAAO,CAQnB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,6CAEe,kBAAkB,kCAAkC,IAAI,GAC3E,gBAAgB,CA6B5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,mCAHoB,MAAM,WACb,OAAO,CA2DnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,mDAHoB,MAAM,WACb,MAAM,CA+ClB;IAED,gBAwIC;IA2BD;;;OAGG;IACH,2CA0FC;IA6BD;;;;;;;;;;;;OAYG;IACH;gBAFqB,EAAE;mBAAa,EAAE;MA6DrC;IAED;;;;;OAKG;IACH,eAFY,MAAM,CA6LjB;IAGL;;;;OAIG;IACH,uBAFU,OAAO,CAEgB;;CAPhC;gCA9nC+B,sBAAsB;8BAKxB,oBAAoB;6BACrB,mBAAmB;mCAFb,yBAAyB;iCAF3B,uBAAuB"}

package/src/engine/graphics/render/frame_graph/FrameGraph.js

@@ -3,9 +3,11 @@ import { float_to_uint8 } from "../../../../core/binary/float_to_uint8.js";
 import LineBuilder from "../../../../core/codegen/LineBuilder.js";
 import { rgb_to_hex } from "../../../../core/color/hex/rgb_to_hex.js";
 import { okhsv_to_linear_srgb } from "../../../../core/color/oklab/okhsv_to_linear_srgb.js";
+import { convert_channel_linear_to_sRGB } from "../../../../core/color/sRGB/linear_to_sRGB.js";
 import { Signal } from "../../../../core/events/signal/Signal.js";
 import { noop } from "../../../../core/function/noop.js";
-import { graphviz_escape_string } from "../../../../core/graph/format/graphviz/graphviz_escape_string.js";
+import { graphviz_escape_html_label } from "../../../../core/graph/format/graphviz/graphviz_escape_html_label.js";
+import { graphviz_escape_quoted } from "../../../../core/graph/format/graphviz/graphviz_escape_quoted.js";
 import { lerp } from "../../../../core/math/lerp.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { FrameGraphScope } from "./FrameGraphScope.js";
@@ -72,6 +74,15 @@ export class FrameGraph {
     name = "";
 
     /**
+     * Every pass that survived culling has run, successfully.
+     *
+     * **Success-only.** A pass that throws takes the failure out of {@link execute} without sending
+     * this — the graph hands its transients back and re-raises, and a listener waiting on this one
+     * is left waiting. Anything that must settle on both paths belongs in the caller's own
+     * `finally`, not here. Deliberate rather than incidental: this says "the frame's work is
+     * recorded", which a failed frame has not done.
+     *
+     * Read-only, and swallowing, on the same terms as {@link onPassBegin}.
      *
      * @type {Signal<IFrameGraphContext,this>}
      */
@@ -90,6 +101,14 @@ export class FrameGraph {
      * Fires only for passes that survive culling, in execution order, and never nests: {@link
      * execute} runs one pass at a time.
      *
+     * **A listener is a read-only observer.** The graph is handed over for symmetry with the signal
+     * convention, not as an invitation: recording or compiling from a listener corrupts the counts
+     * and lifetimes `execute()` is in the middle of using. The one-shot state assertions guard
+     * against that, but they cannot stop a listener — `Signal` catches whatever a handler throws
+     * and logs it — so a misbehaving listener produces two console lines and the frame carries on.
+     * By the same token an `expect()` inside a listener can never fail a test; assert after the
+     * dispatch, as `FrameGraph.pass_signals.spec.js` does.
+     *
      * @type {Signal<FramePassNode,this>}
      */
     onPassBegin = new Signal();
@@ -101,6 +120,8 @@ export class FrameGraph {
      * something on begin is not left holding it open by an exception. A listener must therefore
      * treat this as "that pass is over" rather than "that pass succeeded".
      *
+     * Read-only, and swallowing, on the same terms as {@link onPassBegin}.
+     *
      * @type {Signal<FramePassNode,this>}
      */
     onPassEnd = new Signal();
@@ -126,6 +147,21 @@ export class FrameGraph {
      */
     __resource_registry = [];
 
+    /**
+     * The passes {@link execute} will run, in recording order, as decided by {@link compile}.
+     *
+     * Computed once and then iterated, rather than re-derived at execution time. It is also the set
+     * the lifetime loop has to cover: a pass that runs without ever becoming a resource's
+     * {@link ResourceEntry.last} user reads a transient the graph has already handed back to the
+     * pool, and the pool re-issues within the frame. Deriving "does this pass run" in two places is
+     * exactly what let the two answers differ — `ref_count === 0` in the lifetime loop against
+     * {@link FramePassNode.can_execute} in `execute()`, which disagree for every read-only
+     * {@link FramePassBuilder.make_side_effect} pass.
+     *
+     * @type {FramePassNode[]}
+     */
+    #surviving_passes = [];
+
     /**
      * Position in the one-shot lifecycle.
      * @type {FrameGraphState}
@@ -498,10 +534,95 @@ export class FrameGraph {
         return valid;
     }
 
+    /**
+     * Report physical resources this graph holds under more than one {@link ResourceEntry}.
+     *
+     * Everything {@link validate} reasons about — versions, supersession, `producer` ordering — is
+     * scoped to a single entry, and {@link import_resource} has no identity check, so importing one
+     * `GPUTexture` twice gives it two independent version chains that the checker treats as
+     * unrelated resources. Every read/write hazard between them is invisible, and
+     * {@link is_valid_resource} answers about the wrong chain.
+     *
+     * **Detection only, and not wired into {@link compile}.** The live `Shading` graph imports the
+     * camera buffer seven times and the hierarchical-Z buffer three, and none of those produces an
+     * incorrect frame today: the duplicate sites happen to be ordered safely, and their passes write
+     * imported resources, so they are side-effect passes that never cull. Failing `compile()` on
+     * them would break the renderer over a hazard that is structural rather than live, and
+     * collapsing them into one entry changes which handle every one of those callers gets back.
+     * Both are decisions of their own; this reports the shape so that either can be taken with the
+     * numbers in hand.
+     *
+     * Only entries that hold a resource are considered, so a transient is reported only if the
+     * backend handed the same object out twice while both were live — which is itself the bug
+     * {@link RenderResourceManager} guards against.
+     *
+     * @param {function(string):*} [problem_consumer] invoked once per aliased resource
+     * @returns {number} how many physical resources are held under more than one entry
+     */
+    report_resource_aliasing(problem_consumer = noop) {
+        const registry = this.__resource_registry;
+        const entry_count = registry.length;
+
+        /**
+         * Entry IDs by the physical resource they hold.
+         * @type {Map<*,number[]>}
+         */
+        const by_resource = new Map();
+
+        for (let i = 0; i < entry_count; i++) {
+            const entry = registry[i];
+
+            if (entry.resource === null) {
+                continue;
+            }
+
+            const existing = by_resource.get(entry.resource);
+
+            if (existing === undefined) {
+                by_resource.set(entry.resource, [i]);
+            } else {
+                existing.push(i);
+            }
+        }
+
+        let aliased = 0;
+
+        for (const entry_ids of by_resource.values()) {
+            if (entry_ids.length < 2) {
+                continue;
+            }
+
+            aliased++;
+
+            const names = entry_ids.map(id => {
+                const node = this.__resource_nodes.find(n => n.resource_id === id);
+
+                return `${id} '${node === undefined ? "?" : node.name}'`;
+            });
+
+            problem_consumer(`One resource is held under ${entry_ids.length} entries — ${names.join(", ")}. Versions and supersession are scoped to a single entry, so no hazard between them can be seen.`);
+        }
+
+        return aliased;
+    }
+
     compile() {
         assert.equal(this.#state, FrameGraphState.Recording, `FrameGraph '${this.name}': compile() is one-shot, a second compile accumulates resource reference counts instead of resetting them and culling stops working, graph is ${frame_graph_state_name(this.#state)}`);
 
         assert.equal(this.#scope, null, `FrameGraph '${this.name}': recording finished with scope '${this.#scope}' still open, every push_scope() needs its pop_scope()`);
+
+        /*
+         `validate()` is called *inside* the assert on purpose, and must stay there.
+
+         @rollup/plugin-strip deletes a matched call together with its arguments, so under the strip
+         the consuming project applies (README, "Shipping a build") the whole gate — the walk, the
+         two Int32Arrays, and `console.error` — disappears. That is the intent: this is a
+         development check over what was recorded, run five or more times a frame, and a shipped
+         game should not pay for it.
+
+         Hoisting it to `const valid = this.validate(...)` would leave the walk running in every
+         shipped build while stripping only the assert that reads the result. Do not "clean this up".
+        */
         assert.ok(this.validate(console.error), `FrameGraph '${this.name}': the recorded graph is invalid, the problems are logged above`);
 
         this.#state = FrameGraphState.Compiled;
@@ -570,30 +691,84 @@ export class FrameGraph {
             }
         }
 
-        // calculate lifetimes
+        // decide which passes run, once. `execute()` iterates this set instead of asking again.
+        const surviving_passes = this.#surviving_passes;
+
+        surviving_passes.length = 0;
+
         for (let i = 0; i < pass_node_count; i++) {
             const pass = pass_nodes[i];
-            if (pass.ref_count === 0) {
-                // unused pass
+
+            if (!pass.can_execute()) {
+                // culled
                 continue;
             }
 
+            surviving_passes.push(pass);
+        }
+
+        // calculate lifetimes, over exactly the passes that will run
+        const surviving_pass_count = surviving_passes.length;
+
+        for (let i = 0; i < surviving_pass_count; i++) {
+            const pass = surviving_passes[i];
+
+            const allocates = pass.resource_allocates;
+
+            allocates.length = 0;
+
             for (const id of pass.resource_creates) {
                 const entry = this.getResourceEntry(id);
+
                 entry.producer = pass;
                 entry.last = pass;
+
+                allocates.push(id);
             }
 
             for (const id of pass.resource_writes) {
-                this.getResourceEntry(id).last = pass;
+                const entry = this.getResourceEntry(id);
+
+                this.#claim_unparented_transient(entry, pass, id);
+
+                entry.last = pass;
             }
 
             for (const id of pass.resource_reads) {
-                this.getResourceEntry(id).last = pass;
+                const entry = this.getResourceEntry(id);
+
+                this.#claim_unparented_transient(entry, pass, id);
+
+                entry.last = pass;
             }
         }
     }
 
+    /**
+     * Make `pass` the allocator of a transient no pass created.
+     *
+     * {@link create_resource} is public, so a caller can reserve a handle before it knows which
+     * pass will fill it — which is what the extension surface does, handing the graph out through
+     * `FrameContext.graph`. Such an entry appears in no pass's {@link FramePassNode.resource_creates},
+     * so nothing allocated it: the pass was handed `null` and the release scan then tried to give
+     * `null` back to the pool. Allocating it at its first surviving user gives it the same lifetime
+     * any other transient has, and matches what {@link validate} already blesses — reading a
+     * transient no pass writes is legal, because the reader may be the pass about to fill it.
+     *
+     * @param {ResourceEntry} entry
+     * @param {FramePassNode} pass
+     * @param {number} id resource node ID
+     */
+    #claim_unparented_transient(entry, pass, id) {
+        if (entry.producer !== null || entry.isImported()) {
+            return;
+        }
+
+        entry.producer = pass;
+
+        pass.resource_allocates.push(id);
+    }
+
     /**
      *
      * @param {IFrameGraphContext} context
@@ -606,77 +781,117 @@ export class FrameGraph {
 
         this.#state = FrameGraphState.Executed;
 
-        const pass_nodes = this.__pass_nodes;
+        // Whatever `compile()` computed lifetimes over, and nothing else. Re-deriving the survivor
+        // set here is what let the two disagree.
+        const pass_nodes = this.#surviving_passes;
         const pass_node_count = pass_nodes.length;
 
-        for (let i = 0; i < pass_node_count; i++) {
-            const node = pass_nodes[i];
+        try {
+            for (let i = 0; i < pass_node_count; i++) {
+                const node = pass_nodes[i];
 
-            if (!node.can_execute()) {
-                continue;
-            }
+                const node_allocated_resources = node.resource_allocates;
 
-            const node_created_resources = node.resource_creates;
+                for (const id of node_allocated_resources) {
 
-            for (const id of node_created_resources) {
-
-                // allocate resource
-                this.getResourceEntry(id).create(context.resource_manager);
-            }
-
-            const resources = new FramePassResources();
-            resources.init(this, node);
-
-            /*
-             Guarded rather than dispatched unconditionally: `send2` on a signal with no handlers
-             still bumps `generation` and walks a Map iterator, and this pair runs twice per pass
-             over a couple of hundred passes a frame. Nothing observes the graph in a normal frame,
-             so the common case should cost a size comparison and nothing else.
-            */
-            const announce_passes = this.onPassBegin.hasHandlers() || this.onPassEnd.hasHandlers();
-
-            if (announce_passes) {
-                this.onPassBegin.send2(node, this);
-            }
+                    // allocate resource
+                    this.getResourceEntry(id).create(context.resource_manager);
+                }
 
-            // execute pass
-            try {
-                node.execute(node.data, resources, context);
-            } catch (e) {
-                // decorate
-                const error = new Error(`RenderPass '${node.name}' failed to execute`);
+                const resources = new FramePassResources();
+                resources.init(this, node);
 
-                error.cause = e;
+                /*
+                 Guarded rather than dispatched unconditionally: `send2` on a signal with no handlers
+                 still bumps `generation` and walks a Map iterator, and this pair runs twice per pass
+                 over a couple of hundred passes a frame. Nothing observes the graph in a normal frame,
+                 so the common case should cost a size comparison and nothing else.
+                */
+                const announce_passes = this.onPassBegin.hasHandlers() || this.onPassEnd.hasHandlers();
 
-                throw error;
-            } finally {
-                // `finally` so a pass that throws still closes its bracket — a listener that opened
-                // a scope on begin would otherwise attribute the rest of the frame to the pass that
-                // died.
                 if (announce_passes) {
-                    this.onPassEnd.send2(node, this);
+                    this.onPassBegin.send2(node, this);
+                }
+
+                // execute pass
+                try {
+                    node.execute(node.data, resources, context);
+                } catch (e) {
+                    // decorate
+                    const error = new Error(`RenderPass '${node.name}' failed to execute`);
+
+                    error.cause = e;
+
+                    throw error;
+                } finally {
+                    // `finally` so a pass that throws still closes its bracket — a listener that opened
+                    // a scope on begin would otherwise attribute the rest of the frame to the pass that
+                    // died.
+                    if (announce_passes) {
+                        this.onPassEnd.send2(node, this);
+                    }
                 }
-            }
 
 
-            const resource_entries = this.__resource_registry;
-            const resource_entry_count = resource_entries.length;
+                const resource_entries = this.__resource_registry;
+                const resource_entry_count = resource_entries.length;
 
-            for (let entry_index = 0; entry_index < resource_entry_count; entry_index++) {
-                const entry = resource_entries[entry_index];
+                for (let entry_index = 0; entry_index < resource_entry_count; entry_index++) {
+                    const entry = resource_entries[entry_index];
+
+                    if (entry.last === node && entry.isTransient()) {
+                        // this was the last user of the resource and the resource is transient (no external usage)
+                        entry.destroy(context.resource_manager);
+                    }
 
-                if (entry.last === node && entry.isTransient()) {
-                    // this was the last user of the resource and the resource is transient (no external usage)
-                    entry.destroy(context.resource_manager);
                 }
 
             }
+        } catch (e) {
+            /*
+             Nothing further will run, so every transient still checked out is checked out forever —
+             in the Shading graph, tens of MB of render targets, leaked again on every failing frame
+             of a render loop that catches and carries on.
 
+             Deliberately here and not in a `finally` around the pass body: that `finally` belongs to
+             the onPassBegin/onPassEnd bracket, and putting a release scan inside it would run the
+             sweep on the success path too, once per pass.
+            */
+            this.#release_live_transients(context.resource_manager);
+
+            throw e;
         }
 
         this.onExecuted.send2(context, this);
     }
 
+    /**
+     * Hand back every transient still holding a resource.
+     *
+     * Only reachable when a pass throws — {@link execute} releases as it goes, so on the success
+     * path there is nothing left to find.
+     *
+     * The `resource !== null` filter is only a safe way to ask "is this still checked out" because
+     * {@link ResourceEntry.destroy} clears the field. The pool re-issues immediately and within the
+     * frame, so an entry naming a resource it has already returned would be pooled a second time,
+     * and `TransientResourcePool.release` would take it, because that resource *is* bound — to
+     * whoever owns it now.
+     *
+     * @param {RenderResourceManager} resources
+     */
+    #release_live_transients(resources) {
+        const entries = this.__resource_registry;
+        const entry_count = entries.length;
+
+        for (let i = 0; i < entry_count; i++) {
+            const entry = entries[i];
+
+            if (entry.isTransient() && entry.resource !== null) {
+                entry.destroy(resources);
+            }
+        }
+    }
+
     /**
      * Should only call after {@link compile}
      *
@@ -772,7 +987,7 @@ export class FrameGraph {
          * @param {FramePassNode} node
          * @returns {string}
          */
-        const pass_declaration = (node) => `P${node.id} [label=<{ {<B>${node.name}</B>} | {${(node.has_side_effects ? "&#x2605; " : "")} Refs: ${node.ref_count}<BR/> Index: ${node.id}} }> style=\"rounded,filled\", fillcolor=${(node.ref_count > 0 || node.has_side_effects) ? "orange" : "lightgray"}]`;
+        const pass_declaration = (node) => `P${node.id} [label=<{ {<B>${graphviz_escape_html_label(node.name)}</B>} | {${(node.has_side_effects ? "&#x2605; " : "")} Refs: ${node.ref_count}<BR/> Index: ${node.id}} }> style=\"rounded,filled\", fillcolor=${(node.ref_count > 0 || node.has_side_effects) ? "orange" : "lightgray"}]`;
 
         out.add("");
         out.add("# Pass Nodes");
@@ -815,7 +1030,12 @@ export class FrameGraph {
             const color_rgb = [];
             okhsv_to_linear_srgb(color_rgb, color_hue, saturation, 1)
 
-            const hex = rgb_to_hex(...color_rgb.map(float_to_uint8));
+            /*
+             GraphViz reads `#rrggbb` as sRGB, so a linear-light value quantized straight to bytes
+             arrives at roughly three times the chroma the okhsv parameters asked for — which turns
+             the deliberately quiet imported-vs-transient saturation split into a loud one.
+            */
+            const hex = rgb_to_hex(...color_rgb.map(c => float_to_uint8(convert_channel_linear_to_sRGB(c))));
 
             return `#${hex}`;
         }
@@ -827,10 +1047,12 @@ export class FrameGraph {
         const resource_declaration = (node) => {
             const entry = this.__resource_registry[node.resource_id];
 
-            const type = graphviz_escape_string(entry.resource_descriptor?.type ?? "");
+            const type = graphviz_escape_html_label(entry.resource_descriptor?.type ?? "");
+
+            const block_title = `${entry.isImported() ? "↪ " : ""}${graphviz_escape_html_label(node.name)}`;
 
-            const block_title = `${entry.isImported() ? "↪ " : ""}${node.name}`;
-            const block_tooltip = graphviz_escape_string(entry.toString());
+            // a plain quoted attribute, not a record label: `{`, `}` and `|` are ordinary here
+            const block_tooltip = graphviz_escape_quoted(entry.toString());
 
             return `R${entry.resource_id}_${node.version} [label=<{ {<B>${block_title}</B>${node.version > 0 ? ` <FONT>v${(node.version + 1)}</FONT>` : ""}<BR/>${type}} | {Index: ${entry.resource_id}<BR/> Refs : ${node.ref_count} } }> style=filled, fillcolor="${entry_to_background_color(entry)}" tooltip="${block_tooltip}"]`;
         };
@@ -865,7 +1087,7 @@ export class FrameGraph {
             out.indent();
 
             // the root graph is drawn invisible, so a cluster has to ask for its own frame
-            out.add(`label="${graphviz_escape_string(scope.name)}"`);
+            out.add(`label="${graphviz_escape_quoted(scope.name)}"`);
             out.add("style=\"rounded,dashed\", color=\"gray55\", fontname=\"helvetica\", fontsize=10, labeljust=\"l\"");
 
             for (const node of this.__pass_nodes) {

package/src/engine/graphics/render/frame_graph/FramePassBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FramePassBuilder.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/frame_graph/FramePassBuilder.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH;IAgBI;;;;OAIG;IACH,mDAMC;IAED;;;;;;OAMG;IACH,aAJW,MAAM,mCAEJ,MAAM,CAiBlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,MAAM,CA2BlB;IAED;;;;OAIG;IACH,yBAIC;;CACJ"}
+{"version":3,"file":"FramePassBuilder.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/frame_graph/FramePassBuilder.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH;IAgBI;;;;OAIG;IACH,mDAMC;IAED;;;;;;OAMG;IACH,aAJW,MAAM,mCAEJ,MAAM,CAiBlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,MAAM,CAsClB;IAED;;;;OAIG;IACH,yBAIC;;CACJ"}

package/src/engine/graphics/render/frame_graph/FramePassBuilder.js

@@ -97,19 +97,30 @@ export class FramePassBuilder {
             node.has_side_effects = true;
         }
 
-        if (node.creates(resource)) {
-            return node.write(resource);
-        } else {
-            // writing to a resource produces a renamed handle
-            node.read(resource);
+        /*
+         A pass produces exactly one version of a resource, so a second write of the same entry —
+         whether of the original handle, or of the handle the first write handed back — is the same
+         write. Branching on `creates` alone took the clone path again: a second version nobody can
+         read, since the caller only kept the last, and a `resource_writes` one longer than the
+         pass's logical writes. Nothing reported it: the orphan is unreferenced by construction, so
+         culling quietly cancels the extra count and `validate()` sees a well-formed graph.
+        */
+        const entry_id = graph.getResourceNode(resource).resource_id;
+
+        for (const id of node.resource_writes) {
+            if (graph.getResourceNode(id).resource_id === entry_id) {
+                return id;
+            }
+        }
 
-            const clone = graph.clone_resource(resource);
+        // writing to a resource produces a renamed handle
+        node.read(resource);
 
-            graph.getResourceNode(clone).producer = node;
+        const clone = graph.clone_resource(resource);
 
-            return node.write(clone);
-        }
+        graph.getResourceNode(clone).producer = node;
 
+        return node.write(clone);
     }
 
     /**