Aquarium

Aquarium is Epiphany's native visual body. It is the client that turns Epiphany state into a spatial scene: Self, Face, Imagination, Eyes, Body, Hands, Soul, Life, the cursor, the Grid, Face voice routing, client state, and the Epiphany-specific SDF body language.

Fensalir supplies the native host, D3D12 renderer, hot reload, audio output, and shared contracts. Aquarium supplies the meaning, layout, state documents, voice surface, render plan, and SDF shaders that make the scene Epiphany instead of a generic renderer demo.

Front Door

• Value: the spatial client for Epiphany: a scene of analytic SDF role bodies (Self, Face, Imagination, Eyes, Body, Hands, Soul, Life) orbiting a height-field Grid, with a Face voice-routing surface and typed CultCache client state.
• Problem: Epiphany's organs are state documents. Aquarium gives each organ a readable, bounded body so an operator can see the machine instead of reading a dashboard.
• Entry points:
  • src/Aquarium.Epiphany: the IAquariumRuntime Fensalir loads each frame (AquariumRuntime.cs, EpiphanySceneBuilder.cs, EpiphanyRenderPlan.cs, Shaders/, Voice/, State/).
  • src/Aquarium.Epiphany.AgentPreview: renders one body through the real Fensalir renderer; run it with scripts/render-agent-preview.ps1 -Agent Soul.
  • docs/epiphany-agent-sdf-visual-language.md: the SDF design contract for every body.
  • scripts/dev-reload.ps1: launch the client through Fensalir (see Run below).
• Live: the runtime loop, scene builder, render plan, role-body shaders, orbit camera, CultCache client state, and Face voice routing state.
• Planned: projecting live Epiphany documents (memory, heartbeat, pressure, role results) into the bodies. Today EpiphanySceneBuilder drives each role's activity, heartbeat and pressure from synthetic functions of time; the visual-language document names the intended inputs.
• Build: Windows only. Needs sibling Fensalir and CultLib checkouts (see Dependency and Building against CultLib).

What The Client Is

Aquarium is not an engine repo and not a dashboard with a viewport bolted on. The viewport is the client. Epiphany appears as bodies in a field:

• Self is the central body, coordinator anchor, and scene light.
• Face, Imagination, Eyes, Body, Hands, Soul, and Life are orbiting role bodies with distinct anatomy and materials.
• The cursor is a scene body with current and previous world-space state.
• The Grid is a height-field surface shaped by Self, role wells, and cursor pressure.
• The camera is an orbit rig around the Grid center, persisted through CultCache.
• Overlay UI exists for runtime control, but the embodied scene is the app.

The repo contains the Aquarium runtime, an isolated agent preview tool, docs, scripts, and persistent project memory. Reusable host/renderer machinery lives next door in Fensalir.

Runtime Loop

src/Aquarium.Epiphany implements IAquariumRuntime. Fensalir loads it and calls into it each frame:

Fensalir host
  -> Aquarium.Epiphany runtime
  -> CultCache state load/save
  -> orbit camera + input projection
  -> Epiphany scene builder
  -> Epiphany render plan
  -> Grid height-field brushes
  -> Epiphany SDF body shaders
  -> Face voice routing and optional PCM audio

AquariumRuntime owns live client state. It loads typed CultCache documents, keeps camera/runtime settings warm, saves on a short cadence, builds the Epiphany debug panel, accepts runtime UI commands, and composes each frame.

The panel exposes time pause/scrub, explicit state flush, graphics settings, Face voice endpoint rows, prompts, routing state, transcript counters, and transport status. It is operational surface. The app is still the spatial body it controls.

SDF Body Work

Aquarium's current visual language is analytic SDF role bodies over the Grid. The body shaders live under src/Aquarium.Epiphany/Shaders; the design contract lives in docs/epiphany-agent-sdf-visual-language.md.

The live rules are:

• each organ gets a distinct SDF family, not a color swap;
• each shader exposes a cheap bound/hit distance and a refined surface material;
• material regions stay inside the role shader: core, shell, tool edge, lens, ribbon, memory seed, bubble, risk seam, and similar readable anatomy;
• state should move low-dimensional parameters first: radius, lobe count, twist, aperture, rib spacing, pulse phase, shell openness, wake length;
• interaction roots must stay stable even while bodies breathe, fold, shimmer, or speak;
• role placement is Aquarium-owned world-space layout, derived from Epiphany semantic state rather than supplied as world coordinates by Epiphany.

The eight bodies are not a single heroic scene march. Aquarium renders bounded per-agent SDF proxy objects so role anatomy remains readable and cost remains inspectable. The agent preview tool exists to render one body through the real Fensalir renderer without dragging the whole client loop into every visual iteration.

Visible Machine

EpiphanySceneBuilder turns time, camera input, persistent state, and voice surface state into an AquariumSceneState.

The current scene contains:

• a 128x128 R16 height-field target for the Grid;
• a Self gravity bowl and wave contribution;
• orbiting brush wells for each role agent;
• SDF proxy objects for Self, the seven roles, and the cursor;
• Self-owned scene light;
• cursor projection from screen space onto the Grid plane;
• normalized state scalars passed into shaders for each body.

EpiphanyRenderPlan declares the pass structure: height-field, HDR scene, SDF proxies, bloom/presentation, DirectWrite overlay, and debug views for the height field and scene.

Epiphany Integration

Aquarium owns the projection from Epiphany's semantic surfaces into visible spatial state. The SDF visual-language document names the intended inputs: agent memory, heartbeat, role surfaces, role results, coordinator state, Face surface, jobs, pressure, and reorientation documents.

Planned, not yet wired: those documents are normalized into bounded visual fields such as activity, readiness, load, blocked/completed state, heartbeat phase, wake intensity, memory resonance, pressure, review state, risk, confidence, evidence gaps, speaking state, job count, home orbit slot, expressive offset, gravity-well pulse, lift, and trait activations.

Epiphany supplies meaning. Aquarium owns the spatial projection and SDF language. Fensalir renders the pixels.

Face Voice Surface

Face voice routing is Aquarium state because it is Epiphany meaning, not renderer machinery. The runtime stores endpoint rows, voices, prompts, enablement, active thread, audible radius, and auto-route settings through CultCache-backed state.

When enabled, the Face voice surface can start active or enabled endpoints, stop active speech, clear local transcript counters, and route speech by the scene/proximity model. Fensalir supplies the audio output lane; Aquarium decides which Face should speak and why.

Projects

• src/Aquarium.Epiphany: runtime, render plan, scene builder, persistent state, voice routing, camera rig, UI commands, and shaders.
• src/Aquarium.Epiphany.AgentPreview: isolated preview tool for rendering one Epiphany agent body through the real Fensalir renderer.
• scripts: wrappers around Fensalir dev scripts, plus the agent preview renderer.
• docs: SDF visual grammar, CultCache state surface, and Fensalir dependency notes.
• state: repo-local memory, map, evidence, and scratch state.

Dependency

This repo currently references sibling Fensalir source projects at ..\Fensalir (a Fensalir checkout next to this one). That is intentional until Fensalir has a packaged API.

Do not copy renderer contracts, host scripts, or D3D12 helpers into Aquarium. If Aquarium needs new renderer authority, add it in Fensalir and consume it through contracts. If a behavior names Epiphany roles, client voice policy, agent meaning, SDF anatomy, or scene semantics, it belongs here.

Build

Requirements:

• Windows
• .NET SDK matching global.json
• sibling checkouts ..\Fensalir and ..\CultLib

dotnet build EpiphanyAquarium.sln

Run

Launch through Fensalir:

.\scripts\dev-reload.ps1

Run headless:

.\scripts\dev-reload.ps1 -Headless -RetainSlots 4

Watch and reload on source changes:

.\scripts\dev-watch.ps1

Render isolated agent preview frames:

.\scripts\render-agent-preview.ps1 -Agent Soul

State

Aquarium persists typed client state through CultCache:

• camera target, yaw, pitch, distance, and runtime time;
• renderer presentation settings owned by shared contracts;
• Face voice endpoint rows, prompts, routing state, and transport settings.

Speech transcript counters are local runtime surface, not durable Epiphany memory.

Docs

• docs/epiphany-agent-sdf-visual-language.md: SDF visual grammar for Epiphany bodies.
• docs/cult-runtime-surface.md: client CultCache document surface.
• docs/fensalir-dependency.md: what Aquarium consumes from Fensalir.
• state/README.md: persistent state machinery.

Building against CultLib

Builds are pinned to CultLib 2.0.0 (tag cultlib-unity-v2.0.0, revision 42dce3611a81adc5c5fac54cadbaa5637d6022d3); the build fails if the CultLib checkout differs or is dirty. Create a pinned worktree and point the build at it:

git -C <CultLib> worktree add --detach <path> cultlib-unity-v2.0.0
dotnet build -p:CultLibRoot=<path>   # or set CULTLIB_ROOT=<path>

Without an override the sibling ..\CultLib checkout is used and must itself be at that tag.