@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,918 +1,918 @@
-# 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.
-
----
-
-## 0. Summary
-
-An extension is a **named object with declarations** — a phase, ordering constraints, 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.** `TerrainSystem3.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).
-- **`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 ordering diagnostics, error decoration and `describe()`.
-     * @type {string}
-     */
-    name = "";
-
-    /** @type {FramePhase} */
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * Extension classes this one records after / before. Constructors, not instances — an
-     * extension does not need a reference to another system's object to state an order.
-     * @type {Function[]}
-     */
-    after = [];
-    before = [];
-
-    /**
-     * 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 the topological order of the `after` / `before` edges. Cycles throw at
-registration, naming the cycle. Both directions exist because an extension that must precede one it
-cannot edit is exactly the case an extension mechanism is for.
-
-Unconstrained pairs 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.
-
-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, with no ordering path between 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 |
-| ordering cycle | registration | `after`/`before` cycle, named |
-| publication ambiguity | end of phase | two extensions writing one field with no order between them |
-
-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, a cycle has no order, 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. `GraphicsEngine3` 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.
-
-`GraphicsEngine3` 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; after; before; 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 GraphicsEngine3 / Renderer
-add_extension(e); remove_extension(e); extension_count(phase);
-```
-
----
-
-## 8. Migration
-
-Nine live systems, one probe, one prototype viewer. 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 |
-| --- | --- | --- |
-| `TerrainSystem3` | `AfterGBuffer` | drops the registration-before-`await` comment; nothing else |
-| `DecalSystem3` | `AfterGBuffer` | `after: [TerrainExtension]`, which is the constraint the comment in `TerrainSystem3` was hand-enforcing; stops assigning through `context.gbuffer` |
-| `WaterSystem3` | `AfterLighting` | publication instead of return; a candidate first consumer of `FrameProduct.ColorCopy` if refraction is wanted |
-| `FogOfWarSystem3` | `AfterTransparency` | the grid update becomes a `FrameStart` extension publishing `FogOfWarVisibility`, and the composite reads it; declares `after` the four content extensions — **this is where §1.3a's shipped bug is fixed** |
-| `ParticleEmitterSystem3` | `AfterTransparency` | — (now before the fog, by declaration) |
-| `PathDisplaySystem3` | `AfterTransparency` | — |
-| `HighlightSystem3` | `AfterTransparency` | reads `ViewTextures.visibility_*`, unchanged in meaning |
-| `DebugDrawSystem3` | `AfterTransparency` | `after: [FogOfWarExtension]` |
-| `Trail3DSystem3` | `AfterTransparency` | — |
-| `probeShadePassInjection` | all | the gate is rewritten and gains the two checks it is currently blind to: a G-buffer replacement, and an order flip |
-| `prototypeVGEOFormatViewer` | `AfterTransparency` | prototype; mechanical |
-
-**The `AfterTransparency` chain is settled, not open.** Fog of war is last among 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 draw before it and are all subject
-to it. Debug draw is the single deliberate exception, `after: [FogOfWarExtension]`: 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 declarations. Written down once, in the two files that care, instead
-of being a property of where an `await` sits.
-
-**The bug does not have to wait for the migration.** Today's ordering is registration order, so
-moving `FogOfWarSystem3` below `Trail3DSystem3` 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.
-
-**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, cycle detection 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 `after` / `before`; a cycle throws and names both;
-  unconstrained pairs resolve by name and the result does not change when registration order does.
-- `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 the `after` edge reversed 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.
-
-**"`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. `GraphicsEngine3` 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.
+# 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.
+
+---
+
+## 0. Summary
+
+An extension is a **named object with declarations** — a phase, ordering constraints, 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.** `TerrainSystem3.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).
+- **`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 ordering diagnostics, error decoration and `describe()`.
+     * @type {string}
+     */
+    name = "";
+
+    /** @type {FramePhase} */
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * Extension classes this one records after / before. Constructors, not instances — an
+     * extension does not need a reference to another system's object to state an order.
+     * @type {Function[]}
+     */
+    after = [];
+    before = [];
+
+    /**
+     * 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 the topological order of the `after` / `before` edges. Cycles throw at
+registration, naming the cycle. Both directions exist because an extension that must precede one it
+cannot edit is exactly the case an extension mechanism is for.
+
+Unconstrained pairs 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.
+
+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, with no ordering path between 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 |
+| ordering cycle | registration | `after`/`before` cycle, named |
+| publication ambiguity | end of phase | two extensions writing one field with no order between them |
+
+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, a cycle has no order, 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. `GraphicsEngine3` 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.
+
+`GraphicsEngine3` 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; after; before; 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 GraphicsEngine3 / Renderer
+add_extension(e); remove_extension(e); extension_count(phase);
+```
+
+---
+
+## 8. Migration
+
+Nine live systems, one probe, one prototype viewer. 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 |
+| --- | --- | --- |
+| `TerrainSystem3` | `AfterGBuffer` | drops the registration-before-`await` comment; nothing else |
+| `DecalSystem3` | `AfterGBuffer` | `after: [TerrainExtension]`, which is the constraint the comment in `TerrainSystem3` was hand-enforcing; stops assigning through `context.gbuffer` |
+| `WaterSystem3` | `AfterLighting` | publication instead of return; a candidate first consumer of `FrameProduct.ColorCopy` if refraction is wanted |
+| `FogOfWarSystem3` | `AfterTransparency` | the grid update becomes a `FrameStart` extension publishing `FogOfWarVisibility`, and the composite reads it; declares `after` the four content extensions — **this is where §1.3a's shipped bug is fixed** |
+| `ParticleEmitterSystem3` | `AfterTransparency` | — (now before the fog, by declaration) |
+| `PathDisplaySystem3` | `AfterTransparency` | — |
+| `HighlightSystem3` | `AfterTransparency` | reads `ViewTextures.visibility_*`, unchanged in meaning |
+| `DebugDrawSystem3` | `AfterTransparency` | `after: [FogOfWarExtension]` |
+| `Trail3DSystem3` | `AfterTransparency` | — |
+| `probeShadePassInjection` | all | the gate is rewritten and gains the two checks it is currently blind to: a G-buffer replacement, and an order flip |
+| `prototypeVGEOFormatViewer` | `AfterTransparency` | prototype; mechanical |
+
+**The `AfterTransparency` chain is settled, not open.** Fog of war is last among 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 draw before it and are all subject
+to it. Debug draw is the single deliberate exception, `after: [FogOfWarExtension]`: 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 declarations. Written down once, in the two files that care, instead
+of being a property of where an `await` sits.
+
+**The bug does not have to wait for the migration.** Today's ordering is registration order, so
+moving `FogOfWarSystem3` below `Trail3DSystem3` 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.
+
+**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, cycle detection 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 `after` / `before`; a cycle throws and names both;
+  unconstrained pairs resolve by name and the result does not change when registration order does.
+- `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 the `after` edge reversed 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.
+
+**"`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. `GraphicsEngine3` 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.