Fensalir/state/map.yaml

project:
  name: Aquarium Engine
  root: E:\Projects\Aquarium-Engine
  upstream: https://github.com/GameCult/Aquarium-Engine
  purpose: >
    Native C# engine core for the Epiphany Aquarium client. The engine owns the
    Win32 host, D3D12 renderer, input loop, client reload boundary, and future
    render graph abstractions. The Epiphany client owns frontend intent and
    configures those engine abstractions.

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
    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
  samples:
    minimal_client: src/Aquarium.Sample.Minimal
  dependencies:
    cult_math: E:\Projects\CultMath
    cult_lib: E:\Projects\CultLib
    aquarium_synth_dsl: NuGet package AquariumSynth.Dsl 0.1.0-aquarium.1 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
    input: docs/input.md
    hdr_pbr_presentation: research/rendering/hdr-pbr-presentation.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.
    - 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.
    - Aquarium exposes an optional synth/audio hosting boundary through AquariumSynthDocument; Aquarium consumes AquariumSynth.Dsl as a pinned repo-local NuGet package so synth-agent construction cannot break Aquarium builds until the package is intentionally updated.
    - 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.
    - 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.
    - 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 AquariumSynth.Dsl only by packing a new version into packages and changing the pinned PackageReference version deliberately.
  - Grow renderer debug controls through the Direct2D/DirectWrite overlay path.
  - Follow research/rendering/hdr-pbr-presentation.md before changing HDR exposure, bloom, tonemapping, or display transforms.
  - Follow docs/tsr-inspired-taa-spec.md when changing current temporal diagnostics.
  - Promote future runtime knobs into typed CultCache documents before they become process folklore.