Jira progress: loading…

WTR-CONS

Water Discharge Aggregation

1. Identity

Loading identity…

Depends on module:

Purpose
Aggregates water discharge (water returned from the organization to the environment or third parties) into canonical totals and structured breakdowns aligned with ESRS E3-style water accounting.

This engine is the discharge counterpart to:

• MEID_CALC_WATER_AGGR (withdrawal)
• and is a key upstream input to MEID_CALC_WATER_CONS (derived consumption mode).

Typical usage

• Total water discharge (m³)
• Discharge by destination (surface water, sewer, sea, third party, etc.)
• Discharge by quality category (if reported)
• Input to mass-balance consumption calculation

---

2. Contract References (ZAR)

2.1 Input Schema

ZAR Address: schema.compute.water.discharge.inputs.v1_0_0

Required conceptual fields:

• discharge_items: list of water discharge records
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Each discharge_item conceptually includes:

• period (typically year)
• value
• unit (e.g., m3, L, ML)
• destination: canonical discharge destination identifier
• optional:
  • quality: TREATED | UNTREATED | UNKNOWN
  • site_id
  • basin_id
  • geo_ref
  • meter_id / invoice_id
  • is_estimate (boolean)

Canonical destinations (v1):

• surface_water
• groundwater (rare but included)
• seawater
• municipal_sewer
• third_party
• other

Note: In many orgs, discharge is best represented as “to sewer” vs “to environment”. Destinations support both.

---

2.2 Options Schema

ZAR Address: schema.compute.water.discharge.options.v1_0_0

Common options:

• unit_output: default m3
• destination_normalization: STRICT | LENIENT (default STRICT)
• unknown_destination_policy: ERROR | DROP | ASSIGN_OTHER (default ERROR)
• negative_values_policy: ERROR | ALLOW_WITH_FLAG
• missing_policy: ERROR | SKIP
• rounding: optional digits
• include_quality_breakdown: boolean (default false)

---

2.3 Output Schema

ZAR Address: schema.compute.water.discharge.output.v1_0_0

Outputs include:

• $W_{\mathrm{discharge,total}}(t)$
• $W_{\mathrm{discharge,by\_destination}}(d,t)$
• optional $W_{\mathrm{discharge,by\_quality}}(q,t)$
• metadata (unit conversions, unknown destinations, flags, completeness)

---

3. Accepted Input Shapes

A. Flat discharge item list (preferred)

{
  "discharge_items": [
    { "destination": "municipal_sewer", "period": 2025, "value": 90000, "unit": "m3" },
    { "destination": "surface_water",   "period": 2025, "value": 18000, "unit": "m3" }
  ],
  "alignment": "BY_YEAR"
}

B. Mixed units

{
  "discharge_items": [
    { "destination": "municipal_sewer", "period": 2025, "value": 90000, "unit": "m3" },
    { "destination": "third_party",     "period": 2025, "value": 25000000, "unit": "L" }
  ]
}

C. With quality tagging

{
  "discharge_items": [
    { "destination": "municipal_sewer", "quality": "TREATED",   "period": 2025, "value": 85000, "unit": "m3" },
    { "destination": "surface_water",   "quality": "UNTREATED", "period": 2025, "value": 5000,  "unit": "m3" }
  ],
  "include_quality_breakdown": true
}

All supported shapes MUST be normalized internally to:

Map<period, Map<destination, discharge_m3>> (+ optional quality dimension)

---

4. Destination Normalization Rules (Normative)

4.1. Canonical destination identifiers

Input destinations MUST normalize to canonical keys:

• surface_water
• groundwater
• seawater
• municipal_sewer
• third_party
• other

If destination_normalization = STRICT:

• unknown destinations MUST error (default)

If LENIENT:

• unknown destinations handled per unknown_destination_policy

4.2. Unknown destination handling

If a record cannot be mapped:

• ERROR: fail the computation
• DROP: omit record and record in metadata
• ASSIGN_OTHER: map to other and record in metadata

---

5. Compute Semantics (Normative)

Let $D(d,t)$ be discharge volume to destination $d$ at time $t$ (after unit normalization).

5.1. Discharge by destination

$W_{\mathrm{discharge,by_destination}}(d,t) = D(d,t)$

5.2. Total discharge

$W_{\mathrm{discharge,total}}(t) = \sum_{d \in D_{\mathrm{all}}} D(d,t)$

Where $D_{\mathrm{all}}$ is the set of included canonical destinations.

5.3. Optional quality breakdown

If include_quality_breakdown = true, let $q \in {TREATED, UNTREATED, UNKNOWN}$:

$W_{\mathrm{discharge,by_quality}}(q,t) = \sum_{d \in D_{\mathrm{all}}} D(d,q,t)$

---

6. Completeness & Coverage Metadata (Normative)

This engine MUST compute a structural completeness measure:

• $D_{\mathrm{present}}$: destinations present in input (post-normalization)
• $D_{\mathrm{expected}}$: expected destinations (defaults to the canonical set unless overridden)

$coverage_{ratio} = \frac{|D_{\mathrm{present}} \cap D_{\mathrm{expected}}|}{|D_{\mathrm{expected}}|}$

Metadata MUST include:

• destinations_present
• destinations_expected
• coverage_ratio
• unknown_destination_count
• negative_value_count (if allowed)

---

7. Validation & Error Model

Invariants

• Values must be finite
• Units must be convertible to unit_output
• Negative values rejected unless explicitly allowed
• Period keys coherent under alignment rules

Error codes (suggested)

• WATER_DISC_INVALID_DESTINATION
• WATER_DISC_UNIT_CONVERSION_FAILED
• WATER_DISC_NEGATIVE_VALUE
• WATER_DISC_NON_FINITE_VALUE
• WATER_DISC_ALIGNMENT_MISMATCH

Errors MUST include:

• engine cmi_short_code
• destination and period context

---

8. Dependencies

MEID_CALC_WATER_DISC depends on:

• schema resolver (ZAR)
• unit conversion capability (delegated)
• canonical discharge destination reference list

Declared via ZAR dependencies.

---

9. Federation & Audit Requirements

To reproduce water discharge externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• raw discharge items
• destination normalization policy used
• unit conversion reference/version used (if applicable)

Provenance chain MUST show:

… → MEID_CALC_WATER_DISC → …

with cmi_short_code recorded in USO tail arrays.

---

10. Performance Notes

• Complexity: $O(n_{items})$
• Memory: $O(|T| \times |D|)$
• Suitable for batch reporting and KPI analytics

---

11. Methods Served (v1)

• Water.discharge.abs
• Water.discharge.by_destination.abs
• Water.discharge.by_quality.abs (if enabled)
• Water.discharge.total.abs

---