Skip to main content
Water Conservation / Water BudgetingBrainstorm

Water Budget Engine

site plannerbrief
Created 2026-07-09
Brief

Water Budget Engine

Status: Brief · Author: Dan (Product Lead) · Created: 2026-07-09 Product: Site Planner (product-level engine — no single capability owns it) Origin: 2026-07-06 Utah Water Ways working session (Cynthia Bee) + CEO direction 2026-07-09. Altitude: Product brief (pre-spec). Defines what the engine is, where it sits, and what it reconciles. Formula-level detail, schema, and API design are deferred to the spec — the math itself is already documented (see Existing Foundation).

Overview

Digitize the EPA WaterSense Version 2.0 water-budget spreadsheet into a per-design engine that computes a landscape water budget continuously and invisibly from the geometry, plant schedule, and irrigation design the user has already created in Site Planner — then compares it against a per-jurisdiction baseline and surfaces exactly one thing: a pass/fail headline.

The engine is the computational backbone behind three surfaces that already exist in design or research form:

  1. The Irrigation tab's water-budget cue — the single pass/fail readout defined in the Site Planner design doc §9.3 ("Water budget met / exceeded by X"), whose math that document explicitly deferred.
  2. The water-savings estimator — existing-vs-proposed savings per property (the scenario diff's water_saved_gal line, already slotted in the X1 unified engine rollup).
  3. Any future usage score — an opt-in rating of actual water use against the property's computed budget (consumer of this engine, not part of it).

The governing design principle, verbatim from the program partner who administers these budgets professionally: the homeowner should "never have to talk about it" (Cynthia Bee, Utah Water Ways, 2026-07-06). Water budgeting is a compliance formality that terrifies laypeople and bores professionals — the engine does it silently, and the product only speaks up when the design crosses a line.

Problem Statement

  • Water-budget compliance today is a spreadsheet exercise (the EPA WaterSense 2.0 workbook, MWELO worksheets) done manually, late, and only by the fraction of users who know it exists. Everyone else finds out at plan review or rebate inspection — after the design is finished.
  • Every jurisdiction expresses "how much water is allowed" differently — as a percentage of a reference baseline (e.g., California's MWELO expresses the allowance as a fraction of reference evapotranspiration; the 2026-07-06 session cited it as "roughly 60% of baseline," and the 2024 MWELO ETAF caps documented in the drip irrigation spec put residential projects at ≤ 0.55). SimplyScapes has no configurable home for these per-jurisdiction values.
  • Site Planner already computes a water budget (see Existing Foundation) but as a stateless display, not a jurisdiction-aware, design-persistent engine that other features (savings estimator, rebate eligibility, usage score) can consume.
  • Districts and states need to know that designs produced on the platform can demonstrate regulatory compliance — while the product's own ruling (CEO 2026-04-16) is that compliance must not hard-block creative work. No current document reconciles those two postures; this brief does (see Advisory-first).

Proposed Solution

The engine

A per-design computation that runs whenever the relevant inputs change:

  • Inputs (all already in the canvas): hydrozone areas by layer type (Layers tab), plant water-need factors from the plant schedule (Plants tab), irrigation method efficiency (Irrigation tab), and reference-ET climate data for the property location.
  • Method: the EPA WaterSense 2.0 water-budget methodology — the same one the shipped Water Budget tab already applies (MAWA vs. ETWU) — extracted from the spreadsheet into engine code, with the formula chain documented in the drip irrigation spec's MWELO section and the methodology comparison (QWEL vs. WaterSense 2.0 vs. MWELO) in the turf scheduling research report §3.3.
  • Outputs: budget (allowed), estimated use (designed), the delta, and a boolean pass/fail — each with provenance back to the geometry that produced it, per the X1 provenance rule.

Invisible by default

The engine computes continuously behind the scenes; it has no tab, no wizard, no worksheet. The user experience is the single headline cue of design.md §9.3: "Water budget met" or "exceeded by X," with hydrozone color-coding as the secondary layer and formulas visible only to those who go looking. This is the "never have to talk about it" principle operationalized: compliance becomes an ambient property of the design, not a step.

Jurisdiction baselines as configuration

The baseline percentage (what fraction of reference-condition water use a compliant design may consume) is config data per jurisdiction, not engine code — the same config-not-engine pattern the X1 rebate-rule-set established for rebate rules. Examples of the kind of values the config carries (all public program facts): California MWELO 2024 ETAF caps (residential ≤ 0.55, non-residential ≤ 0.45), the WaterSense 2.0 default baseline, and whatever a Utah district adopts. Where the jurisdiction rules engine (see design.md Addendum) resolves a property to its governing entities, the water-budget baseline is simply one more field those entities carry.

Advisory-first, enforcement-capable (the reconciliation)

Two prior positions appear to conflict, and this engine is where they reconcile:

  • CEO 2026-04-16: hard compliance enforcement was explicitly de-scoped — plant-zone fit and similar checks surface as warnings, never blocks. Creative work is never dead-ended.
  • 2026-07-06 session: program partners need the platform to demonstrate that "we at least have a system in place to enforce regulatory requirements."

Resolution — an advisory→enforcement toggle, per jurisdiction/tenant:

  • Advisory (default, everywhere): the engine computes; the pass/fail cue and warnings show; nothing is ever blocked. This is the 2026-04-16 posture, unchanged, for all retail and default-tenant use.
  • Enforcement-capable (opt-in, per program tenant): a white-label tenant operating a regulated program may flip specific checks from advisory to gating (e.g., "cannot submit a rebate reservation while the budget fails") — gating program actions (submit, export packet), never the design canvas itself. The system is thereby capable of enforcement where a program requires it, without ever hard-blocking design work.

The toggle's precedent is the soft-flag-never-hard-block pattern already resolved in the guided-design flow work; the same toggle is specified for the broader jurisdiction rules engine in the Site Planner design addendum.

Single pass/fail surface

One headline, everywhere the budget appears: met / exceeded by X. No score, no gauge, no worksheet on the happy path. Faces that need more (district review, pro ledger) read the same engine outputs with more lines visible, per the X1 faces model.

Downstream Consumers

| Consumer | What it reads | Where it's documented | |---|---|---| | Irrigation tab budget cue | pass/fail + delta | design.md §9.3 | | Water-savings estimator | budget + estimated use per scenario → water_saved_gal diff | X1 rollup water_budget slot | | Rebate eligibility checks | budget pass/fail as one checklist line (where a program requires it) | Turf Rebate Program Tool brief | | Usage / good-citizen score (future idea) | actual metered use vs. this engine's budget | not yet an idea directory — depends on this engine |

Existing Foundation (De-risking)

This is a small-to-medium build because the hard parts already exist:

  • Water budget calculation is shipped (web repo PR #148, merged Feb 2026): the irrigation engine's Water Budget tab already computes MAWA vs. ETWU using the EPA WaterSense 2.0 methodology on live design geometry.
  • The full formula chain is documented: MAWA/ETWU formulas with 2024 ETAF caps in the drip irrigation spec — MWELO Compliance Calculation and its Project Water Budget API sketch.
  • The methodology trade-space is researched: QWEL (operational runtimes) vs. WaterSense 2.0 (compliance budgets) vs. MWELO (regulatory budgets) in the turf scheduling report §3.3.
  • The UX surface is designed: the single pass/fail headline in design.md §9.3.
  • The integration slot exists: the X1 unified engine's per-scenario rollup already carries a water_budget line.

Net-new work is therefore: (1) spreadsheet-formula extraction into a persistent, per-design engine (vs. today's stateless tab display); (2) the jurisdiction-baseline config layer; (3) the advisory→enforcement toggle; (4) the invisible-computation UX wiring.

Candidate Architecture — Geo-Entity Overlay (CEO 2026-07-09)

Recorded as candidate architecture — the CEO's framing is to "guide what's possible — don't close down discovery"; the spec phase should treat this as the leading candidate, not a closed decision:

  • A hierarchy of geo-entities — State → District → Municipality → HOA — each stored with a service-area geometry and matched to a property by address via PostGIS GPS lookup (point-in-polygon against the entity's boundary).
  • Each entity carries structured rule fields (e.g., the water-budget baseline percentage, rebate rates) plus markdown (MD) context fields — free-form rule text, terms & conditions, program guidance — written once by the program administrator.
  • The MD context fields are ingested into Milo (the in-app AI widget — web repo PR #250, open), so jurisdiction rules and T&C context reach the user conversationally at the moment they matter, instead of as legal walls of text. This aligns with the platform's SSFM markdown decision — markdown as the direct agent-readable source of truth, no translation layer — per the Agent-Native Rich Text Format (SSFM) decision.
  • For this engine specifically: the property's resolved entity chain supplies the baseline percentage (structured field) and the explanatory context Milo can voice when the pass/fail cue trips ("your district allows X% of baseline because…").

The same overlay serves the broader jurisdiction rules/T&C engine — see the Site Planner design addendum — so entity matching, storage, and Milo ingestion should be specified once, shared.

Scope & Phasing

  • Phase 1 — Engine foundation (stage): extract the WaterSense 2.0 computation into a persistent per-design engine; jurisdiction baseline as config (seed: one Utah district profile + the CA MWELO profile as the two reference configs); wire the §9.3 pass/fail cue; expose outputs to the X1 rollup. Advisory posture only.
  • Later phases (not yet staged): the enforcement-capable toggle wired to program-tenant actions; geo-entity overlay integration once that shared infrastructure exists; usage-score consumers.

Out of scope for this idea: irrigation scheduling (runtime minutes — that is the automated turf irrigation scheduling idea's QWEL chain); rebate rule evaluation (the jurisdiction rules engine); any usage-data collection.

Dependencies & Constraints

  • Site Planner geometry + plant schedule + irrigation design as inputs (shipped / in redesign — design doc).
  • Plant water-need data (plant library; WUCOLS mapping researched in the drip irrigation spec).
  • Reference-ET source (Open-Meteo recommended Phase 1 source in the irrigation cluster).
  • Jurisdiction rules engine / geo-entity overlay — only for baseline resolution; Phase 1 can hardcode per-tenant baseline config and adopt the overlay when it lands.
  • Constraint: never hard-block design work (CEO 2026-04-16) — enforcement gates program actions only, behind the per-tenant toggle.

Open Questions

  1. Spreadsheet fidelity: does the WaterSense 2.0 workbook contain edge-case handling (special landscape areas, pools, recycled-water credits) beyond what PR #148's MAWA/ETWU implementation covers? A cell-by-cell extraction pass is the first spec task.
  2. Baseline config shape: one percentage per jurisdiction, or a formula variant selector (WaterSense 2.0 vs. MWELO vs. district-custom)? Leaning: method + parameters per entity.
  3. Where the engine persists — per design, per scenario (design_version), or both. The savings estimator needs per-scenario values, which suggests per-scenario.
  4. Enforcement toggle granularity: per-check, per-tenant, or per-program? Needs a program partner's real requirements to settle.
  5. Catalog placement ratified? This brief places the engine at Site Planner product level (math consumed from irrigation, UX in the redesign, savings in scenarios) — flagged as an open placement decision in the 2026-07-09 cross-check; Jarvis/CEO to confirm.

References

Internal: Site Planner design doc §9.3 · Site Planner design addendum (2026-07-09) · X1 Adaptive Unified Engine · Drip irrigation spec — MWELO Compliance Calculation · Turf scheduling report §3.3 — QWEL vs. WaterSense 2.0 vs. MWELO · Turf Rebate Program Tool brief · Agent-Native Rich Text Format (SSFM)

External: EPA WaterSense Water Budget Tool · MWELO.org · EPA WaterSense Version 2.0 Specification for Homes

Version History

| Date & Time (MT) | Author | Summary | |-------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 2026-07-09 06:20 PM MT | Dan | Initial brief — WaterSense 2.0 spreadsheet digitized as an invisible per-design engine; per-jurisdiction baseline config; advisory-first / enforcement-capable toggle reconciling CEO 2026-04-16 with the 2026-07-06 UWW session; single pass/fail surface per design.md §9.3; geo-entity overlay + Milo ingestion recorded as candidate architecture (CEO 2026-07-09); Phase 1 stage scaffolded. |