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.
  - Native-domain reservoirs are not native-resolution buffers. The reservoir
    work grid is an explicit budgeted sampler below final present resolution;
    scene evidence targets, candidate/history rows, resolve, bloom sources, and
    match-window graph targets follow that grid. The final present buffer is
    the only full-resolution surface, where reconstruction and denoising spend
    visible-output budget.
  - 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.
  - Use docs/perfect-fensalir-machine-roadmap.md as the controlling
    implementation roadmap. The first proof is native-domain reservoir state
    for mixed TubeField/SDF/splat reuse; broader fractal, sensor, flow,
    residency, and learned-priority work waits behind that gate.
  - Cut the rendering rebuild through explicit field-domain/field-claim
    contracts before adding another backend-specific visual path.
  - Before more occlusion-threshold tuning, extend native-domain replay beyond
    the first TubeField proof path. TubeField and SDF proposals now include
    selected domain/sample-coordinate and support data, reuse validates support
    overlap, TubeField history chooses a replay source through a bounded
    producer-keyed manifest before re-evaluating the shifted logical
    column/curve coordinate against the live producer buffer, and SDF history
    carries the previous selected hit through object motion before validating
    current ray/travel/support. A field-reservoir mode switch now captures
    native-domain validation against a texel-owned baseline; the first paired
    set is `reservoir-compare-20260529-231904-*`, where native versus baseline
    changed 10.8208% of final-frame pixels, and
    `scripts/measure-reservoir-mode-comparison.ps1` now repeats those
    single-frame deltas. The reservoir work grid is now clamped below present
    resolution by `GraphicsSettings.FieldReservoirScale` (0.5 default, 0.75
    maximum), so native-domain replay spends bounded fill/compute before the
    full-resolution presentation pass. A sequence probe now captures
    native/baseline timelines from one disposable slot and measures per-frame
    mode disagreement plus frame-to-frame temporal deltas; the first smoke set
    is `reservoir-sequence-20260529-234414-*`. The probe is now resumable and
    rejection-mask-aware; `reservoir-sequence-20260529-235031-*` proves masked
    mode/temporal rows over rejection-debug pixels. Debug mode 19 now exposes a
    temporal-owner disocclusion mask from previous UV loss, previous-closer
    history, and support loss; the sequence measurer prefers it over broad
    rejection masks, and `reservoir-sequence-20260530-000151-*` proves the
    narrower mask path. The sequence harness can also capture a same-time
    native-domain reference at a higher reservoir work-grid scale through
    `-ReferenceFieldReservoirScale`; `reservoir-sequence-20260530-001046-*`
    proves reference-error rows from scale 0.5 against scale 0.75. The offline
    budget-pressure probe `reservoir-budget-pressure-20260530-001046.*` ranks
    masked reference error by tile; its first smoke found the top 5 of 50 tiles
    carried 99.3305% of measured reference-error delta. Runtime now has a fixed
    spatial-reuse sampling budget via `FieldReservoirSpatialReuseBudget`; every
    work-grid pixel writes current/temporal rows, while a deterministic phase
    spends 3x3 neighbor sampling. Smoke `reservoir-sequence-20260530-003006-*`
    proves native scale 0.5 / spatial budget 0.5 against reference scale 0.75 /
    spatial budget 1.0. Debug mode 20, `Reservoir Spatial Budget`, now exposes
    the active spatial reuse phase at the visible layer; smoke
    `reservoir-sequence-20260530-003746-*` proves it. The next cut is turning
    budget-pressure evidence into a renderer-owned per-tile adaptive update
    contract plus future exact producer SDF replay.
  - 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.
  - For planetary flow modeling, treat FlowNet-S (8-15M params) as the local
    contract/inference baseline, FlowNet-M (40-60M params) as the first serious
    runtime/distillation model with local tile encoders plus cube-sphere graph
    transformer blocks, and FlowNet-T (150-300M params) as an offline teacher
    only if global coherence needs it. Do not let an oversized teacher become
    the runtime authority before the packet contract and LOD path are proven.
    External forcing and Coriolis are first-class conditioning inputs to both
    training and runtime evaluation. Do not hardcode Earth sun/moon semantics:
    represent arbitrary directional, point, area, volumetric, transient, and
    periodic energy/mass/momentum sources in planet/global and local tangent
    bases, and pass explicit rotation/Coriolis features so fast rotators, gas
    giants, multiple suns, eruptions, and extreme atmospheres do not become
    hidden side channels.
  - 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,
    optional local source, and optional unordered-access output intent; the
    D3D12 registry allocates/imports them as shader-readable page textures or
    compute-writable UAV-backed pages. Empty SurfacePage version is content
    freshness, not texture identity, so compute outputs can update without
    reallocating when shape/format/access are unchanged. FieldEvidence now has
    an explicit `AquariumFieldStereoDepthLowering` sidecar for future calibrated
    stereo compute dispatch: validation requires a Height claim whose payload is
    the compute-writable disparity SurfacePage, shader-readable left/right
    Texture2D or RollingTexture resources, profile/calibration/camera-pair
    identity, and coherent output shape/range. This keeps Mimir's libSGM-shaped
    D3D12 depth path inside typed field/resource authority instead of a private
    texture or CUDA/TensorRT dependency. The D3D12 renderer now evaluates
    stereo-depth dispatch readiness without writing fake depth: a lowering is
    ready only when its Height claim is planned and left/right input textures
    plus UAV disparity SurfacePage resolve through the field resource registry;
    capacity logs still state that the kernel is not installed. The lowering
    sidecar now carries the first SGM-shaped kernel constants too: min
    disparity, disparity levels, aggregation paths, census radius, and P1/P2
    smoothness penalties. 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 nine-lane `FieldReservoirSample`
    colorTravel/metadata/control/guide/motion/domainSample/domainSupport/proposal/stats
    record. `domainSample` stores selected pixel/sample UV plus packed producer
    coordinate; `domainSupport` stores support footprint, domain kind, and shift
    kind. 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. TubeField row-0
    proposals also write selected subpixel UV, logical source column, curve
    coordinate, tube support footprint, and explicit motion shift kind when
    available; field id still carries physical rolling-column identity. SDF
    scene proposals reconstruct object-local hit coordinates and mark
    object-motion replay. SDF temporal reuse reconstructs the previous selected
    world hit from stored UV/travel, carries it through object center motion,
    and rejects it unless it still lands on the current ray/travel/support
    envelope. 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, guide
    confidence, support overlap, TubeField producer re-evaluation through the
    replay manifest/source table, and SDF object-hit replay before RIS merge;
    rejected history cannot become visible fallback by itself. TubeField replay
    sources beyond the bounded manifest cap are invalid until the source table
    grows or a replay atlas replaces per-source descriptors. Spatial reuse validates neighboring
    current reservoirs by field id, travel, normal, support overlap, 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-18 inspect the
    compute-owned final/reuse layer: rejection state, selectedTarget, weightSum,
    candidateCount, proposal target/sourcePdf, contribution weight, selected
    domain/sample coordinate, support footprint/domain kind, and shift kind. 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.