refactor(engine)!: GPU pass fusion — record-then-plan pipeline with fused shader passes

.gitignore

@@ -389,3 +389,4 @@ telemetry-data.json
 
 # `.mcp.json` is team-shared (see docs/ai-workflow/README.md); override any global gitignore
 !.mcp.json
+

.specify/memory/constitution.md

@@ -22,7 +22,7 @@ Beutl targets `net10.0` and `net10.0-windows`. Both targets must keep building.
 
 ### III. Test-First with NUnit
 
-- Test framework is NUnit + Moq. Tests are organized under `tests/` in per-area projects (e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available.
+- Test framework is NUnit + Moq. Tests are organized under `tests/` in per-area projects (e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.PublicApiContractTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.PublicApiContractTests/` is the non-friend compile gate for public authoring APIs; `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available.
 - New logic in `src/` is incomplete without an accompanying test.
 - Benchmarks (`tests/Beutl.Benchmarks`, `tests/Beutl.FFmpegBenchmarks`) use BenchmarkDotNet and are excluded from regular `dotnet test` runs.
 - CI quality gate: `dotnet test Beutl.slnx -f net10.0 --settings coverlet.runsettings` must pass, with the coverage threshold configured in [`.github/workflows/dotnet.yml`](../../.github/workflows/dotnet.yml) honored.

AGENTS.md

@@ -13,7 +13,7 @@ Beutl is a cross-platform video editing / compositing application built on Avalo
 
 - License: the main app is **MIT**; `Beutl.FFmpegWorker` alone is **GPL-3.0-or-later** (a separate process)
 - UI: Avalonia (XAML + ViewModel)
-- Tests: NUnit + Moq under `tests/` (per-area projects, e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available — see `tests/CLAUDE.md`
+- Tests: NUnit + Moq under `tests/` (per-area projects, e.g. `tests/Beutl.UnitTests/`, `tests/Beutl.PublicApiContractTests/`, `tests/Beutl.Graphics3DTests/`, `tests/SourceGeneratorTest/`, `tests/Beutl.FFmpegIpc.Tests/`). `tests/Beutl.PublicApiContractTests/` is the non-friend compile gate for public authoring APIs; `tests/Beutl.Graphics3DTests/` is a Vulkan-gated NUnit suite that self-skips when no Vulkan device is available — see `tests/CLAUDE.md`
 - E2E / headless-UI tests: `tests/Beutl.E2ETests/` (library-level) and `tests/Beutl.HeadlessUITests/` (drives the real shell, the sole test referencing `src/Beutl`) on `Avalonia.Headless.NUnit`, with shared helpers in `tests/Beutl.Testing.Headless/`. They run on headless CI without xvfb or a GPU — see `tests/CLAUDE.md`
 - Build: Nuke (`nukebuild/`) or `dotnet` directly
 

Beutl.slnx

@@ -36,6 +36,7 @@
     <Project Path="tests\Beutl.UnitTests\Beutl.UnitTests.csproj" />
     <Project Path="tests\Beutl.E2ETests\Beutl.E2ETests.csproj" />
     <Project Path="tests\Beutl.HeadlessUITests\Beutl.HeadlessUITests.csproj" />
+    <Project Path="tests\Beutl.PublicApiContractTests\Beutl.PublicApiContractTests.csproj" />
     <Project Path="tests\Beutl.Testing.Headless\Beutl.Testing.Headless.csproj" />
     <Project Path="tests\SourceGeneratorTest\SourceGeneratorTest.csproj" />
     <File Path="tests\ArtifactProvider.cs" />

docs/specs/003-resolution-independent-pipeline/contracts/public-api.md

@@ -2,6 +2,14 @@
 
 **Feature**: 003 | Consumers: `Beutl.NodeGraph`, `Beutl.Extensibility`, out-of-tree plugin drawables/effects, `Beutl.ProjectSystem`, `Beutl` (editor).
 
+> **Superseded API note (Feature 004):** the symbol table, call-site inventory, and downstream
+> migration summary below record the Feature 003 API at the time it shipped. Feature 004 removes
+> `RenderNodeOperation`/`RenderNodeProcessor` and revises the filter-effect compatibility surface.
+> Use Feature 004's [breaking-change contract](../../004-gpu-pass-fusion/contracts/breaking-changes.md)
+> and [public API contract](../../004-gpu-pass-fusion/contracts/public-api.md) for current migration
+> instructions. For current author guidance, use
+> [Resolution-independent rendering](../../../ai-workflow/resolution-independent-rendering.md).
+
 This feature ships as a **breaking change**: `refactor!:` / `feat!:` with a `BREAKING CHANGE:` footer naming `Beutl.Engine`, `Beutl.NodeGraph`, `Beutl.ProjectSystem`. **No `[Obsolete]` shims** (AGENTS.md); all in-tree call sites updated in the same change. Route through `beutl-design-reviewer` (FR-028). **No file-format change** (FR-001/SC-002).
 
 ## Breaking symbols
@@ -11,14 +19,14 @@ This feature ships as a **breaking change**: `refactor!:` / `feat!:` with a `BRE
 | `RenderNodeContext` ctor | `Rendering/RenderNodeContext.cs:3` | `ctor(RenderNodeOperation[] input)` | `ctor(input, float outputScale = 1f, float maxWorkingScale = +∞)` + `float OutputScale { get; }` + `float MaxWorkingScale { get; }` + `static float ResolveWorkingScale(inputs, outputScale, maxWorkingScale)` (FR-036 floor rule `min(max(s_out, supply), max)`, **no `policy` param**). The ctor **sanitizes degenerate inputs once** so downstream consumers (effects, particles, 3D) need not re-validate: a non-finite / non-positive `OutputScale` (`0`/`NaN`/`∞`) → `1`, a `NaN` / non-positive `MaxWorkingScale` → `+∞` (no ceiling). | Sole construction at `RenderNodeProcessor.cs:176`; reaches ~28 `Process` overrides (FR-004) |
 | `RenderNodeOperation` | `Rendering/RenderNodeOperation.cs:6-64` | 4 static factories, `Bounds`/`Render`/`HitTest` | + `EffectiveScale EffectiveScale { get; }` (**value type**, default `Unbounded`); factories gain `EffectiveScale effectiveScale = default`. **No `LosslessReRasterizable` bool** — `IsUnbounded` subsumes it | Subclasses + `FilterEffectRenderNode.cs:47,73`, `RenderNodeProcessor.cs:102`, `ParticleRenderNode.cs:83`, `SceneDrawable.cs:185` |
 | `EffectiveScale` (new type) | `Rendering/EffectiveScale.cs` | — | **As shipped:** a non-positional `readonly record struct` with a private inverted `_bounded` flag (NOT the positional `(float Value, bool IsUnbounded)` form — that would make `default` wrongly `At(0)`); `Unbounded`/`At(float)`/**`AtOrUnbounded(float)`**/`IsUnbounded`/`Value`; `default == Unbounded`. **`At(scale)` THROWS** `ArgumentOutOfRangeException` on a non-finite / non-positive density and the render pull path has **no try/catch** (a throw aborts the render), so a plugin `RenderNodeOperation`/`EffectiveScale` override deriving a density from animatable geometry MUST pre-guard the quotient or use the non-throwing **`AtOrUnbounded`** (degrades a bad density to `Unbounded`). | FR-018; produced by flushed effect buffers (`At(w)`), `CreateTarget`, 3D surfaces; consumed by `EffectTarget.Draw` + the op factories |
-| ~~`ResolutionPolicy` (new type)~~ **NOT shipped** | — | — | **Removed.** Earlier drafts added a `readonly record struct ResolutionPolicy` (`Inherit`/`ClampToOutput`/`Oversample(k)`, `PreserveSource` already dropped) + a `virtual FilterEffect.ResolutionPolicy`. No built-in needed a non-default value and a custom `FilterEffectRenderNode` is strictly more flexible, so the type, the virtual, the never-added `RenderNode.ResolutionPolicy`, and the `ResolveWorkingScale` `policy` param were all removed. An effect needing a non-supply `w` overrides `Process` in a node from `FilterEffect.Resource.CreateRenderNode()`. | FR-036 |
+| ~~`ResolutionPolicy` (new type)~~ **NOT shipped** | — | — | **Removed.** Earlier drafts added a `readonly record struct ResolutionPolicy` (`Inherit`/`ClampToOutput`/`Oversample(k)`, `PreserveSource` already dropped) + a `virtual FilterEffect.ResolutionPolicy`. No built-in needed a non-default value, so the type, the virtual, the never-added `RenderNode.ResolutionPolicy`, and the `ResolveWorkingScale` `policy` param were removed. An effect needing a non-supply `w` overrides `GetWorkingScaleContract()` in a node from `FilterEffect.Resource.CreateRenderNode()`; overriding `Process` is reserved for genuinely different topology/lowering. | FR-036 |
 | `RenderNodeProcessor` ctor | `Rendering/RenderNodeProcessor.cs:6` | `ctor(RenderNode root, bool useRenderCache)` | `ctor(root, useRenderCache, float outputScale = 1f, float maxWorkingScale = +∞)` + `float OutputScale { get; }` + `float MaxWorkingScale { get; }`; rasterization sinks rasterize at `OutputScale` (`PixelRect.FromRect(bounds, OutputScale)`); the per-input working scale is resolved at `FilterEffectRenderNode` | `Renderer.cs:214`, `NodeGraphFilterEffectRenderNode.cs:45`, `ParticleRenderNode.cs:144` |
 | `Renderer` ctor | `Rendering/Renderer.cs:45` | `ctor(int width, int height)` | `ctor(int width, int height, float renderScale = 1f, float maxWorkingScale = float.PositiveInfinity)` (the output scale `s_out` + the FR-037 ceiling) + `OutputScale`/`DeviceSize` getters; width/height **logical**, surface `ceil(FrameSize×s_out)` | FR-003/FR-026/FR-037; `SceneDrawable.cs:181`, `EditViewModel.cs:75`, `OutputViewModel.cs:283` |
 | `IRenderer` | `Rendering/IRenderer.cs:7` | — | + `float OutputScale { get; }`, + `PixelSize DeviceSize { get; }` (default-interface-impl → `1f`/`FrameSize` to soften third-party impls, mirroring `GetBoundary` default at `:30`) | third-party `IRenderer` implementers |
 | `SceneRenderer` ctor | `ProjectSystem/SceneRenderer.cs:10` | `ctor(Scene scene, bool disableResourceShare = false)` | `ctor(Scene scene, float renderScale = 1f, bool disableResourceShare = false, float maxWorkingScale = float.PositiveInfinity)` | `EditViewModel.cs:75` (passes `maxWorkingScale: 2f * s_out`), `OutputViewModel.cs:283` (passes `+∞` — export imposes no working-scale quality ceiling, *amended 2026-06-15*; was `max(8, 4 × s_out)`) |
 | `GraphicsContext2D` ctor + `Size` | `Rendering/GraphicsContext2D.cs:9` | `ctor(ContainerRenderNode, PixelSize canvasSize = default)`; `PixelSize Size` | **As shipped:** `ctor(ContainerRenderNode, Size canvasSize = default, float outputScale = 1f)` + `OutputScale`; **`Size` is now an exact logical `Size`** (float), not a rounded `PixelSize` — it feeds `Drawable.Render`'s `MeasureCore`/`GetTransformMatrix` where a fractional viewport changes placement, so readers drop the `.ToSize(1)`. `DrawBackdrop` uses `new Rect(canvasSize)` | FR-021; **most-consumed changed ctor** — full call-site list below |
 | `ImmediateCanvas` / `ICanvas` (**density-aware logical surface**) | `Graphics/ImmediateCanvas.cs`, `Graphics/ICanvas.cs` | `ctor(RenderTarget, float outputScale = 1f, float maxWorkingScale = +∞)`; `PixelSize Size`; `float OutputScale`; public `Matrix Transform { get; set; }` | **As shipped (base-CTM redefinition):** the canvas **bakes** the base CTM `CreateScale(density)` at construction (true no-op at density 1). `ctor(RenderTarget, float density = 1f, float maxWorkingScale = +∞, Size logicalSize = default)`; `ICanvas.Size` → **`LogicalSize` (`Size`) + `DeviceSize` (`PixelSize`)**; `OutputScale` → **`SurfaceDensity`** (immutable, drives base CTM + snapshot capture) + **`Density`** (current, push/pop, drives brush fills + nested pulls); new **`PushDeviceSpace()`** (CTM → identity, density → 1) on `ICanvas`; `Transform` **setter is `internal`** (getter stays public and now includes the base) | feature 003 base-CTM redefinition; all `FilterEffect`/`CustomEffect` authors + `ICanvas` implementers |
-| `FilterEffectContext` | `FilterEffects/FilterEffectContext.cs:39` | no scale | + ctor `(outputScale, workingScale)` + `float WorkingScale { get; }` + `float OutputScale { get; }`; **CustomEffect point-blit** code × **`WorkingScale`**, Skia `SKImageFilter` primitives ride the `CreateScale(w)` CTM (NOT multiplied) | FR-009/FR-015; `FilterEffectRenderNode.cs:30` |
+| `FilterEffectContext` | `FilterEffects/FilterEffectContext.cs:39` | no scale | + ctor `(outputScale, workingScale)` + `bool TryGetWorkingScale(out float)` + `float WorkingScale { get; }` + `float OutputScale { get; }`; author-time working scale is unavailable for symbolic/branch-dependent inputs (`TryGet... == false`, getter throws), and available values are nominal before operation-specific bounds clamps; **CustomEffect point-blit** code uses its execution-time density, while Skia `SKImageFilter` primitives ride the `CreateScale(w)` CTM (NOT multiplied) | FR-009/FR-015; `FilterEffectRenderNode.cs:30` |
 | `CustomFilterEffectContext` | `FilterEffects/CustomFilterEffectContext.cs` | `CreateTarget` `(int)bounds.W/H` | + `float WorkingScale { get; }` + `float OutputScale { get; }` (forwarded for nested re-application); `CreateTarget` `ceil(bounds×WorkingScale)`; **`Open` returns a canvas with the baked base CTM `CreateScale(target.Scale.Value)`** (the author no longer pushes `CreateScale(WorkingScale)`); `DeviceBufferSize(bounds, w)` is public so custom effect authors can compute shader/device uniforms with the same scale-1.0-sensitive rounding as `CreateTarget` | FR-009/FR-015; migrate off `(int)` cast (scale-1.0-sensitive) |
 | `FilterEffectActivator` | `FilterEffects/FilterEffectActivator.cs` | `ctor(targets, builder, workingScale = 1f)` | + `float outputScale = 1f` **and `float maxWorkingScale = +∞`** ctor params + `OutputScale` / `MaxWorkingScale` getters (forwarded into the nested `FilterEffectContext`/`CustomFilterEffectContext` so nested pulls stay under the FR-037 ceiling); `Flush` sizes `ceil(×w)`, the **flatten canvas bakes the base CTM `CreateScale(w)`** (translation-only push), tags buffers `At(w)` | FR-009/FR-015/FR-019/FR-037; scale-1.0-sensitive |
 | `EffectTarget` | `FilterEffects/EffectTarget.cs:6` | `Empty`/`Size` (obsolete) | + `EffectiveScale Scale { get; set; }` (default `Unbounded`); **remove** `Empty`/`Size` | FR-019; LayerEffect mixed-scale detection (dossier §4.5) |