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 alive."
  },
  "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.",
    "Plain renderer truth beats decorative fog hiding a confused light story.",
    "Fast iteration matters. Hot reload must protect the last good runtime and state.",
    "Typed state beats sidecar soup."
  ],
  "technical_memory": {
    "native_engine": [
      "Aquarium Engine lives at E:\\Projects\\Aquarium-Engine and is the live C# line. Main is the development branch after the 2026-05-08 merge.",
      "The host owns Win32 windowing, D3D11 swapchain creation, shader compilation, input translation, and the live-runtime assembly boundary. Do not outsource the core frame protocol to a hidden framework loop.",
      "Use Vortice at the graphics API membrane. Keep CultMath as the CPU math grammar. Do not let third-party math opinions leak inward unless the conversion is explicit.",
      "The renderer currently uses a fullscreen HLSL path. Traditional geometry is allowed only as scaffolding; the visible Aquarium world should be shader-owned."
    ],
    "camera_and_grid": [
      "The camera target is the Grid center on XY. Grid radius derives from zoom distance. 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, weather, line, and future fog domains should sample world-space coordinates so panning reveals the field instead of sliding a texture under the camera.",
      "Aquarium/Aetheria clouds are local SDF media: above, below, around, and sometimes enclosing the camera. Do not build the core cloud path on skybox, hemisphere, paraboloid, or far-only assumptions.",
      "Cursor and camera interactions should project onto the same XY surface used by the Grid contract."
    ],
    "raymarching": [
      "Broad-phase structures are conservative skipping tools, not visible geometry. They may decide which primitives a ray checks; they may not clip a surface early.",
      "Planetoids are bounded by spheres. Once a ray segment intersects the sphere, solve entry/exit analytically and refine against displaced SDF inside the bounded interval instead of wasting global march steps.",
      "Planet-local detail must be translation-invariant: local coordinates can be point minus body center, but seeds come from stable body identity, never position or transient slot order.",
      "Normals must be evaluated from the same surface definition that produced the visible hit. A broad sphere normal is not acceptable once displacement shapes the visible surface.",
      "Keep lockstep march modes while debugging. Blue-noise jitter and temporal smoothing are useful after the artifact is understood, not before."
    ],
    "lighting": [
      "Lighting must be diegetic by default. Self is the initial emitter; later light should come from Aquarium-owned fields and transport, not ambient convenience fill.",
      "If surfaces read brighter than Self, the light story is broken. Diagnose source terms, texture contents, bloom order, and tonemapping before polishing.",
      "HDR bloom belongs before tonemapping and should be gentle in intensity but broad enough to spread true emissive energy.",
      "Future volumetric lighting should be a field sampled consistently by terrain, planets, fog, particles, and diegetic UI. Do not fake only the planet term if the scene is supposed to bounce light.",
      "Volumetric design must start from research/volumetrics/synthesis.md. The first pass should follow Wronski/Hillaire production shape: explicit low-resolution frustum volume, injected density/extinction/scattering, Self as first emitter, front-to-back transmittance/in-scattering integration, then consistent composition.",
      "For GPU SDF or newer volumetric storage, consult research/volumetrics/recent-volumetrics-and-gpu-sdf.md. The durable pattern is cascaded sparse bricks, compressed distance/occupancy, separate static/dynamic updates, toroidal partial updates, and learned fields only when runtime evaluation stays cheap and inspectable.",
      "For research decks with recordings, pull subtitles/transcripts before distilling. The Dreams transcript changed the lesson: preserve the evaluator/field that serves the image, not the elegant SDF/brick/froxel experiment that drifted away from the art direction.",
      "Sea of Thieves clouds are the stylized counterexample: authored opaque cloud geometry filtered through low-res blurred color/depth compositing can beat dense raymarching when clouds are symbolic world objects or gameplay signage. Consider tool-time SDF baking for per-vertex cloud lighting, not runtime volume traversal by reflex.",
      "The SDF field renderer plan is docs/sdf-field-renderer-plan.md: solids and clouds should share one field grammar, with distance, density, material, medium, bounds, and debug views.",
      "SDF cloud distance should shape and accelerate the medium, not create a positive-distance absorbing shell. Prototype ellipsoid edges occluded farther clouds until density was changed to eroded interior occupancy with lower extinction.",
      "A bounded cloud prototype should march analytic ray/volume intervals, not global SDF shells. The first cloud artifact persisted until rays jumped between true ellipsoid entry/exit intervals; otherwise near fields can consume the sample budget and masquerade as occluders.",
      "SDF clouds/solids need waterfall architecture, not agile accretion. Define and build the field contract, broad phase, explicit local volume pass, composition contract, and acceleration gates before adding more cloud features.",
      "Until the real field renderer exists, do not composite the analytic SDF cloud scaffold into the Aquarium scene. The Grid should read as a transparent schematic overlay; volumetrics will own scene mass later.",
      "For diegetic Grid transparency over raymarched content, use Aetheria-style stochastic coverage rather than alpha blending, and depth-test it against nearer solid bodies so the Grid does not draw over planets. Aquarium has copied Aetheria's LDR_LLL1_0 blue-noise texture and binds it for Grid dither coverage.",
      "TSR-inspired TAA is specified in docs/tsr-inspired-taa-spec.md. Gate 1 is an owned clean-room temporal resolve: HDR/travel scene target, Halton jitter, camera reprojection, 3x3 neighborhood clamp, travel rejection, ping-pong history, and tonemap after resolve.",
      "TAA Gate 2A adds scene/history metadata with field identity and surface normal rejection. Grid stochastic surfaces must record Grid travel/normal even on dither-miss pixels so history accumulates the diegetic Grid surface instead of the solid behind it.",
      "TAA Gate 2B uses stable field ids and analytic object-motion reprojection for orbiting planets: current planet hit positions are offset from current center to previous center before projecting into history.",
      "TAA Gate 3A adds a separate current-frame temporal-control target: reactive strength, stochastic/composition coverage, reserved medium opacity, and reserved spare. The resolver reduces history for low-coverage reactive Grid samples; future volumetrics must extend this contract rather than pretending one opaque hit depth is enough.",
      "TAA Gate 3B ping-pongs temporal-control history. Resolve now compares previous/current coverage and reserved medium opacity at the reprojected UV, reducing history across composition and future medium discontinuities.",
      "TAA Gate 3C stores accepted history age in temporal-control history w. Validation grows age, failed validation resets it, and history authority ramps with age so fresh history can contribute without instantly gaining full trust.",
      "TAA travel validation must compare previous history travel to the reprojected previous-world point's distance from the previous camera. Comparing previous travel directly to current travel falsely rejects stable history during camera motion.",
      "Stochastic Grid TAA must not use opaque-surface neighborhood color clamp or current-frame color-delta rejection. A dither miss makes the current color look like background; Grid history should validate through field/travel/normal/coverage/reactive/age instead.",
      "Stochastic Grid TAA needs high-retention history and must not reduce history weight just because current coverage is low. Low coverage is exactly where temporal accumulation has to do the work; coverage belongs in continuity validation, not as an authority penalty.",
      "TAA identity/control buffers must be point-loaded, not linearly sampled. Field ids are identities, not colors; interpolating them at silhouettes lets foreground solids contaminate background Grid history. Grid history color should use identity-aligned nearest sampling to avoid bright foreground bleed.",
      "Grid temporal coverage must mean current line/contour/field-line support, not broad overlay alpha. Broad low-alpha tint can render, but it must not keep history age alive across the Grid surface or stale stochastic hits billow into smoke.",
      "Grid TAA must not use the raw stochastic hit/miss scene color as the current radiance truth. The resolve should reconstruct analytic Grid overlay color at the current world hit and use premultiplied color as the current estimate, then use history for stability rather than reconstructing alpha from binary noise alone.",
      "For the current Grid renderer, final Grid color should not blend previous color history. Use analytic current Grid color for the final pixel and write it into history; keep history age/weight/debug as diagnostics until a real transparent/volumetric composition contract needs color history again.",
      "Projection jitter is currently scaled to zero. If Self or planet surfaces visibly judder, the resolve is not hiding jitter and the correct live choice is no jitter until opaque and Grid paths both prove stable.",
      "Temporal debug views are live keys: F1 cycles, 0 final, 1 raw current scene, 2 reprojected history, 3 history age, 4 history weight. Use these before guessing whether TAA is sampling, validating, or presenting the wrong signal.",
      "Bruneton-style atmospheric scattering is the later sky/planet solution, not the first Grid fog pass. Use LUTs, explicit texture mappings, and unit-tested physical terms when Aquarium reaches ground-to-space atmosphere.",
      "GigaVoxels-style ray-guided sparse bricks are only for large sparse field/world storage. Do not turn early fog into a monolithic persistent volume cache."
    ],
    "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.",
      "Bundled fonts are Montserrat for thin small-cap display text and Ubuntu Sans for body/debug copy. Runtime must not depend on fonts installed in Windows.",
      "Scene/diegetic labels should use renderer-owned MSDF/SDF billboards when they live in world space. Overlay text should not be shoved into HDR just because it is convenient.",
      "Debug UI is allowed as an explicit escape hatch. Object-owned radial surfaces remain the target interaction grammar."
    ],
    "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.",
      "The current live document is epiphany.aquarium.live_state, stored through CultLib MessagePack backing. Direct runs can use --cache or AQUARIUM_CULTCACHE_PATH.",
      "dev-reload builds disposable apphost slots so a running window does not lock normal build output. dev-watch hot reloads shaders and live runtime DLLs while preserving the last good process. Host/core/content changes, scripts, and src/Aquarium.Engine/Assets must rebuild and restart the apphost on demand. dev-watch must also relaunch if its recorded script-owned process is no longer running. For visible windows, dev-watch -ReopenWhenClosed reopens the last good visible slot without rebuilding.",
      "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, or treat the update as failed and keep the previous runtime/process alive.",
      "dev-watch must not use Start-Process -Wait to run dev-reload while dev-reload launches the long-lived Aquarium app. On Windows that can leave the watcher stuck after initial launch, never reaching the poll loop. Invoke the reload script synchronously and let dev-reload own the detached app process.",
      "Shader reload failure must keep the previous good shader objects bound. Live-runtime reload failure must keep the previous runtime alive. Rehydrate from CultCache before claiming reload survival."
    ],
    "salvage_without_baggage": [
      "Earlier UI work proved object-owned progressive disclosure and crisp text. Carry the interaction lesson, not the stack.",
      "Earlier renderer work proved raymarched bodies, Grid-space fields, HDR, and explicit camera/Grid invariants. Carry the renderer lessons, not the host architecture.",
      "Earlier synth work is useful as an external oracle for patch grammar, analysis, and performance targets. Port ideas intentionally when audio returns; do not vendor abandoned branches into the engine."
    ]
  },
  "warnings": [
    "A clean repo can still grow Jenga if state and docs lag behind the 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."
  ]
}