@woosh/meep-engine 3.60.4 → 3.60.5

package/src/shade/renderer/extension/RENDER_EXTENSION_DESIGN.md

@@ -1,964 +0,0 @@
-# Render extensions — design
-
-Replaces `Renderer.add_pass` / `remove_pass`, `FramePhase`, `FramePassContext` and
-`FramePassRegistry` (MEEP 3, phase 2, item S3).
-
-Status: **design, not built.** Nothing in §3 through §11 is committed code.
-
-**Revised 2026-08-24** against the frame-graph work that has landed since the first draft:
-`FrameGraphState`, `validate()`, recording scopes, record-time producers, and the `exportToJson`
-fix. Those came out of this document's §4 and §13 and are tracked in
-`engine/graphics/render/frame_graph/FRAME_GRAPH_RECOMMENDATIONS.md`. §1.2, §3.4, §4, §5 and §13
-describe what the graph does now, not what it did — the net effect is that the design leans on the
-graph in three more places and asks it for nothing.
-
-The same revision **withdrew the cull diagnostic** and the engine change it needed, on sponsor
-review: culling is what a frame graph is for, and a check that calls it a failure when an extension
-is the recorder invents a distinction that does not exist and outlaws the speculative producer.
-§5.1 is the argument; the bar it sets — a check may only fire on something that cannot be true —
-also took out a provenance check in §3.4.
-
-**Revised 2026-09-16: `after` / `before` are gone, replaced by `relative_order`.** They were
-built as specified, shipped, and then did the thing §1.4 rejected integer offsets to avoid — from
-the other direction. A constraint over classes is an import: `DebugDrawSystem`, which draws
-developer gizmos and knows nothing about anything, had to import `FogOfWarExtension` in order to
-say "on top". That is a generic extension acquiring a dependency on a game-specific one, at module
-scope, to express a fact about itself. `relative_order` is a number that defaults to 0 and names
-nothing: lower records first, negative pulls forward, positive pushes back. It is **less precise**
-and that is the trade — it cannot say "immediately after that one", and there is no cycle to detect
-because there is no graph. §1.4, §3.1, §3.6, §5, §7, §8 and §11 are updated; §3.6's ambiguity check
-was never built and is unaffected.
-
-**Revised 2026-09-24: trails left the `AfterTransparency` chain.** §9's first known limit — an
-extension cannot take part in OIT — still holds for extensions, and it is why trails moved out: a
-trail drawn at `AfterTransparency` covered every transparent surface whatever its depth. They are now
-a *transparency channel* (`Renderer.add_transparency_channel`, `GraphicsEngine.add_transparency_channel`),
-drawn inside the AVBOIT pipeline beside the particles; see the AVBOIT ledger, entries 22 and 23. The
-chain in §8's table is five deep, and the fog still covers trails, by construction: it runs after the
-transparency resolve they are part of. So does the rest of the chain, which is the one visible
-reordering — path display and the highlight, which trails used to draw over, now draw over trails.
-
----
-
-## 0. Summary
-
-An extension is a **named object with declarations** — a phase, where in that phase it sits, the
-optional frame products it needs — and one method that records into the frame's graph. Everything it exchanges
-with the frame goes through **typed per-frame records** holding frame-graph handles: it reads a
-handle out of a record and writes a replacement back. There is no return value and no privileged
-resource.
-
-Three properties follow, and they are the point:
-
-1. **Every resource the frame carries is exchangeable**, not just the colour. The G-buffer stops
-   being a documented special case, depth stops being read-only, and an extension can publish a
-   record of its own that another extension reads.
-2. **Order is declared**, not emergent from the order in which ECS systems happened to reach their
-   first `await`.
-3. **The frame can be described without being rendered, and read back attributed once it has been.**
-   The set of extensions, their order per phase, and the products they force on are data, so
-   `describe()` prints the pipeline; and the registry records each extension inside its own graph
-   scope, so a DOT export of the frame groups by who asked for what instead of by whatever the
-   `graph_*` helpers named things. That pair is what "the frame graph is a first-class construct"
-   has to mean at this seam.
-
-Underneath all three, one correction that is not an abstraction: **the upscale is a phase boundary
-and the surface says so.** Three phases are before it and two are after, the before case is the
-common one, and the size of what an extension is drawing into is derived from the live handle rather
-than handed over as a field the renderer fills in once for the whole frame — which is what the
-current mechanism does, and gets wrong at two of its five phases (§1.3b).
-
-The shape is Unity 6 URP's — `ContextContainer` / `ContextItem`, `ScriptableRenderPass`,
-`ConfigureInput` — with URP's two worst traits removed (§2).
-
----
-
-## 1. What is wrong with `add_pass`
-
-### 1.1 One resource is modifiable
-
-`FramePassRegistry.run` threads exactly one value:
-
-```js
-const produced = passes[i](context);
-if (produced === undefined) { continue; }
-context.color = produced;
-```
-
-A pass's only sanctioned output is a colour handle. Everything else on `FramePassContext` — depth,
-previous depth, the four G-buffer targets, the two visibility targets — is an input. The one
-exception, the G-buffer being in/out at `AfterGBuffer`, is implemented by letting the pass reach into
-`context.gbuffer` and assign, and costs three paragraphs of prose in `FramePassContext` to explain
-why replacing beats writing in place.
-
-What that closes off, concretely: writing depth (terrain and water both rasterize geometry that
-should own depth), publishing a resource an extension computed for other extensions to read (fog of
-war's visibility grid is exactly this and currently lives outside the graph), and reading anything
-the frame builds but the struct does not name — velocity, the Hi-Z pyramid, the TAA history, the
-shadow atlas, the light cluster tables.
-
-The struct is closed by construction: adding a field is an edit to Shade. That is the wrong cost for
-"my game needs one more thing from the frame".
-
-### 1.2 The graph is an escape hatch, not the mechanism
-
-`context.graph` hands the pass the `FrameGraph` and steps back. The registry never learns what the
-pass read or wrote, so:
-
-- **It cannot order passes.** It orders by registration order.
-- **It cannot attribute anything.** `exportToDot` shows the nodes an extension created with whatever
-  names its helpers gave them, unrelated to the extension. The graph has since gained recording
-  scopes, which are exactly the missing mechanism — but they are opt-in and `add_pass` opens none,
-  so a frame's DOT export is still one flat wall of passes.
-- **It cannot validate.** Reading `context.color` at `AfterGBuffer` yields `-1` and fails somewhere
-  inside a binding builder. Retaining a handle across frames is undetectable. Publishing a stale
-  handle is now caught, but by the graph at `compile()` and against the *reader* — the pass that
-  consumed it — so the report names the built-in pass that broke, never the extension that handed
-  it the bad handle.
-- **`AfterGBuffer` has no return channel, so the culling contract cannot be met there.** The rule
-  itself is the graph's, and it is right everywhere: work nothing consumes is elided. But the only
-  way this mechanism lets a pass thread its result into the frame is by returning a colour handle,
-  and at `AfterGBuffer` there is no colour — so a pass whose G-buffer work *should* be consumed
-  reaches for `make_side_effect()` instead, which does not say "my output is used", it says "run me
-  anyway". Three paragraphs of `FramePhase` document the workaround. The record model removes the
-  reason for it (§3.3) and leaves the culling rule alone (§5.1).
-
-And the injection points themselves are call sites: a phase is wherever `#run_frame_passes` was
-typed inside an 800-line method. There are five because five were typed.
-
-### 1.3 What this has already produced
-
-Four findings from reading the current code, each independent of the design that replaces it.
-
-**(a) Order is an accident, and the code says so.** `TerrainSystem.startup`:
-
-> `// before anything is awaited, so that pass order within the phase is the profile's system order —`
-> `// the decal composite has to see the textured ground, not precede it`
-
-An ordering requirement between two extensions is being met by placing a registration call above an
-`await`. Adding an `await` to a system's startup silently reorders the frame.
-
-The same mechanism decides the six-deep chain at `AfterTransparency`, and **it has already produced a
-shipped bug**. In profile order that chain is fog of war, particles, path display, highlight, debug
-draw, trails — so the fog composites *first* and everything drawn after it is unfogged. Confirmed
-with the sponsor: that is not intended. Fog of war conceals, so it belongs over everything it
-conceals; particles drawing on top of it defeat what it is for.
-
-Nobody chose that order. Nothing recorded it. Nothing failed when it turned out wrong. That is the
-argument for §3.6 in one paragraph.
-
-**(b) The one size the context states is wrong at two phases.** `Renderer` fills
-`pass_context.resolution` from `resolution_internal.asArray()`, once, for all five phases. But TAA
-and NSS upscale to `output_resolution` before `BeforePresent`, and the tonemap writes the canvas at
-output resolution — so at `BeforePresent` and `Overlay` the colour is *not* the size the context
-reports, whenever TAA is on. With TAA off it is, because the upscale is missing (there is a `TODO`
-in `Renderer` saying so). The size of the frame's colour at `BeforePresent` is therefore not
-derivable from the context at all; it depends on a renderer feature flag the extension cannot see.
-
-`probeShadePassInjection` — the gate for the current mechanism — does
-`output_resolution: context.resolution` at `BeforePresent`. It passes because the probe runs at 100%
-scale. The game ships with dynamic resolution scaling enabled against a 30 fps floor, and at any
-scale below 100% that pass produces a cropped, wrongly-scaled frame while the gate still measures a
-luminance change and reports green.
-
-The single field is the tell: the surface was built as though a frame had one resolution. Three of
-the five phases are before the upscale and two are after it, and nothing in the surface says which
-is which — `FramePhase`'s own text for `BeforePresent` says "still HDR" and never mentions that the
-colour has been upscaled by then. §3.5 makes the boundary part of what a phase *is*.
-
-**(c) `-1` is a sentinel with no guard.** `color` is `-1` at `AfterGBuffer`. Nothing stops a pass
-reading it. The house rule is that the common case is the only case and preconditions are asserted,
-not encoded as magic values.
-
-**(d) The G-buffer special case exists only because colour owns the return channel.** Given a
-uniform way to publish any handle, "the G-buffer is in/out at one phase" stops being a rule and
-becomes an instance of the general one.
-
----
-
-## 2. What is borrowed from URP, and what is not
-
-Borrowed:
-
-| URP 6 | Here | Why |
-| --- | --- | --- |
-| `ContextContainer` + `ContextItem` | `FrameContext.get(RecordType)` + frame records | The open, typed resource vocabulary. This is the fix for §1.1, and the reason it is keyed by type rather than by string is that the house rule forbids string-keyed registries. |
-| `UniversalResourceData` | `SceneColor`, `GBufferTextures`, `ViewTextures`, `PresentTarget` | Built-in resources are ordinary classes with named fields, carried in the same container as anyone else's. One mechanism, not two. |
-| `ScriptableRenderPass` | `RenderExtension` | A declaring object, not a closure. Declarations are what makes ordering, validation and description possible. |
-| `ConfigureInput(ScriptableRenderPassInput.Motion)` | `RenderExtension.requires` + `FrameProduct` | An extension states what the frame must produce and the renderer turns it on. This is the answer to "velocity exists, is built, and is unreachable". |
-| Renderer feature list, ordered | The registry's resolved order, printable | The pipeline is inspectable before it runs. |
-
-Not borrowed, deliberately:
-
-- **`RenderPassEvent` + integer offsets.** URP orders same-event passes by an `int` you add to the
-  enum. It is the same defect as registration order with an extra step: unreadable, unstable under
-  insertion, and it makes every ordering question a numerology question. Replaced by explicit
-  `after` / `before` constraints over extension classes (§3.6).
-
-  > *Reversed, 2026-09-16.* Constraints over classes were built and are gone; §3.6 is now an offset
-  > within the phase. What this entry got right is that an offset is imprecise. What it missed is
-  > that it is imprecise *and names nothing*, where a constraint is precise and is an import — and
-  > an import is how a debug overlay ends up depending on the fog of war. The enum-offset objection
-  > also does not carry over: URP's `int` is an offset into a 17-value event enum, where a phase
-  > here is one of six coarse points and the offset orders only what shares it.
-- **`SetGlobalTexture` / global shader state.** An implicit channel between passes that the graph
-  cannot see. Records are the channel.
-- **`AddUnsafePass`.** URP needs a legacy `CommandBuffer` escape hatch. There is no legacy to carry
-  here, and adding an unchecked door on day one guarantees it becomes the door.
-- **Two-level feature/pass split.** URP splits `ScriptableRendererFeature` from
-  `ScriptableRenderPass` because a feature is a `ScriptableObject` living on an asset. That reason
-  does not exist here, so there is one class.
-
----
-
-## 3. The model
-
-### 3.1 `RenderExtension`
-
-```js
-export class RenderExtension {
-    /**
-     * Stable identity. Used in error decoration and `describe()`, and the tie-break within one
-     * `relative_order`.
-     * @type {string}
-     */
-    name = "";
-
-    /** @type {FramePhase} */
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * Where in the phase this records. Lower first; any finite number, negative to pull forward.
-     * It names no other extension, which is the point.
-     * @type {number}
-     */
-    relative_order = 0;
-
-    /**
-     * Optional frame products this extension reads. A bitmask of {@link FrameProduct}.
-     * Reading a product nobody required is an assert failure, not a silent `-1`.
-     * @type {number}
-     */
-    requires = 0;
-
-    /**
-     * Record this extension's work into the frame. Called once per frame, when the phase comes
-     * round. Returns nothing: everything this produces reaches the rest of the frame by
-     * publication (§3.4).
-     *
-     * @param {FrameContext} frame
-     */
-    record(frame) {}
-}
-```
-
-`record` returning `void` is load-bearing. It is what makes colour stop being privileged.
-
-An extension that has nothing to draw this frame returns without recording; that is the only "off"
-switch and there is no `enabled` flag beside it.
-
-### 3.2 `FrameContext`
-
-```js
-export class FrameContext {
-    /** @type {FrameGraph} the frame's graph — record into this with the `graph_*` helpers */
-    graph;
-    /** @type {ViewRenderContext} */
-    view;
-    /** @type {FramePhase} */
-    phase;
-
-    /** @template T @param {new()=>T} type @returns {T} throws if not present at this phase */
-    get(type) {}
-
-    /** @param {Function} type @returns {boolean} */
-    has(type) {}
-
-    /** @template T @param {new()=>T} type @returns {T} adds a record this extension owns */
-    create(type) {}
-
-    /**
-     * Pixel size of the target this phase carries, derived from the live handle rather than filled
-     * in by the renderer.
-     * @returns {number[]}
-     */
-    get resolution() {}
-
-    /** @param {number} handle @returns {ResourceDescriptor} size, format and usage of a handle */
-    describe(handle) {}
-}
-```
-
-Three accessors rather than one `get_or_create`, because "absent" has to stay distinguishable from
-"empty" — that is what lets `get(SceneColor)` at `AfterGBuffer` throw with a sentence instead of
-handing back `-1`.
-
-**`resolution` is derived, and that is the whole of the fix for defect (b).** It reads the graph
-through the handle this phase's target actually is, so it is right before the upscale, right after
-it, right when TAA is off and the upscale does not happen at all, and right at every dynamic
-resolution scale. The common case — "how big is the thing I am drawing into" — stays one property
-access and cannot be wrong.
-
-`describe(handle)` is the general form, and it is needed whenever two things in one pass are
-different sizes: an extension at `BeforePresent` reading the G-buffer is working across the upscale
-boundary and has to ask for both.
-
-> Both lean on descriptors being trustworthy, which was checked: transient and imported resources
-> both carry a real `TextureResourceDescriptor` holding absolute pixels.
-> `TextureResourceDescriptor.resolution_domain` says otherwise by default and is vestigial — nothing
-> branches on it, only `hash()` folds it in. It stays; it is now documented as vestigial on the field
-> itself so the next reader does not take it for a contract.
-
-### 3.3 Frame records
-
-A record is a plain class holding frame-graph handles. The renderer publishes the built-in ones as
-the frame reaches the phase where they are meaningful.
-
-```js
-/** present from AfterGBuffer */
-class GBufferTextures { albedo; normal; pbr; emissive; }
-
-/** present from AfterGBuffer */
-class ViewTextures {
-    depth; depth_previous;
-    visibility_mesh; visibility_triangle;
-    velocity;   // requires FrameProduct.Velocity
-}
-
-/** present from AfterLighting through BeforePresent */
-class SceneColor {
-    color;
-    copy;       // requires FrameProduct.ColorCopy
-}
-
-/** present at Overlay, and only there */
-class PresentTarget { canvas; }
-```
-
-Presence by phase:
-
-| phase | records | resolution |
-| --- | --- | --- |
-| `FrameStart` | — (the view only) | internal |
-| `AfterGBuffer` | `GBufferTextures` (writable), `ViewTextures` | internal |
-| `AfterLighting` | `GBufferTextures` (frozen), `ViewTextures`, `SceneColor` | internal |
-| `AfterTransparency` | as above | internal |
-| `BeforePresent` | as above — but `SceneColor` and `GBufferTextures` are now different sizes | output |
-| `Overlay` | `PresentTarget` | output |
-
-Two of those rows are decisions worth naming.
-
-**`SceneColor` is absent at `Overlay`, and `PresentTarget` is not `SceneColor`.** The current
-mechanism hands the tonemapped colour to `Overlay` passes and then documents, at length, that they
-must not read it — a texture cannot be a render attachment and a sampled source in the same pass.
-That was found by measurement after the fact. Handing back a differently-named record with one field
-says the same thing structurally: there is no `color` at `Overlay` to be tempted by, and an
-extension that wants the finished image as *input* discovers at `get` time that it belongs at
-`BeforePresent`.
-
-**`GBufferTextures` is present but frozen after `AfterGBuffer`.** Outline and highlight effects
-legitimately read the G-buffer and the visibility buffer late. Publishing into it late is
-meaningless — shading has run — so the record is frozen and the assert says why (§5). At
-`BeforePresent` it is also on the far side of the upscale from the colour (§3.5), so the two are
-different sizes; `describe()` is how a pass learns the ratio, and the record's own doc comment says
-to expect it.
-
-Extensions add their own records with `create`:
-
-```js
-export class FogOfWarVisibility { grid; }   // a graph buffer handle
-
-// producer, at FrameStart
-frame.create(FogOfWarVisibility).grid = this.#update_grid(frame.graph);
-
-// consumer, at AfterTransparency
-if (frame.has(FogOfWarVisibility)) { ... }
-```
-
-Which is the second half of the fix for §1.1: the vocabulary is open, and extending it costs no
-edit to Shade.
-
-### 3.4 Publication
-
-A field on a record is an accessor. Writing it is publication:
-
-```js
-const scene = frame.get(SceneColor);
-
-const [fogged] = graph_image_pass({
-    graph: frame.graph,
-    shader: this.#shader,
-    output_resolution: frame.describe(scene.color).resolution,
-    inputs: { input_color: scene.color, input_depth: frame.get(ViewTextures).depth }
-});
-
-scene.color = fogged;   // the rest of the frame carries this
-```
-
-The setter asserts three things, all free in production:
-
-1. The record is not frozen (§3.3), and the frame index matches — a handle captured last frame
-   cannot be published this frame.
-2. `graph.is_valid_resource(handle)` — the handle is the current version of its resource.
-3. The current phase is one where the record is writable.
-
-Check 2 exists for **attribution**, not detection. The graph catches a superseded handle on its
-own: whoever reads it next trips `validate()`'s superseded-read check at `compile()` (§4). But that
-report names the *reader* — some built-in pass downstream — and says nothing about which extension
-put the bad handle into the record. Checking at the setter fails at the line that caused it, with
-the extension's name on it. It forbids nothing: one `ResourceEntry` owns one concrete resource, so
-an older node is not a snapshot of older contents and publishing one is wrong in every case.
-
-**A provenance check was considered here and rejected** — "the handle's producer is a pass recorded
-inside this extension's scope", which the record-time producer (§4) made possible. It would have
-forbidden a legitimate thing: `import_resource` leaves a node with no producer, so an extension that
-imports a texture it owns and publishes it as the frame's colour — a debug view, video playback —
-would have failed a check aimed at typos. What it uniquely caught, publishing a handle you read
-rather than wrote, surfaces immediately downstream anyway.
-
-Reading a field asserts frame identity and, for product-gated fields, that the *recording extension*
-declared the product (§3.7).
-
-**Publication is not the dependency edge.** The graph already has the edge: `FramePassBuilder.write`
-renames a written resource into a versioned clone and records the read, so "this pass consumed the
-colour as it stood and produced a new one" is already a graph fact. Publication is the *naming*
-step — which handle currently means "the scene colour". Keeping those two ideas separate is what
-lets the record model be this small.
-
-### 3.5 Phases
-
-`FrameStart`, `AfterGBuffer`, `AfterLighting`, `AfterTransparency`, `BeforePresent`, `Overlay`.
-
-**The upscale is a phase boundary, and saying so is part of what a phase means.** `AfterGBuffer`,
-`AfterLighting` and `AfterTransparency` are before it and run at internal resolution; TAA and NSS
-upscale to output resolution, so `BeforePresent` and `Overlay` are after it and run at output
-resolution.
-
-**Before the upscale is the common case, and the design leans on it.** An extension drawing into the
-scene belongs at `AfterTransparency`: its work is then temporally resolved, upscaled and sharpened
-along with everything else, and it is the cheapest place to draw because it draws at internal
-resolution. `BeforePresent` is the deliberate other choice — full output resolution, still HDR,
-nothing after it but the tonemap — and it is a trade, not an upgrade: work there gets no temporal
-history and costs full-resolution pixels. An extension that does not have a reason to be after the
-upscale should not be.
-
-One wrinkle, and it belongs to the renderer rather than to this design: with
-`feature_taa_enabled === false` the upscale does not happen at all — there is a `TODO` in `Renderer`
-saying exactly that — so in that configuration `BeforePresent` is at internal resolution. A derived
-`frame.resolution` (§3.2) is right in both configurations. A documented constant would be wrong in
-one, which is how the current mechanism ended up wrong in two.
-
-Five phases are the existing ones, unchanged in meaning. **`FrameStart` is the one addition**: a point after
-the view is updated and before anything is rasterized. It exists because per-frame GPU compute that
-later phases depend on currently has nowhere to go — fog of war's grid update, a custom cull, a
-procedural buffer build — so it is either bolted onto a draw pass at a later phase, which puts it in
-the wrong place in the graph and mis-attributes it in a capture, or done outside the graph entirely,
-which is precisely the aliasing-and-lifetime blindness §1.2 is about.
-
-Considered and rejected: `BeforeGBuffer` (nothing distinguishes it from `FrameStart` for anything an
-extension can do), `AfterShadows` (shadow rendering is per-light and interior to
-`GPULightCollection`; a phase there would be a lie about what is stable), per-post-effect phases
-(URP has seventeen events and their number is a symptom, not a feature).
-
-### 3.6 Ordering
-
-Within a phase, order is `relative_order` ascending. It defaults to 0, takes any finite number, and
-says nothing about any other extension: an extension states where it belongs from what it *does* — a
-fog conceals, so it is late; a debug overlay must not be concealed, so it is later still.
-
-Ties are broken by `name`, ascending. Stable and reproducible; deliberately *not* registration
-order, so that adding an `await` to a system's startup cannot change the picture.
-
-**This is coarse on purpose.** It cannot express "immediately after that one", and an effect that
-genuinely needs one particular extension's result has a real dependency rather than a positional
-one — it should read a record that extension published, which the graph then orders and keeps alive
-(§4). Because there are no edges there is no cycle: an order always resolves, and `add` refuses
-only a `relative_order` that is not a finite number.
-
-Name-order is stable, not correct. So the resolver also reports **ambiguity**: two extensions on one
-phase that publish the same field of the same record at the same `relative_order` — so that only
-their names separate them — is an assert failure naming both and the field. Publication goes through our setters, so the frame knows
-who published what — no extra syntax on the author's side. This is the check that would have made
-somebody write down what the six-deep `AfterTransparency` chain is supposed to be.
-
-The ambiguity check is per-frame and assert-only. It costs nothing in production and fires on the
-first frame in development.
-
-### 3.7 Products
-
-`FrameProduct` is a bitmask of things the frame *can* build but does not always:
-
-```js
-export const FrameProduct = {
-    /** per-object + camera velocity, built even when TAA and motion blur are off */
-    Velocity: 1,
-    /** a readable snapshot of the scene colour as it stood when the phase began */
-    ColorCopy: 2,
-};
-```
-
-The union over registered extensions is computed once per registration change, and the renderer
-consults it the way it consults its own feature flags. `ColorCopy` is produced immediately before
-the passes of each phase that requires it.
-
-Two members, because two have a nameable consumer: `Velocity` for any effect an extension wants to
-temporally reproject itself (currently built for TAA, unreachable by anyone else), and `ColorCopy`
-for refraction — a pass that rasterizes geometry *into* the live colour with a `load` op and must
-also sample what is behind it, which is refractive water and distortion particles. A full-screen
-pass that reads the colour and writes a new one does not need it and must not ask for it.
-
-Considered and deferred with reasons in §9: `HiZ`, `PreviousColor`, `SceneDepthPyramid`.
-
-This is the part of the design with the weakest present-day demand and it ships last (§10).
-
----
-
-## 4. What the frame graph does, and what it does not
-
-Stated plainly, because the design would be dishonest without it.
-
-`FrameGraph.execute` iterates `__pass_nodes` **in insertion order**. It does not topologically sort,
-and there is no plan for it to. What the graph gives is culling (`ref_count` propagation from
-unreferenced resources), transient resource lifetime and aliasing, versioned renaming of written
-resources, and export.
-
-So: **the graph does not order extensions; §3.6 does.** Every claim in this document about ordering
-is a claim about the resolver, not about the graph.
-
-**What the graph does instead of sorting is check.** The first draft of this document listed two
-implementation constraints the design had to route around. Both are now fixed, and a third thing
-landed that the design had assumed away, so the division of labour is different from what §3.6 was
-written against. The four that matter here — the full list and its evidence are in
-`engine/graphics/render/frame_graph/FRAME_GRAPH_RECOMMENDATIONS.md`:
-
-- **`validate()` proves the insertion order is a valid topological order**, and `compile()` asserts
-  on it. It reports a *read before write* (a pass reading a node a later pass produces) and a
-  *superseded read* (a pass reading a version an earlier pass has already replaced — one
-  `ResourceEntry` owns one concrete resource, so an older node is not a snapshot). This is the
-  honest answer to insertion-order execution: not to sort, but to refuse a recording whose order is
-  wrong. It is asserted, so it costs nothing shipped and fails the frame in development.
-- **The lifecycle is one-shot and stated.** `FrameGraphState`: `Recording` → `Compiled` →
-  `Executed`, monotonic, asserted at every mutating entry point. `compile()` was not idempotent and
-  `execute()` could not tell whether `compile()` had run — a graph executed uncompiled culls itself
-  entirely and says nothing. The design's old "the extension layer must never compile the graph
-  itself" caveat is deleted: the graph says so now.
-- **`ResourceNode.producer` is assigned at record time**, by `FramePassBuilder`, rather than in
-  `compile()`. So "this handle was produced by the pass that is publishing it" is answerable at
-  publication (§3.4).
-- **Recording scopes exist.** `push_scope(name)` / `pop_scope()` stamp every pass and resource node
-  created inside them, nesting through a parent chain. This supersedes §13's request for a
-  `pass_count` getter and is what §1.2's attribution complaint was asking for.
-
-One finding from that work belongs here rather than there, because it is the strongest available
-argument for the whole model: `validate()`, on its first run against the live 61-pass `Shading`
-graph, found that **Shade's own rasterization was not threading its colour targets.** Depth was
-threaded through the two-phase opaque pass and colour was not, so every rasterization pass read
-`out_color/0` at version 0 while depth advanced. It was harmless only because those passes write an
-imported resource and therefore always execute, and because insertion order happened to give the
-right picture — the colour dependency between them was simply not a graph fact. That is what
-"working around the graph rather than through it" costs, in the engine's own code, found the day
-someone checked.
-
-What remains true, and what §3.6 rests on: the graph checks that a recording order is *consistent*,
-never that it is the one anybody wanted. Two extensions each reading the colour and writing a new
-one are valid in either order. Data-order violations are the graph's; visual-order mistakes are
-§3.6's, and nothing else will catch them.
-
----
-
-## 5. Validation and diagnostics
-
-All of it under `assert`, which is compiled out of production builds — so the price of every check
-here is zero in a shipped game and the checks may be as thorough as they like.
-
-| check | when | what it catches |
-| --- | --- | --- |
-| record present at phase | `get` | reading `SceneColor` at `AfterGBuffer` — replaces `-1` |
-| record frozen | publish | publishing a G-buffer handle after shading |
-| frame identity | read + publish | a handle retained across frames |
-| `is_valid_resource` | publish | publishing a superseded handle, attributed to the extension |
-| product declared by the recording extension | read | reading `velocity` because *someone else* required it |
-| `relative_order` finite | registration | an order that no comparator can answer, so the phase would sort by luck |
-| publication ambiguity | end of phase | two extensions writing one field at the same `relative_order` |
-
-Beneath all of them the graph runs its own `validate()` inside `compile()` (§4), which catches the
-data-order failures this layer cannot see.
-
-Every one of these fires on a **statement that cannot be true** — a superseded handle names one
-physical resource holding newer contents, `NaN` is not a position, an undeclared collision has no
-answer. None of them fires on an extension that is behaving correctly. That is the bar; §5.1 is
-what happens when a check is written without holding to it.
-
-### 5.1 Culling is not an error, and no diagnostic here treats it as one
-
-An earlier revision of this document asked the graph to report per-scope culling so that "an
-extension whose entire recorded work was culled" could be an assert. **That was wrong and it is
-removed**, along with the engine change it needed. Three reasons, in increasing order of weight.
-
-Culling is what a frame graph is *for*. Frostbite's paper is about eliminating work nobody
-consumes; that is why the pattern spread. A mechanism cannot adopt the construct and then treat its
-central behaviour as a failure.
-
-The distinction it drew does not exist. "Culled built-in pass: optimisation. Culled extension pass:
-bug." Nothing about the recorder changes what culling means, and encoding the split would have made
-extensions second-class in the one place the design claims they are not.
-
-And it forbids the pattern this design exists to enable. §3.3's own worked example is an extension
-publishing `FogOfWarVisibility` at `FrameStart` for a consumer at `AfterTransparency`. Take the
-consumer out — disable fog — and the producer's work is dead, the graph elides it, and the frame is
-correct and cheaper. Under the assert that is a hard error. A speculative producer whose consumer
-may or may not be present is the whole point of an open record vocabulary, and the check would have
-outlawed it on day one.
-
-**What replaces it: nothing, because nothing is missing.** `exportToJson` already reports
-`culled` per pass and `exportToDot` already greys culled passes out; with the registry's scopes
-(§5.2) a culled extension is a grey cluster with its own name on it. An author asking "why did my
-pass not run" dumps the graph and sees it. That is a tool, not a tribunal.
-
-The culling contract itself is stated once, on `RenderExtension.record`, in the same terms it holds
-for every other pass in the graph: work whose output nothing consumes is elided; thread your result
-into a record and it is consumed; if you want work that runs regardless, `make_side_effect()` says
-so, exactly as it does for a built-in pass.
-
-### 5.2 Recording scopes
-
-**The registry opens a recording scope per extension**, named after it, around the `record()` call:
-
-```js
-graph.push_scope(extension.name);
-
-try {
-    extension.record(frame);
-} finally {
-    graph.pop_scope();
-}
-```
-
-The `finally` is not error handling — nothing is caught and nothing is swallowed. It is there
-because `compile()` asserts the scope stack came back empty, so an extension that throws while
-recording would otherwise fail on an unbalanced scope and bury the real error behind it. The throw
-propagates, decorated with the extension's name the way `FrameGraph` already decorates a failing
-pass with its own.
-
-**Scopes are for reading the frame back, not for policing it.** `exportToDot` puts each extension's
-passes in its own labelled cluster, nested as the scopes nest, and a graph that opens no scope
-exports byte-identically to before. That is the whole of §1.2's attribution complaint, answered by
-an API that already exists and that nothing currently calls — and it is what makes §5.1's answer to
-culling a real answer rather than a shrug: the grey box in the dump has the extension's name on it.
-
-No check depends on scopes. The one that did is gone (§5.1), and the provenance check that would
-have used `is_within` was rejected on its own merits (§3.4).
-
-`RenderExtensionRegistry.describe()` returns the resolved pipeline as text: per phase, the extensions
-in resolved order, each with the products it required and the records it publishes into. Printable
-without a device, which is what makes it testable without one.
-
----
-
-## 6. Lifecycle
-
-Registration is device-free and survives device loss — the current mechanism's one clearly right
-decision, kept. `GraphicsEngine` holds the extension list; a renderer replaced by a restart is
-re-populated from it. A system registers once at startup without knowing whether a device exists.
-
-```js
-graphics.add_extension(extension);      // returns the extension
-graphics.remove_extension(extension);   // returns whether it was registered
-```
-
-Identity is the object, so the phase no longer has to be passed to removal. Registering or removing
-during `record` is an assert failure.
-
-`GraphicsEngine` gains no surface it did not have: this replaces `add_pass` / `remove_pass`
-one-for-one, so D14's "the facade does not grow" holds. `pass_count(phase)` becomes
-`extension_count(phase)`, which the start → stop → start leak gate needs.
-
-**Views.** There is one injection site today: the primary view inside `render_to_target`. Shadow
-views, probe bakes and picking do not run extensions and this design does not change that. When a
-second view kind gains injection points, the filter belongs on the registry and the extension gains
-a declaration for it; building that now would be inventing a contract for a caller that does not
-exist.
-
----
-
-## 7. The whole API
-
-That is the entire surface.
-
-```js
-// declaration
-class RenderExtension { name; phase; relative_order; requires; record(frame); }
-const FramePhase = { FrameStart, AfterGBuffer, AfterLighting, AfterTransparency, BeforePresent, Overlay };
-const FrameProduct = { Velocity, ColorCopy };
-
-// recording
-class FrameContext { graph; view; phase; resolution; get(type); has(type); create(type); describe(handle); }
-
-// built-in records
-class GBufferTextures { albedo; normal; pbr; emissive; }
-class ViewTextures { depth; depth_previous; visibility_mesh; visibility_triangle; velocity; }
-class SceneColor { color; copy; }
-class PresentTarget { canvas; }
-
-// registration
-class RenderExtensionRegistry { add(e); remove(e); count(phase); describe(); run(frame); }
-// on GraphicsEngine / Renderer
-add_extension(e); remove_extension(e); extension_count(phase);
-```
-
----
-
-## 8. Migration
-
-Nine live systems and one probe. Every one of them is the same mechanical change:
-a closure becomes a class, `context.color` becomes `frame.get(SceneColor).color`, and the return
-value becomes a publication.
-
-| consumer | phase | change beyond the mechanical |
-| --- | --- | --- |
-| `TerrainSystem` | `AfterGBuffer` | drops the registration-before-`await` comment; nothing else |
-| `DecalSystem` | `AfterGBuffer` | `relative_order = 1`, which is what the comment in `TerrainSystem` was hand-enforcing; stops assigning through `context.gbuffer` |
-| `WaterSystem` | `AfterLighting` | publication instead of return; a candidate first consumer of `FrameProduct.ColorCopy` if refraction is wanted |
-| `FogOfWarSystem` | `AfterTransparency` | the grid update becomes a `FrameStart` extension publishing `FogOfWarVisibility`, and the composite reads it; `relative_order = 1` — **this is where §1.3a's shipped bug is fixed** |
-| ~~`ParticleEmitterSystem`~~ | ~~`AfterTransparency`~~ | *removed 2026-09-28 with the CPU particle system; the GPU particles draw inside the transparency pipeline* |
-| `PathDisplaySystem` | `AfterTransparency` | — |
-| `HighlightSystem` | `AfterTransparency` | reads `ViewTextures.visibility_*`, unchanged in meaning |
-| `DebugDrawSystem` | `AfterTransparency` | `relative_order = 2` |
-| `Trail3DSystem` | ~~`AfterTransparency`~~ | *since 2026-09-24 a transparency channel, not an extension — see the revision note at the top* |
-| `probeShadePassInjection` | all | the gate is rewritten and gains the two checks it is currently blind to: a G-buffer replacement, and an order flip |
-
-**The `AfterTransparency` chain is settled, not open.** Fog of war is after the content
-extensions, because it conceals and therefore belongs over everything it is meant to conceal —
-particles, trails, path display and the selection highlight all sit at the default order and are all
-subject to it. Debug draw is the single deliberate exception at `relative_order = 2`: developer
-geometry that the fog can hide is a debugging tool that stops working exactly where debugging is
-needed.
-
-That is six extensions and two numbers. Written down once, in the two files that care, instead of
-being a property of where an `await` sits — and a seventh content extension is concealed by being
-added, without either of those two files changing.
-
-**The bug does not have to wait for the migration.** Today's ordering is registration order, so
-moving `FogOfWarSystem` below `Trail3DSystem` in `graphics_profile.js` fixes the picture now — at
-the cost of it being another undeclared ordering fact, which is what this design exists to end.
-
----
-
-## 9. Non-goals and known limits
-
-**Shade's own frame is not rewritten into a list of extensions.** URP's real strength is that
-built-in and injected passes are the same type. Getting there means restructuring
-`Renderer.render_to_target`, and renderer internals are hands-off. The consequence, stated so it is
-not discovered later: injection points remain hand-placed call sites, so the phase set is only as
-good as the places the renderer publishes records, and an extension cannot insert itself between two
-built-in post passes.
-
-**Extensions cannot participate in OIT.** Work at `AfterTransparency` composites over the resolved
-transparency; it cannot interleave with sorted transparents. True today, unchanged, and the honest
-reason the phase model has a ceiling. *2026-09-24:* the ceiling is on extensions, not on callers —
-content that has to interleave registers a transparency channel (`AVBOITSideChannel`) instead, which
-is asked for its contribution inside the AVBOIT pipeline; trails do.
-
-**Extensions cannot add to a built-in pass** — no extra material variants in the G-buffer raster, no
-extra lights. A new pass is the only unit.
-
-**No `FrameProduct` for `HiZ` / `PreviousColor` / depth pyramid yet.** Each is built by the renderer
-and each would be a one-line addition, and none has a consumer today. Adding them speculatively puts
-three untested branches in the renderer's product wiring.
-
-**No view kinds.** §6.
-
-**Ordering ambiguity is caught at frame time, not registration time**, because publication is
-observed rather than declared. Declaring publications up front would catch it earlier at the cost of
-a second declaration that can disagree with the code; observation cannot disagree with the code.
-
----
-
-## 10. Delivery
-
-Three steps, each independently green.
-
-- **A — the model.** Records, `FrameContext`, publication with all four checks, registry with
-  ordering and scoped recording. Port the nine systems and the viewer. Delete
-  `FramePassContext`, `FramePassRegistry` and `add_pass` / `remove_pass`. `FrameStart` and
-  `PresentTarget` land here, because they are what the fog-of-war split and the `Overlay` rule need.
-- **B — diagnostics.** Ambiguity check and `describe()`. Nothing here waits on the engine; scoped
-  recording lands in A, because it needs nothing that is not already there.
-- **C — products.** `FrameProduct.Velocity` and `ColorCopy`, and the renderer wiring that honours
-  them.
-
-A is the whole of the user-visible design. B is what makes it hold. C is the part with the weakest
-demand and it is separable on purpose.
-
----
-
-## 11. Tests and gates
-
-Device-free (`vitest`, from the moh root), black-box, real objects:
-
-- resolved order for a set of extensions with a `relative_order`, positive and negative; ties
-  resolve by name and the result does not change when registration order does; an order that is not
-  a finite number is refused and leaves the registry as it was.
-- `get` of an absent record throws; `create` twice throws; `has` agrees with both.
-- publication of a superseded handle fails; publication into a frozen record fails; a handle from a
-  previous frame fails. `FrameGraph` and a `SoftwareGPUDevice` are enough for all of these — no real
-  device, per the standing rule.
-- **an extension whose output nothing consumes is culled, and that is not an error** — the frame
-  renders, no assert fires, and the pass reports `culled` in the JSON export. Pinned as a test
-  because it is a property somebody will otherwise "fix" (§5.1).
-- an extension's passes land inside its own DOT cluster, and a graph recorded with no extensions
-  exports exactly as it did before. The scope machinery is already specced on the graph; what this
-  adds is that the registry opens and closes one per extension, including when `record()` throws.
-- `describe()` output is stable and contains every registered extension.
-- registry survives a simulated renderer replacement with the same extensions in the same order.
-
-On a device, extending `probeShadePassInjection`:
-
-- a colour-writing extension at each colour-carrying phase, in and out, restoring to within the
-  existing 25% bar.
-- **a G-buffer-replacing extension at `AfterGBuffer`** — writes a flat albedo, and the lit frame
-  changes. The current gate has no such check, which is why the in/out G-buffer has never been
-  exercised outside the decal system.
-- **an order flip** — two extensions publishing the colour, with their `relative_order` swapped
-  between runs, producing different frames. This is the property the current mechanism cannot state
-  at all.
-- **the upscale boundary, at 60% dynamic resolution scale**: an extension at `AfterTransparency` and
-  one at `BeforePresent`, each sizing its output from `frame.resolution`, both producing a full,
-  uncropped frame. They must resolve to *different* sizes. The `BeforePresent` half of this fails on
-  the current mechanism (§1.3b), and the same check run with `feature_taa_enabled = false` must
-  still pass, which is what pins `resolution` as derived rather than declared.
-- **fog of war over particles** — the `AfterTransparency` chain resolved from declarations, with a
-  particle emitter inside the concealed region staying concealed. This is §1.3a's bug, as a gate.
-
----
-
-## 12. Adversarial review
-
-The design above is the post-review version. What follows is what was attacked and what changed.
-
-**"A type-keyed container is a registry, and the house rule forbids registries."** The rule forbids
-*string*-keyed factories chosen to save boilerplate. A class is a type; the container is a typed
-map. The alternative — a struct with fixed fields — is defect §1.1 restated. *Survived, with the
-concession that every built-in record is an ordinary class with named fields, so the container is
-the only indirection.*
-
-**"You claim the graph orders passes. It executes in insertion order."** Correct, and the first
-draft leaned on the graph for ordering. **Changed:** §4 now states the execution model outright, and
-every ordering claim is attributed to the resolver. The design would have been wrong without this.
-
-> *Since.* The graph answered this from its own side rather than by being routed around: `validate()`
-> now proves that the recorded insertion order is a valid topological order and `compile()` asserts
-> on it. The design's position is unchanged — §3.6 still owns ordering — but the failure mode it was
-> protecting against narrowed sharply. A recording order that is *inconsistent* is now the graph's
-> to reject; §3.6 is left owning the orders that are consistent and still wrong, which is exactly
-> the fog-over-particles case (§1.3a) and is the only kind of ordering bug the game actually had.
-
-**"A constraint over classes is an import, and you have just given the debug overlay a dependency on
-the fog of war."** Correct, and not caught here: it was caught by the shipped code, where
-`DebugDrawSystem` imports `FogOfWarExtension` at module scope for no reason but to say "on top".
-**Changed, 2026-09-16:** §3.6 is `relative_order`, a number that names nothing. The cost is real
-and is stated rather than argued away — an offset cannot express "immediately after that one", and
-§1.4 rejected offsets for being imprecise. The answer to the case that needs precision is that it is
-not a positional requirement at all: it is a data dependency, and a published record states it
-exactly and is enforced by the graph.
-
-**"`scene.color = handle` is untracked mutation — the same side channel you criticised
-`context.gbuffer` for being."** Half right. The criticism of `context.gbuffer` was that it was the
-*only* extra mutable thing, at *one* phase, invisible in the pass signature. **Changed:** publication
-is now uniform across every record and validated at the setter — freeze state, frame identity, and
-`is_valid_resource` against the graph. The last of those catches a class of silent wrong-picture bug
-that neither the current mechanism nor URP catches at all.
-
-**"You deleted `resolution` and told every extension to call `describe()`. That is a worse API for
-the case everyone has."** Fair, and the first draft did exactly that in reaction to defect (b).
-**Changed:** `frame.resolution` came back as a derived getter over the phase's live target handle,
-so the common case is one property access *and* correct on both sides of the upscale, with
-`describe()` left for the genuinely two-sized case. The lesson from (b) is that the number must not
-be a field somebody fills in, not that the number should be hard to get.
-
-**"Ambiguity detection needs the frame to know who is recording — hidden global state."** One field,
-set by the loop that calls `record`. Re-entrant recording is an assert failure. *Survived.*
-
-**"Alphabetical tie-breaking is arbitrary. Why is arbitrary-by-name better than
-arbitrary-by-registration?"** Because it does not change when a system's `startup` gains an `await`.
-Reproducibility is the property, not correctness. **Changed:** the ambiguity check was added in the
-same pass, so an arbitrary order between two extensions that actually conflict is an error rather
-than a silently-chosen order.
-
-**"`FrameProduct` is a closed enum, so §1.1 is only half fixed."** Concede. The frame's own optional
-products are Shade's features and enumerating them is correct; the *open* half is the record
-vocabulary, which needs no engine edit. **Changed:** §3.7 says this, the enum was cut to two members
-with named consumers, and it was moved to the last delivery step.
-
-**"An `enabled` flag and an early return from `record` are two ways to do one thing."** Agreed.
-**Changed:** the flag was cut.
-
-**"`get_or_create` is friendlier than three methods."** It is, and it destroys the property that
-made `-1` go away: absent has to stay distinguishable from empty. *Rejected.*
-
-**"Six phases plus a blackboard plus a topological sort, to replace two methods, for nine
-consumers."** The two methods currently need four paragraphs of documentation about culling, carry a
-wrong resolution at two of five phases, and enforce a documented ordering requirement through the
-placement of an `await`. The sort is thirty lines over at most a dozen nodes. *Survived, and it is
-the reason §10 splits diagnostics out: if the sort and the records are the value, B and C can be
-judged separately.*
-
-**"`SceneColor` absent at `Overlay` means an extension that wants the tonemapped image just gets a
-throw."** Yes, with a message naming `BeforePresent`. That is strictly better than the current
-outcome, which is a validation error from inside a binding builder, and it is better than the
-documentation-only fix that shipped, which was discovered by measurement after the fact. *Survived.*
-
-**"The migration makes somebody decide the `AfterTransparency` order, and they may get it wrong."**
-It was decided while this document was under review, and the order in the shipped game turned out to
-be wrong (§1.3a). That is the argument for declaring it, not a counter to it — a mechanism where the
-answer is written down is a mechanism where being wrong is a diff. **Changed:** §8 states the
-resolved chain instead of leaving it open.
-
-**"`describe()` is a feature nobody asked for."** It is the only thing that makes "the frame graph is
-a first-class construct" mean something testable at this seam — a pipeline you can print without a
-device is a pipeline you can spec without a device. *Survived, in delivery step B.*
-
-**"Culling is what a frame graph is for. You made it an error for one class of user."** Sponsor, on
-the revision that asked the graph to report per-scope culling so a fully-culled extension could
-assert. **The objection is correct and the check is gone (§5.1).** Three ways it was wrong, and the
-review that produced the rest of this document did not catch any of them:
-
-- It adopted the construct and then treated its central behaviour as a failure.
-- The line it drew — culled built-in pass is optimisation, culled extension pass is a bug — has
-  nothing behind it. Who recorded a pass does not change what culling means.
-- Fatally, it outlawed a pattern this document's own §3.3 puts forward as the reason the record
-  vocabulary is open: an extension publishing `FogOfWarVisibility` for a consumer that may not be
-  registered. Disable the consumer and the producer is correctly elided — and the assert would have
-  called that a hard error. A speculative producer is the point, not an accident.
-
-Withdrawn with it: `FRAME_GRAPH_RECOMMENDATIONS.md` item 5, which was the last open engine change,
-and the provenance check in §3.4, which fell to the same standard once it was applied consistently
-— it forbade publishing an imported texture in order to catch a typo. What the argument leaves
-standing is a bar the remaining checks are now stated against: **a check may only fire on something
-that cannot be true**, never on an extension behaving correctly.
-
----
-
-## 13. Engine changes required
-
-Small, and enumerated so the blast radius is visible. **`FrameGraph` needs nothing.** The graph-side
-items this document originally asked for have either landed or been withdrawn — the last of them,
-the culling report, was withdrawn on the reasoning in §5.1. Everything below is renderer and facade
-work.
-
-1. `Renderer` publishes records at six points instead of filling one context at five. The record
-   objects are built where `#frame_pass_context` is built today.
-2. `Renderer` gains a `FrameStart` call site, and (delivery C) honours the product union when
-   deciding whether to build velocity and the colour copy.
-3. `GraphicsEngine` swaps `add_pass`/`remove_pass`/`pass_count` for
-   `add_extension`/`remove_extension`/`extension_count`. No net surface change.
-4. `src/shade/renderer/pass/` becomes `src/shade/renderer/extension/`. The folder is MEEP 3's, not
-   Shade's, and "pass" collides with `FramePassNode` — the graph's passes and an extension are
-   different things and should not share a word.
-
-Nothing in Shade's frame structure, no pass reordering, no change to how built-in passes record.
-
-**Already done, and nothing further is needed from them** — `FrameGraphState` and its asserts,
-`validate()` with both order checks, `push_scope` / `pop_scope` and DOT clustering,
-`ResourceNode.producer` at record time, and the `exportToJson` fix. `getDescriptor`,
-`is_valid_resource` and `onExecuted` were already there and the design uses them as they stand.