Add fractal surface page contracts

docs/perfect-machine-architecture.md

@@ -509,6 +509,11 @@ resource-tier residency fields remain open.
 Build cached 2D SDF/height/material pages for cube-sphere and torus domains.
 Use parent summaries while child pages stream.
 
+Current state: `AquariumFractalSurfacePageKey` and
+`AquariumFractalSurfacePage` define renderer-agnostic page metadata for height,
+2D signed-distance, material, and confidence pages. The page store and D3D12
+lowering remain open.
+
 ### Phase F: 3D SDF Splat Backend
 
 Build compact-support 3D SDF splat packets for object/volume domains. Keep

research/rendering/fractal-brush-implementation-roadmap.md

@@ -400,6 +400,8 @@ Goal: prove page/key semantics before real SSD/GPU streaming.
 
 Tasks:
 
+- [x] Add renderer-agnostic surface page key/metadata contracts for height,
+  2D signed-distance, material, and confidence pages.
 - [x] Add fake payload store with resident/missing states.
 - [x] Add child request queue.
 - [ ] Add score/cost eviction policy.

src/Aquarium.Engine.Contracts/Fractal/AquariumFractalContracts.cs

@@ -47,6 +47,67 @@ public enum AquariumFractalPayloadKind
     SignedDistance,
 }
 
+public enum AquariumFractalSurfacePageKind
+{
+    Height,
+    SignedDistance2D,
+    Material,
+    Confidence,
+}
+
+public readonly record struct AquariumFractalSurfacePageKey
+{
+    public AquariumFractalSurfacePageKey(
+        AquariumFractalKey domainKey,
+        AquariumFractalKey nodeKey,
+        AquariumFractalSurfacePageKind kind,
+        int mipLevel)
+    {
+        if (domainKey.Value is null)
+        {
+            throw new ArgumentException("Surface page domain key must not be empty.", nameof(domainKey));
+        }
+
+        if (nodeKey.Value is null)
+        {
+            throw new ArgumentException("Surface page node key must not be empty.", nameof(nodeKey));
+        }
+
+        if (mipLevel < 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(mipLevel), mipLevel, "Surface page mip level must not be negative.");
+        }
+
+        DomainKey = domainKey;
+        NodeKey = nodeKey;
+        Kind = kind;
+        MipLevel = mipLevel;
+    }
+
+    public AquariumFractalKey DomainKey { get; }
+
+    public AquariumFractalKey NodeKey { get; }
+
+    public AquariumFractalSurfacePageKind Kind { get; }
+
+    public int MipLevel { get; }
+
+    public string Value => $"{DomainKey.Value}:{NodeKey.Value}:{Kind}:mip{MipLevel:D2}";
+
+    public override string ToString()
+    {
+        return Value;
+    }
+}
+
+public readonly record struct AquariumFractalSurfacePage(
+    AquariumFractalSurfacePageKey Key,
+    Vector4 BoundsMinMax,
+    int Width,
+    int Height,
+    int PayloadHandle,
+    float MaxError);
+
 public readonly record struct AquariumBrushClaim(
     AquariumFractalKey Key,
     AquariumFractalKey DomainKey,

state/evidence.jsonl

@@ -168,3 +168,4 @@
 {"timestamp":"2026-05-19T21:01:00+01:00","topic":"structural-probe-generator","lesson":"IFS structure can now enter the reservoir path as typed evidence. `FractalStructuralProbeGenerator` lowers `AquariumFractalSummary` rows into `FractalProbeSample` candidates with local center, bound radius, projected target contribution, clamped source PDF, material delta, and payload handle. This gives structural `.aquageo` summaries a real producer boundary before renderer-facing temporal validation and GPU reservoir reuse are added.","files":["src/Aquarium.Engine.Fractal/Lod/FractalStructuralProbeGenerator.cs","tests/Aquarium.Engine.Fractal.Tests/FractalStructuralProbeGeneratorTests.cs","docs/perfect-machine-architecture.md","research/rendering/fractal-brush-implementation-roadmap.md","state/memory.json"],"source":"Perfect Machine Phase C implementation after occupancy graph promotion"}
 {"timestamp":"2026-05-19T21:18:00+01:00","topic":"zyphos-structural-probe-reservoir","lesson":"Zyphos now exposes a structural probe reservoir beside its selected cut and resource plan. `FractalStructuralProbeReservoir` builds a selected-cut `FractalProbeSample` reservoir from the ownership tree, summaries, node domains, and projected pixels per world unit; `ZyphosFractalRenderPlan` carries the snapshot and the debug dump reports selected probe weight/candidate count. This connects the pure IFS structural-probe producer to a live client path before GPU reservoir buffers are introduced.","files":["src/Aquarium.Engine.Fractal/Lod/FractalStructuralProbeReservoir.cs","src/Aquarium.Zyphos/ZyphosFractalTerrain.cs","tests/Aquarium.Engine.Fractal.Tests/FractalStructuralProbeReservoirTests.cs","tests/Aquarium.Engine.Fractal.Tests/ZyphosFractalTerrainTests.cs","docs/perfect-machine-architecture.md","research/rendering/fractal-brush-implementation-roadmap.md"],"source":"continuing Perfect Machine Phase C after adding structural probe generation"}
 {"timestamp":"2026-05-19T21:42:00+01:00","topic":"fractal-probe-temporal-validation","lesson":"Fractal probe reuse now has a CPU temporal validation contract before GPU reuse exists. `FractalProbeReuseValidator.ValidateTemporal` composes domain/local-shift validation with renderer-facing gates for camera motion, disocclusion confidence, material delta, and visibility confidence, returning explicit rejection reasons. This keeps future ReSTIR/GRIS probe reuse from becoming private shader folklore.","files":["src/Aquarium.Engine.Fractal/Lod/FractalProbeSample.cs","tests/Aquarium.Engine.Fractal.Tests/FractalProbeSampleTests.cs","docs/perfect-machine-architecture.md","research/rendering/fractal-brush-implementation-roadmap.md","state/memory.json"],"source":"Perfect Machine Phase C validation contract work"}
+{"timestamp":"2026-05-19T22:03:00+01:00","topic":"fractal-surface-page-contract","lesson":"Phase E has a portable page contract before renderer lowering. `AquariumFractalSurfacePageKey` gives height, 2D signed-distance, material, and confidence pages stable domain/node/kind/mip identity; `AquariumFractalSurfacePage` carries bounds, dimensions, payload handle, and max error without D3D12 types. This lets the residency/page store evolve without treating current height brushes as the page model.","files":["src/Aquarium.Engine.Contracts/Fractal/AquariumFractalContracts.cs","tests/Aquarium.Engine.Fractal.Tests/FractalSurfacePageContractTests.cs","docs/perfect-machine-architecture.md","research/rendering/fractal-brush-implementation-roadmap.md","state/memory.json"],"source":"Perfect Machine Phase E groundwork after fractal probe validation"}

state/memory.json

@@ -99,6 +99,7 @@
       "Zyphos camera distance limits belong to the selected spatial domain, not one global planetary clamp. Leaf/pebble domains must be able to zoom below whole-body distances, and the parent star must be a visible SDF body when it is also the primary light source.",
       "The consolidated fractal brush architecture lives in research/rendering/fractal-brush-architecture-plan.md. Its pipeline is client intent -> domain roots -> semantic IFS brush grammar -> ownership tree -> node summaries -> contribution cache/residency scheduler -> backend packets -> renderer passes -> debug/evidence. Its credibility depends on module boundaries and tests: contracts, pure CPU fractal core, D3D12 backend, client adapters, mock payload/probe/random/clock seams, shader parity tests, and deterministic performance fixtures.",
       "The Perfect Machine waterfall architecture lives in docs/perfect-machine-architecture.md. Treat it as the design authority before expanding SDF splat backends, sensor-fusion candidate adapters, reservoir guide buffers, occupancy graph state, resource-tier residency, or stochastic learned priority. Its core split is domains -> evidence candidates -> target evaluation -> ReSTIR/GRIS reservoirs -> occupancy graph -> residency -> 2D/3D/projected SDF splat packets -> TAA guide buffers.",
+      "AquariumFractalSurfacePageKey and AquariumFractalSurfacePage are the renderer-agnostic page contracts for Phase E: height, SignedDistance2D, material, and confidence surface pages carry stable domain/node/kind/mip keys, bounds, dimensions, payload handles, and max error before any D3D12 page store exists.",
       "The actionable fractal brush roadmap lives in research/rendering/fractal-brush-implementation-roadmap.md. Start with the first work packet: add Aquarium.Engine.Fractal and tests, cube-face/tile key types, identity and tangent projection candidates, an area distortion sampler, face-edge tests, and a projection report before touching recursive detail."
     ],
     "text_and_ui": [

tests/Aquarium.Engine.Fractal.Tests/FractalSurfacePageContractTests.cs

@@ -0,0 +1,56 @@
+using System.Numerics;
+using Aquarium.Engine.Fractal;
+
+namespace Aquarium.Engine.Fractal.Tests;
+
+public sealed class FractalSurfacePageContractTests
+{
+    [Fact]
+    public void SurfacePageKeyIsStableAndIncludesDomainNodeKindAndMip()
+    {
+        var key = new AquariumFractalSurfacePageKey(
+            new AquariumFractalKey("zyphos/tile/0"),
+            new AquariumFractalKey("zyphos/tile/0/forest"),
+            AquariumFractalSurfacePageKind.SignedDistance2D,
+            mipLevel: 3);
+
+        Assert.Equal("zyphos/tile/0:zyphos/tile/0/forest:SignedDistance2D:mip03", key.Value);
+        Assert.Equal(key.Value, key.ToString());
+    }
+
+    [Fact]
+    public void SurfacePageKeyRejectsNegativeMip()
+    {
+        var ex = Assert.Throws<ArgumentOutOfRangeException>(() => new AquariumFractalSurfacePageKey(
+            new AquariumFractalKey("domain"),
+            new AquariumFractalKey("node"),
+            AquariumFractalSurfacePageKind.Height,
+            mipLevel: -1));
+
+        Assert.Equal("mipLevel", ex.ParamName);
+    }
+
+    [Fact]
+    public void SurfacePageContractCarriesRendererAgnosticPayloadMetadata()
+    {
+        var key = new AquariumFractalSurfacePageKey(
+            new AquariumFractalKey("domain"),
+            new AquariumFractalKey("node"),
+            AquariumFractalSurfacePageKind.Material,
+            mipLevel: 0);
+
+        var page = new AquariumFractalSurfacePage(
+            key,
+            new Vector4(-1.0f, -2.0f, 3.0f, 4.0f),
+            Width: 128,
+            Height: 64,
+            PayloadHandle: 42,
+            MaxError: 0.125f);
+
+        Assert.Equal(key, page.Key);
+        Assert.Equal(128, page.Width);
+        Assert.Equal(64, page.Height);
+        Assert.Equal(42, page.PayloadHandle);
+        Assert.Equal(0.125f, page.MaxError);
+    }
+}