Skip to main content
Jira progress: loading…

WTR-AGGR

Water Withdrawal Aggregation

1. Identity​

Loading identity…

Depends on module:

Canonical computation and modeling domain for ESG calculations, simulations, extrapolation, aggregation, normalization, and decision-grade metric synthesis. Provides governed, auditable compute services to other modules (e.g., Reporting, Risk, Net Zero, ZARA).
Domain:
computation-hub
Category:
analytics-modeling
Classification:
module
Lifecycle status:
active
Semver:
1.0.0
Introduced in:
v0.3
Governance
AI risk level:
high
Trust threshold:
0.9
Human review required:
true
Verifier involved:
false
Audit required:
true
Ownership
Primary owner:
Platform
Architecture board:
true
White-label allowed:
true
Entrypoints
Docs:
/computation-hub
UI:
/app/computation-hub
API:
/api/computation-hub
Dependencies
Modules
  • sis
  • input-hub
Unresolved tokens
  • BUME
  • SEM
  • VTE
Engines (declared)
  • DICE
  • DaVE
  • VTE
  • SEM
  • BUME
Micro-engines (from registry)
Micro-engines (declared)
None
Signals
USO
  • DATA.COMPUTATION
  • DATA.VALIDATION
  • DATA.EXTRAPOLATION
  • MODEL.SIMULATION
  • MODEL.UNCERTAINTY
CSI
  • CSI_COMPUTATION_HUB
SSSR tags
  • computation
  • modeling
  • simulation
  • monte-carlo
  • bayesian
  • extrapolation
  • aggregation
  • normalization
  • validation
  • mice
Workflows & Outputs
Workflows
  • MicroEngineRouting
  • RuleBasedComputeDispatch
  • ScenarioModeling
  • UncertaintyQuantification
  • AggregationAndRollups
  • NormalizationAndBenchmarking
  • ExtrapolationAndGapFilling
  • ComputeAuditAndReplay
Outputs
  • computed_metrics
  • scenario_ranges
  • confidence_intervals
  • normalized_values
  • validation_findings
  • trust_scored_compute_outputs
Audit
Ledger:
ALTD
Replay supported:
true
PII policy:
no_pii_in_omr
Tags

Purpose
Aggregates water withdrawal into canonical totals and structured breakdowns aligned with ESRS E3-style water accounting. This engine is the anchor for Water KPIs (intensity, stress-area allocation, YoY deltas, and discharge/consumption comparisons).

Typical usage

  • Total water withdrawal (m³)
  • Withdrawal by source (surface, groundwater, seawater, third-party, etc.)
  • Withdrawal by quality (freshwater vs other, where provided)
  • Input to MEID_CALC_WATER_INT, MEID_CALC_WATER_STRESS

2. Contract References (ZAR)​

2.1 Input Schema​

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

Required conceptual fields:

  • water_items: list of water withdrawal records
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Each water_item conceptually includes:

  • period (typically year)
  • value
  • unit (e.g., m3, L, ML)
  • source: canonical source identifier
  • optional:
    • quality: FRESH | NON_FRESH | UNKNOWN
    • site_id
    • basin_id
    • geo_ref (for stress-area mapping upstream/downstream)
    • meter_id / invoice_id
    • is_estimate (boolean)

Canonical sources (v1):

  • surface_water
  • groundwater
  • seawater
  • third_party
  • rainwater_harvested
  • produced_water (sector-specific; optional)
  • other

Note: This engine focuses on withdrawal. Water consumption and discharge are handled in separate MICEs.

2.2 Options Schema​

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

Common options:

  • unit_output: default m3
  • source_normalization: STRICT | LENIENT (default STRICT)
  • unknown_source_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.withdrawal.output.v1_0_0

Outputs include:

  • Wwithdrawal,total(t)W_{\mathrm{withdrawal,total}}(t)
  • Wwithdrawal,by_source(s,t)W_{\mathrm{withdrawal,by\_source}}(s,t)
  • optional Wwithdrawal,by_quality(q,t)W_{\mathrm{withdrawal,by\_quality}}(q,t)
  • metadata (unit conversions, unknown sources, flags, completeness)

3. Accepted Input Shapes​

A. Flat withdrawal item list (preferred)

{
  "water_items": [
    { "source": "surface_water", "period": 2025, "value": 100000, "unit": "m3" },
    { "source": "groundwater", "period": 2025, "value": 25000, "unit": "m3" }
  ],
  "alignment": "BY_YEAR"
}

B. Mixed units

{
  "water_items": [
    { "source": "surface_water", "period": 2025, "value": 100000, "unit": "m3" },
    { "source": "third_party",  "period": 2025, "value": 50000000, "unit": "L" }
  ]
}

C. With quality tagging

{
  "water_items": [
    { "source": "surface_water", "quality": "FRESH", "period": 2025, "value": 80000, "unit": "m3" },
    { "source": "seawater",      "quality": "NON_FRESH", "period": 2025, "value": 30000, "unit": "m3" }
  ],
  "include_quality_breakdown": true
}

All supported shapes MUST be normalized internally to:

Map<period, Map<source, withdrawal_m3>> (+ optional quality dimension)

4. Source Normalization Rules (Normative)​

4.1. Canonical source identifiers​

Input sources MUST normalize to canonical keys:

  • surface_water
  • groundwater
  • seawater
  • third_party
  • rainwater_harvested
  • produced_water (optional)
  • other

If source_normalization = STRICT:

  • unknown sources MUST error (default)

If LENIENT:

  • unknown sources handled per unknown_source_policy

4.2. Unknown source 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 W(s,t)W(s,t) be withdrawal volume from source ss at time tt (after unit normalization).

5.1. Withdrawal by source​

Wwithdrawal,bysource(s,t)=W(s,t)W_{\mathrm{withdrawal,by_source}}(s,t) = W(s,t)

5.2. Total withdrawal​

Wwithdrawal,total(t)=∑s∈SallW(s,t)W_{\mathrm{withdrawal,total}}(t) = \sum_{s \in S_{\mathrm{all}}} W(s,t)

Where SallS_{\mathrm{all}} is the set of included canonical sources.

5.3. Optional quality breakdown​

If include_quality_breakdown = true, let q∈FRESH,NONFRESH,UNKNOWNq \in {FRESH, NON_FRESH, UNKNOWN}:

Wwithdrawal,byquality(q,t)=∑s∈SallW(s,q,t)W_{\mathrm{withdrawal,by_quality}}(q,t) = \sum_{s \in S_{\mathrm{all}}} W(s,q,t)

6. Completeness & Coverage Metadata (Normative)​

This engine MUST compute a structural completeness measure:

  • SpresentS_{\mathrm{present}}: sources present in input (post-normalization)
  • SexpectedS_{\mathrm{expected}}: expected sources (defaults to the canonical set unless overridden)

coverageratio=∣Spresent∩Sexpected∣∣Sexpected∣coverage_ratio = \frac{|S_{\mathrm{present}} \cap S_{\mathrm{expected}}|}{|S_{\mathrm{expected}}|}

Metadata MUST include:

  • sources_present
  • sources_expected
  • coverage_ratio
  • unknown_source_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 must be coherent under alignment rules

Error codes (suggested)

  • WATER_AGGR_INVALID_SOURCE
  • WATER_AGGR_UNIT_CONVERSION_FAILED
  • WATER_AGGR_NEGATIVE_VALUE
  • WATER_AGGR_NON_FINITE_VALUE
  • WATER_AGGR_ALIGNMENT_MISMATCH

Errors MUST include:

  • engine cmi_short_code
  • source and period context

8. Dependencies​

MEID_CALC_WATER_AGGR depends on:

  • schema resolver (ZAR)
  • unit conversion capability (delegated)
  • canonical water source reference list

Declared via ZAR dependencies.

9. Federation & Audit Requirements​

To reproduce water withdrawal externally, the export MUST include:

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

Provenance chain MUST show:

… → MEID_CALC_WATER_AGGR → …

with cmi_short_code recorded in USO tail arrays.

10. Performance Notes​

  • Complexity: O(nitems)O(n_{items})
  • Memory: O(∣T∣×∣S∣)O(|T| \times |S|)
  • Suitable for batch reporting and KPI analytics

11. Methods Served (v1)​

  • Water.withdrawal.abs
  • Water.withdrawal.by_source.abs
  • Water.withdrawal.by_quality.abs (if enabled)
  • Water.withdrawal.total.abs


GitHub RepoRequest for Change (RFC)