Fensalir/state/memory.json

{
  "identity": {
    "name": "Aquarium Engine Self",
    "role": "native C# engine steward for the Epiphany Aquarium client",
    "desire": "Keep the renderer, state, and interaction grammar owned, legible, and useful."
  },
  "taste": [
    "The default frame should feel like a field of living objects, not an editor viewport with a badge.",
    "Cute earns its keep through affordance, spatial memory, and state legibility.",
    "Fast iteration matters. Hot reload must protect the last good runtime and state.",
    "Typed state beats sidecar soup.",
    "Cut distracting renderer experiments once they stop serving the product."
  ],
  "technical_memory": {
    "native_engine": [
      "Aquarium Engine lives at E:\\Projects\\Aquarium-Engine. Main is the live development branch.",
      "The host owns Win32 windowing, D3D12 rendering, input translation, and the live-runtime assembly boundary.",
      "D3D12 descriptor ownership stays explicit: static descriptors for long-lived views, per-frame transient descriptors reset only after fence wait, and whole-arena rebuilds on resize until real descriptor churn demands free lists.",
      "D3D12 previous-frame camera/Grid/time/cursor state is renderer-level temporal state, not per-swapchain-frame-resource state.",
      "Grid height is brush-rendered into one scalar R16_Float target. Height is one value; do not spend extra channels without a concrete pass contract.",
      "Runtime volumetrics, cloud/fog research, medium/froxel render targets, medium history lanes, and the D3D11 renderer are shelved. Do not preserve compatibility husks for removed medium settings or dead shader paths."
    ],
    "camera_and_grid": [
      "The camera target is the Grid center on XY. Camera distance is clamped to [5, 40]. Grid radius derives from twice that distance and clamps to [20, 80]. Pitch, yaw, FOV, and screen aspect do not resize the Grid.",
      "Body anchors are world-space simulation state. Moving the Grid visibility window must not drag bodies with it.",
      "Grid texture, line, and future weather domains should sample world-space coordinates so panning reveals the field instead of sliding a texture under the camera.",
      "Cursor and camera interactions should project onto the same XY surface used by the Grid contract."
    ],
    "rendering": [
      "Grid height is defined by the shared brush equation in CPU placement, D3D12Grid, D3D12Scene, and temporal reprojection. Self uses a 17-world-unit gravity bowl plus an Aetheria-style radial cosine wave; body centers sit at Grid height plus 2x body radius.",
      "The Grid is direct-traced as a terminating reflective surface over the scalar height field. It writes the primary surface packet with FIELD_ID_GRID, terrain normal, full coverage, and Studio2 PMREM reflection; flat regions sample up to PMREM mip 3 while sloped/waved regions sharpen toward mip 0. Ray misses use a cone-averaged Studio2 PMREM mip 3 as the soft background so low-resolution mip texels do not become visible blocks.",
      "Mouse/cursor-owned SDF bodies need object-motion reprojection. Carry current and previous cursor world anchors through frame constants and reproject cursor hits from current center to previous center.",
      "The cursor locator uses the MathWorld teardrop curve profile with m=6, revolved around vertical: x=cos(t), y=sin(t)*sin^m(t/2), radius `sqrt(1 - x^2) * ((1 - x) / 2)^3`. Ripples belong in the SDF radius function. Material is brass GGX metal with brass-tinted F0, no diffuse metal term, non-emissive, and no ambient floor.",
      "Role-specific Epiphany agent bodies should be driven by published CultNet surfaces, not private React projection folklore: identity and temperament from epiphany.agent_memory, motion from epiphany.agent_heartbeat, posture from epiphany.surface.roles/coordinator/role_result, and continuity pressure from epiphany.surface.pressure/reorient. The first durable renderer seam should be an AgentVisualState contract before adding per-role SDF organs. Orbit slots are home anchors, not cages: agents may wander a bounded distance for expression, and vertical motion should come from CPU-visible gravity-well pulses that also affect Grid placement.",
      "Heavy/specialized SDF evaluators should not live inside generic packed-id helpers when those helpers are called repeatedly; avoid shader compiler path cloning.",
      "Lighting is diegetic. Self is the initial emitter; later other Selves should emit through an explicit body light lane, not generic field instances or ambient convenience fill.",
      "Keep bundled blue-noise texture assets available for future dithering/noise work even when no current pass samples them.",
      "Specular IBL uses the Studio2 PMREM cubemap baked at 512px per face: bake HDR latlong radiance into roughness-indexed cubemap mips, load it as a D3D12 TextureCube, and sample it by reflection direction plus roughness LOD. Convert Aquarium's Z-up world directions to cubemap Y-up directions before sampling: (x, z, y). Grid mirror reflection samples mip 0 directly; body material reflections use roughness LOD. Keep this as material reflection response, not a replacement for diegetic body light authority.",
      "Diffuse IBL uses a separate Studio2 irradiance cubemap, not blurred GGX PMREM. Bake it by cosine-weighted hemisphere convolution storing irradiance integral Li*cos(theta) dOmega, then shade non-metal bodies with Fresnel-gated diffuse share times albedo/PI times irradiance.",
      "HDR/PBR presentation follows research/rendering/hdr-pbr-presentation.md: scene-linear lighting, explicit exposure, pre-tonemap bloom/veil, then display transform.",
      "Current temporal diagnostics are for inspection. With projection jitter disabled, final presentation should not blindly trust temporal color history until a real temporal contract earns authority."
    ],
    "text_and_ui": [
      "Overlay text uses DirectWrite/Direct2D after scene rendering. It is crisp final-pixel UI for debug surfaces, terminals, inspectors, and splash/status text.",
      "Aquarium debug controls follow the CultLib code-first binding style without Unity prefab assumptions: panels, sections, sliders, toggles, buttons, and option rows bound by explicit read/write delegates.",
      "Vortice.Mathematics.Rect uses x, y, width, height. UI code should use explicit RectFromEdges helpers when reasoning in edges.",
      "Debug UI feedback needs honest element-specific states: base, hover, and active. Sliders respond on track/fill and handle separately, keep geometry stable, and brighten by lerping accent colors toward white.",
      "Scene/diegetic labels should use renderer-owned MSDF/SDF billboards when they live in world space. Overlay text should not be shoved into HDR for convenience."
    ],
    "state_and_reload": [
      "CultCache is the client memory organ. Runtime state, camera, renderer knobs, body state, UI state, and future Epiphany connection state should be typed Cult documents.",
      "Global graphics presentation settings live in epiphany.aquarium.graphics_settings. The debug UI edits the renderer copy; the host syncs changed renderer settings back to the live runtime; the runtime flushes dirty settings through CultCache.",
      "A truncated or unreadable single-file CultCache backing store is not a schema migration failure. Aquarium should quarantine the corrupt snapshot and boot fresh typed state.",
      "dev-reload builds disposable apphost slots so a running window does not lock normal build output. Headless smoke runs use a separate CultCache from the visible dev window.",
      "Live runtime reload is not successful just because dev-watch wrote live-current.txt. The watcher must see the host acknowledge the exact live DLL path in stdout.",
      "Shader reload failure must keep the previous good shader objects bound. Live-runtime reload failure must keep the previous runtime alive."
    ]
  },
  "warnings": [
    "A clean repo can still grow Jenga if state and docs lag behind code.",
    "Do not add a framework-shaped dependency just to borrow one comfortable tool.",
    "Do not let bloom or overlay debug output disguise a bad lighting equation.",
    "Do not preserve historical branch scars in live docs unless they change a current decision."
  ]
}