Introduction
============

This documentation describes the HyFlux v10 calculation engine as it is
**implemented** in ``src/engine/`` — every formula shown is the formula the
code evaluates, and every page names its source function, its test evidence,
its implementation status against the CASCADE coverage matrix, and its known
deviations. Where a formulation reproduces a published CASCADE equation, the
CASCADE equation label is cited (cf. :cite:`cascadedocs`); the surrounding
prose is HyFlux's own.

Nomenclature
------------

Units
~~~~~

* **GtCO₂ / MtCO₂** — giga-/mega-tonnes of carbon dioxide (or CO₂-equivalent,
  where stated). The engine's headline emissions are in GtCO₂; the removal
  module works in MtCO₂ and converts at the wedge boundary (÷1000), a unit
  boundary covered explicitly by the test suite.
* **TTW / WTW** — tank-to-wake (combustion only) vs well-to-wake (full
  life-cycle) emissions. The engine is canonical at **WTW**; the UI display
  scope (``scope: 'wtw' | 'ttw' | 'nonco2'``) is a presentation multiplier
  only. Reference anchors: Jet-A1 WTW 89 gCO₂e/MJ, TTW 74, WtT 15
  (``constants.ts``).
* **EJ / MJ** — exajoules and megajoules of energy (LHV basis throughout).
  The energy-demand roll-up works in EJ; per-flight route energy in MJ.
  Conversion identity: 1 GtCO₂ at 89 gCO₂e/MJ ⇔ 1000/89 ≈ 11.236 EJ
  (``energyDemand.ts:GT_CO2_TO_EJ``).

Route-level vs fleet-level symbols
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CASCADE's introduction uses lower-case symbols for route-level quantities
(:math:`d`, :math:`e`, :math:`n`, :math:`x`) and upper-case for fleet-level
aggregates (:math:`E`, :math:`G`). HyFlux keeps the same convention where it
is meaningful: the route-level Future Aircraft module (``futureAircraft.ts``)
uses lower-case per-route quantities (:math:`e^*(d)`, :math:`n_{in}(rt,t)`,
:math:`x(ac_{fut},rt,t)`), aggregated to fleet totals (:math:`E(t)`,
:math:`G`). The aggregate engine (``cascade.ts``) has no route dimension, so
its quantities are fleet-level by construction — an honest limitation
recorded on each affected page (cf. CASCADE *Introduction*, nomenclature).

Two-track baselines
-------------------

HyFlux preserves a **frozen legacy baseline** alongside **corrected
defaults**, so that historical parity evidence remains reproducible while
defects are fixed in the default path. Three scenario switches control this
(decision log DL-006, DL-012, DL-022, DL-024):

* ``traffic_model: 'cascade_series'`` (default) compounds the 2019 baseline
  exactly like the time-series sweep; ``'legacy_anchor'`` reproduces the
  frozen v3.3 scalar anchor (2.82 Gt at defaults) pinned by the parity spec.
* ``offset_mode: 'constrained'`` (default) bounds the offsets wedge by
  physical removal capacity applied to **residual** emissions;
  ``'percent'`` reproduces the legacy unconstrained gross-percentage
  behaviour.
* ``ptl_model: 'cascade_stoich'`` (default) evaluates the stoichiometric PtL
  carbon-intensity formulation; ``'legacy_factor'`` keeps the pre-DL-024
  single-factor curve.

Rule: any change that alters a default result is explained number-by-number
in a phase report; the frozen track is never silently rebased
(``Phase1-Regression-Report.md`` §1, ``Completion-Report-2026-07-18.md`` §1).

Synthetic-data disclaimer
-------------------------

All traffic and aircraft reference data in HyFlux are **synthetic,
first-principles substitutes** chosen to be plausible: the 24-route traffic
dataset (:doc:`trafficDataset`), the 16 range-energy reference tables
(:doc:`aircraft`), and the Cirium-benchmark corridor panel
(``src/data/cirium-mock.ts``) contain no measured, licensed or proprietary
values. Data is deterministic (hard-coded tables, pure functions, no RNG)
and injectable — every consumer accepts an override — so licensed data can
be dropped in later without touching the model. No exact value-parity claim
against Boeing's datasets is made or implied anywhere in this documentation.