Jira progress: loading…

WST-DIV

Waste Diversion Rate Calculator

1. Identity

Loading identity…

Depends on module:

Purpose
Computes waste diversion rate (share of generated waste diverted from disposal through recycling and/or recovery), producing disclosure-ready KPIs aligned with ESRS E5 reporting patterns.

This engine governs:

• what counts as “diverted”
• how “unknown treatment” is handled
• caps and completeness metadata

It does not reclassify waste; it consumes treatment-tagged flows.

Typical usage

• Diversion rate (%)
• Recycled / recovered / disposed totals (tonnes)
• Data quality flags (unknown treatment share)

---

2. Contract References (ZAR)

2.1 Input Schema

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

Required conceptual fields:

• generated_total: scalar or time-series (total waste generated)
• treatment_flows: list or map of treatment-tagged waste quantities
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Treatment flow categories (v1 canonical):

• recycled
• recovered (energy recovery / other recovery)
• disposed (landfill, incineration without recovery, etc.)
• unknown

Each treatment flow conceptually includes:

• period
• value
• unit
• treatment: one of the canonical categories above
• optional:
  • hazard_class (HAZ/NON_HAZ) for future splits
  • site_id
  • waste_category (EWC/internal)
  • evidence_ref (ticket/manifest id)

Inputs are commonly produced upstream from waste contractor reports and manifests, and may require normalization/tagging before reaching this engine.

---

2.2 Options Schema

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

Common options:

• unit_output: default tonne
• diversion_definition: RECYCLED_ONLY | RECYCLED_PLUS_RECOVERED (default RECYCLED_PLUS_RECOVERED)
• unknown_treatment_policy: ERROR | EXCLUDE_FROM_NUMERATOR | TREAT_AS_DISPOSED | ALLOW_WITH_FLAG (default EXCLUDE_FROM_NUMERATOR)
• mass_balance_policy: CAP_AT_GENERATED | ERROR_IF_EXCEEDS (default CAP_AT_GENERATED)
• denominator_floor: default 1e-9
• rounding: optional digits

---

2.3 Output Schema

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

Outputs include:

• $W_{\mathrm{recycled}}(t)$
• $W_{\mathrm{recovered}}(t)$
• $W_{\mathrm{disposed}}(t)$
• $W_{\mathrm{unknown}}(t)$
• diversion_rate (ratio or percent per schema)
• metadata (unknown handling, caps applied, mass-balance checks)

---

3. Accepted Input Shapes

A. Treatment flow list (preferred)

{
  "generated_total": [[2025, 1285], [2026, 1250]],
  "treatment_flows": [
    { "treatment": "recycled",  "period": 2025, "value": 600, "unit": "tonne" },
    { "treatment": "recovered", "period": 2025, "value": 150, "unit": "tonne" },
    { "treatment": "disposed",  "period": 2025, "value": 400, "unit": "tonne" },
    { "treatment": "unknown",   "period": 2025, "value": 135, "unit": "tonne" }
  ],
  "alignment": "BY_YEAR"
}

B. Treatment map (compact)

{
  "generated_total": [[2025, 1285]],
  "treatment_flows_map": {
    "recycled": [[2025, 600]],
    "recovered": [[2025, 150]],
    "disposed": [[2025, 400]],
    "unknown": [[2025, 135]]
  }
}

All supported shapes MUST be normalized internally to:

Map<period, { generated, recycled, recovered, disposed, unknown }>

---

4. Diversion Governance Rules (Normative)

4.1. What counts as “diverted”

If diversion_definition = RECYCLED_ONLY:

• diverted = recycled only

If RECYCLED_PLUS_RECOVERED (default):

• diverted = recycled + recovered

4.2. Unknown treatment handling

If unknown_treatment_policy is:

• ERROR: fail if any unknown exists
• EXCLUDE_FROM_NUMERATOR (default): exclude unknown from diverted, but include in mass balance checks
• TREAT_AS_DISPOSED: add unknown to disposed for conservative reporting
• ALLOW_WITH_FLAG: allow unknown but flag in metadata

---

5. Compute Semantics (Normative)

For each aligned period $t$:

Let:

• $G(t)$ = generated total
• $R(t)$ = recycled
• $Q(t)$ = recovered
• $D(t)$ = disposed
• $U(t)$ = unknown

All values are assumed normalized to unit_output.

5.1. Diverted amount

If RECYCLED_ONLY:

$V_{\mathrm{diverted}}(t) = R(t)$

If RECYCLED_PLUS_RECOVERED:

$V_{\mathrm{diverted}}(t) = R(t) + Q(t)$

5.2. Apply unknown policy (if conservative)

If unknown_treatment_policy = TREAT_AS_DISPOSED:

$D(t) \leftarrow D(t) + U(t), \quad U(t) \leftarrow 0$

If EXCLUDE_FROM_NUMERATOR, $U(t)$ remains separate and does not affect $V_{\mathrm{diverted}}(t)$.

5.3. Mass-balance check

Total treated:

$T(t) = R(t) + Q(t) + D(t) + U(t)$

If $T(t) > G(t)$:

• if mass_balance_policy = ERROR_IF_EXCEEDS: fail
• if CAP_AT_GENERATED (default): scale down treated totals proportionally or cap diversion numerator only

v1 recommended cap strategy (simple + safe): $V_{\mathrm{diverted}}(t) \leftarrow \min\left(V_{\mathrm{diverted}}(t), G(t)\right)$

and record the cap event.

5.4. Diversion rate

Let $\epsilon$ be denominator_floor.

If output is ratio:

$diversion_rate(t) = \frac{V_{\mathrm{diverted}}(t)}{\max(|G(t)|,\epsilon)}$

If output is percent:

$diversion_rate(t) = 100 \cdot \frac{V_{\mathrm{diverted}}(t)}{\max(|G(t)|,\epsilon)}$

---

6. Validation & Error Model

Invariants

• Values must be finite
• Units convertible to unit_output
• Treatments must be canonical categories
• Generated total must be provided for each period
• Diversion rate MUST be capped to [0,1] or [0,100] unless schema allows otherwise

Error codes (suggested)

• WASTE_DIV_MISSING_GENERATED_TOTAL
• WASTE_DIV_INVALID_TREATMENT_CATEGORY
• WASTE_DIV_UNIT_CONVERSION_FAILED
• WASTE_DIV_UNKNOWN_TREATMENT_ERROR
• WASTE_DIV_MASS_BALANCE_EXCEEDED
• WASTE_DIV_NON_FINITE_VALUE

Errors MUST include:

• engine cmi_short_code
• period context and (if applicable) affected treatment category

---

7. Dependencies

MEID_CALC_WASTE_DIV depends on:

• schema resolver (ZAR)
• unit conversion capability (delegated)
• canonical treatment category list (recycled/recovered/disposed/unknown)

Declared via ZAR dependencies.

---

8. Federation & Audit Requirements

To reproduce diversion KPIs externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• generated total series
• treatment flow totals (by category)
• unknown policy + mass-balance policy applied
• evidence references (if present)

Provenance chain MUST show:

… → MEID_CALC_WASTE_AGGR → MEID_CALC_WASTE_DIV → …

with cmi_short_code recorded in USO tail arrays.

---

9. Performance Notes

• Complexity: $O(n)$ over periods (or $O(n_{flows})$ if list-based)
• Memory: $O(n)$
• Suitable for batch reporting and KPI analytics

---

10. Methods Served (v1)

• Waste.diversion_rate
• Waste.recycled.abs
• Waste.recovered.abs
• Waste.disposed.abs
• Waste.treatment.unknown.abs

---