Skip to main content
Jira progress: loading…

GHG-SCC

GHG Share / Composition Calculator Micro Engine

1. Identity​

Loading identity…

Depends on module:

Purpose
Computes GHG composition shares (ratios or percentages) in a GHG-governed way, enforcing canonical scope/category identifiers and disclosure-grade metadata.

Typical uses include:

  • Scope 3 category share of total Scope 3
  • Scope shares of total GHG (S1/S2/S3 composition)
  • Optional: category share of total GHG (if configured)

This engine is a domain adapter over the generic MEID_CALC_SHARE primitive.

2. Contract References (ZAR)​

2.1. Input Schema​

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

Required conceptual fields:

  • numerator_ref: identifies numerator source (e.g. cat6, scope3, scope2)
  • denominator_ref: identifies denominator source (e.g. scope3_total, ghg_total)
  • values: the numeric series for numerator and denominator, or resolvable refs (see below)
  • share_mode: RATIO | PERCENT (default PERCENT)
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Two supported input styles:

Style A (direct values):

  • numerator: scalar or time-series
  • denominator: scalar or time-series

Style B (reference values):

  • numerator_signal_ref and denominator_signal_ref (CSI/USO references)
  • resolved upstream by orchestration, then provided here as values at runtime

2.2. Options Schema​

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

Common options:

  • denominator_floor (default: 1e-9)
  • cap_range: ENFORCE | ALLOW (default ENFORCE)
  • missing_policy: ERROR | SKIP
  • category_normalization: STRICT | LENIENT (default STRICT)
  • rounding: optional digits

2.3. Output Schema​

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

Outputs include:

  • share_series
  • share_unit (ratio or percent)
  • metadata (normalized keys, caps applied, denominator floors, alignment)

3. Accepted Input Shapes​

A. Scope 3 category share of Scope 3 total

{
  "numerator_ref": "cat6",
  "denominator_ref": "scope3_total",
  "numerator": [[2025, 150], [2026, 140]],
  "denominator": [[2025, 3000], [2026, 2800]],
  "share_mode": "PERCENT",
  "alignment": "BY_YEAR"
}

B. Scope composition (Scope 2 share of total GHG)

{
  "numerator_ref": "scope2",
  "denominator_ref": "ghg_total",
  "numerator": [[2025, 800]],
  "denominator": [[2025, 12500]],
  "share_mode": "RATIO"
}

4. Compute Semantics (Normative)​

For each aligned period tt:

4.1. Base ratio​

shareraw(t)=N(t)max⁡(∣D(t)∣,ϵ)share_{raw}(t) = \frac{N(t)}{\max(|D(t)|, \epsilon)}

Where:

  • N(t)N(t) is numerator value,
  • D(t)D(t) is denominator value,
  • ϵ\epsilon is denominator_floor.

4.2. Output scaling​

If share_mode = RATIO, output: share(t)=shareraw(t)share(t) = share_{raw}(t)

If share_mode = PERCENT, output: share(t)=100⋅shareraw(t)share(t) = 100 \cdot share_{raw}(t)

4.3. Range enforcement​

If cap_range = ENFORCE:

  • For ratio mode: clamp to [0,1][0, 1]
  • For percent mode: clamp to [0,100][0, 100]

All clamp events MUST be recorded in metadata.capped_values_count.

5. GHG-Specific Normalization Rules (Normative)​

5.1. Allowed numerator_ref / denominator_ref​

This engine MUST enforce canonical allowed refs.

Allowed numerator_ref

  • scope1, scope2, scope3
  • cat1 … cat15

Allowed denominator_ref

  • ghg_total
  • scope3_total
  • scope1+2
  • scope1+2+3 (alias of ghg_total if configured)

5.2. Strict category normalization​

If category_normalization = STRICT:

  • Cat6, CAT6, cat06 MUST normalize to cat6
  • non-mappable category keys MUST error

If LENIENT:

  • non-mappable keys MAY be dropped with metadata annotation

Metadata MUST include:

  • normalized_numerator_ref
  • normalized_denominator_ref

6. Alignment Rules​

BY_YEAR​

  • Numerator and denominator MUST share the same period keys unless missing_policy = SKIP.

BY_INDEX​

  • Ordered alignment; length mismatch handled per missing_policy.

Metadata MUST include:

  • aligned_periods
  • missing_in_numerator
  • missing_in_denominator
  • denominator_floor_applied_count

7. Validation & Error Model​

Invariants​

  • Values must be finite
  • denominator_floor > 0
  • Denominator must not be negative (default) unless explicitly allowed by schema
  • Refs must be valid canonical forms

Error codes (suggested)​

  • GHG_SHARE_INVALID_REF
  • GHG_SHARE_ALIGNMENT_MISMATCH
  • GHG_SHARE_DENOMINATOR_ZERO_GUARDED (informational if floor applied)
  • GHG_SHARE_VALUE_OUT_OF_RANGE
  • GHG_SHARE_NON_FINITE_VALUE

Errors MUST include:

  • engine cmi_short_code
  • offending ref and period

8. Dependencies​

MEID_CALC_GHG_SHARE depends on:

  • MEID_CALC_SHARE (primitive)
  • schema resolver (ZAR)
  • canonical Scope 3 category reference list (Cat1–Cat15)

Declared via ZAR dependencies.

9. Federation & Audit Requirements​

To reproduce GHG share outputs externally, the export MUST include:

  • Engine identity (cmi or zar_code)
  • Engine build proof (execution_ref + build_hash)
  • Input/options/output schemas
  • Numerator and denominator series used
  • Normalization settings and caps

Provenance chain MUST show:

… → MEID_CALC_GHG_SHARE → …

with cmi_short_code recorded in USO tail arrays.

10. Performance Notes​

  • Complexity: O(n)O(n) over periods
  • Memory: O(n)O(n)
  • Suitable for batch reporting and KPI analytics

11. Methods Served (v1)​

  • GHG.scope3.cat.share (primary)
  • Optional (if method registry includes):
    • GHG.scope3.share
    • GHG.scope2.share
    • GHG.scope1.share


GitHub RepoRequest for Change (RFC)