Skip to main content
Jira progress: loading…

WTR-SHR

Water Share / Composition Calculator

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
Computes water composition shares (ratios or percentages) with water-governed semantics, enforcing canonical source/stress identifiers, valid denominator choices, and disclosure-grade metadata for ESRS E3.

This engine is a domain adapter over MEID_CALC_SHARE.

2. Contract References (ZAR)​

2.1 Input Schema​

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

Required conceptual fields:

  • numerator_ref: water component identifier (source/stress/basis)
  • denominator_ref: water total identifier
  • share_mode: RATIO | PERCENT (default PERCENT)
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

And either:

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

(or resolvable signal refs, if your orchestration supports that pattern)

2.2 Options Schema​

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

Common options:

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

2.3 Output Schema​

ZAR Address: schema.compute.water.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. Source share of withdrawal (surface water / total withdrawal)

{
  "numerator_ref": "source:surface_water",
  "denominator_ref": "withdrawal_total",
  "numerator": [[2025, 100000]],
  "denominator": [[2025, 125000]],
  "share_mode": "PERCENT"
}

B. Stress share of withdrawal (high-stress / total withdrawal)

{
  "numerator_ref": "stress:high",
  "denominator_ref": "withdrawal_total",
  "numerator": [[2025, 45000]],
  "denominator": [[2025, 125000]],
  "share_mode": "RATIO"
}

C. Consumption ratio (consumption / withdrawal)

{
  "numerator_ref": "consumption_total",
  "denominator_ref": "withdrawal_total",
  "numerator": [[2025, 15000]],
  "denominator": [[2025, 125000]],
  "share_mode": "PERCENT"
}

4. Water-Specific Normalization Rules (Normative)​

4.1. Allowed numerator_ref values (v1)​

Source shares

  • source:surface_water
  • source:groundwater
  • source:seawater
  • source:third_party
  • source:rainwater_harvested
  • source:other

Stress shares

  • stress:high
  • stress:medium
  • stress:low
  • stress:unknown

Totals

  • withdrawal_total
  • consumption_total
  • discharge_total

4.2. Allowed denominator_ref values (v1)​

  • withdrawal_total
  • consumption_total
  • discharge_total

4.3. Pairing rules (governed)​

The engine MUST enforce the following valid combinations:

  • source:* MAY only be divided by withdrawal_total or consumption_total (not discharge unless explicitly added later)
  • stress:* MAY only be divided by withdrawal_total or consumption_total
  • consumption_total / withdrawal_total is allowed (consumption ratio)
  • discharge_total / withdrawal_total is allowed only if explicitly enabled by schema in later versions

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)}

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]

6. Validation & Error Model​

Error codes (suggested)

  • WATER_SHARE_INVALID_REF
  • WATER_SHARE_INVALID_PAIRING
  • WATER_SHARE_ALIGNMENT_MISMATCH
  • WATER_SHARE_DENOMINATOR_ZERO_GUARDED
  • WATER_SHARE_NON_FINITE_VALUE

7. Dependencies​

  • MEID_CALC_SHARE (primitive)
  • schema resolver (ZAR)
  • canonical water source list
  • canonical stress bucket list (if used)

Declared via ZAR dependencies.

8. Methods Served (v1)​

  • Water.withdrawal.source.share
  • Water.consumption.source.share
  • Water.withdrawal.stress.share
  • Water.consumption.stress.share

Recommendation on naming​

Use metric types (CSI) like:

  • water.withdrawal.by_source.share
  • water.withdrawal.by_stress.share

…and keep the engine MEID generic: MEID_CALC_WATER_SHARE.



GitHub RepoRequest for Change (RFC)