diff --git a/docs/temporal-sdf-gaussian-field.md b/docs/temporal-sdf-gaussian-field.md index 6a9540f..59ff5ac 100644 --- a/docs/temporal-sdf-gaussian-field.md +++ b/docs/temporal-sdf-gaussian-field.md @@ -31,6 +31,10 @@ The Gaussian field is one backend for this reservoir, not the reservoir's identity. Fractal SDF probes, visual point-cloud features, and future acoustic constraints can all enter as stable keyed spatial evidence as long as each producer declares confidence, time, bounds, and payload lowering rules. +`TemporalSpatialEvidenceLowering` owns the current packet conversions for +`TemporalGaussianObservation`, `AquariumTemporalSdfGaussian`, and +`AquariumGpuFusionSeed`; consumers should use those helpers instead of packing +payload vectors privately. The D3D12 renderer lowers the field into `D3D12TemporalGaussianPacket`, uploads the active packet span into a 1,048,576-entry structured buffer, and renders an diff --git a/src/Aquarium.Engine.Fractal/Temporal/TemporalGaussianAccumulator.cs b/src/Aquarium.Engine.Fractal/Temporal/TemporalGaussianAccumulator.cs index 10bc867..90acb06 100644 --- a/src/Aquarium.Engine.Fractal/Temporal/TemporalGaussianAccumulator.cs +++ b/src/Aquarium.Engine.Fractal/Temporal/TemporalGaussianAccumulator.cs @@ -38,20 +38,7 @@ public sealed class TemporalGaussianAccumulator public void Observe(IEnumerable observations) { - reservoir.Observe(observations.Select(observation => new TemporalSpatialEvidenceObservation( - observation.StableKey, - observation.Center, - observation.Radii, - observation.Orientation, - observation.ColorOpacity, - new Vector4( - MathF.Max(0.0001f, observation.Falloff), - MathF.Max(0.0001f, observation.ShapePower), - 0.0f, - 0.0f), - observation.Confidence, - observation.ObservedTimeSeconds, - observation.FieldId))); + reservoir.Observe(observations.Select(TemporalSpatialEvidenceLowering.FromGaussianObservation)); } public AquariumTemporalGaussianField BuildField(float renderTimeSeconds) @@ -61,21 +48,7 @@ public sealed class TemporalGaussianAccumulator for (var index = 0; index < snapshot.Samples.Count; index++) { - var sample = snapshot.Samples[index]; - gaussians[index] = new AquariumTemporalSdfGaussian( - sample.StableKey, - sample.Center, - sample.PreviousCenter, - sample.Velocity, - sample.Radii, - sample.Orientation, - sample.Payload0, - sample.Confidence, - sample.HistoryWeight, - sample.LastObservedTimeSeconds, - sample.Payload1.X, - sample.Payload1.Y, - sample.FieldId); + gaussians[index] = TemporalSpatialEvidenceLowering.ToTemporalGaussian(snapshot.Samples[index]); } return new AquariumTemporalGaussianField diff --git a/src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceLowering.cs b/src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceLowering.cs new file mode 100644 index 0000000..f5eab44 --- /dev/null +++ b/src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceLowering.cs @@ -0,0 +1,77 @@ +using System.Numerics; +using Aquarium.Engine.Render; + +namespace Aquarium.Engine.Fractal.Temporal; + +public static class TemporalSpatialEvidenceLowering +{ + public static TemporalSpatialEvidenceObservation FromGaussianObservation(TemporalGaussianObservation observation) + { + return new TemporalSpatialEvidenceObservation( + observation.StableKey, + observation.Center, + observation.Radii, + observation.Orientation, + observation.ColorOpacity, + new Vector4( + MathF.Max(0.0001f, observation.Falloff), + MathF.Max(0.0001f, observation.ShapePower), + 0.0f, + 0.0f), + observation.Confidence, + observation.ObservedTimeSeconds, + observation.FieldId); + } + + public static AquariumTemporalSdfGaussian ToTemporalGaussian(TemporalSpatialEvidenceSample sample) + { + return new AquariumTemporalSdfGaussian( + sample.StableKey, + sample.Center, + sample.PreviousCenter, + sample.Velocity, + sample.Radii, + sample.Orientation, + sample.Payload0, + sample.Confidence, + sample.HistoryWeight, + sample.LastObservedTimeSeconds, + MathF.Max(0.0001f, sample.Payload1.X), + MathF.Max(0.0001f, sample.Payload1.Y), + sample.FieldId); + } + + public static TemporalSpatialEvidenceObservation FromGpuFusionSeed(AquariumGpuFusionSeed seed, float observedTimeSeconds) + { + return new TemporalSpatialEvidenceObservation( + seed.StableKey, + seed.Center, + seed.Radii, + Quaternion.Identity, + seed.ColorOpacity, + new Vector4( + MathF.Max(0.0001f, seed.Falloff), + MathF.Max(0.0001f, seed.ShapePower), + seed.HistoryWeight, + 0.0f), + seed.Confidence, + observedTimeSeconds, + seed.FieldId); + } + + public static AquariumGpuFusionSeed ToGpuFusionSeed(TemporalSpatialEvidenceSample sample) + { + return new AquariumGpuFusionSeed( + sample.StableKey, + sample.Center, + sample.PreviousCenter, + sample.Velocity, + sample.Radii, + sample.Payload0, + sample.Confidence, + sample.HistoryWeight, + MathF.Max(0.0001f, sample.Payload1.X), + MathF.Max(0.0001f, sample.Payload1.Y), + sample.FieldId); + } +} diff --git a/src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs b/src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs index a6740be..51699b6 100644 --- a/src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs +++ b/src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs @@ -1,4 +1,3 @@ -using System.Numerics; using Aquarium.Engine.Fractal.Temporal; using Aquarium.Engine.Render; @@ -28,7 +27,7 @@ public sealed class LocalCastGpuFusionAccumulator { var field = mapper.Map(frame); var frameTimeSeconds = mapper.ToTimelineSeconds(frame.SourceTimeMaxNs); - reservoir.Observe(field.Seeds.Select(seed => ToObservation(seed, frameTimeSeconds))); + reservoir.Observe(field.Seeds.Select(seed => TemporalSpatialEvidenceLowering.FromGpuFusionSeed(seed, frameTimeSeconds))); } public AquariumGpuFusionField BuildField(float renderTimeSeconds) @@ -37,43 +36,9 @@ public sealed class LocalCastGpuFusionAccumulator return new AquariumGpuFusionField { - Seeds = snapshot.Samples.Select(ToSeed).ToArray(), + Seeds = snapshot.Samples.Select(TemporalSpatialEvidenceLowering.ToGpuFusionSeed).ToArray(), AccumulationWindowSeconds = historySeconds, PresentationDelaySeconds = PresentationDelaySeconds, }; } - - private static TemporalSpatialEvidenceObservation ToObservation(AquariumGpuFusionSeed seed, float frameTimeSeconds) - { - return new TemporalSpatialEvidenceObservation( - seed.StableKey, - seed.Center, - seed.Radii, - Quaternion.Identity, - seed.ColorOpacity, - new Vector4( - MathF.Max(0.0001f, seed.Falloff), - MathF.Max(0.0001f, seed.ShapePower), - seed.HistoryWeight, - 0.0f), - seed.Confidence, - frameTimeSeconds, - seed.FieldId); - } - - private static AquariumGpuFusionSeed ToSeed(TemporalSpatialEvidenceSample sample) - { - return new AquariumGpuFusionSeed( - sample.StableKey, - sample.Center, - sample.PreviousCenter, - sample.Velocity, - sample.Radii, - sample.Payload0, - sample.Confidence, - sample.HistoryWeight, - MathF.Max(0.0001f, sample.Payload1.X), - MathF.Max(0.0001f, sample.Payload1.Y), - sample.FieldId); - } } diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 7e06477..f5c5f9d 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -154,3 +154,4 @@ {"timestamp":"2026-05-19T14:20:00+01:00","topic":"zyphos-fractal-resource-observability","lesson":"Zyphos exposes `zyphos-fractal-plan`, a command-level dump of the current fractal selected cut and resource plan. Keep this kind of budget/cut observability alongside renderer work: pixels alone are not enough to validate stochastic LOD, residency, or cache behavior.","files":["src/Aquarium.Zyphos/ZyphosFractalTerrain.cs","src/Aquarium.Zyphos/ZyphosRuntime.cs","tests/Aquarium.Engine.Fractal.Tests/ZyphosFractalTerrainTests.cs"],"source":"third implementation slice after adding resource planning; the machine needs to explain itself without screenshot divination"} {"timestamp":"2026-05-19T14:43:00+01:00","topic":"fractal-contribution-cache-live-loop","lesson":"Fractal contribution planning now has a live cache loop. `FractalContributionCache` builds a resource plan from current summaries and cached states, stochastically observes only budgeted update nodes, updates estimator confidence, and lets Zyphos reuse compiled brush packets by selected-cut key instead of freezing the whole render plan by camera bucket. Static plan caches are not acceptable for stochastic LOD because they stop learning.","files":["src/Aquarium.Engine.Fractal/Lod/FractalContributionCache.cs","src/Aquarium.Zyphos/ZyphosFractalTerrain.cs","tests/Aquarium.Engine.Fractal.Tests/FractalContributionCacheTests.cs"],"source":"follow-up after resource observability revealed the old bucket plan cache prevented continual cache updates"} {"timestamp":"2026-05-19T15:12:00+01:00","topic":"localcast-shared-temporal-reservoir","lesson":"LocalCast fallback GPU fusion history now delegates to `TemporalSpatialEvidenceReservoir`. `LocalCastGpuFusionAccumulator` maps LocalCast GPU fusion seeds into shared evidence observations and lowers reservoir samples back into `AquariumGpuFusionSeed`; it no longer owns separate stable-key history, smoothing, expiry, or max-count logic. This is the first consumer-side takeover of duplicated temporal reservoir code.","files":["src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs","src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceReservoir.cs","docs/temporal-sdf-gaussian-field.md"],"source":"user made Aquarium responsible for resolving temporal reservoir sampling architecturally and taking over consumer half-versions"} +{"timestamp":"2026-05-19T15:29:00+01:00","topic":"temporal-evidence-lowering-boundary","lesson":"Shared temporal evidence now has named lowering helpers. `TemporalSpatialEvidenceLowering` converts Gaussian observations and GPU fusion seeds to/from reservoir samples, so consumer adapters do not privately pack Payload0/Payload1 conventions. Keep new reservoir consumers on this lowering seam unless they need a genuinely new payload contract.","files":["src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceLowering.cs","src/Aquarium.Engine.Fractal/Temporal/TemporalGaussianAccumulator.cs","src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs","tests/Aquarium.Engine.Fractal.Tests/TemporalSpatialEvidenceLoweringTests.cs"],"source":"follow-up after moving LocalCast history onto the shared reservoir; adapter payload packing needed to become a tested engine boundary"} diff --git a/state/memory.json b/state/memory.json index 3ea2799..fed170a 100644 --- a/state/memory.json +++ b/state/memory.json @@ -82,6 +82,7 @@ "Aquarium's fractal renderer and Mimir-style sensor fusion share a deeper shape: both accumulate confidence-weighted spatial evidence into temporal reservoirs, then render a resolved surface/volume field. Keep the budget planner vocabulary general enough for CPU update work, GPU packet cost, RAM residency, and SSD request pressure; do not trap the future shared machinery inside renderer-only folklore.", "Temporal Gaussian splats lower through TemporalSpatialEvidenceReservoir: stable keyed observations become delayed, smoothed, confidence-weighted tracks with velocity prediction, expiry, and max-track eviction before backend packet lowering. Treat Gaussian fields, fractal SDF probes, and Mimir sensor-fusion features as different evidence producers for this reservoir shape, not separate accumulator folklore.", "LocalCastGpuFusionAccumulator must remain a thin adapter over TemporalSpatialEvidenceReservoir. LocalCast may own mapping from visual points/seeds into evidence payloads, but it must not grow a second stable-key history, smoothing, expiry, or sample-budget algorithm.", + "TemporalSpatialEvidenceLowering owns conversion between shared evidence samples and backend packets such as TemporalGaussianObservation, AquariumTemporalSdfGaussian, and AquariumGpuFusionSeed. Consumers should not pack Payload0/Payload1 by private convention when a lowering helper exists.", "Zyphos fractal stress data should keep authored topology richer than the first renderer backend: both Zyphos and Umbros expose lat/long, surface, object-scale, and cube-tile domains in `.aquageo`, with explicit continent/forest/tree/leaf/coast/pebble and crater/boulder/pebble recursion. The current D3D12 height-field stress table uploads 64 shaped 2D brushes and the SDF planet shaders carry separate cheap bounded quadtree-style relief.", "The `.aquageo` compiler must preserve each tile declaration as its own ownership-tree node. Collapsing every claim under the final tile makes the authored multi-domain world a lie even if the brush count looks impressive.", "Zyphos passes cube-tile domain metadata through height brush packets and binds those packets into the SDF pass. The planet shader may use authored brush packets for post-hit material/detail evaluation; traced geometry must wait for selected-cut/resident packet policy so SDF distance loops do not evaluate every brush at every step.", diff --git a/tests/Aquarium.Engine.Fractal.Tests/TemporalSpatialEvidenceLoweringTests.cs b/tests/Aquarium.Engine.Fractal.Tests/TemporalSpatialEvidenceLoweringTests.cs new file mode 100644 index 0000000..42755e0 --- /dev/null +++ b/tests/Aquarium.Engine.Fractal.Tests/TemporalSpatialEvidenceLoweringTests.cs @@ -0,0 +1,85 @@ +using System.Numerics; +using Aquarium.Engine.Fractal.Temporal; +using Aquarium.Engine.Render; + +namespace Aquarium.Engine.Fractal.Tests; + +public sealed class TemporalSpatialEvidenceLoweringTests +{ + [Fact] + public void GaussianLoweringRoundTripsKernelPayload() + { + var observation = new TemporalGaussianObservation( + "gaussian/a", + Vector3.One, + new Vector3(0.2f, 0.3f, 0.4f), + Quaternion.Identity, + new Vector4(0.1f, 0.2f, 0.3f, 0.4f), + Confidence: 0.75f, + ObservedTimeSeconds: 12.0f, + Falloff: 5.0f, + ShapePower: 1.8f, + FieldId: 44); + + var lowered = TemporalSpatialEvidenceLowering.FromGaussianObservation(observation); + var sample = new TemporalSpatialEvidenceSample( + lowered.StableKey, + lowered.Center, + lowered.Center, + Vector3.Zero, + lowered.Radii, + lowered.Orientation, + lowered.Payload0, + lowered.Payload1, + lowered.Confidence, + HistoryWeight: 0.6f, + lowered.ObservedTimeSeconds, + lowered.FieldId); + var gaussian = TemporalSpatialEvidenceLowering.ToTemporalGaussian(sample); + + Assert.Equal(observation.StableKey, gaussian.StableKey); + Assert.Equal(observation.ColorOpacity, gaussian.ColorOpacity); + Assert.Equal(5.0f, gaussian.Falloff); + Assert.Equal(1.8f, gaussian.ShapePower); + Assert.Equal(44, gaussian.FieldId); + } + + [Fact] + public void GpuFusionLoweringRoundTripsSeedPayload() + { + var seed = new AquariumGpuFusionSeed( + "fusion/a", + Vector3.One, + Vector3.Zero, + new Vector3(0.1f, 0.0f, 0.0f), + new Vector3(0.2f), + new Vector4(0.4f, 0.5f, 0.6f, 0.7f), + Confidence: 0.8f, + HistoryWeight: 0.65f, + Falloff: 4.4f, + ShapePower: 2.1f, + FieldId: 91); + + var lowered = TemporalSpatialEvidenceLowering.FromGpuFusionSeed(seed, observedTimeSeconds: 3.0f); + var sample = new TemporalSpatialEvidenceSample( + lowered.StableKey, + lowered.Center, + seed.PreviousCenter, + seed.Velocity, + lowered.Radii, + lowered.Orientation, + lowered.Payload0, + lowered.Payload1, + lowered.Confidence, + lowered.Payload1.Z, + lowered.ObservedTimeSeconds, + lowered.FieldId); + var roundTrip = TemporalSpatialEvidenceLowering.ToGpuFusionSeed(sample); + + Assert.Equal(seed.StableKey, roundTrip.StableKey); + Assert.Equal(seed.ColorOpacity, roundTrip.ColorOpacity); + Assert.Equal(seed.Falloff, roundTrip.Falloff); + Assert.Equal(seed.ShapePower, roundTrip.ShapePower); + Assert.Equal(seed.FieldId, roundTrip.FieldId); + } +}