Scientific contract / version 1.0
Methodology
SHFT explores scientifically constrained future Earth trajectories. It does not forecast one future, optimize toward an outcome, or let interpretation alter computation.
Active engine
shft-earth-core-0.2.0
Earth-state schema
earth-state-0.2
Status
validated default
Active production backbone
SURFER v3.0
Adapter
SHFT adapter
Tolerance set
engine-0.2
How SHFT works
- 01Scenario
- 02Scientific engine
- 03Earth state
- 04Validation
- 05Provenance
- 06Observatory
A user-defined scenario is executed outside the interface by the pinned scientific model. SHFT maps its supported outputs into a versioned Earth-state schema, applies binary gates, records the complete lineage, and displays only what survives those checks.
Scientific philosophy
- Physical Earth systems are modeled before biological and human systems.
- The engine has no preferred outcome.
- Unknown is an explicit scientific state.
- Uncertainty language never exceeds evidence.
- Interpretation never changes computation.
- Validation may withhold unsupported results.
Scientific backbone registry
SURFER v3.0 — active production backbone
SURFER is executed from its pinned archive without rewriting its equations. SHFT adds scenario inputs, explicit state mapping, unit and timestep transformations, validation, provenance, and the Observatory.
Other published Earth-system models may be registered alongside it as reference backbones, used only to validate, constrain, or bound production output. A reference model never supplies a value SHFT reports, never fills a quantity marked not modeled, and disagreement between models is kept as scientific information rather than averaged away.
Source
Where a value or method originated.
Epistemic label
What kind of evidence supports this value.
Validation
Whether predefined tests passed or failed.
Constitutional Gate catalog — v1.0 disposition
6 of 13 catalogued gates are evaluated for tolerance set engine-0.2. A passed-gate count on any run refers only to those 6 active criteria. The remaining 7 are not evaluated: they are neither passed nor failed, and each records why, and what evidence would be required to promote it to an independent SHFT check in a later version. Silence is not a pass.
Carbon mass conservation
carbon_conservation
Upstream property — not independently re-verified by SHFT v1.0
Evidence basis · Carbon conservation is a property of the pinned upstream SURFER v3.0 formulation and is evidenced only by the reproduced upstream carbon-budget benchmark (carbon_budget_2000_2009_and_cumulative). The earth-state-0.2 schema stores no carbon reservoir masses. Of the two catalogued flux-like quantities, net_primary_productivity is defined but not represented; weathering_rate is represented. SHFT therefore holds no complete reservoir/flux inventory and cannot construct an independent closure test. Completeness is not inferred.
Required to promote · Store the complete upstream carbon reservoir and flux diagnostics per stored time point in a new schema version, then add an engine-0.2+ criterion computing a residual against a sourced tolerance.
Independent SHFT verification · inherited upstream
CO2 and GMST numeric guard range
emulator_domain
Active — evaluated for engine-0.2
Evidence basis · Evaluated for every engine-0.2 run by evaluate_engine_gates within its stated scope.
Required to promote · None; already active. Any widening of scope requires a new criterion and tolerance set.
Independent SHFT verification · performed
Energy balance closure
energy_balance
Upstream property — not independently re-verified by SHFT v1.0
Evidence basis · Energy closure is a property of the pinned upstream formulation. The adapter/payload stores only global mean surface temperature and ocean heat content; no top-of-atmosphere or component energy fluxes are stored, so no auditable closure residual can be computed by SHFT v1.0.
Required to promote · Store the complete upstream energy-flux inventory (top-of-atmosphere imbalance and component fluxes) per stored time point, then add a criterion checking the imbalance against a sourced tolerance.
Independent SHFT verification · inherited upstream
Hindcast: last deglaciation
hindcast_ice
Deferred — not independently validated in v1.0
Evidence basis · Deferred in v1.0. No reconstruction-based ice benchmark has been sourced or reproduced for the pinned backbone, and no engine-0.2 criterion evaluates ice volume against any target. No pass is inherited from tol-0.1.
Required to promote · A cited deglaciation ice-volume reconstruction with a declared tolerance, an executed adapter-path run over that interval, and an engine-0.2+ criterion comparing served ice_sheet_volume output against it.
Independent SHFT verification · not performed
Hindcast: sea level
hindcast_sea_level
Deferred — not independently validated in v1.0
Evidence basis · Deferred in v1.0. The upstream publication compares thermosteric sea level with IPCC evidence, but no sourced, reproducible adapter-path comparison exists in SHFT and no engine-0.2 criterion evaluates it. The seeded tol-0.1 demonstration result is hand-authored and is not evidence about the SURFER-backed engine.
Required to promote · A sourced tide-gauge or reconstruction target with a declared tolerance, an executed historical adapter-path run, and an engine-0.2+ criterion comparing served sea_level output against it.
Independent SHFT verification · not performed
Hindcast: surface temperature
hindcast_temperature
Upstream property — not independently re-verified by SHFT v1.0
Evidence basis · Upstream reproduction evidence only. The reproduced pinned-model benchmarks atmospheric_co2_curve_1850_2015_rmse_ppm and gmst_anomaly_2014_k compare upstream output with published historical evaluation, and are recorded under upstream_reproduction. No engine-0.2 criterion compares served SHFT adapter-path output against a sourced historical temperature target, so there is no independent SHFT hindcast gate.
Required to promote · A stored historical-period adapter-path run with a sourced observational temperature target and declared tolerance, plus an engine-0.2+ criterion comparing served SHFT output against it.
Independent SHFT verification · inherited upstream
Provenance completeness
provenance_completeness
Active — evaluated for engine-0.2
Evidence basis · Evaluated for every engine-0.2 run by evaluate_engine_gates within its stated scope.
Required to promote · None; already active. Any widening of scope requires a new criterion and tolerance set.
Independent SHFT verification · performed
Schema compatibility
schema_compatibility
Active — evaluated for engine-0.2
Evidence basis · Evaluated for every engine-0.2 run by evaluate_engine_gates within its stated scope.
Required to promote · None; already active. Any widening of scope requires a new criterion and tolerance set.
Independent SHFT verification · performed
Seed reproducibility
seed_reproducibility
Active — evaluated for engine-0.2
Evidence basis · Evaluated for every engine-0.2 run by evaluate_engine_gates within its stated scope.
Required to promote · None; already active. Any widening of scope requires a new criterion and tolerance set.
Independent SHFT verification · performed
Long-run numerical stability
stability_longrun
Deferred — not independently validated in v1.0
Evidence basis · Deferred in v1.0. No long-run SURFER-backed stability experiment has been executed and stored: the longest reproduced evidence is the LTMIP long-tail CO2 comparison, and the interface offers horizons far short of the 1 Myr integration the catalogued gate describes. The seeded tol-0.1 demonstration does not count.
Required to promote · A defined and executed long-run adapter-path experiment at the declared resolution with stored trajectories, plus an engine-0.2+ criterion checking for numerical blow-up over that integration.
Independent SHFT verification · not performed
Declared schema-range check
unit_validation
Active — evaluated for engine-0.2
Evidence basis · Evaluated for every engine-0.2 run by evaluate_engine_gates within its stated scope.
Required to promote · None; already active. Any widening of scope requires a new criterion and tolerance set.
Independent SHFT verification · performed
Upstream reproduction
upstream_reproduction
Active — evaluated for engine-0.2
Evidence basis · Evaluated for every engine-0.2 run by evaluate_engine_gates within its stated scope.
Required to promote · None; already active. Any widening of scope requires a new criterion and tolerance set.
Independent SHFT verification · performed
Water mass conservation
water_conservation
Not applicable to the active production backbone
Evidence basis · SURFER v3.0, the sole active production backbone, models no hydrological cycle and SHFT Layer 1 stores no water inventory. The catalogued river_discharge quantity is defined but not represented. There is no quantity against which water mass closure could be tested, so the gate is outside the scope of the active backbone and must never be displayed as passed.
Required to promote · A production backbone that resolves a water inventory (reservoir masses and fluxes) plus a sourced closure tolerance. Not achievable by adapter work on SURFER v3.0.
Independent SHFT verification · not applicable
Scientific Backbone Registry
Exactly one production backbone computes Earth state. Every other registered model exists only to validate, constrain, or bound that output — it never supplies a reported value and never fills a quantity marked not modeled. The five maturity dimensions below are independent: an inability to execute a model in our environment is never a judgement about the quality of its science, and executing successfully never promotes a model toward production.
SURFER v3.0
v3.0 · MIT · role production
Scientific
established
Peer-reviewed model description: Couplet, Martinez Montero and Crucifix (2025), Geoscientific Model Development 18, 3081-3105, doi:10.5194/gmd-18-3081-2025.
Reproducibility
reproduced in environment
Nine upstream benchmarks reproduced from the pinned archive SURFER_v3.zip (MD5 82c0537c42b66451a7550bb6fa7ef88e); engine/upstream/reproduction_report.json.
Integration
mapped with executed comparison
Declarative adapter engine/shft_engine/surfer/adapter.py maps seven quantities and declares six not_modelled; CM-01 executed against GEOCLIM 7.0.
Validation
cross validated
Internal benchmark reproduction plus one executed external cross-model comparison (CM-01, weathering magnitude only). Cross-validation is quantity-specific and does not extend to any other quantity.
Production
active production
Promoted to validated_default as shft-earth-core-0.2.0 after historical, centennial and long-tail gate families passed.
GEOCLIM 7.0
7.0 · CC-BY-4.0 · role validation reference
Scientific
established
Peer-reviewed model description: Maffre et al. (2025), Geoscientific Model Development 18, 6367, doi:10.5194/gmd-18-6367-2025.
Reproducibility
reproduced in environment
Built unmodified from pinned archive piermafrost-GEOCLIM-v7.0.zip (MD5 02579825643a90017d19dea9930fd109); upstream make_test ascii reports Template comparison check PASSED. Environment shim (nc-config) lives outside the archive and is removable.
Integration
mapped with executed comparison
Weathering capability cells mapped; CM-01 declared with tolerance before execution and executed.
Validation
internally validated
Reproduces its own upstream template comparison. Its role in SHFT is to test SURFER claims, not to be validated by SHFT.
Production
none
Never executes inside the production Earth Engine and never fills a production not_modelled value.
cGENIE (cgenie.muffin)
v0.9.60 · MIT · role validation reference
Scientific
established
Widely used peer-reviewed Earth system model of intermediate complexity; base description Ridgwell et al. (2007), Biogeosciences 4, 87-104, doi:10.5194/bg-4-87-2007.
Reproducibility
reproduced in environment
Published known-good BIOGEM test from the pinned v0.9.60 release passed unmodified in this environment.
Integration
dossier only
Dossier and reproduction recorded. No Earth-state variable mapping and no executed comparison yet: a published equilibrium configuration with practical spin-up runtime has not been established here.
Validation
internally validated
Reproduces its own published known-good test. No SHFT cross-model comparison executed against it.
Production
none
Never executes inside the production Earth Engine.
SCION
v1.1.6 · Apache-2.0 (LICENSE file inside the pinned archive; the Zenodo record metadata label other-open is less specific) · role validation reference
Scientific
established
Peer-reviewed SCION model description, doi:10.1029/2020GC009361, and associated deep-time publications.
Reproducibility
not reproducible here
Octave ode15s corrector convergence failure; requires MATLAB or an equivalent solver environment.
Integration
dossier only
Dossier from published evidence only. No executed comparison.
Validation
declared only
Published validation exists in the literature; nothing has been reproduced or cross-validated inside SHFT.
Production
none
Never executes inside the production Earth Engine.
EONS
v1.0.0 · CC-BY-4.0 (Zenodo record metadata for the pinned release; the earlier triage entry recording MIT was incorrect) · role boundary reference
Scientific
established
Peer-reviewed: Horne et al. (2024), doi:10.1029/2023GC011252.
Reproducibility
not reproducible here
MATLAB script-local-function resolution and ode15s dependence; requires MATLAB.
Integration
dossier only
Dossier from published evidence only. No executed comparison.
Validation
declared only
Published validation only; nothing reproduced inside SHFT.
Production
none
Never executes inside the production Earth Engine.
COPSE
Zenodo record 17416376 (COPSE / PALEO MATLAB distribution) · CC-BY-4.0 (Zenodo record metadata for the pinned archive). Repository-level licensing remains UNRESOLVED: bjwmills/COPSE states Apache-2.0, sjdaines/COPSE states nothing. · role calibration reference
Scientific
established
Peer-reviewed lineage: Bergman et al. (2004) and Lenton et al. (2018) COPSE reloaded, American Journal of Science.
Reproducibility
not reproducible here
MATLAB import statement and Java-backed YAML library unsupported by Octave; requires MATLAB.
Integration
dossier only
Dossier from published evidence only. No executed comparison. COPSE ships its own tolerance-based reproduction harness, so it becomes a strong reproduction candidate once a MATLAB environment exists.
Validation
declared only
Published validation and an upstream test harness exist; neither has been executed inside SHFT.
Production
none
Never executes inside the production Earth Engine.
Currently modeled
- Atmospheric CO₂
- Global mean surface temperature anomaly
- Whole-ocean heat content anomaly
- Upper-ocean global mean pH
- Land ice volume
- Global mean sea level anomaly relative to run start
- Global carbonate + silicate weathering flux
Intentionally not modeled
- Regional or spatial prediction
- Ocean circulation and hydrology
- Vegetation and ecosystems
- Tectonic geography
- Human population and urban land
- Organized systems
Current limitations
Unsupported quantities remain unknown, not estimated. SHFT does not fill gaps with plausible-looking values or downgrade missing data into a weaker confidence label.
The current engine resolves global-scale Earth-system behaviour. It does not resolve regional, ecological, or human-system outcomes. Results marked not_modelled are outside the validated scope of the active production backbone.
Primary references
Scientific foundations
SHFT Observatory Constitution v1.0
The permanent scientific-integrity rules governing computation and display.
SURFER v3.0: a reduced model of the global carbon cycle and climate
Victor Couplet, Marina Martinez Montero, Michel Crucifix
Paper DOI 10.5194/gmd-18-3081-2025Pinned SURFER v3.0 code archive
Archive DOI 10.5281/zenodo.14717610Promotion evidence
9 passed comparisons across historical, centennial, long tail. CMIP6, Global Carbon Budget, and LTMIP/Archer data are evaluation evidence, not components of SHFT.