Gaia Domain — Technical Specifications

1. Status and Scope#

Gaia is a planned domain. No code exists yet: there are no apps/gaia/*, libs/gaia/*, or services/gaia/* packages in the monorepo, and no @gaia/* path mappings in tsconfig.base.json. This document is therefore a planned / design-level specification — it describes the domain as designed in TODOS/phase-175.md, DOMAINS/gaia/features.md, and DOMAINS/gaia/architecture.md, not implemented code. Every schema, enum, endpoint, event, and state below is grounded in those three documents. Items not yet defined in any of them are not invented here.

Gaia is the sovereign weather and climate ML platform: an end-to-end data, training, and serving pipeline that turns global weather and climate observations into operational forecast products and weather-impact APIs for the rest of Oshun. It replicates and extends the frontier AI-for-Earth-sciences stack — GraphCast, GenCast, FGN, and WeatherNext (Google DeepMind), Pangu-Weather (Huawei), FourCastNet and StormCast (NVIDIA), and Aurora (Microsoft) — across medium-range deterministic forecasting, probabilistic ensemble forecasting, direct tropical-cyclone prediction, minute-scale precipitation nowcasting, decadal climate emulation, and statistical downscaling.

Gaia in DOMAINS/ means Earth-system forecasting and climate ML. It is distinct from Nyx's gaia star-catalog references (the ESA Gaia astrometry mission); those live under libs/nyx/catalogs/gaia and are unrelated.

2. Package Prefix and Library Inventory#

All Gaia libraries share the @gaia/* package prefix and will live under libs/gaia/* in the monorepo. Phase 175 is the canonical task-level checklist.

• Library package prefix: @gaia/*
• Planned library paths: libs/gaia/*
• Canonical task-level checklist: TODOS/phase-175.md (Phase 175)

Phase 175 specifies eight planned libraries, covering the complete pipeline from raw data ingestion through forecast serving.

3. Technology Stack#

Gaia is a polyglot domain. The Phase 175 header fixes the language split based on each sub-domain's performance and ecosystem requirements: Python for the model-training workloads where JAX and PyTorch tooling is richest, Rust for the high-throughput data conversion workers, and TypeScript for orchestration and API services that integrate with the rest of the Oshun monorepo.

Distributed training targets named in Phase 175: TPU-v5e and H100-class pods, with JAX pjit or PyTorch FSDP2, BF16 mixed precision, and activation checkpointing. Operational ensemble generation targets a single H100 or B200 accelerator.

4. Core Data Contracts#

The TypeScript contracts below are the canonical domain objects used by the TypeScript orchestration and serving layers. @gaia/weather-data owns WeatherGrid and WeatherSample; @gaia/forecast-serving owns ForecastRequest and ForecastProduct. These interfaces are the primary cross-package API surface — every other @gaia/* library either produces or consumes values conforming to these types.

type GaiaGridType = 'lat_lon' | 'icosahedral_mesh' | 'regional_projected';

interface WeatherGrid {
  id: string;
  type: GaiaGridType;
  resolution: string;
  bounds?: {
    north: number;
    south: number;
    east: number;
    west: number;
  };
  meshLevel?: number;
}

interface WeatherSample {
  id: string;
  validTime: string;
  leadTimeHours: number;
  grid: WeatherGrid;
  pressureLevels: number[];
  surfaceVariables: string[];
  upperAirVariables: string[];
  source:
    | 'era5'
    | 'era5_land'
    | 'hres'
    | 'gfs'
    | 'merra2'
    | 'radar'
    | 'satellite'
    | 'station'
    | 'lightning'
    | 'ibtracs';
  zarrPath: string;
  provenanceHash: string;
  normalizationVersion?: string;
}

interface ForecastRequest {
  cycleTime: string;
  horizonHours: number;
  region?: WeatherGrid['bounds'];
  product:
    | 'deterministic'
    | 'ensemble'
    | 'cyclone'
    | 'nowcast'
    | 'climate_scenario'
    | 'downscaled';
  variables: string[];
  outputFormat: 'json' | 'zarr' | 'grib2' | 'stac' | 'ogc_edr';
}

interface ForecastProduct {
  id: string;
  modelId: string;
  modelVersion: string;
  cycleTime: string;
  horizonHours: number;
  grid: WeatherGrid;
  variables: string[];
  productUris: string[];
  skillSummary?: SkillSummary;
  publicationStatus: 'draft' | 'published' | 'rolled_back';
}

4.1 GaiaGridType (literal union)#

Three grid representations are used throughout the domain. The type controls how coordinates and chunk layouts are interpreted at every layer from storage to serving.

4.2 WeatherGrid interface#

WeatherGrid describes the spatial grid a WeatherSample or ForecastProduct is defined on. Every sample and every product carries a WeatherGrid so consumers always know the coordinate system and resolution of the data they are reading.

4.3 WeatherSample interface#

WeatherSample is the canonical sample unit of the domain. @gaia/weather-data produces WeatherSample records from every ingested source, and training and serving jobs read them. The schema is designed around full traceability: every field exists so a sample can be traced back to its exact source data and the normalization applied, which is required for auditable model checkpoints.

The reanalysis-ingestion design (Phase 175.1.1.1) targets ERA5 surface fields including 2m temperature, 10m u/v winds, mean sea-level pressure, total precipitation, and 2m dewpoint, plus 37 pressure levels carrying geopotential, u/v wind, vertical velocity (w), temperature, and specific humidity. These are the variables surfaceVariables, upperAirVariables, and pressureLevels enumerate; the schema itself stores them as open string lists rather than a fixed enum.

4.4 WeatherSample.source (literal union)#

The source field records which ingestion client and data provider produced the sample. Each value maps directly to a distinct ingestion client specified in Phase 175.1, and the mapping is intentionally one-to-one so provenance is unambiguous.

4.5 ForecastRequest interface#

ForecastRequest describes a forecast job submitted to @gaia/forecast-serving. The product field is the primary routing key: it tells the serving layer which @gaia/* model library to invoke (see §4.6). The outputFormat field controls serialization without changing what is computed.

4.6 ForecastRequest.product (literal union)#

The product field routes a ForecastRequest to the appropriate model library. Each value maps to exactly one @gaia/* package, keeping routing logic centralized and the model libraries independently deployable.

4.7 ForecastRequest.outputFormat (literal union)#

The outputFormat field lets different consumer types pull data in the format their tooling expects. A shell surface (e.g. Uzume's event dashboard) pulls JSON; a scientific user or retraining job pulls Zarr or GRIB2 directly from object storage using signed URLs.

4.8 ForecastProduct interface#

ForecastProduct is the resolved output of a ForecastRequest. @gaia/forecast-serving persists ForecastProduct records to the warehouse and registers them in the catalogs. Every field is designed for auditability: consumers must always be able to trace a product back to the model version and source data that produced it.

4.9 SkillSummary interface#

SkillSummary is referenced as the optional skillSummary field of ForecastProduct. The features and architecture documents describe it qualitatively — it is "a summary of the product's evaluation skill" reported "where available" — but they do not enumerate its fields. The concrete field list is not specified in features.md, architecture.md, or TODOS/phase-175.md, and is therefore left to implementation. The metrics that feed product skill are catalogued in §14 (Evaluation Requirements).

4.10 ForecastProduct.publicationStatus (product lifecycle state machine)#

publicationStatus tracks a product through its operational lifecycle. The three states encode whether a product is safe to surface to downstream consumers. The rolled_back state is important for auditability: it ensures that a bad cycle's products are retained and inspectable rather than silently deleted.

The allowed transitions are:

rolled_back is the terminal state. draft is terminal for products of a cycle that never passes its gates — they remain draft rather than being deleted.

5. Cyclone Contracts (@gaia/cyclone-forecast)#

Direct tropical-cyclone prediction produces a CycloneForecastProduct keyed by stormId and basin, holding an ordered list of CycloneForecastPoint records — one per forecast lead time. The two interfaces below define the complete wire format for cyclone products.

interface CycloneForecastPoint {
  leadTimeHours: number;
  probabilityOfCyclone: number;
  centerLat: number;
  centerLon: number;
  maxSustainedWindKt?: number;
  centralPressureHpa?: number;
  radiusOfMaximumWindNm?: number;
  r34QuadrantsNm?: [number, number, number, number];
  r50QuadrantsNm?: [number, number, number, number];
  r64QuadrantsNm?: [number, number, number, number];
  saffirSimpsonCategory?: 0 | 1 | 2 | 3 | 4 | 5;
  eyeFormationProbability?: number;
}

interface CycloneForecastProduct {
  stormId: string;
  basin: string;
  cycleTime: string;
  points: CycloneForecastPoint[];
  atcfUri?: string;
  uncertaintyConeUri?: string;
}

5.1 CycloneForecastPoint interface#

One forecast point represents a single lead time for one storm. Points are emitted along the standard forecast horizon — Phase 175.4 targets a 0–120h trajectory distribution — so reading points in order gives the full predicted track.

Intensity and structure fields are optional per point because a low-probability or pre-formation point may carry only position. leadTimeHours, probabilityOfCyclone, centerLat, and centerLon are always present.

5.2 saffirSimpsonCategory (numeric literal union)#

The category is encoded as a numeric literal union rather than a string to make threshold comparisons cheap and unambiguous. Category 0 covers tropical storms and sub-tropical systems that do not yet meet hurricane criteria.

5.3 CycloneForecastProduct interface#

CycloneForecastProduct is the top-level object returned by the cyclone forecast endpoint. The atcfUri and uncertaintyConeUri fields are signed object-storage URIs — they are optional because not every cycle will produce both assets, but they must be present for any product that is consumed by NHC-compatible emergency-response tooling.

5.4 Model Design#

The cyclone model is built on four numbered Phase 175 design points. Each point must be implemented for the model to produce ATCF-compliant output.

• Functional cyclone output (Phase 175.4.1.1). At each 6-hour lead time the model jointly predicts probability-of-cyclone, center lat/lon, max sustained wind, central MSLP, radius of maximum wind, R34/R50/R64 quadrants, and an eye formation flag, as a differentiable head conditioned on the diffusion-backbone latent.
• Trajectory decoder (Phase 175.4.1.2). A Transformer decoder over the predicted cyclone centers, conditioned on the past 24h IBTrACS track plus the model latent, outputs a 0–120h trajectory distribution with stochastic sampling. Track and intensity are decoded jointly so they stay physically consistent.
• Loss formulation (Phase 175.4.1.3). Training uses a combined loss: position (great-circle Haversine), intensity (Huber on Vmax and MSLP), categorical class (Saffir-Simpson), and Brier score on formation. The model is penalized for a good track with a wrong intensity as well as the reverse.
• ATCF output (Phase 175.4.1.4). An automated NHC-compatible ATCF generator emits the technical-format deck (BASIN, CY, YYYYMMDDHH, TAU, Lat N/S, Lon E/W, Vmax, MSLP, category, R34/R50/R64) for ingestion by downstream emergency-response systems.

6. Nowcast Contracts (@gaia/nowcast)#

Minute-scale precipitation nowcasting answers a PrecipitationNowcastRequest and returns a PrecipitationNowcastProduct. The contracts below are the wire format for the nowcast endpoint.

interface PrecipitationNowcastRequest {
  issuedAt: string;
  horizonMinutes: number;
  cadenceMinutes: number;
  region: WeatherGrid['bounds'];
  thresholdsMmPerHour: number[];
  ensembleMembers?: number;
}

interface PrecipitationNowcastProduct {
  id: string;
  issuedAt: string;
  horizonMinutes: number;
  cadenceMinutes: number;
  productUris: string[];
  convectiveMode:
    | 'stratiform'
    | 'convective'
    | 'tropical'
    | 'frontal'
    | 'mixed';
  verification?: {
    csi: number;
    pod: number;
    far: number;
    fss: number;
  };
}

6.1 PrecipitationNowcastRequest interface#

region is required (not optional) because nowcasting is inherently regional — there is no meaningful global nowcast given the fine spatial resolution and the radar/satellite inputs that anchor the model. thresholdsMmPerHour lets the consumer specify which rain-rate thresholds they want probability fields for, rather than receiving a fixed set.

6.2 PrecipitationNowcastProduct interface#

The verification block is absent from freshly issued nowcasts — it cannot be computed until the valid period has elapsed and stage observations are available. Consumers should not treat a missing verification block as a failure; it will be filled in after the fact.

6.3 PrecipitationNowcastProduct.convectiveMode (literal union)#

convectiveMode encodes the precipitation regime classified by the model. The mode matters to downstream consumers because the skill and predictability of a nowcast differs significantly by regime: a convective cell evolves over minutes and is hard to track beyond 30–60 minutes, while a stratiform shield is predictable over several hours. A convective-mode classifier (Phase 175.5.1.3) derives this value from radar, satellite, and lightning inputs.

6.4 PrecipitationNowcastProduct.verification block#

The four verification metrics in the verification block are standard deterministic precipitation-verification scores widely used in operational NWP. They are computed against Stage IV and radar-gauge blends (Phase 175.5.1.4 specifies verification at 0.1/1/5/10 mm h⁻¹ thresholds).

6.5 Model Design#

Two model variants share the same output contract, selected by the presence of ensembleMembers in the request. A consumer that needs only a single best-estimate track can use the lighter deterministic model; a consumer that needs uncertainty bounds (e.g. for event-cancellation risk thresholds) sets ensembleMembers to receive a spread.

• Deterministic model (Phase 175.5.1.1). A MetNet-3-class axial transformer over stacked radar composites (last 90 minutes, 2-minute cadence), geostationary satellite, topography, and NWP boundary conditions, producing 0–12 hour precipitation at 1 km, 5-minute resolution. Radar and satellite supply the recent motion and convection signal; NWP boundary conditions keep the longer lead times physically anchored.
• Ensemble model (Phase 175.5.1.2). A DGMR-class conditional GAN generates an ensemble of precipitation fields (a 4-member radar ensemble is the baseline), so downstream consumers see spread rather than a single track.

7. Climate and Downscaling Contracts#

ClimateScenarioRequest and DownscalingRequest serve two related but distinct needs: the climate emulator produces long-horizon scenario projections under tunable greenhouse-gas forcing, while the downscaler refines an existing coarse forecast to finer spatial scale. Their contracts are defined below.

interface ClimateScenarioRequest {
  baselinePeriod: string;
  rolloutYears: number;
  forcing: {
    co2Ppm?: number;
    ch4Ppb?: number;
    aerosolScenario?: string;
    ssp?: 'ssp2_45' | 'ssp5_85' | 'custom';
  };
  variables: string[];
}

interface DownscalingRequest {
  sourceForecastId: string;
  targetResolution: '2km' | '1km' | '50m_urban' | 'station';
  method:
    | 'residual_diffusion'
    | 'station_bias'
    | 'quantile_mapping'
    | 'urban_uhi';
  region?: WeatherGrid['bounds'];
  stationIds?: string[];
}

7.1 ClimateScenarioRequest interface (@gaia/climate-emulator)#

ClimateScenarioRequest describes a multi-decade climate-emulation rollout. The forcing block is the mechanism that distinguishes scenarios: consumers can select a standard IPCC pathway (SSP2-4.5 or SSP5-8.5) or specify explicit greenhouse-gas concentrations for a custom scenario.

7.2 ClimateScenarioRequest.forcing block#

All four fields in the forcing block are optional because a standard SSP pathway is self-contained (no explicit gas concentrations needed), while the custom path requires explicit co2Ppm and ch4Ppb. An implementation must validate that a custom ssp is accompanied by at least one explicit concentration.

7.3 ClimateScenarioRequest.forcing.ssp (literal union)#

The two standard SSP pathways map to IPCC scenario definitions. The custom value unlocks the explicit gas-concentration path, useful for sensitivity analyses that do not correspond to any published SSP.

7.4 DownscalingRequest interface (@gaia/downscale)#

DownscalingRequest takes a coarse ForecastProduct identified by sourceForecastId and produces a finer-scale output. The method and targetResolution fields are related — certain methods are designed for specific resolution targets (see §7.6), and the implementation should validate that the chosen combination is supported.

7.5 DownscalingRequest.targetResolution (literal union)#

The four resolution targets span the range from gridded regional products to point-site station corrections.

7.6 DownscalingRequest.method (literal union)#

Each method is designed for a specific class of downscaling problem. The associations between method and target are: residual_diffusion → 2km or 1km grid refinement; station_bias → station site correction; quantile_mapping → derived-variable distribution correction; urban_uhi → 50m_urban city-scale heat.

7.7 Climate-Emulator Model Design#

Three Phase 175 design points define the emulator's stability and validation requirements. The drift target (≤ 0.05 K decade⁻¹) is a hard requirement rather than a best-effort target because an emulator that drifts on long rollouts is useless for the decadal decision support that Cybele and Lakshmi need.

• Emulator model (Phase 175.6.1.1). A spherical-FNO / Ai2 ACE-class emulator trained on CMIP6 pre-industrial control plus SSP2-4.5 and SSP5-8.5 runs, producing stable 100-year rollouts at 1° resolution with closed energy/moisture budgets. The drift target is ≤ 0.05 K decade⁻¹ on global mean surface temperature.
• Coupled feedbacks (Phase 175.6.1.2). Sea-ice-albedo and soil-moisture feedback modules are coupled into the rollout via FNO-in-FNO composition, so ice-albedo and land-surface feedbacks evolve rather than being held fixed.
• Hindcast validation (Phase 175.6.1.3). A decadal hindcast driver (1960–2020) is validated against HadCRUT5, GISTEMP, and AMIP-SST before a checkpoint is promoted.

8. Operational Forecast Cycle (@gaia/forecast-serving)#

The live operational cycle turns the latest analysis into published forecast products. This section describes its cadence, gates, and rollback semantics — all of which are enforced automatically by @gaia/forecast-serving without manual intervention.

8.1 Cycle Cadence#

Cycles run on the 00/06/12/18 UTC analysis schedule. A cycle launches when live IFS HRES initial conditions are available, or fallback GFS initial conditions if HRES is missing — the cycle is not skipped for want of the primary source. The gaia.forecast.cycle.started event records which initial-condition source (HRES or GFS) was used.

8.2 Publication Gate#

A cycle's products may publish only when all three gates pass. The gates exist to prevent bad model output from reaching downstream consumers. Any single gate failure blocks the entire cycle from publishing.

1. Rollout-stability diagnostics — energy conservation, spectra, and blur checks (see §9.2).
2. Skill-regression check — a comparison against the prior promoted baseline. Failure fires gaia.skill.regression_detected.
3. Data-completeness check — a check on the cycle's inputs.

A cycle that fails any gate does not publish; its ForecastProduct records stay in publicationStatus: 'draft'.

8.3 Cycle Rollback#

When a published cycle is later found bad, it is rolled back: affected products transition to publicationStatus: 'rolled_back', a gaia.forecast.cycle.rolled_back event fires, and downstream consumers fall back to the previous good cycle. A rolled-back product is retained, not deleted, so the failure is auditable.

8.4 Latency Target#

The operational deterministic cycle has a p95 completion target under 20 minutes, measured from analysis availability to product publication, on the planned H100-class cluster (Phase 175.8.1.5 names the H100-40 cluster). A companion accuracy target: 24h deterministic RMSE within 2% of the published GraphCast baseline.

8.5 Cycle State Sequence#

The cycle runner moves through the following six stages in order. The stage descriptions correspond to the Phase 175.8.1.2 design and the event set defined in §11.

9. Model Architecture (planned)#

9.1 Deterministic Spherical GNN (@gaia/graphcast)#

The GraphCast-Sovereign model follows the published GraphCast architecture closely, with Oshun-specific training plans and stability diagnostics added on top. The five design points below map to Phase 175 sub-tasks.

• Icosahedral multi-mesh (Phase 175.2.1.1). An icosahedral multi-mesh generator builds M0 (icosahedron) through M6 refinement (40,962 nodes), with uniform-area triangular faces and pre-computed edge lists for every refinement level.
• Grid→Mesh encoder (Phase 175.2.1.2). For each mesh node, the encoder attends to nearby 0.25° grid nodes (radius ≈ 0.6× mesh edge length) via an MLP on (node feature, grid feature, relative position) — identical semantics to the public GraphCast encoder.
• Mesh processor (Phase 175.2.1.3). 16 rounds of interaction-network message passing over all 6 refinement levels simultaneously (hierarchical multi-mesh), with residual updates and layer norm, producing updated mesh node embeddings.
• Mesh→Grid decoder (Phase 175.2.1.4). For each grid node, the decoder attends to its containing mesh triangle's 3 nodes via an MLP, predicts a residual tendency relative to the input state, and adds it to the input to produce the +6h forecast.
• Autoregressive rollout (Phase 175.2.1.5). A rollout driver applies the 6h step up to 40 times for a 10-day horizon, with checkpoint-supported gradient accumulation for multi-step fine-tuning.

9.2 Rollout-Stability Diagnostics (Phase 175.2.2.5)#

Rollout-stability diagnostics are the first gate in the publication check (§8.2). They guard against spectral collapse — a failure mode in autoregressive GNN models where the spatial spectrum blurs or collapses over long rollouts, making the forecast physically unrealistic even if per-step errors look acceptable. Diagnostics cover energy conservation, the spectrum at T+240h versus ERA5 climatology, and a blur detector, with automatic early-stop on spectral collapse. These diagnostics also drive checkpoint rejection during training.

9.3 Probabilistic Diffusion (@gaia/gencast)#

The ensemble model extends the deterministic backbone with a diffusion process over residual states. This produces calibrated spread across ensemble members rather than a single trajectory, which is required for any consumer that needs to estimate tail risk rather than a best-guess outcome.

• State-diffusion model (Phase 175.3.1.1). A state-diffusion model operating on +12h residuals over the icosahedral mesh, with EDM parametrization (preconditioned score-matching, ρ=7, σ_min 0.02, σ_max 88), using the deterministic GNN as the score-network backbone, conditioned on the previous two states.
• Samplers (Phase 175.3.1.2). A deterministic DPM-Solver++ sampler for 20-step ensemble generation, and a stochastic Heun sampler for calibrated tail sampling.
• Operational ensemble (Phase 175.3.1.4). 50-member operational ensemble generation on a single H100 / B200, with batched multi-seed sampling.

9.4 Training Plans#

Four training plans are defined for the deterministic model. The base plan establishes the initial checkpoint; the XL plan scales to 0.25° resolution; the ensemble plan provides a cheap diversity baseline; and the loss-weighting plan ensures physically important regions and variables are prioritized.

• GraphCast-Sovereign base (Phase 175.2.2.1). 37M parameters, 1° ERA5. Single-step MSE for 300k steps, then multi-step fine-tuning for 2, 4, … up to 12 rollout steps with linearly decayed loss weights.
• GraphCast-Sovereign-XL (Phase 175.2.2.2). A 0.25°, 226M-parameter variant trained on a TPU-v5e / H100 pod.
• Ensemble-of-Sovereigns (Phase 175.2.2.3). 10 random seeds × different training subsets, a cheap deterministic ensemble baseline.
• Loss weighting (Phase 175.2.2.4). Per-variable, per-level, per-latitude loss weighting (area-weighted cos(lat) plus published GraphCast variable weights).

10. Data Architecture and Sampling (planned)#

10.1 Storage and Catalog#

The storage design is built around immutability and efficient access. Raw source files are kept exactly as received from the provider; derived Zarr stores are chunked for training locality. All products register STAC items so external scientific users can discover them through standard geospatial catalog interfaces.

• Raw source files are immutable and retained with source URL, provider, acquisition time, checksum, license, and access-policy metadata.
• ERA5 ingestion uses tiered MinIO storage: hot (last 5 years), warm (1990–present), cold (1940–1989).
• Derived Zarr stores are chunked by variable, level, time, and grid so training and serving jobs can read contiguous forecast windows efficiently. GRIB2→Zarr conversion uses xarray + dask + kerchunk.
• Zarr products preserve chunk layout, grid metadata, variable units, level metadata, the time axis, and the provenance hash.
• Forecast products are persisted as Zarr, GRIB-compatible export bundles, JSON summaries, STAC items, and OGC EDR/Features products where applicable.

10.2 Sampling and Splits#

The sampling design ensures training data reflects the full distribution of weather events, including rare extremes, and prevents any temporal leakage between splits.

• Stratified loader (Phase 175.1.3.2). A stratified training-sample loader balances across seasons, basins, and extreme-event classes (from IBTrACS, SPI, and heat-wave indices), with a curriculum scheduler that up-weights tropical cyclones, atmospheric rivers, and blocking events.
• Temporal split (Phase 175.1.3.3). A rolling train/validation/test split enforces strict temporal separation — train ≤ 2018, validation 2019–2020, test 2021+ — to prevent leakage through persistence and climate drift.
• Statistics (Phase 175.1.3.4). A statistics package computes per-variable, per-level mean, standard deviation, min, and max for model normalization and denormalization, stored versioned alongside each trained checkpoint. This is the source of WeatherSample.normalizationVersion.

11. Domain Events#

Gaia publishes ten domain events. These events are the primary integration surface for downstream consumers — rather than polling forecast endpoints, consumers subscribe to the relevant events and react when products or alerts arrive. Internal operations also use these events for monitoring, rollback triggers, and model-promotion audit trails.

Gaia consumes shared identity, tenant, storage, queue, model-serving, observability, and evaluation contracts.

12. Forecast API Surface (@gaia/forecast-serving)#

@gaia/forecast-serving exposes an OpenAPI 3.1 forecast API as a BFF, with per-tenant rate limiting and signed-URL GRIB/Zarr output streaming. The ten endpoints below cover the six forecast product types plus retrieval, download, and alert operations.

12.1 Mandatory Response Metadata#

Every forecast response must include the model version, the cycle time, the data-source versions used, an output hash, the skill summary where available, and signed output URIs for large products. This requirement is non-negotiable: a forecast a consumer cannot trace back to a model version and source set is not publishable.

12.2 Product Warehouse and Catalogs#

Products are persisted to a Zarr forecast-product warehouse on MinIO and registered in a STAC 1.0 catalog, with OGC EDR and OGC API Features endpoints so external scientific users can query products through standard geospatial interfaces. The STAC catalog and OGC endpoints are the external-facing discovery surface; the REST API is the primary interface for Oshun internal consumers.

12.3 CAP Alerts#

POST /forecast/alerts/cap publishes CAP 1.2-compatible severe-weather alerts, using the CAP 1.2 profile urn:oid:2.49.0.1.840.1. Each alert preserves the source forecast identity and the threshold rule, integrates with Kuanyin emergency escalation and Oshun shell-routine weather notifications, and emits a gaia.alert.cap.published audit event for downstream publication.

13. Storage and Catalog Requirements#

These requirements follow from the auditability and traceability goals of the data architecture. Every stored artifact — raw data, derived Zarr, forecast product, or CAP alert — must carry enough metadata to reconstruct its full provenance chain.

• Raw data must retain the source provider, license/access policy, acquisition timestamp, checksum, and immutable object URI.
• Zarr products must preserve chunk layout, grid metadata, variable units, level metadata, the time axis, and the provenance hash.
• Forecast products must register STAC items and OGC EDR/Features metadata for external scientific users.
• CAP alerts must preserve the source forecast id, the threshold rule, the reviewer state if applicable, and downstream publication targets.

14. Evaluation Requirements#

Model promotion is gated by per-model-class evaluation suites. A checkpoint that passes its gates fires gaia.model.promoted; one that fails fires gaia.model.rejected naming the failed gate. The gates are grounded in community benchmarks so Gaia's published skill can be directly compared against external frontier models.

• Deterministic — checkpoints must pass WeatherBench-2 and ECMWF-style scorecards, reproducing published 0.25° headline skill on Z500, T850, Q700, and U10.
• Ensemble — checkpoints must pass CRPS, reliability, rank histogram, spread-skill ratio, and tail-calibration gates, with CRPS validated against IFS-ENS (51 members, 9 km) and extreme-percentile verification (P99.9 precipitation, heat-wave return periods, wind-speed tails) guarding against distributional shortcut learning.
• Cyclone — checkpoints must pass NHC-style track, intensity, formation, landfall, and ATCF product validation.
• Nowcast — checkpoints must pass CSI, POD, FAR, and FSS thresholds across precipitation rates (0.1/1/5/10 mm h⁻¹) and regions, versus Stage IV and radar-gauge blends.
• Climate emulator — checkpoints must pass energy, moisture, and drift budgets for long rollouts and validate the decadal hindcast against HadCRUT5, GISTEMP, and AMIP-SST.
• Downscaling — checkpoints must validate against HRRR, CERRA, and station residuals, and validate derived-variable calibration.
• Stress tests — promotion requires red-team cases: Hurricane Ian 2022, Hurricane Lee 2023, the 2021 Pacific Northwest heat dome, the February 2021 Texas cold snap, and the July 2022 UK record heat. Every new checkpoint must match or exceed the prior on all cases before promotion.
• Benchmarks and leaderboard — a public-benchmark suite (WeatherBench-2, ECMWF scorecards, NHC verification, pysteps verification) publishes an automated leaderboard per checkpoint to the Phase 91 evaluation hub.

14.1 Data Flywheel#

Evaluation results are not discarded after promotion gating — they feed back into the training loop through the Phase 85 data flywheel. A weather-outcomes collector extends this flywheel: forecast vs. analysis deltas per cycle, per variable, per lead-time, and per region are fed back into training-data difficulty weighting (Phase 89.4.1.8) and retraining triggers (Phase 85.17.1.5). An observational feedback loop compares operational forecasts against surface station, radiosonde, and buoy arrivals in real time and feeds per-station residuals back into the station-bias correction heads.

15. Observability#

Forecast availability, skill, latency, calibration, cycle completion, cost, and downstream publication failure are first-class metrics with Grafana dashboards. They are instrumented from the start, not derived after the fact. The SLO dashboard tracks two specific targets: the p95 cycle-completion target (< 20 min, §8.4) and the 24h deterministic RMSE target (within 2% of the published GraphCast baseline).

16. Downstream Contract Requirements#

The contract boundary between Gaia and its consumers is the forecast product and the CAP alert. Consumers must not read Gaia's internal training splits, must preserve forecast uncertainty when surfacing results to users, and must carry Gaia's provenance identifiers through their own audit trails.

• Asase, Demeter, Oya, Galatea, Cybele, Lakshmi, Uzume, Aphrodite, Veritas, Kuanyin, and Oshun integrations must consume public Gaia products or signed product URIs. They must not read Gaia private training splits directly.
• Downstream adapters must preserve forecast uncertainty and must not convert low-confidence forecasts into deterministic user actions without domain-owned policy gates.
• Severe-weather alert consumers must preserve CAP IDs and Gaia provenance in user-facing notifications and audit logs.

16.1 Downstream Consumers#

Gaia owns forecast products; the consumer owns the decision made from them. The table below maps each consumer to the Gaia outputs it reads and the decision it owns independently.

@gaia/forecast-serving also exposes renewable-energy potential (solar GHI, wind 100m, hydro-inflow) to Lakshmi for energy trading and capacity planning. Themis consumes the urban-downscaling product for climate-adaptation work.

17. Verification and Completion Criteria#

Gaia is not complete until all of the following conditions are satisfied. Each criterion has a corresponding automated check.

• Planned packages appear in the Nx project graph with scope:gaia tags.
• Data adapters have fixture-backed ingestion and checksum tests.
• The WeatherSample schema and the forecast product schemas have contract tests (the WeatherSample schema is Zod-validated and Zarr-chunk-aligned per Phase 175.1.3.1).
• Forecast APIs validate OpenAPI 3.1 output and generated clients.
• Model promotion is gated by deterministic, ensemble, cyclone, nowcast, climate, and downscaling evaluation suites.
• Downstream adapters have integration tests proving uncertainty, provenance, and alert IDs survive handoff.
• Observability dashboards cover cycle latency, skill, availability, calibration, cost, and rollback.

18. Research Release#

The research-sovereignty plan publishes a scientific paper and an open-weights release for each major model class, under Apache 2.0 where the model is derived from openly-licensed pre-training data.

19. Source Coverage#

This specifications document is a planned/design-level specification. Gaia has no implemented code (libs/gaia/*, apps/gaia/*, and services/gaia/* do not exist, and there are no @gaia/* path mappings in tsconfig.base.json). It was written against TODOS/phase-175.md, DOMAINS/gaia/features.md, and DOMAINS/gaia/architecture.md. Every schema, field, enum value, endpoint, event, state, and design statement above traces to one of those three documents; no items were invented to round out a section. The SkillSummary field list is intentionally left unspecified because none of the three source documents enumerate it. Task-level checkboxes remain in TODOS/phase-175.md.