Lifecycle boundaries
====================

.. note::
   Engine source: ``src/engine/lifecycle-boundaries.ts`` (DL-162, programme
   *Unlock Full Per-Carrier Emission Scope Controls*). Every chart, selector
   and label consumes this one module; the UI never re-derives boundary
   arithmetic. Validation: ``tests/lifecycle-boundaries.spec.ts`` (21 tests)
   inside the full regression suite.

Definitions
-----------

Every aviation energy carrier can be evaluated at any of four boundaries:

Well-to-Wake (WTW)
   The full chain — extraction/feedstock, processing, logistics and
   combustion. WTW values come from the engine's existing carbon-intensity
   sources unchanged.

Tank-to-Wake (TTW)
   **Fossil combustion CO₂ only.** Biogenic (HEFA/FT/ATJ, biomethane) and
   atmospheric-carbon (PtL e-SAF, e-methane) combustion counts zero — the
   CORSIA/EU convention that the carbon was drawn down upstream. Hydrogen
   and electricity emit no carbon in the wake. LCAF is fossil crude-derived:
   its TTW equals Jet-A combustion (≈ 73.15 gCO₂e/MJ), so its WTT is
   **negative** — the pathway's claim is lower-carbon extraction.

Well-to-Tank (WTT)
   Upstream only, defined as ``WTW − TTW`` so the identity
   ``WTW = WTT + TTW`` holds by construction for every carrier (test-locked
   at 10⁻⁹).

Custom
   A per-stage boundary: the sum of exactly the stages the user includes
   (see below). With the default stage set (all CO₂ stages) Custom equals
   WTW; combustion-only equals TTW; all-CO₂-stages-minus-combustion equals
   WTT — all three equivalences are test-locked.

Carriers
--------

Thirteen carriers, each with an independent selector: Conventional Jet-A,
HEFA SAF, FT SAF, ATJ SAF, PtL e-SAF, LCAF (liquid fuels); LH₂ aircraft,
GH₂ feedstock (hydrogen); fossil LNG, biomethane, synthetic methane
(methane); grid electricity, dedicated renewable electricity.

Worked examples (2035, engine defaults): Jet-A WTW 89 / TTW ≈ 73.15;
LH₂ WTW > 0 (production + liquefaction + boil-off + distribution) / TTW 0;
biomethane TTW 0; fossil LNG TTW ≈ 54.87 (CH₄ combustion CO₂). A carbon
intensity is **never displayed without its boundary and functional unit**
(gCO₂e/MJ) — UI rule, enforced in the settings cards and the
lifecycle-comparison chart.

Per-stage Custom boundary
-------------------------

``carrierStagesAt()`` decomposes each carrier into the engine's **own
published terms** — the aggregate functions delegate to term-level exports
(``deliveredLH2CITermsAtYear``, ``ptlStoichCITerms``, ``ciCh4PtgTermsAt``,
``ch4LossTermsAt``), so stage sums equal WTW *by construction*, not by
re-derivation. Canonical stages: extraction, feedstock, transport/leakage,
processing/production, liquefaction, compression, storage/boil-off, airport
distribution, aircraft transfer, combustion, non-CO₂ effects.

Two disclosure rules govern the decomposition:

* **Grouped aggregates.** Where a source publishes only an aggregate — the
  CORSIA static SAF pathway CIs (feedstock + processing + logistics), the
  [F]-graded LH₂ distribution+airport bracket (which includes aircraft
  transfer), the CORSIA fossil-LNG constant — the whole aggregate sits in
  one stage and carries a ``grouped`` provenance flag. Nothing is invented
  apart; toggling a sibling stage of a grouped term is a no-op by design.
* **Non-CO₂ is not an additive CO₂ term.** Including the non-CO₂ stage
  applies the engine's ERF-style multiplier (``nonco2.ts``) as an add-on:
  ``(central − 1) × WTW`` for the four fuel families the engine defines.
  First-order screening only — the §11 finding stands: the envelopes
  overlap and fuel rankings can compress or invert, so non-CO₂ must never
  be collapsed to a single number.

Presets
-------

CASCADE Compatibility (default)
   Reproduces the historical behaviour bit-identically: the conventional
   fuel follows the user-selectable global scope; every alternative fuel is
   **locked** to its CASCADE-methodology WTW value. This is the parity mode
   for CASCADE-derived scenarios.

Full Lifecycle / Tank-to-Wake / Custom
   All-WTW (editable) / all-TTW (propulsion comparison) / unrestricted.

Regulatory presets (scope-selection aids)
   Five presets load the per-carrier boundary implied by each instrument's
   stated accounting basis: **ICAO LTAG** (WTW — life-cycle fuel basis),
   **CORSIA** (WTW — life-cycle values against the 89 gCO₂e/MJ fossil
   baseline), **EU ETS** (TTW — combustion accounting; compliant
   biofuel/RFNBO combustion zero-rated, matching the engine's TTW
   convention), **FuelEU** (WTW), **ReFuelEU Aviation** (WTW — RED
   life-cycle methodology). They are **not compliance calculators**: no
   baselines, eligibility rules, ILUC factors or credit mechanics are
   modelled, and the UI displays that disclaimer whenever one is active.

Mixed boundaries
----------------

When carriers sit at different boundaries the UI shows a *Mixed lifecycle
boundaries* warning naming the boundaries in play, with one-click
Normalize-to-WTW / Normalize-to-TTW actions.

Serialisation and API
---------------------

Flat ``scope_<carrier>`` keys plus ``scope_preset`` travel through the
standard URL codec, so legacy URLs (no scope keys ⇒ CASCADE behaviour),
CASCADE URLs (global ``scope`` translated through the CASCADE preset) and
new per-carrier URLs coexist without ambiguity. The Custom stage set
serialises as compact two-letter codes in ``custom_stages`` (full stage
names also parse). ``carrierScopesJSON()`` provides the explicit
carrier-field API object; CSV exports carry ``scope_preset``, the full
carrier-scope object, ``custom_stages``, engine/basis, model, functional
units and the export date.

Boundary of validity
--------------------

Per-carrier boundaries drive **CI-space** views, comparisons and labels.
The wedge/net accounting keeps the engine basis plus the global display
scope (the v10 convention), so CASCADE parity is preserved bit-identically;
per-carrier boundaries inside the NET accounting are a registered follow-up
(V14), not a shipped claim.