Skip to main content
Jira progress: loading…

WST-SHR

Waste Share / Composition Calculator

1. Identity​

Loading identity…

Depends on module:

Purpose
Computes waste composition shares (ratios or percentages) with waste-governed semantics, enforcing canonical hazard classes and (optionally) category identifiers, valid denominator choices, and disclosure-ready metadata aligned with ESRS E5.

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

Typical usage

  • Hazardous share of total waste (%)
  • Non-hazardous share of total waste (%)
  • Category share of total waste (optional, if categories are tracked)

2. Contract References (ZAR)​

2.1 Input Schema​

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

Required conceptual fields:

  • numerator_ref: identifies numerator basis (hazard class or category)
  • denominator_ref: identifies denominator basis
  • 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)
  • values resolved upstream by orchestration and provided at runtime

2.2 Options Schema​

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

Common options:

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

2.3 Output Schema​

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

Outputs include:

  • share_series
  • share_unit (ratio or percent)
  • metadata (normalized refs, floors, caps, alignment)

3. Accepted Input Shapes​

A. Hazardous share of total waste

{
  "numerator_ref": "hazard:hazardous",
  "denominator_ref": "waste_total",
  "numerator": [[2025, 85], [2026, 82]],
  "denominator": [[2025, 1285], [2026, 1250]],
  "share_mode": "PERCENT",
  "alignment": "BY_YEAR"
}

B. Non-hazardous share (ratio)

{
  "numerator_ref": "hazard:non_hazardous",
  "denominator_ref": "waste_total",
  "numerator": [[2025, 1200]],
  "denominator": [[2025, 1285]],
  "share_mode": "RATIO"
}

C. Category share (optional)

{
  "numerator_ref": "category:17-01-07",
  "denominator_ref": "waste_total",
  "numerator": [[2025, 500]],
  "denominator": [[2025, 1285]],
  "share_mode": "PERCENT"
}

All supported shapes MUST be normalized internally to:

Map<period, numerator_value> + Map<period, denominator_value>

4. Waste-Specific Normalization Rules (Normative)​

4.1. Canonical numerator_ref values (v1)​

Hazard shares

  • hazard:hazardous
  • hazard:non_hazardous

Category shares

  • category:
<ewc_code> or <ewc_id> where <ewc_...> is an EWC-like code or internal canonical category id

4.2. Canonical denominator_ref values (v1)​

  • waste_total
  • waste_hazardous (allowed only if we explicitly want “share of hazardous by category” later)
  • waste_non_hazardous (same)

4.3. Pairing rules (governed)​

The engine MUST enforce valid combinations:

  • hazard:* MAY only be divided by waste_total
  • category:* MAY be divided by:
  • waste_total, or
  • waste_hazardous / waste_non_hazardous only if enabled by schema (v1 default: disabled)

Invalid pairings MUST error (v1 strict).

5. Compute Semantics (Normative)​

For each aligned period tt:

Let N(t)N(t) be numerator and D(t)D(t) be denominator.

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

Where ϵ\epsilon is denominator_floor.

If share_mode = RATIO: share(t)=shareraw(t)share(t) = share_{\mathrm{raw}}(t)

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

If cap_range = ENFORCE:

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

Clamp events MUST be recorded in:

  • metadata.capped_values_count

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
  • Refs must be valid canonical forms
  • Governed pairing rules must pass

Error codes (suggested)

  • WASTE_SHARE_INVALID_REF
  • WASTE_SHARE_INVALID_PAIRING
  • WASTE_SHARE_ALIGNMENT_MISMATCH
  • WASTE_SHARE_DENOMINATOR_ZERO_GUARDED
  • WASTE_SHARE_NON_FINITE_VALUE

Errors MUST include:

  • engine cmi_short_code
  • offending ref and period

8. Dependencies​

MEID_CALC_WASTE_SHARE depends on:

  • MEID_CALC_SHARE (primitive)
  • schema resolver (ZAR)
  • canonical hazard classes
  • optional waste category taxonomy (if category:* is used)

Declared via ZAR dependencies.

9. Federation & Audit Requirements​

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

  • engine identity (cmi or zar_code)
  • engine build proof (execution_ref + build_hash)
  • input/options/output schemas used
  • numerator and denominator series used (or resolvable signal refs)
  • normalization settings and caps

Provenance chain MUST show:

… → MEID_CALC_WASTE_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)​

  • Waste.hazardous.share
  • Waste.non_hazardous.share
  • Waste.category.share (optional)


GitHub RepoRequest for Change (RFC)