AquaVein Methodology — v1.0
Public document · July 14, 2026 · This paper governs every report the engine emits. It is versioned; each report bundle records the methodology version it was generated under.
1. What an AquaVein report is — and is not
An AquaVein report is a compilation of sourced public records about groundwater conditions relevant to a geographic point, organized, computed, and graded under the fixed rules below. It documents conditions and margins as recorded on the issue date. It is not a prediction that any well will or will not fail, not a hydrogeologic study, and not engineering, legal, or investment advice. Where the data cannot support a statement, the report says so instead of estimating.
2. Data layers and sources
| Layer | Source of record | What we take |
|---|---|---|
| Well inventory | CA DWR Well Completion Reports (i07) | Completed depths, use class, completion dates within the report envelope |
| Water levels | DWR/CNRA Periodic Groundwater Level Measurements (gse_gwe) | Full per-station depth-to-water time series |
| Plan criteria | DWR SGMA Monitoring Network Module (SMC_MT, SMC_MO, LAST_GSE) | Adopted minimum thresholds / objectives, converted to depth-below-ground per site |
| Governance | Same module, PROGRAM_TYPE | GSP-managed vs. court-adjudicated vs. other |
| Regional context | NASA/NDMC GRACE-DA weekly percentile | ~8-mile-cell shallow-groundwater percentile vs. 1948–2012 climatology |
| Wells and levels (AZ) | ADWR GWSI sites layer | Well depth + latest depth-to-water per site (WL_DTW, LASTWLDATE) |
Every figure in a report carries its layer; every layer carries its source; the bundle's data.json preserves the raw values used.
3. Computations
· Station selection (CA): all monitoring stations within the trend radius (default 6.5 mi) are fetched in full; stations qualify with ≥6 measurements and a reading within the last ~4 years; the nearest qualifying stations (≤5) are reported with distance, station depth, decade medians, and latest dated reading.
· Threshold conversion: MT_depth_below_ground = LAST_GSE − SMC_MT, per site. Reported per site with distance; never averaged across sites.
· Margins (AZ): margin = completed_depth − latest_depth_to_water, per site; summarized as median, count under 50 ft, and count at/below datum.
· Well statistics: domestic-well completed depths within the envelope, reported as count and P25/median/P75.
· GRACE: single-cell sample at the point; reported with its week; regional context only.
4. Grading rubric (fixed; the engine implements this verbatim)
Confidence — HIGH: ≥3 qualifying stations with nearest ≤4 mi (CA), or ≥100 margin-computable sites (AZ). MEDIUM: ≥2 stations / ≥25 sites. Otherwise LOW — FLAGGED, NOT SCORED: data is displayed but no grade is issued, and purchase flows disclose LOW status before payment. Grade (CA) — ELEVATED RISK when any in-area adopted minimum threshold lies deeper than the area's median domestic well, or ≥2 nearby long-record stations show multi-decade decline (>15 ft vs. an earlier-era median). STABLE / MANAGED when stations are flat-to-improving inside an adjudicated area. NO ELEVATED SIGNALS otherwise. Grade (AZ) — ELEVATED RISK when >15% of margin-computable sites hold <50 ft of margin, or any site sits at/below its own datum; otherwise NO ELEVATED SIGNALS.Grades describe documented conditions and direction. The words "will" and "safe" do not appear in grades.
5. Standing doctrines (violations are defects)
1. Sourced facts only — nothing modeled, nothing estimated, nothing filled in.
2. Aquifer-zone rule — a station reads the zone its screen reaches; station depth accompanies every trend row; deep-well readings are never presented as the level facing shallow domestic wells.
3. Vintage caveat (AZ) — latest-per-site readings span dates; dates ride with values; vintages are never pooled silently.
4. Low data = flagged, never scored — false comfort and false alarm are equal defects.
5. Both directions — stable findings are published with the same prominence as elevated ones.
6. Integrity, versioning, correction
Every report ships as a .dvnr signed bundle: a manifest binding the SHA-256 of every payload, signed Ed25519 by the issuer key; verification is offline and permanent. Reports are versioned; if a defect is found post-issue, a corrected bundle is issued as rid-r2 with a correction note, the original is preserved unaltered in the archive, and the customer is notified. Methodology changes increment this document's version; a report is always interpreted under the version stamped in its manifest.
7. Considered and not included in v1.0
Surface water rights (SWRCB eWRIMS Points of Diversion). Evaluated and deliberately excluded. eWRIMS permits surface diversions; groundwater pumping is not eWRIMS-permitted in California, so the layer cannot answer the question a well owner is asking, and its presence on a groundwater report invites exactly the wrong inference — that an absence of nearby PODs means an absence of nearby pumpers. If it is ever added it will be labelled surface-only and scoped accordingly. It is not in this version, and no report has ever used it.8. Known limitations
Monitoring wells measure their own locations; parcel-scale conditions vary between sites. Screening margins are not well tests — pump setting, screen interval, yield decline, and seasonal drawdown all matter. Rural coverage varies; unmonitored areas produce LOW-confidence outputs by design. GRACE cells blend terrain. Source datasets carry their agencies' own errors; we transmit, cite, and date them — we do not adjudicate them.