Aquarium/state/map.yaml

project:
  name: Aquarium Engine
  root: E:\Projects\Aquarium-Engine
  upstream: https://github.com/GameCult/Aquarium-Engine
  purpose: >
    Native C# runtime and renderer core for Aquarium clients. The engine owns
    the Win32 host, D3D12 renderer, input loop, client reload boundary, debug UI,
    audio host, persistent-state transport, and future render graph
    abstractions. Epiphany is the current first-party client: it owns frontend
    intent, agent visuals, CultCache/CultNet semantics, and render-plan
    configuration through the engine contracts.

current_model:
  host:
    solution: Aquarium.Engine.sln
    window: src/Aquarium.Engine/Platform/Win32Window.cs
    renderer: src/Aquarium.Engine/Render/D3D12Renderer.cs
    height_field_shader: src/Aquarium.Engine/Render/Shaders/D3D12HeightField.hlsl
    scene_shader: src/Aquarium.Engine/Render/Shaders/D3D12Scene.hlsl
    sdf_common_include: src/Aquarium.Engine/Render/Shaders/D3D12SdfCommon.hlsli
    sdf_proxy_include: src/Aquarium.Engine/Render/Shaders/D3D12SdfProxy.hlsli
    sdf_math_include: src/Aquarium.Engine/Render/Shaders/D3D12SdfMath.hlsli
    post_shader: src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl
    overlay_text: src/Aquarium.Engine/Render/DirectWriteOverlay.cs
    debug_ui: src/Aquarium.Engine/Render/Ui/DebugUi.cs
    synth_host: src/Aquarium.Engine/Audio/AquariumSynthHost.cs
    wasapi_audio_device: src/Aquarium.Engine/Audio/WasapiAudioDevice.cs
    faust_toolchain_sync: scripts/sync-faust-toolchain.ps1
    synth_package_update: scripts/update-synth-package.ps1
    local_package_feed: packages
    runtime_loader: src/Aquarium.Engine/Runtime/ClientRuntimeLoader.cs
    dev_reload: scripts/dev-reload.ps1
    dev_watch: scripts/dev-watch.ps1
  epiphany_client:
    contracts: src/Aquarium.Engine.Contracts
    implementation: src/Aquarium.Epiphany
    render_plan: src/Aquarium.Epiphany/EpiphanyRenderPlan.cs
    scene_builder: src/Aquarium.Epiphany/EpiphanySceneBuilder.cs
    agent_preview: src/Aquarium.Epiphany.AgentPreview
    shaders: src/Aquarium.Epiphany/Shaders
    state_store: src/Aquarium.Epiphany/State/AquariumCultStateStore.cs
    state_document: epiphany.aquarium.live_state
    graphics_settings_document: epiphany.aquarium.graphics_settings
  zyphos_client:
    implementation: src/Aquarium.Zyphos
    render_plan: src/Aquarium.Zyphos/ZyphosRenderPlan.cs
    scene_builder: src/Aquarium.Zyphos/ZyphosSceneBuilder.cs
    shaders: src/Aquarium.Zyphos/Shaders
    worldbuilding_sync: docs/zyphos-eusocial-sync.md
    setting_authority: E:\Projects\Eusocial Interbeing
    purpose: >
      Non-Epiphany planetary-scale rendering demo using the shared Aquarium host,
      D3D12 renderer, reload transport, UI contracts, bloom, and SDF proxy path.
  samples:
    minimal_client: src/Aquarium.Sample.Minimal
  dependencies:
    cult_math: E:\Projects\CultMath
    cult_lib: E:\Projects\CultLib
    aqua_synth_faust: NuGet package AquaSynth.Faust 0.1.0-alpha.3 from repo-local packages feed
    aqua_synth_core: transitive NuGet package AquaSynth.Core 0.1.0-alpha.3 from repo-local packages feed
  docs:
    doctrine: docs/aquarium-engine-doctrine.md
    engine_client_boundary: docs/engine-client-boundary.md
    epiphany_extraction_render_api_plan: docs/epiphany-extraction-render-api-plan.md
    renderer: docs/hlsl-renderer.md
    agent_sdf_visual_language: docs/epiphany-agent-sdf-visual-language.md
    runtime_surface: docs/cult-runtime-surface.md
    native_spine: docs/vortice-spine.md
    tsr_inspired_taa_spec: docs/tsr-inspired-taa-spec.md
    temporal_sdf_gaussian_field: docs/temporal-sdf-gaussian-field.md
    temporal_spatial_evidence_reservoir: docs/temporal-spatial-evidence-reservoir.md
    input: docs/input.md
    zyphos_eusocial_sync: docs/zyphos-eusocial-sync.md
    hdr_pbr_presentation: research/rendering/hdr-pbr-presentation.md
    cube_sphere_fractal_brushes: research/rendering/cube-sphere-fractal-brushes.md
    fractal_brush_architecture_plan: research/rendering/fractal-brush-architecture-plan.md
    fractal_brush_implementation_roadmap: research/rendering/fractal-brush-implementation-roadmap.md
    perfect_machine_architecture: docs/perfect-machine-architecture.md

invariants:
  - The camera target is the Grid center on the global XY plane.
  - Grid radius follows twice the clamped camera zoom distance, then clamps to [20, 80]; pitch/yaw/projection do not resize it.
  - Body anchors remain world-space and independent of the moving Grid window.
  - Visible scene lighting is diegetic; no default ambient/global fill.
  - Overlay text is DirectWrite final-pixel UI; scene text needs renderer-owned billboards.
  - CultCache persists live app state through reload.
  - Global GraphicsSettings persists renderer debug/HDR presentation knobs through restart and live reload.
  - Failed shader/live-runtime reloads must leave the last good frame alive.
  - Closed visible dev windows can be reopened from the last good slot without rebuilding.

renderer_state:
  current:
    - D3D12 default renderer behind IAquariumRenderer with explicit device/queue/swapchain, command allocators, fences, descriptor arenas, upload ring constants, tracked render targets, command events, resize rebuild, HDR/bloom/present, temporal diagnostics, and DirectWrite overlay bridge.
    - Deferred scalar Grid height target rendered from additive brush passes.
    - Epiphany owns its client surface brush list, SDF object table, SDF light table, shader manifest, and cursor projection policy through Aquarium.Engine.Contracts; the engine consumes those as generic rendering data.
    - Direct-traced height-field surface is a terminating reflective surface over the scalar height field, sampling Studio2 PMREM mip 0.
    - Fullscreen scene pass owns background and height-field surface only; each client-declared SDF shader owns a separate proxy pipeline, with shared proxy plumbing factored into generic engine HLSL includes. Proxy marching evaluates only sdfDistance; sdfSurface runs once at the refined hit and returns only PBR material values.
    - Reusable SDF primitives live in engine D3D12SdfMath.hlsli; current Epiphany role character organs live under src/Aquarium.Epiphany/Shaders.
    - Epiphany's cursor is a luminous five-petal hibiscus SDF centered one cursor radius above the XY plane so its contact tip reaches Grid z=0 without projecting to the Grid surface.
    - SDF/analytic Epiphany role visuals upload current centers, previous centers, and state scalars through the public `AquariumSdfObject` contract.
    - Agent SDF visual language is documented against Epiphany's published CultNet surfaces: identity from agent memory, motion from heartbeat, posture from role/coordinator/result surfaces, pressure from reorient/pressure surfaces, and expression through bounded orbit wandering plus CPU-visible gravity-well pulses.
    - Life is a memory-nautilus seed-shell SDF: a protective revolved seed/cardioid shell owns the silhouette, a visible ember sits inside the aperture, and the logarithmic spiral domain owns seam, bead trail, pressure breathing, rupture scar, and surface masks. Nautilus references inform the coordinate mapping, not the object silhouette.
    - SDF light buffer feeds Self emission and direct object lighting; future other Selves should join this light lane, not a generic field-instance table.
    - Studio2 PMREM and irradiance DDS cubemaps are loaded as D3D12 TextureCubes; PMREM serves roughness-mip specular, irradiance serves Lambertian diffuse IBL for non-metal bodies.
    - DirectWrite/Direct2D unified debug panel with tabs for Aquarium renderer controls, client-declared debug panels, terminal commands, and engine/client tooling surfaces.
    - DirectWrite/Direct2D debug panels own body scrolling and clipping; overflowing client controls must stay inside the panel with a visible scrollbar.
    - Client-declared UI panels are folded into the unified Debug tab strip by default; panels that opt into proximity fading render as independent floating overlays. Floating panels can right-anchor with negative left offsets and fade to 10% opacity when the mouse is not near.
    - Aquarium UI exposes generic selectable tree rows with disclosure arrows. Clients use them for hierarchy navigation without teaching DebugUi about client-specific spatial domains.
    - Aquarium exposes an optional synth/audio hosting boundary through AquariumSynthDocument; Aquarium consumes AquaSynth.Faust as a pinned repo-local NuGet package so synth-agent construction cannot break Aquarium builds until the package is intentionally updated. AquaSynth.Core arrives transitively for patch editor/parser surfaces. AquaSynth owns live patch compilation and native Faust factory lifetime; Aquarium owns debounce, playback scheduling, cached rendered buffers, and WASAPI output.
    - Aquarium now exposes a generic queued PCM audio lane through AquariumAudioDocument. Epiphany Face voice uses it to play streamed Codex realtime output without reaching into the engine's WASAPI internals.
    - Epiphany owns the first native Face realtime voice session controller. It stores loopback app-server URI, thread id, voice, and speech prompt in CultCache live state; starts `thread/realtime/start` with audio output over the experimental Codex app-server WebSocket JSON-RPC edge; sends text utterances; reflects ephemeral transcript/error/audio counters in the debug UI; and treats speech as transient Face surface, not durable memory or project authority.
    - Face voice routing is no longer a singleton. Epiphany persists typed FaceVoiceEndpoint rows with id, display name, thread id, voice, prompt, enabled flag, XY proximity anchor, and an audible-radius scale. FaceVoiceRouter uses proximity only to choose the addressed endpoint for user input; enabled endpoints can all run concurrently so active rumination loops may speak regardless of listener distance. Distance shapes PCM output gain and stereo pan through AquariumAudioDocument/WasapiAudioDevice.
    - Global GraphicsSettings document feeding render debug, exposure, bloom intensity, and bloom veil.
    - Temporal resolve uses scene color, metadata, and control history only; dormant event history lanes are cut until a real producer and consumer contract exists.
    - Aquarium owns the temporal SDF Gaussian field renderer boundary: clients can publish `AquariumTemporalGaussianField`, `TemporalGaussianAccumulator` can buffer stable keyed observations in world space, and D3D12 lowers those packets into an instanced compact-kernel splat pass that writes normal scene color/travel/metadata/control targets.
    - Temporal Gaussian accumulation now lowers through `TemporalSpatialEvidenceReservoir`, a renderer-agnostic stable-key reservoir for confidence-weighted spatial samples with presentation delay, smoothing, velocity prediction, expiry, and max-track eviction. Gaussian splats are one lowering; fractal SDF probe evidence and Mimir sensor-fusion features should use the same reservoir shape when they need delayed coherence solving.
    - LocalCast fallback GPU fusion history delegates to `TemporalSpatialEvidenceReservoir`. `LocalCastGpuFusionAccumulator` is now an adapter that maps LocalCast stable seeds into shared evidence observations and back into GPU fusion seeds; it does not own a parallel temporal sampling algorithm.
    - The temporal reservoir ownership contract lives in docs/temporal-spatial-evidence-reservoir.md. `ResampledImportanceReservoir<TSample>` owns RIS/ReSTIR-style candidate selection math: selected sample, target value, weight sum, represented candidate count, merge, and contribution weight. Raw producer reservoirs own capture-time retention; Aquarium's temporal spatial evidence track layer owns stable resolved spatial history; lowerings own backend packet conversion; TAA owns pixel history validation.
    - Isolated Epiphany agent preview renders run through the real D3D12 renderer from src/Aquarium.Epiphany.AgentPreview; preview isolation is owned by a preview-only scene shader, while the engine exposes only final-frame PNG capture.
    - Zyphos is the first nontrivial non-Epiphany client: a planetary-scale demo with spherical-domain terrain, atmospheric rim lighting, night-side glints, fixed-sky Umbros, and first-pass eclipse cadence.
    - Zyphos/Umbros render-scale binary constants live in src/Aquarium.Zyphos/ZyphosUmbrosSystem.cs: Umbros is modeled as a 0.9-radius mutually tidally locked twin at 8 Zyphos radii, while the dim primary star phase moves through the Zyphos-local frame.
    - Zyphos simulates the neighboring Eusocial Interbeing setting; the vault at E:\Projects\Eusocial Interbeing owns canon, while Aquarium owns demo rendering constraints and feeds worldbuilding questions back through the vault's Zyphos Simulation Brief.
    - Future planetary terrain and fractal body detail should use a cube-sphere/QSC-family address space: six quadtree cube faces projected to the sphere with a measured low-distortion warp, avoiding lat-long pole singularities.
    - Fractal world patches can declare nested semantic domains before terrain tiles. The first .aquageo patch declares solar, orbital, planetary, lat/long, and cube-tile domains for both Zyphos and Umbros so DSL nodes can attach to explicit reference frames before backend lowering.
    - The fractal grammar layer validates nested domain topology through FractalDomainGraph: duplicate keys, missing parents, cycles, and root-to-leaf paths are grammar concerns, not renderer folklore.
    - Aquarium frames now carry a 3D camera target in addition to the legacy 2D ViewFrame center. Zyphos uses a camera composer to separate tracked subject, parent composition anchor, and camera orbit distance.
    - Zyphos camera navigation is domain-key driven: selecting any solar/orbital/planetary/surface/object/tile domain in the floating Navigation tree changes the active camera mode, derives the parent pivot from the domain hierarchy, and lets mouse drag/wheel orbit or zoom that selected spatial frame. Zyphos and Umbros both expose lat/long surface domains, recursive subdomains, object-scale domains, and cube-tile children.
    - Zyphos domain zoom is scale-aware: leaf/pebble domains can drive the camera below planetary distances, while larger domains retain broad framing. The parent star is a rendered SDF object as well as a light source, so selecting the Solar domain targets a visible sun instead of an invisible lamp.
    - The current height-field stress backend uploads a fixed table of 64 shaped 2D brushes to D3D12. The richer Zyphos/Umbros .aquageo patch currently emits 61 brushes across recursive continent/forest/leaf/flame/coast/pebble and Umbros crater/boulder/pebble domains.
    - Zyphos and Umbros SDF planet shaders include cheap bounded quadtree-style layered relief in object space, separate from the flattened 2D height-brush stress path.
    - SceneState can disable the legacy height-field surface trace and request a procedural starfield background; Zyphos uses this for space views so the old Grid does not leak into planetary rendering.
    - Future multiscale terrain and agent/body detail should come from bounded IFS brush grammars using shared shaped anisotropic envelopes; texture/material detail can be abundant, but traced SDF form detail must be proxy-bounded, LOD-gated, and measured.
    - The IFS brush grammar should preserve a semantic ownership tree before backend lowering: local frames, deterministic seeds, named fields/captures, tags, payload bindings, LOD/cost tiers, and boolean-style union/subtract/common nodes should survive even if the first renderer path flattens them into fixed brush tables or SDF shader code.
    - IFS LOD should be driven by cached node contribution summaries: each node carries bounds, projected error/material delta, coverage, cost, estimator state, residency, and summary/child payload handles so traversal can choose a stable hierarchy cut and render parent summaries while child details stream or fade in.
    - Contribution weights cannot all be refreshed every frame; the cache needs a probabilistic online estimator that samples nodes under budget, updates mean/uncertainty/sample age/confidence, preserves nonzero exploration for visible or near-threshold nodes, and can later become a learned predictor without replacing conservative SDF bounds.
    - Fractal resource planning is explicit: one plan coordinates CPU contribution updates, GPU selected-cut estimated cost, RAM resident payload budget, and SSD request pressure before backend packet compilation. This same budget language should generalize to Mimir-style sensor fusion because both fractal SDF probes and camera/microphone feature detections accumulate confidence-weighted spatial samples into temporal reservoirs.
    - The consolidated fractal brush architecture plan defines the intended pipeline: client intent -> domain roots -> semantic IFS brush grammar -> ownership tree -> node summaries -> contribution cache/residency scheduler -> backend packets -> renderer passes -> debug/evidence, with explicit module boundaries and mockable unit-test seams.
    - The Perfect Machine architecture lives in docs/perfect-machine-architecture.md. It is the current waterfall design authority for fast 2D SDF splats, 3D SDF splats, 2D-projected-to-3D surface splats, IFS `.aquageo` structural probes, Mimir-style camera/audio evidence candidates, ReSTIR/GRIS reservoir reuse, heuristic occupancy graph updates, resource-tier residency, and TAA guide-buffer integration.
    - The actionable fractal brush implementation roadmap lives in research/rendering/fractal-brush-implementation-roadmap.md and is the execution authority for the first pass.
    - Bundled blue-noise texture assets are retained for future dithering/noise work even though the removed medium path no longer samples them.
    - D3D11 scene renderer, runtime volumetrics, cloud/fog research, medium/froxel render targets, and the SDF-field renderer plan are shelved and removed from live repo state.
  next:
    - Extend explicit renderer debug modes for hits, normals, depth, bins, and lighting.
    - Replace the current legacy fixed D3D12 pass execution with the declared AquariumRenderPlan graph compiler and executor.
    - Keep src/Aquarium.Sample.Minimal building and launchable as the non-Epiphany boundary proof.
    - Replace fixed fallback role motion with real CultNet-derived AgentVisualState.
    - Build each agent role body from one coherent low-cost SDF form model before adding ornamental or state-reactive detail.
    - Prototype cube-sphere projection candidates for Zyphos: tangent warp, fifth-order odd polynomial warp, and COBE/QSC-style bivariate warp. Measure area error, inverse lookup cost, and shader cost before committing the terrain address space.
    - Define the first shaped brush envelope contract as a compact-support anisotropic kernel with rotation, radii/inverse covariance, falloff, shape controls, payload type, and explicit bounds shared by 2D terrain brushes and 3D SDF/body brushes.
    - Design the first Aquarium IFS/CSG brush DSL as semantic claims plus an ownership tree, informed by VibeGeometry's `vg_grammar` and `vg_csg` tree: the tree is durable design; flattened shader packets are backend output.
    - Define the first IFS LOD node-summary and contribution-cache layout before rendering recursive detail: stable domain keys, projected-error scoring, stochastic update priority, mean/variance/confidence estimator state, hysteresis fade weights, resident/missing child states, and debug views for score/uncertainty/sample-age/depth/cache/cost.
    - Replace the legacy height-field plane with explicit 2D SDF domain surfaces. Aquarium's Grid should become a dynamic gravity-updated domain surface; Zyphos' terrain surfaces can stay static and should flow through the same cache-friendly surface-domain path.
    - Follow the step-by-step roadmap in research/rendering/fractal-brush-architecture-plan.md before implementing recursive terrain or agent-body detail; first slice is cube-face projection harness, shaped 2D brush envelope, semantic claim/tree structs, flattening to the current height brush pass, and debug overlays.
    - Begin fractal brush implementation with the first work packet from research/rendering/fractal-brush-implementation-roadmap.md: add Aquarium.Engine.Fractal plus tests, cube-face/tile keys, identity/tangent projection candidates, area distortion sampler, face-edge tests, and a projection report.
    - Add diegetic labels and object-local menus after renderer and text contracts are stable.
    - Continue replacing legacy fixed D3D12 pass execution with client-declared render targets, cameras, shaders, passes, resources, and features.

next_actions:
  - Keep main as the live development branch.
  - Keep scripts/verify-boundaries.ps1 green: Aquarium.Engine and Aquarium.Engine.Contracts must not contain Epiphany/client policy nouns such as grid, agent, body, or epiphany.
  - Verify publish output after every packaging-affecting change.
  - Update AquaSynth.Faust/Core only by packing new versions into packages and changing the pinned PackageReference version deliberately.
  - Grow renderer debug controls through the Direct2D/DirectWrite overlay path.
  - Use scripts/render-agent-preview.ps1 for multi-view isolated SDF review before asking the user to judge another agent body iteration.
  - Follow research/rendering/hdr-pbr-presentation.md before changing HDR exposure, bloom, tonemapping, or display transforms.
  - Follow research/rendering/cube-sphere-fractal-brushes.md before replacing planetary terrain addressing, height brushes, or agent/body detail grammars.
  - Follow research/rendering/fractal-brush-architecture-plan.md before implementing the fractal brush DSL, IFS LOD cache, recursive detail residency, or learned contribution scoring.
  - Follow docs/perfect-machine-architecture.md before expanding SDF splat backends, sensor-fusion candidate adapters, reservoir guide buffers, occupancy graph state, or stochastic learned priority.
  - Use research/rendering/fractal-brush-implementation-roadmap.md as the actionable execution checklist for fractal brush work.
  - Follow docs/zyphos-eusocial-sync.md and E:\Projects\Eusocial Interbeing\Eusocial Interbeing\World\Zyphos Simulation Brief.md before turning Zyphos visual choices into setting claims.
  - Follow docs/tsr-inspired-taa-spec.md when changing current temporal diagnostics.
  - Use docs/temporal-sdf-gaussian-field.md before wiring LocalCastBridge visual sensor fusion into Aquarium or scaling the temporal Gaussian renderer beyond the current bounded instanced pass.
  - Use docs/temporal-spatial-evidence-reservoir.md before adding any stable-key temporal spatial cache, sensor-fusion accumulator, SDF probe reservoir, or new evidence packet lowering.
  - Promote future runtime knobs into typed CultCache documents before they become process folklore.
  - Next Face voice slice: replace text-only input with microphone/WebRTC or a native capture bridge, bind endpoint anchors to real Face/body spatial projections instead of manual XY rows, then move the transport contract from Codex JSON-RPC compatibility toward a typed CultNet FaceVoiceSession once Epiphany advertises that surface.
  - Keep Aquarium and Epiphany in one repo until the contracts and graph API are stable enough for Epiphany to move out without carrying engine policy or reload folklore with it.