GameCult/Fensalir
Watch
9
0
Fork
You've already forked Fensalir
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document planetary flow organ

Browse source
This commit is contained in:
Meta Vens 2026-05-29 18:52:07 +01:00
commit 866f89133d
7 changed files with 656 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/README.md
View file

@ -25,6 +25,10 @@ historical branch scar.
- `tsr-inspired-taa-spec.md`: temporal resolve design and guide-buffer intent.
- `stochastic-transparent-surface-pipeline.md`: density/extinction and
transparent field rendering notes.
- `planetary-flow-organ.md`: architecture and ownership map for reusable
cube-sphere stochastic ocean/atmosphere flow fields.
- `planetary-flow-implementation-plan.md`: staged execution plan for dataset
provenance, cube-sphere bakes, model training, and runtime integration.
## Migration And Demo Context

178
docs/planetary-flow-implementation-plan.md Normal file
View file

@ -0,0 +1,178 @@
# Planetary Flow Implementation Plan
This is the execution plan for Fensalir's planetary flow organ. It is ordered to
prove ownership and data shape before expensive model work.
## Invariants
- Fensalir owns the reusable stochastic advection contract and runtime
streaming machinery.
- Source datasets are offline evidence with provenance, not runtime authority.
- The runtime representation is cube-sphere native.
- The model emits stochastic advection parameters, not only deterministic flow
vectors.
- Client repos can consume, visualize, or condition flow; they do not bypass
the engine field evidence path.
- LOD inheritance must preserve physical continuity across parent and child
tiles.
## Phase 0: Scope And Provenance
Deliverables:
- source manifest format for dataset id, URL, license, citation, access date,
variable list, spatial grid, temporal cadence, and derived artifacts;
- initial source rows for ETOPO 2022, GEBCO, ERA5, OSCAR, PlasticAdrift, and
candidate CMEMS/HYCOM products;
- decision on local storage shape for raw downloads and cube-sphere bakes.
Verification:
- a provenance report can be generated without model code;
- no training shard can be created without a source manifest row.
## Phase 1: Cube-Sphere Bake Pipeline
Deliverables:
- offline tool that samples lat/lon or NetCDF/Zarr inputs into `CubeTileKey`
pages;
- baked static channels: elevation, bathymetry, land/sea mask, slope,
curvature, coastline distance, source quality;
- baked dynamic channel fixture from a small ERA5/OSCAR subset;
- metric metadata per tile: area scale, local tangent frame, latitude/Coriolis,
projection id, and missing-data mask.
Verification:
- round-trip sample checks against source grids at known points;
- area-weighted global summary checks;
- cross-face continuity checks;
- debug image or CSV dump for one tile pyramid.
## Phase 2: Contract Skeleton
Deliverables:
- `PlanetaryFlowDomain`, `PlanetaryFlowRequest`, `PlanetaryFlowSample`, and
`PlanetaryFlowClaim` contracts;
- encoding enum or equivalent for `StochasticAdvection`;
- field evidence validation for Transport-layer flow claims;
- test fixtures with synthetic flow pages.
Verification:
- contract round-trip tests;
- validation rejects missing model/source versions and invalid covariance;
- synthetic claims can pass through the field evidence planner without D3D12
flow rendering.
## Phase 3: Synthetic Runtime Slice
Deliverables:
- analytic synthetic flow model over cube-sphere tiles;
- baked/evaluated flow pages at multiple LODs;
- debug visualization for mean velocity, covariance ellipse, confidence, and
inherited versus evaluated LOD.
Verification:
- particles or probe samples advect continuously across tile and face edges;
- parent-to-child values are consistent under aggregation;
- camera-driven selected cuts request the same flow path as direct debug
sampling.
## Phase 4: Baseline Learning Pipeline
Deliverables:
- Python training workspace or external tool boundary with sharded data loader;
- baseline local tile-pyramid model;
- outputs: mean tangent velocity and covariance;
- losses: vector regression, negative log likelihood, smoothness, and
parent-child scale consistency;
- held-out region/time evaluation.
Training plan:
- start with ERA5 10m wind over a small temporal window;
- add OSCAR surface currents as the first ocean target;
- train on cube-sphere pages, not raw lat/lon;
- normalize per variable and preserve masks;
- keep model identity, source versions, and normalization stats with every
checkpoint.
Verification:
- beat a persistence/climatology baseline;
- visualize residuals by latitude, coastline distance, and LOD;
- check conservation-ish behavior through particle rollouts, not only per-cell
vector error.
## Phase 5: PlasticAdrift Auxiliary Target
Deliverables:
- importer for PlasticAdrift probability outputs and/or transition matrix where
license/access are verified;
- cube-sphere mapping from debris probability cells to transport targets;
- auxiliary loss from predicted stochastic parameters to observed transition
distributions over a lead time;
- validation cases for known garbage-patch accumulation behavior.
Verification:
- probability mass remains normalized after cube-sphere remap within declared
omission thresholds;
- rollouts from predicted parameters reproduce broad PlasticAdrift transition
behavior better than deterministic current-only advection.
## Phase 6: Hierarchical Model And Streaming
Deliverables:
- hierarchical graph or neural-operator model over cube-sphere tiles;
- parent/child and same-level neighbor edges;
- streaming evaluation for requested selected cuts;
- cache/page residency keyed by model and conditioning versions;
- uncertainty-driven refinement.
Architecture hypotheses to test:
- local patch encoder plus graph head for first production model;
- hierarchical graph neural operator for long-term arbitrary LOD;
- sparse transition logits only where PlasticAdrift-style debris transport
needs them;
- covariance output via Cholesky factors to guarantee positive semidefinite
diffusion.
Verification:
- stable cross-LOD particle rollouts;
- bounded frame-time budget under camera motion;
- debug report ties visible flow to model version, source versions, and selected
LOD.
## Phase 7: Renderer And Simulation Integration
Deliverables:
- D3D12 flow page resources;
- compute shader helpers for stochastic particle advection;
- debug overlays and capture fixtures;
- API for clients to request flow at world points or publish visual consumers.
Verification:
- headless capture shows nonblank flow diagnostics;
- direct sampling, debug visualization, and particle advection agree on the
sampled layer;
- stale pages cannot silently render after model/source version changes.
## Recommended First Cut
Build the synthetic runtime slice before downloading the ocean. Then train the
small ERA5 wind model. Then add OSCAR. Then PlasticAdrift. The ocean will try to
turn this into a grand expedition immediately; make the contract prove it can
hold a cup of water first.

277
docs/planetary-flow-organ.md Normal file
View file

@ -0,0 +1,277 @@
# Planetary Flow Organ
## Objective
Add a reusable planetary flow organ to Fensalir that predicts stochastic
advection parameter sets over optimized cube-sphere domains. The organ should
serve whole-planet ocean-surface and atmospheric flow to renderers and
simulations at arbitrary LOD: fine near the camera, coarse far away, and always
bounded by explicit uncertainty.
The product is not "one current vector per point." The product is a streamable
transport field:
```text
cube-sphere tile + time/context + static planet geometry + dynamic state
-> stochastic advection parameters
-> renderer/simulation samples, transition kernels, and uncertainty telemetry
```
## Authority Map
Owner: `Aquarium.Engine.Fractal` should own the domain math, tile identity,
LOD/residency contract, training data preparation shape, and inference packet
schema. Runtime inference may later move to a dedicated ML package, but the
engine owns the field contract that clients consume.
Inputs: cube-sphere tile address, projection metadata, static relief/bathymetry,
land/sea mask, latitude/Coriolis features, calendar/season phase, optional
recent atmosphere/ocean state, and dataset provenance/version.
Outputs: bounded stochastic advection parameter tiles for atmosphere and ocean
surface. The first output schema should support mean velocity, covariance or
diffusivity, optional transition-kernel logits over neighboring cells, and
calibration/confidence.
Derived state: visualization arrows, particle paths, current speed heatmaps,
plastic trajectories, and gameplay/weather effects are derived views. They do
not own flow truth.
Forbidden writers: renderer shaders, demo clients, PlasticAdrift import code,
weather dataset loaders, and particle systems must not invent private flow
fields. They may request or display flow packets; they may not become alternate
advection authorities.
Shared paths: direct camera streaming, background planetary simulation, offline
training export, replay from persisted time, and imported dataset validation
all use the same cube-sphere tile key, same normalization metadata, and same
flow packet schema.
Deletion line: do not add a lat-long-only flow path as a convenient prototype
that later needs adapters. Lat-long sources are ingestion formats; cube-sphere
tiles are the engine domain.
## Current Mechanism
Fensalir already has the right substrate:
- `CubeTileKey` names a six-face quadtree tile.
- cube-sphere projections exist for normalized and tangent mappings.
- surface pages, residency planning, and selected cuts already express
streamable planetary surface data.
- the field architecture already distinguishes Form, Appearance, and Transport
evidence. Planetary flow belongs in Transport.
The missing organ is a data and inference path that fills cube-sphere Transport
pages with stochastic advection parameters instead of authored brush evidence.
## Invariants
- Cube-sphere tile identity is the runtime domain. Lat-long is only source data
layout or debug view.
- Static relief alone is not a sufficient predictor. Bathymetry/topography can
shape flow, but dynamic atmosphere/ocean state and time conditioning are real
inputs.
- A stochastic output must expose uncertainty. A mean vector without dispersion
is a visualization convenience, not the organ.
- Conservative LOD summaries remain renderable. Missing high-resolution child
tiles fall back to parent flow summaries.
- Learned priority may choose what to refine first; it may not replace packet
validity, tile bounds, provenance, or calibration checks.
- PlasticAdrift-style transition matrices are validation and auxiliary targets,
not full ocean-dynamics truth.
## Output Parameterization
Start with a compact packet that can represent both velocity-like and
transition-matrix targets:
```text
FlowTilePacket
Domain: CubeTileKey, projection id, cell spacing, time basis
Layer: oceanSurface | atmosphereNearSurface | atmospherePressureLevel
MeanVelocity: tangent-space u/v per sample
Diffusivity: symmetric 2x2 tangent covariance or log-Cholesky parameters
NeighborKernel: optional logits over fixed cube-tile neighbor stencil
DivergenceCurl: optional diagnostic channels
Confidence: calibration, dataset mask, and extrapolation flags
Provenance: source dataset, model version, normalization version
```
The first implementation should train mean velocity and diffusivity. Add
neighbor-kernel logits once ingestion can derive transition targets from
drifter/plastic or rollouts. A full dense transition matrix is useful offline,
but it is too large as the primary render packet.
## Dataset Spine
Static planet geometry:
- GEBCO_2025 Grid: global land/ocean terrain at 15 arc-second resolution, with
source-type identifier grid and attribution request.
- NOAA ETOPO 2022: 15 arc-second global relief, useful as a CC0-licensed
baseline.
Atmosphere targets:
- ERA5 through the Copernicus Climate Data Store: hourly global reanalysis from
1940 onward, 0.25 degree public data, useful for wind and pressure fields.
Ocean targets:
- Copernicus Marine GLORYS12V1 global ocean physics reanalysis: eddy-resolving
1/12 degree, daily/monthly currents, sea level, temperature, salinity, and
related fields from 1993 onward.
- OSCAR surface currents: satellite-derived upper-ocean currents at coarse
global resolution, useful for surface-current validation and lightweight
baselines.
- HYCOM/NCODA global products: high-resolution operational/reanalysis ocean
fields, useful but operationally rougher because availability and exact data
gaps matter.
Plastic/drifter transport:
- PlasticAdrift/Adrift style transition matrices provide probability
distributions over future surface positions from observed drifter-derived
transport. Use them to supervise or validate stochastic surface transport,
especially transition kernels and long-horizon debris behavior.
See `../research/planetary-flow-organ-literature.md` for source-backed notes.
## Model Hypotheses
### Baseline
Use deterministic interpolation and simple stochastic residuals first:
```text
source reanalysis field
-> reproject to cube-sphere tile pyramid
-> train predictor for mean velocity
-> fit residual covariance/diffusivity per biome/season/tile scale
```
This proves ingestion, normalization, tiling, loss functions, and packet
streaming before the neural architecture gets to wear a crown.
### Strong Candidate
Use a graph/operator hybrid:
- graph mesh over cube-sphere tiles for domain adjacency, seams, and variable
LOD;
- local multiscale tile encoder for relief/bathymetry and recent dynamic
fields;
- message passing across neighboring and parent/child tiles;
- operator-style global context for long-range circulation;
- probabilistic head emitting mean velocity, log-Cholesky diffusivity, and
optional neighbor-kernel logits.
This follows the useful parts of GraphCast and MeshGraphNets while preserving
Fensalir's cube-sphere domain instead of importing an icosahedral mesh as a
second planetary truth.
### Alternative
Train an SFNO/FourCastNet-like global model for atmosphere/ocean state
forecasting, then distill or sample it into cube-sphere flow packets. This is
attractive for global coherence but less naturally aligned with arbitrary
camera-driven LOD.
### Probabilistic Extension
Use diffusion, flow matching, or latent-variable ensembles only after the
packet schema and deterministic/stochastic residual baseline are measurable.
GenCast proves diffusion-style ensemble weather can work; it also proves that
sampling cost is real. Fensalir should not pay that cost per visible tile unless
the result beats calibrated covariance and ensemble heads.
## Training Plan
1. Ingest static relief into a cube-sphere pyramid.
Preserve source resolution, vertical datum notes, land/sea mask, slope,
curvature, roughness, and coastline distance.
2. Ingest ERA5 and GLORYS/OSCAR/HYCOM targets.
Normalize to common time slices, tangent basis, units, masks, and
cube-sphere tile pyramid levels. Store source provenance per tile/time.
3. Build the baseline target set.
Atmosphere: near-surface winds first, then pressure-level winds. Ocean:
surface `uo/vo` or equivalent currents first. Plastic: transition
distributions as auxiliary/validation targets.
4. Train a single-tile local model.
Inputs are multi-channel multiscale crops around a target cell: relief,
slope, land/sea, Coriolis/latitude, season phase, and recent dynamic fields.
Output mean velocity plus diagonal covariance.
5. Add cross-tile and parent/child context.
Replace pure crops with cube-sphere graph adjacency and LOD-aware message
passing. Verify seams explicitly.
6. Add stochastic transport heads.
Upgrade covariance to full tangent 2x2 log-Cholesky. Add neighbor-kernel
logits over a small stencil where transition data supports it.
7. Validate at the layer users see.
Check one-step vector RMSE, calibrated uncertainty, multi-step trajectory
spread, PlasticAdrift-style transition behavior, visible tile LOD stability,
seam continuity, and parent/child summary consistency.
8. Distill for runtime.
Export a tile-streaming inference package or precomputed coefficient pages
with model/version metadata. Runtime packets must be small enough for camera
streaming and cache eviction.
## Implementation Roadmap
### Phase A: Schema And Data Map
- Add `FlowTilePacket` and source provenance notes in docs before code.
- Define tangent-space basis conventions for each cube face.
- Decide the first tile pyramid levels used for training and runtime.
- Create ingestion manifests for GEBCO/ETOPO, ERA5, GLORYS, OSCAR, HYCOM, and
PlasticAdrift.
### Phase B: Offline Reprojection
- Build offline reprojection from lat-long/source grids to cube-sphere tiles.
- Emit min/mean/max/std summaries for parent LODs.
- Validate seam continuity and area weighting.
### Phase C: Baseline Flow Pages
- Store mean velocity and simple covariance pages as engine-readable Transport
pages.
- Add debug visualization: vectors, speed, uncertainty ellipse, mask, source
version, parent/child mismatch.
### Phase D: Training Harness
- Train local multiscale baseline on reanalysis targets.
- Add held-out years/regions and no-cheating temporal splits.
- Compare against source interpolation and seasonal climatology.
### Phase E: Graph/LOD Model
- Add cube-sphere adjacency graph and parent/child message passing.
- Train seam-aware, LOD-aware stochastic packets.
- Verify arbitrary camera streaming by requesting mixed-resolution cuts and
comparing against full-resolution source fields.
### Phase F: Runtime Inference Or Distillation
- Choose between precomputed flow pages, local tile inference, or hybrid
coarse-global plus local-refinement inference.
- Lower results into shared field resource pages and debug telemetry.
## Cut Lines
- No demo-owned flow field.
- No lat-long runtime authority.
- No bathymetry-only predictor except as an explicit baseline.
- No stochastic claims without calibration plots.
- No neural architecture before the baseline proves ingestion and packet
semantics.
- No per-pixel weather model in the renderer. The renderer samples packets.

3
research/README.md
View file

@ -14,6 +14,9 @@ Fensalir keeps engine-relevant research here.
strategy and receipt ladder.
- `rendering/fensalir-spine-emblem-ifs-demo.md`: Fensalir splash visual target.
- `rendering/fractal-projection-report.md`: cube projection measurement notes.
- `planetary-flow-organ-literature.md`: source-backed sidecar distillation for
stochastic transport, bathymetry/topography, reanalysis targets, model
literature, and architecture hypotheses for cube-sphere flow.
- `d3d12/`: source synthesis and migration research for the renderer spine.
Client-only visual grammar belongs in the client repos. Engine research stays

164
research/planetary-flow-organ-literature.md Normal file
View file

@ -0,0 +1,164 @@
# Planetary Flow Organ Research Notes
This note distills the research sidecar for a Fensalir organ that predicts
stochastic advection parameter sets over cube-sphere planetary domains.
## 1. Stochastic Lagrangian And Plastic Transport
PlasticAdrift/Adrift is best treated as a stochastic transition target, not as a
velocity field. The Adrift paper describes a statistical transition-matrix
representation built from trajectories of more than 15,000 surface drifters,
and the PlasticAdrift site refers to its own transition matrix and ten-year
probability animations.
Implementation implication: use PlasticAdrift as auxiliary supervision or
validation for surface transport kernels:
```text
cell now -> probability over future cells
```
This can train or check neighbor-kernel logits, effective diffusivity, seasonal
connectivity, and multi-step debris spread. It should not be the only ocean
truth because it represents observed surface drift statistics, not full ocean
state.
Sources:
- PlasticAdrift: https://plasticadrift.org/
- Adrift.org.au paper abstract: https://www.sciencedirect.com/science/article/abs/pii/S0022098114002445
- McAdam and van Sebille transition matrices: https://dbc.library.uu.nl/handle/1874/362629
## 2. Bathymetry And Topography
GEBCO_2025 is the best current high-resolution global relief/bathymetry source
for broad use. It provides global land/ocean elevation on a 15 arc-second grid,
with 43,200 x 86,400 samples, NetCDF distribution, WGS84 assumption, and a
source-type identifier grid. GEBCO asks for attribution in publications.
NOAA ETOPO 2022 is a strong baseline because it is a 15 arc-second global
relief model and the ESSD dataset paper states that ETOPO data are covered by
CC0-1.0 in NOAA metadata. It is especially useful where a permissive licensing
posture matters more than the newest GEBCO revision.
Implementation implication: ingest both. Use ETOPO as the permissive default
and GEBCO as the higher-confidence bathymetry option with explicit attribution
and source-type channels.
Sources:
- GEBCO_2025 Grid: https://www.gebco.net/data-products-gridded-bathymetry-data/gebco2025-grid
- GEBCO gridded data: https://www.gebco.net/data_and_products/gridded_bathymetry_data/
- NOAA ETOPO: https://www.ncei.noaa.gov/products/etopo-global-relief-model
- ETOPO 2022 ESSD paper/license note: https://essd.copernicus.org/articles/17/1835/2025/
## 3. Atmosphere And Ocean Targets
ERA5 is the default atmospheric target. Copernicus describes ERA5 as global
hourly reanalysis from 1940 onward, updated about five days behind real time,
with 0.25 degree grids and 37 pressure levels. Copernicus Climate Data Store
access is open, free, and unrestricted, though users accept dataset licenses.
GLORYS12V1 through Copernicus Marine is the best first ocean reanalysis target:
global eddy-resolving 1/12 degree, 50 vertical levels, altimetry-era coverage
from 1993 onward, daily/monthly means, currents, sea level, temperature,
salinity, mixed-layer depth, and ice variables. Copernicus Marine describes its
service as free and open access; registration and acknowledgement still matter.
OSCAR is a useful surface-current baseline and validation product. It estimates
upper-ocean currents from satellite sea-surface height, winds, and SST gradients
using simplified geostrophic/Ekman/thermal-wind dynamics. Data.gov lists the
OSCAR final 0.25 degree product under a U.S. government works license URL.
HYCOM/NCODA provides high-resolution global ocean prediction/reanalysis access
through HYCOM servers. HYCOM states the data are UNCLASSIFIED, Distribution A,
approved for public release, with a demonstration-product disclaimer and
availability caveats. Treat HYCOM as valuable but operationally messier than
GLORYS for the first reproducible training set.
Implementation implication: train v1 on ERA5 plus GLORYS, validate against
OSCAR and PlasticAdrift, then consider HYCOM for higher-resolution or near-real
time ocean variants.
Sources:
- ERA5 climate reanalysis: https://climate.copernicus.eu/climate-reanalysis
- Copernicus Climate Data Store: https://climate.copernicus.eu/climate-data-store
- GLORYS global ocean physics reanalysis: https://data.marine.copernicus.eu/product-detail/GLOBAL_MULTIYEAR_PHY_001_030
- Copernicus Marine about/free access: https://marine.copernicus.eu/about/
- OSCAR data.gov entry: https://catalog.data.gov/dataset/ocean-surface-current-analyses-real-time-oscar-surface-currents-final-0-25-degree-version-
- ESR OSCAR overview: https://www.esr.org/data-products/oscar/oscar-surface-currents/
- HYCOM data server/disclaimer: https://www.hycom.org/
- HYCOM reanalysis acknowledgement: https://www.hycom.org/publications/acknowledgements/ocean-reanalysis-data
## 4. Neural And Operator Architectures
GraphCast proves the graph-on-sphere family for global weather. It operates on a
0.25 degree lat-long grid but uses graph neural networks and a high-resolution
multi-scale mesh representation to predict 227 atmospheric variables at 6-hour
steps. The important lesson for Fensalir is not the lat-long input. It is the
encoder/processor/decoder shape and learned multi-scale spherical mesh.
FourCastNet and SFNO prove the operator-learning family. FNOs are attractive
because operator learning can be resolution-aware, and SFNO specifically avoids
flat Fourier artifacts on spherical geometry while producing stable atmospheric
rollouts. This is relevant for global coherence and low-rank long-distance
structure.
MeshGraphNets proves learned simulation over arbitrary meshes. This maps well
to cube-sphere tiles, seam adjacency, and parent/child LOD graphs.
GenCast proves probabilistic weather through conditional diffusion and a
graph-transformer-style spherical denoiser. It produces ensemble forecasts, but
sampling is more expensive than deterministic MLWP. For Fensalir, this is a
later uncertainty-upgrade path, not the first runtime packet machine.
Implementation implication: start with a cube-sphere graph encoder plus local
multiscale tile encoder. Add SFNO/global-context distillation if local graph
context cannot capture long-range circulation. Keep diffusion/flow matching for
offline ensemble generation or teacher models until runtime cost is justified.
Sources:
- GraphCast: https://deepmind.google/research/publications/22598/
- SFNO: https://research.nvidia.com/publication/2023-06_spherical-fourier-neural-operators-learning-stable-dynamics-sphere
- FourCastNet: https://authors.library.caltech.edu/records/k959a-53q45
- NVIDIA FourCastNet V2/SFNO variables: https://docs.api.nvidia.com/nim/reference/nvidia-fourcastnet
- MeshGraphNets: https://arxiv.org/abs/2010.03409
- GenCast: https://www.nature.com/articles/s41586-024-08252-9
- NeuralGCM hybrid model context: https://www.nature.com/articles/s41586-024-07744-y
## 5. Stochastic Advection Outputs
Candidate outputs:
- mean tangent velocity: cheapest and easiest to compare with ERA5/GLORYS;
- diagonal or full diffusivity tensor: compact stochastic spread;
- transition kernel over a fixed neighbor stencil: closest to PlasticAdrift and
best for particle/debris advection on discrete tiles;
- calibrated uncertainty/ensemble moments: needed for visible confidence and
simulation honesty;
- seasonal/time conditioning: required because static geometry alone cannot
determine circulation;
- source/provenance flags: needed where source data is sparse, masked, stale, or
extrapolated.
Recommendation: first train mean velocity plus full 2x2 tangent covariance,
then add neighbor-kernel logits where transition data is available. A dense
global transition matrix is an offline research artifact, not a runtime packet.
## Short Recommendations
1. Use cube-sphere tiles as runtime authority from day one.
2. Use ETOPO as the permissive relief baseline; add GEBCO with attribution and
TID/source-type channels.
3. Train atmosphere on ERA5 and ocean surface on GLORYS first.
4. Use OSCAR and PlasticAdrift as validation/auxiliary transport targets.
5. Treat HYCOM as a later high-resolution or near-real-time source because its
access/disclaimer/data-gap profile is rougher.
6. Start with mean velocity plus calibrated covariance, then add transition
kernels.
7. Use a cube-sphere graph/operator hybrid; do not force the engine to adopt a
second spherical mesh as flow truth.
8. Keep diffusion/flow matching as an ensemble teacher or offline uncertainty
model until the runtime cost earns its keep.

18
state/evidence-planetary-flow-organ.md Normal file
View file

@ -0,0 +1,18 @@
# Planetary Flow Organ Evidence
Date: 2026-05-29
Fensalir is the right owner for reusable planetary flow only after the problem
is reduced to engine mechanisms: cube-sphere addressing, dataset provenance,
stochastic advection contracts, selected-cut streaming, GPU resources, and
debug evidence. Client repos own planet meaning and consumers.
Useful correction: PlasticAdrift is not a velocity-vector field. It is
transition-matrix style surface transport evidence. The runtime organ should
distill such evidence into mean velocity, covariance/diffusivity, optional
sparse transition logits, and calibrated uncertainty.
Do not train elevation-only flow and call it ocean/atmosphere. Relief is a
static conditioning channel. Dynamic state from ERA5, OSCAR/CMEMS/HYCOM, time
phase, Coriolis/latitude, sea-surface variables, masks, and source quality must
participate before the prediction has authority.

12
state/map.yaml
View file

@ -97,12 +97,24 @@ invariants:
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.
- 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