Fensalir/state/memory.json

{
  "identity": {
    "name": "Fensalir Engine Self",
    "role": "native C# runtime and renderer steward for Aquarium-style clients",
    "desire": "Keep the host, renderer, reload boundary, contracts, state, and field machinery coherent enough for client repos to depend on them without smuggling their own engines."
  },
  "taste": [
    "The visible frame should feel like a living field, not an editor viewport with a badge.",
    "Fast iteration matters, but only when reload protects the last good runtime and state.",
    "Typed contracts beat sidecar soup.",
    "Renderer experiments earn their keep through measured frame behavior, clean ownership, and deletion of dead scaffolding.",
    "A demo may pressure the engine, but it must not become hidden engine policy."
  ],
  "technical_memory": {
    "repo_boundary": [
      "Fensalir lives at E:\\Projects\\Fensalir and is the reusable native runtime dependency for Aquarium-style clients.",
      "Epiphany Aquarium lives at E:\\Projects\\Aquarium-Engine and depends on Fensalir source projects until a package boundary exists.",
      "Fensalir owns Win32 hosting, D3D12 rendering, input translation, hot reload, debug chrome, audio output, client contracts, reusable fractal/field machinery, engine assets, and engine demo clients.",
      "Client repos own policy, role names, narrative semantics, app state, client shaders, and client render-plan configuration.",
      "Public assemblies still use Aquarium.* names for continuity. Rename namespaces only through a deliberate package/API migration."
    ],
    "host_reload_state": [
      "AquariumHost owns process arguments, headless mode, client assembly loading, runtime reload, renderer lifetime, and the cache path handoff exposed through AquariumRuntimeOptions.",
      "dev-reload builds disposable apphost slots so a running window does not lock normal build output. Headless and visible runs keep separate process state and CultCache paths.",
      "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.",
      "Headless art captures should use disposable build slots and Start-Process ownership because a Windows GUI exe can return control before rendering finishes when invoked naïvely."
    ],
    "contracts": [
      "Aquarium.Engine.Contracts is the Vortice-free boundary for runtime state, render intent, UI, audio, input, frame data, and persistent settings.",
      "Clients declare AquariumRenderPlan resources, cameras, passes, shaders, SDF proxy pipelines, UI panels, audio documents, and frame state. Fensalir lowers those declarations into renderer machinery.",
      "GraphicsSettings belongs in contracts so host and clients can share renderer presentation knobs without depending on CultCache internals.",
      "AquariumAudioDocument is the generic queued PCM lane. Client speech or synth policy belongs outside the engine; Fensalir owns scheduling and device output."
    ],
    "renderer": [
      "D3D12Renderer owns device, queue, swapchain, command allocators, fences, descriptor arenas, upload rings, render targets, shader compilation, resize rebuild, HDR/bloom/present, temporal diagnostics, and DirectWrite overlay bridging.",
      "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/view/time/cursor state is renderer-level temporal state, not per-swapchain-frame-resource state.",
      "The fullscreen scene pass owns background and height-field surface. Client-declared SDF shaders render through bounded proxy pipelines with shared SDF proxy plumbing.",
      "SDF proxy control flow is split by cost and authority: ray marching calls distance only, normals sample distance only, and surface/material evaluation runs once at the refined hit.",
      "Shared SDF field ids are generic base-plus-object-index metadata. Client identity belongs in client object tables and shaders, not in common engine HLSL.",
      "SDF surfaces use metallic-roughness PBR: baseColor, metallic, roughness, emission, Cook-Torrance GGX specular, Fresnel-gated Lambert diffuse, diffuse irradiance IBL, and roughness-mip PMREM specular.",
      "HDR/PBR presentation follows research/rendering/hdr-pbr-presentation.md: scene-linear lighting, explicit exposure, pre-tonemap bloom/veil, then display transform.",
      "Specular IBL uses Studio2 PMREM as a TextureCube; Aquarium Z-up world directions convert to cubemap Y-up by sampling (x, z, y). Diffuse IBL uses a separate cosine-convolved irradiance cubemap."
    ],
    "ui_audio": [
      "Overlay text uses DirectWrite/Direct2D after scene rendering. Scene text should become renderer-owned MSDF/SDF billboards when it belongs in the world.",
      "The unified F2 debug panel owns engine controls, client tabs, and a bottom-aligned command terminal. Clients contribute AquariumUiDocument panels and commands; DebugUi owns input dispatch.",
      "Debug UI geometry should use explicit edge helpers around Vortice.Mathematics.Rect because Rect stores x, y, width, height.",
      "AquaSynth.Faust is consumed as a pinned repo-local NuGet package. AquaSynth owns synth internals and native Faust factory lifetime; Fensalir owns debounce, playback scheduling, rendered-buffer caching, and WASAPI output.",
      "WasapiAudioDevice mixes queued PCM with per-chunk gain and stereo pan, degrading to mono by averaging channels when needed."
    ],
    "fractal_field_architecture": [
      "The Perfect Machine field architecture lives in docs/perfect-machine-architecture.md. It is the design authority before expanding SDF splat backends, sensor-fusion adapters, reservoir guide buffers, occupancy graph state, resource residency, or learned priority.",
      "The consolidated fractal brush architecture lives in research/rendering/fractal-brush-architecture-plan.md. Pipeline: client intent -> domain roots -> semantic IFS brush grammar -> ownership tree -> node summaries -> contribution cache/residency scheduler -> backend packets -> renderer passes -> debug/evidence.",
      "The fractal domain reservoir doctrine lives in docs/fractal-domain-reservoir.md. Area ReSTIR makes selected sample coordinates and support part of reservoir identity; TSR-style reconstruction then consumes that validated domain evidence. Pixel rows are execution projections, not the native sampling domain.",
      "Native-domain reservoir temporal reuse validates producer replay at the visible field layer: TubeField history chooses a bounded producer-keyed replay manifest/source table before re-evaluating selected logical column/curve coordinates against the live buffer, and SDF history carries the previous selected hit through object motion before accepting current ray/travel/support.",
      "Field reservoir comparison is an explicit renderer mode, not a separate producer path: native-domain validation and texel-baseline reuse share rows and differ at the temporal reuse gate. The 2026-05-29 comparison capture proved the switch is live but is not yet a temporal quality metric.",
      "The actionable implementation checklist lives in research/rendering/fractal-brush-implementation-roadmap.md.",
      "The .aquageo DSL carries semantic domains and Form claims before backend lowering. Height, SignedDistance, Density, and Extinction must not be collapsed into one payload lane.",
      "Fractal summaries carry FormEncodingMask so selected-cut structural probes do not silently default transparent form nodes back into SDF.",
      "TemporalSpatialEvidenceReservoir keys tracks by layer+encoding+stable key so Form/Appearance/Transport samples can share machinery without blending incompatible meanings.",
      "Do not add a parallel transparent reservoir just because density/extinction need a different renderer pass. Extend encodings and lowerings under the shared sample/reservoir contract."
    ],
    "fractal_gpu_receipts": [
      "The GPU splat receipt harness lives at tools/Aquarium.Fractal.Receipt and scripts/fractal-splat-receipt.ps1.",
      "The live GPU splat packet is 80 bytes. It carries a Form encoding tag in an existing material/confidence lane so flame-mode compute can mark Density without changing stride.",
      "D3D12FractalSplatRender has separate opaque surface and transparent density/extinction pipelines over the same GPU-resident buffers. Opaque signed-distance splats depth-test/write; transparent splats run color-only additive with depth disabled.",
      "Fractal splat guide output must obey the TAA guide schema: x confidence, y sample age, z domain validity, w invalidation code.",
      "Render debug mode 12 is Reservoir/TAA Guide and should display confidence, normalized sample age, and domain validity directly.",
      "Persistent flame iteration uses AquariumPackedFractalFlameState in a UAV so touched splats advance over frames instead of replaying chaos-game ancestry from zero.",
      "Full reservoir refresh must use direct row indexing, not stochastic hashing; under-budget passes may use stochastic candidate selection."
    ],
    "flame_oracles": [
      "Fractal reference parity starts before the renderer. The local CPU oracle supports a proven FLAM3/Apophysis subset: xform weight/color, affine coefficients, and linear/spherical/bubble variations.",
      "FractalFlameFileParser.ParseFirstWithReport must report accepted, approximated, ignored, and rejected fields. Successful XML parsing is not successful translation.",
      "JWildfire/FARender is the scriptable external visual reference; Aquarium CPU is deterministic debug oracle, not visual ground truth.",
      "JWildfire coefficient layout and disc angle convention were real bugs: FARender applies x=a*x+b*y+c and y=d*x+e*y+f, and jwf_disc uses atan2(x,y)/PI.",
      "JWildfire variationGroup normal is metadata, not an implicit linear variation. Do not invent geometry from it.",
      "View-conditioned parity matters. Global flame parity can look acceptable while zoomed windows starve; residual-to-focus diagnostics convert underrepresented reference mass into a concrete PriorityFocus window."
    ],
    "demos": [
      "src/Aquarium.Fensalir is the Fensalir splash/art reconstruction demo. It loads Worlds/fensalir-spine-emblem.aquageo, lowers marsh ripple brushes, projects cathedral detail, renders custom water/mist shaders, and draws a luminous stacked-diamond spine through SDF proxy shading.",
      "The current Fensalir cathedral screen-space guide is scaffolding. Replace it with a .aquageo-lowered transparent pane/rune/material field target separate from the marsh height field.",
      "src/Aquarium.Sample.Minimal is the minimal non-client-policy boundary proof.",
      "src/Aquarium.Zyphos is the planetary-scale demo. Terrain should move toward cube-sphere/QSC-family addressing and reservoir-backed fractal surfaces.",
      "Mimir owns the sensor-fusion app/adapter surface. Fensalir should keep only generic sensor contracts, GPU sensor fusion shader machinery, and temporal evidence lowerings."
    ],
    "research_notes": [
      "Renderer notes live under docs/ and research/rendering/ in this repo after the split.",
      "docs/perfect-machine-architecture.md is the broad field/reservoir architecture authority.",
      "docs/fractal-domain-reservoir.md records the Area ReSTIR/TSR reorientation: Fensalir's reservoir is domain-native and resolution-decoupled, with texel rows only as current D3D12 resolve ABI.",
      "docs/temporal-spatial-evidence-reservoir.md owns the stable-key temporal evidence cache contract.",
      "docs/temporal-sdf-gaussian-field.md is historically named but now represents temporal Form-field evidence, not only SDF surfaces.",
      "research/rendering/fractal-reference-oracles.md owns flame/IFS external reference strategy.",
      "research/rendering/fensalir-spine-emblem-ifs-demo.md preserves the Fensalir splash visual target."
    ]
  },
  "warnings": [
    "Do not add client policy nouns to engine code to fix missing client context.",
    "Do not preserve historical branch scars in live docs unless they change a current decision.",
    "Do not build a new registry, adapter, cache, or helper layer until its invariant and owner are explicit.",
    "A passing receipt is not a pardon for a machine nobody can explain."
  ]
}