Fensalir/state/map.yaml

project:
  name: Fensalir
  root: E:\Projects\Fensalir
  upstream: https://github.com/GameCult/Fensalir.git
  purpose: >
    Native C# runtime and renderer dependency for Aquarium-style clients. The
    engine owns Win32 hosting, D3D12 rendering, input, hot reload, debug UI,
    audio output, client contracts, fractal/field machinery, and engine demos.

current_model:
  solution: Fensalir.sln
  host:
    implementation: src/Aquarium.Engine
    contracts: src/Aquarium.Engine.Contracts
    renderer: src/Aquarium.Engine/Render
    shaders: src/Aquarium.Engine/Render/Shaders
    assets: src/Aquarium.Engine/Assets
    built_in_field_resources: src/Aquarium.Engine.Contracts/Render/AquariumBuiltInFieldResources.cs
    scripts: scripts
  fractal:
    implementation: src/Aquarium.Engine.Fractal
    tests: tests/Aquarium.Engine.Fractal.Tests
    receipt_tool: tools/Aquarium.Fractal.Receipt
  demos:
    fensalir_splash: src/Aquarium.Fensalir
    minimal: src/Aquarium.Sample.Minimal
    zyphos: src/Aquarium.Zyphos
  external_clients:
    epiphany_aquarium: E:\Projects\Aquarium-Engine
    mimir: owns the sensor-fusion app/adapter surface formerly prototyped here
  dependencies:
    cult_math: E:\Projects\CultMath
    cult_lib: E:\Projects\CultLib
    aqua_synth_faust: repo-local NuGet package feed under packages

invariants:
  - Fensalir owns reusable host, renderer, audio, reload, contracts, and engine mechanisms.
  - Fensalir is not a traditional rendering pipeline. It is a field/evidence
    machine: contributors emit bounded Form, Appearance, and Transport claims
    with identity, travel/depth, metadata, control, and reservoir-guide lanes.
    Treating a pass as "just drawing pixels" violates the engine invariant
    unless it is explicitly marked as a fallback/debug draw with no authority.
  - Client repos own policy, role names, narrative semantics, app state, and client shaders.
  - Fensalir may own reusable built-in field resources, such as the blackbody
    ramp, when the resource is generic engine utility. Clients should reference
    those through contracts instead of hardcoded project-local asset paths.
  - Epiphany Aquarium depends on Fensalir; Fensalir must not depend on Epiphany.
  - Demo projects inside this repo are allowed to exercise engine features but must not become hidden engine policy.
  - Public `Aquarium.*` assembly names remain for continuity until a deliberate namespace/package migration.
  - Spline/tube visibility is owned by shader SDF evaluation. CPU geometry may
    place conservative sampling envelopes and endpoint/neighbor packets, but
    quad-local strip UVs must not decide visible line coverage.
  - Reservoir splat rendering must not impose large minimum billboard radii on
    transparent buffer-field/tube samples. Sample envelopes should stay tied to
    authored field radius so clients can reduce reservoir sample count without
    turning sparse probes into visible plates.
  - Reservoir contents are not forced to be pixel-sized. Pixel-level resolve
    samples bounded claims; it does not define their native support. Broad,
    smooth surfaces may be represented by few large surface claims. Heightfield
    terrain should be a quadtree of brush-painted surface tiles, subdivided by
    projected footprint, curvature, brush/material detail, silhouettes, and
    temporal uncertainty before SDF probes emit detail-adaptive surface splats.
  - The shared reservoir is a fractal domain reservoir, not a texel cache.
    Pixel rows are the current D3D12 execution projection of selected domain
    evidence. Area-domain contributors must carry selected subpixel or local
    domain coordinates, support/filter footprint, proposal policy, and legal
    shift/reconnection metadata before temporal or spatial reuse can claim
    authority. Sampling budget may scale with target frame time and resolution,
    but identity, support, contribution mass, and visibility authority remain
    domain-native.
  - Rendering backends are lowerings, not truth owners. Heightfields, splines,
    direct SDF proxies, meshes, volumes, fractal probes, and Mimir sensor
    observations must publish bounded Form/Appearance/Transport field claims
    before they can participate in reusable field evidence.
  - Final composition reads the resolved HDR field texture produced by the
    shared reservoir history update pass. TubeField render lowerings inject
    visibility proposals into the shared field reservoir; they must not regain
    private final-visibility authority through blend order, proxy depth, a
    presentation-shader history writer, a TubeField-local K-buffer, or a
    priority-sorted visibility list.
  - Field packet payload handles are not authority. Resource-backed claims and
    packets must reference declared AquariumFieldResourceDeclaration rows with
    kind, GPU residency, shader access, format, shape, validity, version, and
    native handle metadata. Missing, CPU-only, or backend-incompatible resources
    defer lowering instead of becoming visible evidence.
  - Rendering-relevant field buffers move to GPU residency as early as possible
    and stay there. Fensalir must pass GPU resource handles/SRVs/UAVs between
    compute and render lowerings; CPU readback or CPU tessellation is a
    diagnostic-only escape hatch, not the live TubeField path.
  - Audio control frames are contracts, not sample movement. Client runtimes
    may publish DSP targets through `AquariumAudioDocument`, and the engine
    audio host may retain the latest frame, but Faust/native streaming DSP must
    own the hot fractional-delay/resampling path before any aligned-audio claim
    is true.
  - Streaming Faust DSP is now an engine audio mechanism. Clients declare a
    profile-keyed `AquariumStreamingDspProgram`; Fensalir compiles it through
    AquaSynth.Faust, keeps a persistent DSP instance, applies matching audio
    control frames, and processes profile-keyed `AquariumStreamingAudioBlock`
    input lanes into named `AquariumAudioStemFrame` output lanes. The engine
    owns an `IAquariumAudioStemBus` service for published processed stems,
    optional monitor playback is explicit, and OBS-facing publication remains
    a later host cut.
  - The named D3D12 program-output texture is an external publication surface.
    After copying the completed backbuffer into it, the renderer must leave the
    resource in `Common` so OBS/EVE/native consumers can transition it for
    GPU-side reads without inheriting Fensalir's internal copy-destination
    state.
  - Planetary ocean/atmosphere flow is an engine field organ when reduced to
    reusable stochastic advection machinery. Fensalir owns cube-sphere flow
    addressing, dataset provenance, model contracts, stochastic advection
    parameter schema, selected-cut streaming, and renderer/simulation lowerings.
    Client repos may choose planet meaning and consume flow, but must not own a
    private planetary flow truth path. Lat/lon datasets are offline evidence;
    runtime flow authority is cube-sphere native.

next_actions:
  - Keep origin pointed at https://github.com/GameCult/Fensalir.git.
  - Keep `dotnet build Fensalir.sln` green after the split.
  - Cut the rendering rebuild through explicit field-domain/field-claim
    contracts before adding another backend-specific visual path.
  - Before more occlusion-threshold tuning, update the live GPU reservoir ABI or
    packing plan so TubeField and SDF proposals include selected
    domain/sample-coordinate and support data. Then debug temporal/spatial reuse
    in terms of support overlap and legal shifts, not nearest previous texels.
  - Build the planetary flow organ in staged cuts: provenance manifest, static
    relief and reanalysis cube-sphere bake pipeline, stochastic advection
    contracts, synthetic runtime slice, ERA5/OSCAR baseline learning, then
    PlasticAdrift transition validation and hierarchical arbitrary-LOD
    streaming.
  - Extend the D3D12 field packet/resource resolver beyond its first
    structured/curve-buffer cut. Current contracts, DSL, and renderer registry
    can validate and plan resource-backed TubeField packets, import shared GPU
    structured buffers by handle, and allocate Fensalir-owned GPU-resident
    slots only when Fensalir is the producer. The TubeField DSL can now express
    a 2D rolling float buffer as Catmull-Rom XY tubes with modulo column
    addressing, amplitude power/normalization, radius, ramp texture path, and
    emission scale. D3D12 now has a TubeField compute/render lowering:
    compute binds the rolling sample buffer as read-only GPU memory, emits
    fixed-budget vertex/index buffers with endpoint-clamped Catmull-Rom tube
    envelopes, honors declared sample stride with byte-address loads, and
    records one draw batch per lowering so the TubeField pixel shader can bind
    the right source row/column and resample material per pixel with the cheap
    5-tap approximation. Texture2D resources are now declared as first-class
    field resources. Local assets carry source URI metadata, DSL aliases, lazy
    D3D12 upload, SRV binding, and TubeField ramp lookup by resource key;
    shared GPU Texture2D declarations with native D3D12 handles resolve through
    the same field resource registry, using Mimir video format names such as
    Bgra8, Gray8, Rg8, Nv12, and LeapStereoIr as DXGI format input. The direct
    Mimir MF shape is now proven at resolver level: a D3D11 NT shared
    keyed-mutex BGRA texture can be opened by Fensalir's D3D12 registry as a
    shader-readable Texture2D. Shared Texture2D version is content freshness,
    not import identity; the registry reuses an opened shared texture when
    handle, handle kind, dimensions, and format are unchanged. Imported field
    resources may now carry an external producer fence handle/value; the D3D12
    renderer opens and waits that fence before resource resolution and shader
    sampling, giving Mimir's D3D11 MF producer a direct synchronized path.
    Fensalir
    also exposes the first engine-owned texture lease broker through
    `AquariumRuntimeServices`: client runtimes can request keyed D3D12
    Texture2D leases, receive shared texture and producer-fence handles, then
    commit producer fence values so the renderer waits before shader sampling.
    Raw CPU-origin single-plane frames can use the explicit broker upload lane,
    which copies rows into the leased texture on the D3D12 queue and leaves copy
    accounting to the client producer. Multi-plane NV12 CPU upload is rejected
    until a real planar copy path exists; GPU producers can still write NV12
    leases directly. This makes imported handles an edge case, not the primary
    live camera authority. Missing or unresolved TubeField ramps bind a Fensalir-owned linear fallback ramp.
    Camera texture claims can therefore resolve resources, but their first
    visual use stays debug-view-only for now; production visual-fusion and
    feature-extraction lowerings are deferred until the renderer and audio work
    are fixed. TubeField compute now
    emits one GPU-resident D3D12 DrawIndexed indirect argument packet per
    material/resource batch, and render binds the batch source/ramp state then
    executes the packet with ExecuteIndirect. The first material is opaque field
    geometry with squared normalized emission, fake Fresnel center-bright/
    edge-dark shaping, and requested/dispatched/truncated/indirect-draw segment
    reporting. The debug field-evidence summary exposes TubeField requested,
    dispatched, truncated, upload, skipped-upload, and unplanned-lowering
    counts so client-side subdivision budgets can be tuned from the live
    renderer result instead of guessed. SurfacePage resources now have a first
    resolver: contracts and DSL can declare GPU-resident 2D pages with width,
    height, format, version,
    and optional local source, and the D3D12 registry allocates/imports them as
    shader-readable page textures. VolumeTexture resources now have the same
    first resolver shape: contracts and DSL can declare GPU-resident 3D
    textures with dimensions, depth, format, and version, and the D3D12 registry
    allocates them as shader-readable volume textures. Mesh resources are now
    first-class packages with `Mesh.Vertices` and `Mesh.Indices` buffer members,
    topology, index format, bounds, submesh count, and version. The DSL can
    declare a GPU-resident mesh package, and the D3D12 registry allocates and
    reuses matching vertex/index GPU buffers under the mesh resource key. The
    evidence DSL also has a generic resource-backed `claim` command, so Mesh,
    Height/SurfacePage, and Density/VolumeTexture resources can be planned into
    backend packets without pretending a render path exists. Remaining cuts are
    render lowerings that consume those packets. Mesh layout authority is now
    split intentionally: imported/user-facing meshes use the standard
    `PositionNormalUvColor` layout, while generated meshes may declare
    `PipelinePrivate` so the selected lowering owns the minimal bytes it emits
    and consumes. Mesh rendering is now blocked on choosing the first selected
    render lowering/material path, not on a generic imported-mesh ABI. The
    first generated-mesh render cut is TubeField itself: compute emits
    pipeline-private vertex/index/indirect buffers, render binds them through a
    named `D3D12PipelinePrivateGeneratedMesh`, and TubeField material state
    supplies the shader-specific source/ramp/constants. The DrawIndexed indirect
    command signature is now owned by the generated-mesh lane rather than
    TubeField, so future generated page/volume/surface lowerings can share that
    draw ABI while owning their own producer buffers and materials. TubeField
    dispatch now obeys selected packet authority: only lowerings whose claim has
    a planned TubeField backend packet are expanded, and unplanned lowerings are
    counted instead of rendered. Validation also rejects TubeSpline lowering
    metadata whose claim is not Tube-encoded or whose resource does not match
    the claim payload, so split authority is caught before render dispatch.
    Field evidence now carries explicit Float32 resource uploads separate from
    resource declarations. D3D12 uploads those frame samples into resolved
    structured buffers before TubeField compute reads them, so a Fensalir-owned
    GPU resource can be live data rather than paperwork. Resource uploads carry
    an explicit element offset, validation rejects out-of-range writes, and
    D3D12 copies partial uploads into the declared buffer offset. Fensalir now
    tracks uploaded structured-buffer columns beside the resolved resource and
    clamps TubeField dispatch to the contiguous valid logical history range, so
    stale or never-uploaded rolling slots cannot reach the TubeField shader as
    geometry after allocation, reset, or partial update. Structured buffer
    declaration version is content freshness, not buffer-shape authority:
    D3D12FieldResourceRegistry now reuses an existing structured buffer when
    element count, stride, and access are unchanged, updating the recorded
    version without reallocating GPU memory every frame. TubeField metadata now
    carries a stable field id derived from the planned claim key instead of one
    flat family constant, so temporal/reprojection/reservoir consumers can
    distinguish source-lane claims while preserving the TubeField family range.
    D3D12 now has the first real shared field-reservoir spine. The HLSL
    reservoir ABI is a seven-lane `FieldReservoirSample`
    colorTravel/metadata/control/guide/motion/proposal/stats record. Proposal
    stores target, sourcePdf, representedCandidateCount, and proposalKind;
    stats stores selectedTarget, weightSum, candidateCount, and contribution
    weight. The four rows per pixel are no longer a private top-four visible
    list: row 0 is current-frame initial RIS, row 1 is temporal reuse, row 2 is
    spatial/domain reuse, and row 3 is the final resolved reservoir consumed by
    bloom/presentation. Direct scene/SDF contributors are normalized into the
    same deterministic structural one-sample proposal shape as TubeField before
    RIS merge inside `D3D12ReservoirHistoryUpdateCS`, so the SDF/scene path and
    TubeField path share target/sourcePdf and history semantics. The fullscreen
    field resolve pass is explicitly demoted to raw scene/SDF MRT carry-forward;
    it does not call current-frame reservoir merge and cannot import TubeField
    proposals before the compute pass. TubeField candidate discovery is still the
    fixed-function raster path: compute emits conservative GPU-resident segment
    proxy geometry and indirect draw packets, the proxy raster only schedules
    covered pixels, and the proxy pixel shader analytically intersects the
    camera ray with the generated tube frustum/cap neighborhood in world space.
    TubeField now writes a one-sample reservoir proposal into row 0 with target
    derived from projected coverage, guide confidence, and luminance relevance;
    sourcePdf is 1.0 for deterministic structural proposals. The old
    nearest-travel-minus-coverage priority authority is cut from both TubeField
    injection and final resolve. Shared temporal reuse validates only the
    previous frame's row-3 final reservoir by field id, travel, normal, domain
    validity, motion/previous UV, and guide confidence before RIS merge; rejected
    history cannot become visible fallback by itself. Spatial reuse validates
    neighboring current reservoirs by field id, travel, normal, support, and
    domain before merge. Current-frame structural proposal assembly has a
    visibility gate before RIS: if two valid proposals at the same pixel differ
    materially in travel, the farther proposal is treated as occluded and cannot
    compete by target/luminance. Near-equal-depth proposals still merge through
    RIS. TubeField also separates conservative proxy discovery from reservoir
    support; row-0 target/control/guide use narrow tube-core support rather than
    the broad proxy envelope. Reservoir debug modes 13-15 inspect the compute-owned
    final/reuse layer: rejection state, selectedTarget, weightSum,
    candidateCount, proposal target/sourcePdf, and contribution weight. The
    deleted TubeField-local compute
    ReSTIR/tile-bin path is not a live authority, fallback, or hidden mode. Any
    future temporal/spatial reuse for tubes must extend the shared reservoir
    organ rather than resurrecting a payload-local reservoir renderer.
  - Move any remaining client-only Epiphany state found here back to `E:\Projects\Aquarium-Engine`.
  - Keep Mimir app/adapters out of this repo; Fensalir may expose generic sensor-fusion contracts only.
  - Package contracts/host deliberately before replacing sibling source references in client repos.