Jira progress: loading…

GHG-SA

GHG Scenario Align

1. Identity

<Identity meid="MEID_..." />

Depends on module:

---

2. Contract References (ZAR)

2.1 Input Schema

ZAR Address: schema.compute.ghg.scenario.inputs.v1_0_0

Required conceptual fields:

• emissions: company emissions time-series (absolute)
• scenario_curve_ref: reference to a registered scenario pathway
• alignment_metric: DISTANCE | RATIO | AREA (default DISTANCE)
• alignment: BY_YEAR (only supported mode)

Optional:

• scope: TOTAL | SCOPE1+2 | SCOPE1+2+3
• start_year
• end_year

---

2.2 Options Schema

ZAR Address: schema.compute.ghg.scenario.options.v1_0_0

Common options:

• normalization: NONE | BASE_YEAR
• temperature_mapping_ref: optional mapping to temperature outcomes
• exceedance_policy: ALLOW | CLIP
• rounding: optional digits

---

2.3 Output Schema

ZAR Address: schema.compute.ghg.scenario.output.v1_0_0

Outputs include:

• alignment_score
• distance_series
• temperature_score (optional)
• metadata (scenario used, horizon, normalization)

---

3. Accepted Input Shapes

A. Company trajectory vs scenario

{
  "emissions": [[2025, 12500], [2026, 12000], [2027, 11000]],
  "scenario_curve_ref": "IPCC_SSP1_1.9",
  "alignment_metric": "DISTANCE"
}

B. Explicit horizon

{
  "emissions": [[2025, 12500], [2026, 12000], [2027, 11000], [2028, 10500]],
  "scenario_curve_ref": "IEA_NZE_2050",
  "start_year": 2025,
  "end_year": 2030
}

All inputs MUST be normalized internally to:

Map<year, emissions_value>

---

4. Scenario Resolution (Normative)

Let:

• $E(t)$ be company emissions in year $t$
• $S(t)$ be scenario-aligned emissions for the same year

The scenario curve is resolved via scenario_curve_ref to a registered ZAR artifact with:

• version
• provenance
• temperature intent

---

4.1. Sector-Priority Policy (Normative)

4.1.1 Policy Artifact

Scenario resolution MUST be governed by a Sector-Priority Policy artifact.

This artifact defines:

• sector_key
• preferred_order (provider precedence)
• region_ladder
• temp_targets
• metric_default
• policy_profile
• quality_rank

The policy artifact MUST be:

• Versioned
• Hashable
• Audit-referenceable
• Stored in SSOT (e.g., scenario_align.policy.vX.json)

---

4.1.2 Provider Order

For each sector_key, the engine MUST attempt providers in deterministic order:

Example (autos):

{
  "sector_key": "autos",
  "preferred_order": ["IEA","SBTi","NGFS","IPCC"]
}

Rules:

1. Providers MUST be attempted in declared order.
2. Providers MUST NOT be reordered dynamically.
3. Policy changes MUST increment artifact version.

---

4.1.3 Metric Defaults

Each sector declares a default metric type:

• absolute
• intensity

If the input request omits metric, the engine MUST use the sector default.

Example:

"metric_default": "intensity"

This ensures consistent alignment semantics across sectors.

---

4.2. License-Gated Provider Resolution (Normative)

Scenario provider selection MUST be license-validated.

The engine MUST NOT directly inspect flags. It MUST call the License Module.

---

4.2.1 Resolution Algorithm

Given:

• sectorKey
• region
• tempTarget

The engine MUST:

1. Load provider order from Sector-Priority Policy.
2. For each provider:

• Call License Module:

LicenseService.check(clientId, provider, purpose="analytics")

• If granted → attempt scenario resolution.
• If denied → skip provider.

3. If no provider is eligible:

• Fallback to public baseline (IPCC), if not already attempted.

4. If still unresolved:

• Raise SCENARIO_PROVIDER_UNAVAILABLE.

---

4.2.2 Mandatory Audit Metadata

The engine MUST record:

metadata.selection = {
  "policy_version": "v1.0.0",
  "providers_tried": ["IEA","SBTi","NGFS"],
  "provider_selected": "NGFS",
  "license_status": {...},
  "region_used": "EU27",
  "metric_used": "intensity"
}

This metadata is REQUIRED for:

• CSRD defensibility
• External assurance
• Federation reproducibility

---

4.3. Region Ladder Resolution (Normative)

Scenario curves may exist at different geographic resolutions.

The engine MUST apply a deterministic Region Ladder defined by policy or NACE override.

Default ladder:

COUNTRY → EU27 → OECD → GLOBAL

Rules:

1. Attempt scenario at requested country.
2. If unavailable, move to next ladder level.
3. First successful match MUST be selected.
4. Ladder used MUST be recorded in metadata.

If a country_adjustment_factor exists:

• Adjustment MUST be applied AFTER region fallback.
• Adjustment MUST be recorded in metadata.

---

4.4. Variable Resolution & Canonical Keys (Normative)

All scenario curves MUST resolve to:

canonical_variable_key

Examples:

• gco2_per_kwh
• tco2_per_t_steel
• gco2_per_km_passenger
• co2_total_gt_per_year

Scenario artifacts MUST contain:

{
  "canonical_variable_key": "gco2_per_kwh",
  "unit": "gCO2/kWh",
  "series": [[2025,350], [2030,200], ...]
}

If provider uses non-canonical variable names:

• Provider adapter MUST map to canonical key.
• Mapping MUST be versioned in EngineAliasMap.

---

4.4.1 Metric Harmonization

If company metric type ≠ scenario metric type:

• Conversion MUST occur prior to alignment.

Examples:

• Absolute company vs intensity scenario → normalize
• Intensity company vs absolute scenario → derive using activity

Derivations MUST be:

• Deterministic
• Logged
• Reproducible

---

4.5. Ensemble Construction Rules (IPCC)

For IPCC scenarios:

1. Identify all IAM rows for target scenario class:

• C1 (1.5°C)
• C3 (2°C)

2. Compute:

• Median
• Optional p33 / p67

3. Preserve:

• Model list
• Category code
• Temperature exceedance probabilities

Ensemble output MUST record:

{
  "ensemble": "median",
  "models_used": ["REMIND","GCAM","WITCH"],
  "category_code": "C1"
}

Row-level traceability MUST be preserved.

---

4.6. Scope Handling (Normative)

Alignment MAY be computed for:

• TOTAL
• SCOPE1+2
• SCOPE1+2+3

If scope not provided:

• Engine MUST default to sector-appropriate scope defined in NACE table.

Example:

"scope_support": ["S1","S2","S3"]

Scope used MUST be recorded in metadata.

---

4.7. Scenario Artifact Structure (Normative)

A registered scenario artifact MUST contain:

• provider
• scenario_id
• temperature_intent
• canonical_variable_key
• metric_type
• unit
• region
• version
• provenance_hash

Example:

{
  "provider": "NGFS",
  "scenario_id": "NetZero2050",
  "temperature_intent": "1p5C",
  "metric_type": "intensity",
  "canonical_variable_key": "gco2_per_kwh",
  "region": "EU27",
  "version": "2025.1",
  "provenance_hash": "sha256:..."
}

Alignment MUST reference this artifact deterministically.

---

4.8. Separation of Concerns (Normative)

The engine MUST maintain strict separation between:

1. Scenario Resolution
2. Provider Selection
3. Variable Harmonization
4. Alignment Mathematics

Alignment mathematics MUST NOT perform provider selection logic.

---

4.9. Error Model (Extended)

Add new error codes:

• SCENARIO_PROVIDER_UNAVAILABLE
• LICENSE_DENIED
• REGION_FALLBACK_FAILED
• VARIABLE_RESOLUTION_FAILED
• METRIC_TYPE_MISMATCH

Errors MUST include:

• provider attempted
• policy version
• region ladder state
• canonical_variable_key

---

5. Alignment Metrics (Normative)

5.1 Distance-based alignment (default)

For each year $t$:

$d(t) = E(t) - S(t)$

Positive values indicate emissions above the scenario pathway.

Aggregate distance over horizon $[t_0, t_n]$:

$D = \frac{1}{n} \sum_{t=t_0}^{t_n} d(t)$

---

5.2 Ratio-based alignment

$r(t) = \frac{E(t)}{\max(S(t), \epsilon)}$

Aggregate ratio:

$R = \frac{1}{n} \sum_{t=t_0}^{t_n} r(t)$

---

5.3 Area-based alignment (cumulative exceedance)

$A = \sum_{t=t_0}^{t_n} \max(0, E(t) - S(t))$

This represents cumulative overshoot relative to the pathway.

---

6. Normalization Rules

If normalization = BASE_YEAR:

• Both $E(t)$ and $S(t)$ are normalized to 1.0 at the base year
• Alignment metrics are computed on normalized curves

Metadata MUST record:

• base year used
• normalization applied

---

7. Temperature Mapping (Optional)

If temperature_mapping_ref is provided:

• The alignment score is mapped to an implied temperature outcome
• Mapping MUST be deterministic and versioned

Example:

• Alignment score → 1.6°C
• Alignment score → “Well below 2°C”

---

8. Validation & Error Model

Invariants

• Emissions and scenario curves must overlap in time
• Scenario reference must resolve successfully
• Emissions values must be finite

Error codes (suggested)

• SCENARIO_REF_NOT_FOUND
• SCENARIO_NO_OVERLAP
• SCENARIO_ALIGNMENT_INVALID
• SCENARIO_NON_FINITE_VALUE

Errors MUST include:

• engine cmi_short_code
• year causing failure

---

9. Dependencies

MEID_SCEN_GHG_ALIGN depends on:

• MEID_CALC_GHG_AGGR
• MEID_CALC_CARBON_BUDGET
• scenario datasets (IPCC, IEA, SBTi)
• schema resolver (ZAR)

Declared via ZAR dependencies.

---

10. Federation & Audit Requirements

To reproduce scenario alignment externally, the export MUST include:

• Engine identity (cmi or zar_code)
• Engine build proof (execution_ref + build_hash)
• Input/options/output schemas
• Emissions trajectory used
• Scenario curve artifact (or resolvable reference)
• Alignment metric and normalization settings

Provenance chain MUST show:

… → MEID_CALC_GHG_AGGR
→ MEID_CALC_CARBON_BUDGET
→ MEID_SCEN_GHG_ALIGN → …

with cmi_short_code recorded in USO tail arrays.

---

11. Performance Notes

• Complexity: $O(n)$ over years
• Memory: $O(n)$
• Suitable for long-horizon scenario analysis

---

12. Methods Served (v1)

• GHG.scenario_align
• GHG.temperature_align

---