Deploy AquiScore Groundwater Security API v2.0.0 — CCME WQI, DRASTIC vulnerability framework

README.md

@@ -7,14 +7,19 @@ sdk: docker
 app_port: 7860
 pinned: false
 license: mit
-short_description: Groundwater Security Scoring Engine v1.1
+short_description: Groundwater Security Scoring Engine v2.0
 ---
 
-# AquiScore — Groundwater Security API v1.1
+# AquiScore — Groundwater Security API v2.0
 
-Fuses NASA GRACE-FO satellite gravity × USGS NWIS well measurements × GLHYMPS hydrogeology to produce auditable groundwater security scores.
+Fuses NASA GRACE-FO satellite gravity x USGS NWIS well measurements x GLHYMPS hydrogeology to produce auditable groundwater security scores.
 
-## v1.1 Optimizations
+## v2.0 Scientific Enrichments
+
+- CCME Water Quality Index (F1/F2/F3 replaces linear quality scoring)
+- DRASTIC groundwater vulnerability framework (EPA 7-parameter assessment)
+
+## v1.x Foundation
 
 - Batch scoring (up to 500 sites per request)
 - Response caching with content-hash keys
@@ -25,9 +30,13 @@ Fuses NASA GRACE-FO satellite gravity × USGS NWIS well measurements × GLHYMPS
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/v1/score` | Run aquifer security score |
+| POST | `/v1/score` | Run aquifer security score (v2.0 enriched) |
 | POST | `/v1/score/batch` | Batch score multiple aquifers |
 | POST | `/v1/certificate` | Generate security certificate |
+| POST | `/v1/grace/decompose` | GRACE TWS signal decomposition |
+| POST | `/v1/wells/interpolate` | Kriging well field interpolation |
+| POST | `/v1/wqi` | Standalone CCME Water Quality Index |
+| POST | `/v1/drastic` | Standalone DRASTIC vulnerability |
 | GET | `/v1/aquifer-types` | List aquifer types |
 | GET | `/v1/extraction-regimes` | Extraction regime multipliers |
 | GET | `/v1/quality-thresholds` | WHO/EPA water quality thresholds |

api/main.py

@@ -1,13 +1,27 @@
 """
-AquiScore FastAPI Server — Groundwater Security API
+AquiScore FastAPI Server — Groundwater Security API v2.0
+
+Wraps pipeline/aquifer_model.py as a REST API with v2.0 scientific enrichments:
+  - CCME Water Quality Index (replaces linear quality scoring)
+  - DRASTIC groundwater vulnerability assessment
+  Plus v1.x: batch scoring, response caching, GRACE decomposition, kriging
 
 Endpoints:
-  POST /v1/score              — Run aquifer security score
+  POST /v1/score              — Run aquifer security score (v2.0 enriched)
+  POST /v1/score/batch        — Batch score multiple sites
+  POST /v1/certificate        — Generate aquifer certificate
+  POST /v1/grace/decompose    — GRACE TWS signal decomposition
+  POST /v1/wells/interpolate  — Kriging well field interpolation
+  POST /v1/wqi                — Standalone CCME Water Quality Index
+  POST /v1/drastic            — Standalone DRASTIC vulnerability assessment
   GET  /v1/aquifer-types      — List aquifer types
   GET  /v1/extraction-regimes — List extraction regimes
   GET  /v1/quality-thresholds — WHO/EPA water quality thresholds
   GET  /v1/grace-hotspots     — GRACE-FO depletion hotspots
+  GET  /v1/grace-regions      — GRACE regional references
   GET  /v1/presets/{name}     — Run canonical preset
+  GET  /v1/cache/stats        — Cache performance statistics
+  POST /v1/cache/clear        — Clear response cache
   GET  /v1/health             — Health check
 
 Usage:
@@ -35,11 +49,26 @@ from pipeline.aquifer_model import (
 )
 from pipeline.certificate_generator import generate_certificate_json, generate_certificate_text
 from pipeline.grace_fetch import REGIONAL_GRACE_REFS, list_depletion_hotspots
+from pipeline.cache import get_default_cache, ScoreCache
+from pipeline.grace_decomposition import decompose_grace_signal, classify_depletion_pattern
+from pipeline.kriging import interpolate_well_field
+from pipeline.ccme_wqi import compute_ccme_wqi, GUIDELINES as CCME_GUIDELINES
+from pipeline.drastic_rating import compute_drastic, compute_drastic_from_aquifer_type
+
+# Module-level cache instance
+_cache = get_default_cache()
 
 app = FastAPI(
     title="AquiScore API",
-    description="Groundwater Security Scoring Engine — GRACE-FO × NWIS × GLHYMPS",
-    version="1.0.0",
+    description=(
+        "Groundwater Security Scoring Engine v2.0 — "
+        "GRACE-FO × NWIS × GLHYMPS. v2.0: CCME Water Quality Index, "
+        "DRASTIC vulnerability framework, batch scoring, response caching, "
+        "GRACE decomposition, and kriging interpolation."
+    ),
+    version="2.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
 )
 
 app.add_middleware(
@@ -50,6 +79,8 @@ app.add_middleware(
 )
 
 
+# ── REQUEST / RESPONSE MODELS ───────────────────────────────────────────────
+
 class GRACEInput(BaseModel):
     tws_anomaly_cm: float = 0.0
     trend_cm_yr: float = 0.0
@@ -108,18 +139,48 @@ class ScoreRequest(BaseModel):
         return v
 
 
+# ── ENDPOINTS ────────────────────────────────────────────────────────────────
+
 @app.get("/v1/health")
 async def health_check():
     return {
         "status": "healthy",
         "platform": "AquiScore",
-        "version": "1.0.0",
+        "version": "2.0.0",
         "timestamp": datetime.now(timezone.utc).isoformat(),
+        "v1_optimizations": [
+            "batch_scoring", "response_caching", "grace_decomposition",
+            "kriging_interpolation", "well_field_analysis",
+        ],
+        "v2_capabilities": [
+            "ccme_water_quality_index", "drastic_vulnerability",
+        ],
     }
 
 
 @app.post("/v1/score")
 async def run_score(request: ScoreRequest):
+    """
+    Run aquifer security score with response caching.
+
+    Fuses satellite (GRACE-FO), well measurement, substrate (GLHYMPS),
+    and water quality signals with extraction regime multiplier.
+    """
+    # Build cache key from all scoring inputs
+    cache_key = _cache.make_key(
+        grace=request.grace.model_dump(),
+        well=request.well.model_dump(),
+        substrate=request.substrate.model_dump(),
+        quality=request.quality.model_dump(),
+        aquifer_type=request.aquifer_type,
+        extraction_regime=request.extraction_regime,
+    )
+
+    cached = _cache.get(cache_key)
+    if cached is not None:
+        cached["_cached"] = True
+        return cached
+
     result = run_aquifer_score(
         grace=request.grace.model_dump(),
         well=request.well.model_dump(),
@@ -129,7 +190,7 @@ async def run_score(request: ScoreRequest):
         extraction_regime=request.extraction_regime,
     )
 
-    return {
+    response = {
         "score": result.score,
         "confidence_interval": result.confidence_interval,
         "confidence_pct": result.confidence_pct,
@@ -144,8 +205,14 @@ async def run_score(request: ScoreRequest):
         "quality_flags": result.quality_flags,
         "feature_importances": result.feature_importances,
         "citations": result.citations,
+        "ccme_wqi": result.ccme_wqi,
+        "drastic": result.drastic,
+        "_cached": False,
     }
 
+    _cache.set(cache_key, response)
+    return response
+
 
 @app.post("/v1/certificate")
 async def generate_cert(request: ScoreRequest):
@@ -219,7 +286,8 @@ async def run_preset(preset_name: str):
     }
 
 
-# -- Batch Scoring Endpoint ---------------------------------------------------
+# ── v1.1 OPTIMIZATION ENDPOINTS ────────────────────────────────────────────
+
 
 class BatchScoreRequest(BaseModel):
     """Batch aquifer scoring -- score multiple sites in one request."""
@@ -273,7 +341,6 @@ async def run_batch_score(request: BatchScoreRequest):
         except Exception as e:
             errors.append({"index": i, "error": str(e)})
 
-    # Summary statistics
     scores = [r["score"] for r in results]
     summary = {}
     if scores:
@@ -296,3 +363,241 @@ async def run_batch_score(request: BatchScoreRequest):
         "errors": errors,
         "summary": summary,
     }
+
+
+# ── GRACE Decomposition Endpoint ────────────────────────────────────────────
+
+class GRACEDecomposeRequest(BaseModel):
+    """GRACE TWS monthly time series for decomposition."""
+    monthly_tws_cm: list[float] = Field(
+        ...,
+        min_length=24,
+        max_length=600,
+        description="Monthly TWS anomaly values in cm EWT (min 24 months)",
+    )
+    trend_window: int = Field(13, ge=3, le=25, description="Moving average window for trend extraction")
+    site_id: Optional[str] = None
+
+
+@app.post("/v1/grace/decompose")
+async def grace_decompose(request: GRACEDecomposeRequest):
+    """
+    Decompose a GRACE TWS time series into trend, seasonal, and residual.
+
+    Uses STL-like decomposition (Cleveland et al. 1990) to extract:
+    - Trend: long-term storage change direction
+    - Seasonal: annual recharge/discharge cycle
+    - Residual: anomalous signals (drought, pumping events)
+
+    Classifies depletion pattern: stable, linear_decline,
+    accelerating_decline, seasonal_stress, or recovery.
+
+    Minimum 24 months of data required.
+    """
+    try:
+        decomp = decompose_grace_signal(
+            request.monthly_tws_cm,
+            trend_window=request.trend_window,
+        )
+        pattern = classify_depletion_pattern(decomp)
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+    return {
+        "site_id": request.site_id,
+        "n_months": decomp.n_months,
+        "trend_slope_cm_yr": decomp.trend_slope_cm_yr,
+        "trend_r_squared": decomp.trend_r_squared,
+        "is_accelerating": decomp.is_accelerating,
+        "acceleration_rate": decomp.acceleration_rate,
+        "seasonal_amplitude_cm": decomp.seasonal_amplitude_cm,
+        "depletion_pattern": pattern,
+        "trend": decomp.trend,
+        "seasonal": decomp.seasonal,
+        "residual": decomp.residual,
+        "citation": "Cleveland, R.B. et al. (1990) STL: Seasonal-Trend Decomposition. J. Official Statistics 6:3-73.",
+    }
+
+
+# ── Kriging Well Field Interpolation Endpoint ───────────────────────────────
+
+class WellPoint(BaseModel):
+    lat: float = Field(..., ge=-90, le=90)
+    lon: float = Field(..., ge=-180, le=180)
+    depth_m: float = Field(..., ge=0, description="Depth to water table in meters")
+
+
+class KrigingRequest(BaseModel):
+    """Kriging interpolation request for a target location."""
+    wells: list[WellPoint] = Field(
+        ...,
+        min_length=2,
+        max_length=500,
+        description="Known well data points (min 2 required for kriging)",
+    )
+    target_lat: float = Field(..., ge=-90, le=90)
+    target_lon: float = Field(..., ge=-180, le=180)
+    max_distance_km: float = Field(100.0, ge=1, le=500)
+    site_id: Optional[str] = None
+
+
+@app.post("/v1/wells/interpolate")
+async def wells_interpolate(request: KrigingRequest):
+    """
+    Predict groundwater depth at a target location from surrounding wells.
+
+    Uses Ordinary Kriging (Cressie 1993) with a spherical variogram model
+    to provide the Best Linear Unbiased Predictor (BLUP) for spatial data.
+
+    Returns prediction with uncertainty (kriging variance) and 95% CI.
+    """
+    wells = [{"lat": w.lat, "lon": w.lon, "depth_m": w.depth_m} for w in request.wells]
+
+    try:
+        result = interpolate_well_field(
+            wells,
+            target_lat=request.target_lat,
+            target_lon=request.target_lon,
+            max_distance_km=request.max_distance_km,
+        )
+    except ValueError as e:
+        raise HTTPException(400, str(e))
+
+    return {
+        "site_id": request.site_id,
+        "target_lat": request.target_lat,
+        "target_lon": request.target_lon,
+        "predicted_depth_m": result["predicted_depth_m"],
+        "prediction_variance": result["prediction_variance"],
+        "prediction_std_m": result["prediction_std_m"],
+        "confidence_interval_m": result["confidence_interval_m"],
+        "n_wells_used": result["n_wells_used"],
+        "variogram_params": result["variogram_params"],
+        "citation": "Cressie, N.A.C. (1993) Statistics for Spatial Data. Wiley.",
+    }
+
+
+# ── Cache Endpoints ─────────────────────────────────────────────────────────
+
+@app.get("/v1/cache/stats")
+async def cache_stats():
+    """Return cache performance statistics."""
+    return _cache.stats()
+
+
+@app.post("/v1/cache/clear")
+async def cache_clear():
+    """Clear the response cache. Returns count of evicted entries."""
+    count = _cache.clear()
+    return {"cleared": count, "status": "ok"}
+
+
+# ── v2.0 SCIENTIFIC ENDPOINTS ─────────────────────────────────────────────
+
+
+class WQIRequest(BaseModel):
+    """Standalone CCME Water Quality Index request."""
+    nitrate_mg_l: float = Field(5.0, ge=0)
+    arsenic_ug_l: float = Field(3.0, ge=0)
+    fluoride_mg_l: float = Field(0.5, ge=0)
+    tds_mg_l: float = Field(300.0, ge=0)
+    ph: float = Field(7.2, ge=0, le=14)
+    e_coli_cfu_100ml: float = Field(0.0, ge=0)
+
+
+@app.post("/v1/wqi")
+async def run_ccme_wqi(request: WQIRequest):
+    """
+    Compute CCME Water Quality Index from chemical/microbial measurements.
+
+    The CCME WQI is the internationally recognized standard for drinking
+    water quality assessment, combining three factors:
+      F1 (Scope):     % of parameters exceeding guidelines
+      F2 (Frequency): % of individual tests failing
+      F3 (Amplitude): degree of exceedance (asymptotic to 100)
+
+      WQI = 100 - (sqrt(F1² + F2² + F3²) / 1.732)
+
+    Categories:
+      EXCELLENT (95-100), GOOD (80-94), FAIR (65-79),
+      MARGINAL (45-64), POOR (0-44)
+
+    Citation: CCME (2001) Canadian Water Quality Guidelines for the
+              Protection of Aquatic Life. CCME Water Quality Index 1.0.
+    """
+    measurements = {
+        "nitrate_mg_l": request.nitrate_mg_l,
+        "arsenic_ug_l": request.arsenic_ug_l,
+        "fluoride_mg_l": request.fluoride_mg_l,
+        "tds_mg_l": request.tds_mg_l,
+        "ph": request.ph,
+        "e_coli_cfu_100ml": request.e_coli_cfu_100ml,
+    }
+
+    result = compute_ccme_wqi(measurements)
+
+    return {
+        "wqi": result.wqi,
+        "category": result.category,
+        "f1_scope": result.f1_scope,
+        "f2_frequency": result.f2_frequency,
+        "f3_amplitude": result.f3_amplitude,
+        "n_parameters": result.n_variables,
+        "n_failed": result.n_failed_variables,
+        "exceedances": result.exceedances,
+        "interpretation": result.interpretation,
+        "guidelines_used": CCME_GUIDELINES,
+        "citation": "CCME (2001) Canadian Water Quality Guidelines. CCME WQI 1.0.",
+    }
+
+
+class DRASTICRequest(BaseModel):
+    """Standalone DRASTIC vulnerability assessment request."""
+    aquifer_type: str
+    depth_to_water_m: float = Field(15.0, ge=0, description="Depth to water table in meters")
+    hydraulic_conductivity_m_s: float = Field(1e-5, ge=0, description="Hydraulic conductivity in m/s")
+
+    @field_validator("aquifer_type")
+    @classmethod
+    def validate_aquifer_type(cls, v):
+        if v not in AQUIFER_TYPES:
+            raise ValueError(f"Invalid aquifer_type. Must be one of: {list(AQUIFER_TYPES.keys())}")
+        return v
+
+
+@app.post("/v1/drastic")
+async def run_drastic_assessment(request: DRASTICRequest):
+    """
+    Compute DRASTIC groundwater vulnerability index.
+
+    DRASTIC is the EPA-published framework for evaluating intrinsic
+    groundwater vulnerability using seven hydrogeological parameters:
+      D = Depth to water (weight 5)
+      R = Net Recharge (weight 4)
+      A = Aquifer media (weight 3)
+      S = Soil media (weight 2)
+      T = Topography/slope (weight 1)
+      I = Impact of vadose zone (weight 5)
+      C = Conductivity of aquifer (weight 3)
+
+    Index range: 23-230.
+    Converted to security score: 100 × (1 - (DI - 23) / 207)
+
+    Citation: Aller, L. et al. (1987) DRASTIC: A Standardized System
+              to Evaluate Ground Water Pollution Potential. US EPA/600/2-87/035.
+    """
+    result = compute_drastic_from_aquifer_type(
+        aquifer_type=request.aquifer_type,
+        depth_m=request.depth_to_water_m,
+        conductivity_m_s=request.hydraulic_conductivity_m_s,
+    )
+
+    return {
+        "drastic_index": result.drastic_index,
+        "vulnerability_class": result.vulnerability_class,
+        "security_score": result.security_score,
+        "parameter_ratings": result.parameter_ratings,
+        "dominant_factor": result.dominant_factor,
+        "interpretation": result.interpretation,
+        "citation": "Aller, L. et al. (1987) DRASTIC. US EPA/600/2-87/035.",
+    }

pipeline/aquifer_model.py

@@ -23,6 +23,9 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Optional
 
+from pipeline.ccme_wqi import compute_ccme_wqi, ccme_wqi_to_score
+from pipeline.drastic_rating import compute_drastic_from_aquifer_type
+
 
 # ── AQUIFER INDICATOR WEIGHTS ────────────────────────────────────────────────
 # DO NOT CHANGE without updating SOUL.md. Weights sum to 1.00.
@@ -148,7 +151,11 @@ class AquiScoreResult:
     aquifer_type_info: dict
     citations: list[str]
     timestamp: str
-    model_version: str = "1.0.0"
+    model_version: str = "2.0.0"
+
+    # v2.0 enrichments — scientifically grounded diagnostics
+    ccme_wqi: Optional[dict] = None           # CCME Water Quality Index (F1/F2/F3)
+    drastic: Optional[dict] = None            # DRASTIC groundwater vulnerability
 
 
 # ── COMPONENT SCORING FUNCTIONS ─────────────────────────────────────────────
@@ -299,108 +306,69 @@ def compute_substrate_score(params: SubstrateParams, aquifer_type: str) -> tuple
     return composite, details
 
 
-def compute_quality_score(quality: WaterQualityParams) -> tuple[float, list[dict]]:
+def compute_quality_score(quality: WaterQualityParams) -> tuple[float, list[dict], dict]:
     """
-    Score water quality against WHO/EPA thresholds.
+    Score water quality using CCME Water Quality Index (v2.0).
+
+    Replaces the v1.0 per-parameter linear scorer with the Canadian Council
+    of Ministers of the Environment WQI framework:
+        WQI = 100 - (sqrt(F1² + F2² + F3²) / 1.732)
+    where:
+        F1 = Scope (% of parameters that fail guidelines)
+        F2 = Frequency (% of individual tests that fail)
+        F3 = Amplitude (degree to which failing tests exceed guidelines)
+
+    This is the internationally recognized standard for drinking water
+    quality assessment. Categories: EXCELLENT(95-100), GOOD(80-94),
+    FAIR(65-79), MARGINAL(45-64), POOR(0-44).
+
+    Citation: CCME (2001) Canadian Water Quality Guidelines for the
+              Protection of Aquatic Life. CCME Water Quality Index 1.0.
 
-    Each parameter scored independently, then averaged.
-    Contamination flags raised for any exceedance.
+    Returns:
+        (score 0-100, quality flags, ccme_details dict)
     """
+    # Build measurements dict for CCME WQI
+    measurements = {
+        "nitrate_mg_l": quality.nitrate_mg_l,
+        "arsenic_ug_l": quality.arsenic_ug_l,
+        "fluoride_mg_l": quality.fluoride_mg_l,
+        "tds_mg_l": quality.tds_mg_l,
+        "ph": quality.ph,
+        "e_coli_cfu_100ml": quality.e_coli_cfu_100ml,
+    }
+
+    ccme = compute_ccme_wqi(measurements)
+
+    # Convert CCME WQI to AquiScore quality component
+    composite = ccme_wqi_to_score(ccme.wqi)
+
+    # Build quality flags from CCME exceedances
     flags = []
-    scores = []
-
-    # Nitrate
-    nit = quality.nitrate_mg_l
-    t = WATER_QUALITY_THRESHOLDS["nitrate_mg_l"]
-    if nit <= t["safe"]:
-        s = 100.0
-    elif nit <= t["concern"]:
-        s = 100.0 - (nit - t["safe"]) / (t["concern"] - t["safe"]) * 50
-    elif nit <= t["danger"]:
-        s = 50.0 - (nit - t["concern"]) / (t["danger"] - t["concern"]) * 40
-    else:
-        s = max(0.0, 10.0 - (nit - t["danger"]) * 0.2)
-    scores.append(s)
-    if nit > t["safe"]:
-        flags.append({"param": "nitrate", "value": nit, "unit": "mg/L",
-                       "threshold": t["safe"], "severity": "DANGER" if nit > t["danger"] else "CONCERN"})
-
-    # Arsenic
-    ars = quality.arsenic_ug_l
-    t = WATER_QUALITY_THRESHOLDS["arsenic_ug_l"]
-    if ars <= t["safe"]:
-        s = 100.0
-    elif ars <= t["concern"]:
-        s = 100.0 - (ars - t["safe"]) / (t["concern"] - t["safe"]) * 50
-    elif ars <= t["danger"]:
-        s = 50.0 - (ars - t["concern"]) / (t["danger"] - t["concern"]) * 40
-    else:
-        s = max(0.0, 10.0 - (ars - t["danger"]) * 0.2)
-    scores.append(s)
-    if ars > t["safe"]:
-        flags.append({"param": "arsenic", "value": ars, "unit": "µg/L",
-                       "threshold": t["safe"], "severity": "DANGER" if ars > t["danger"] else "CONCERN"})
-
-    # Fluoride
-    flu = quality.fluoride_mg_l
-    t = WATER_QUALITY_THRESHOLDS["fluoride_mg_l"]
-    if flu <= t["safe"]:
-        s = 100.0
-    elif flu <= t["concern"]:
-        s = 100.0 - (flu - t["safe"]) / (t["concern"] - t["safe"]) * 50
-    elif flu <= t["danger"]:
-        s = 50.0 - (flu - t["concern"]) / (t["danger"] - t["concern"]) * 40
-    else:
-        s = max(0.0, 10.0 - (flu - t["danger"]) * 2)
-    scores.append(s)
-    if flu > t["safe"]:
-        flags.append({"param": "fluoride", "value": flu, "unit": "mg/L",
-                       "threshold": t["safe"], "severity": "DANGER" if flu > t["danger"] else "CONCERN"})
-
-    # TDS
-    tds = quality.tds_mg_l
-    t = WATER_QUALITY_THRESHOLDS["tds_mg_l"]
-    if tds <= t["safe"]:
-        s = 100.0
-    elif tds <= t["concern"]:
-        s = 100.0 - (tds - t["safe"]) / (t["concern"] - t["safe"]) * 50
-    elif tds <= t["danger"]:
-        s = 50.0 - (tds - t["concern"]) / (t["danger"] - t["concern"]) * 40
-    else:
-        s = max(0.0, 10.0 - (tds - t["danger"]) * 0.005)
-    scores.append(s)
-    if tds > t["safe"]:
-        flags.append({"param": "tds", "value": tds, "unit": "mg/L",
-                       "threshold": t["safe"], "severity": "DANGER" if tds > t["danger"] else "CONCERN"})
-
-    # pH (range-based)
-    ph = quality.ph
-    if 6.5 <= ph <= 8.5:
-        s = 100.0
-    elif ph < 6.5:
-        s = max(0.0, 100.0 - (6.5 - ph) * 40)
-    else:
-        s = max(0.0, 100.0 - (ph - 8.5) * 40)
-    scores.append(s)
-
-    # E. coli
-    ecoli = quality.e_coli_cfu_100ml
-    t = WATER_QUALITY_THRESHOLDS["e_coli_cfu_100ml"]
-    if ecoli <= t["safe"]:
-        s = 100.0
-    elif ecoli <= t["concern"]:
-        s = 60.0
-    elif ecoli <= t["danger"]:
-        s = 30.0
-    else:
-        s = max(0.0, 10.0 - ecoli * 0.5)
-    scores.append(s)
-    if ecoli > t["safe"]:
-        flags.append({"param": "e_coli", "value": ecoli, "unit": "CFU/100mL",
-                       "threshold": t["safe"], "severity": "DANGER" if ecoli > t["danger"] else "CONCERN"})
+    for exc in ccme.exceedances:
+        severity = "DANGER" if exc.get("excursion", 0) > 2.0 else "CONCERN"
+        flags.append({
+            "param": exc["parameter"],
+            "value": exc["measured"],
+            "unit": exc.get("unit", ""),
+            "threshold": exc["objective"],
+            "severity": severity,
+        })
+
+    # CCME details for enriched response
+    ccme_dict = {
+        "wqi": ccme.wqi,
+        "category": ccme.category,
+        "f1_scope": ccme.f1_scope,
+        "f2_frequency": ccme.f2_frequency,
+        "f3_amplitude": ccme.f3_amplitude,
+        "n_parameters": ccme.n_variables,
+        "n_failed": ccme.n_failed_variables,
+        "exceedances": ccme.exceedances,
+        "citation": "CCME (2001) Canadian Water Quality Guidelines. CCME WQI 1.0.",
+    }
 
-    composite = sum(scores) / len(scores) if scores else 50.0
-    return composite, flags
+    return composite, flags, ccme_dict
 
 
 def compute_confidence(score: int, n_wells: int, record_years: int) -> tuple[int, list[int]]:
@@ -527,8 +495,24 @@ def run_aquifer_score(
     # 3. Substrate score (20%)
     sub_score, sub_details = compute_substrate_score(substrate, aquifer_type)
 
-    # 4. Water quality score (15%)
-    qual_score, quality_flags = compute_quality_score(quality)
+    # 4. Water quality score (15%) — now using CCME WQI (v2.0)
+    qual_score, quality_flags, ccme_details = compute_quality_score(quality)
+
+    # v2.0: DRASTIC vulnerability assessment
+    drastic_result = compute_drastic_from_aquifer_type(
+        aquifer_type=aquifer_type,
+        depth_m=substrate.depth_to_water_m,
+        conductivity_m_s=substrate.hydraulic_conductivity_m_s,
+    )
+    drastic_dict = {
+        "drastic_index": drastic_result.drastic_index,
+        "vulnerability_class": drastic_result.vulnerability_class,
+        "security_score": drastic_result.security_score,
+        "parameter_ratings": drastic_result.parameter_ratings,
+        "dominant_factor": drastic_result.dominant_factor,
+        "interpretation": drastic_result.interpretation,
+        "citation": "Aller, L. et al. (1987) DRASTIC: A Standardized System to Evaluate Ground Water Pollution Potential. US EPA/600/2-87/035.",
+    }
 
     # Extraction regime multiplier
     ext_multiplier = EXTRACTION_REGIMES[extraction_regime]
@@ -579,6 +563,8 @@ def run_aquifer_score(
         "Tapley, B. et al. (2019) Contributions of GRACE to understanding climate change. Nature Climate Change 9:358-369.",
         "USGS National Water Information System (NWIS). U.S. Geological Survey. https://waterdata.usgs.gov",
         "Gleeson, T. et al. (2014) A glimpse beneath earth's surface: GLobal HYdrogeology MaPS (GLHYMPS). Geophysical Research Letters 41:3042-3049.",
+        "CCME (2001) Canadian Water Quality Guidelines. CCME Water Quality Index 1.0.",
+        "Aller, L. et al. (1987) DRASTIC: A Standardized System to Evaluate Ground Water Pollution Potential. US EPA/600/2-87/035.",
     ]
 
     return AquiScoreResult(
@@ -599,6 +585,8 @@ def run_aquifer_score(
         aquifer_type_info=AQUIFER_TYPES[aquifer_type],
         citations=citations,
         timestamp=datetime.now(timezone.utc).isoformat(),
+        ccme_wqi=ccme_details,
+        drastic=drastic_dict,
     )
 
 

pipeline/cache.py

@@ -0,0 +1,396 @@
+"""
+AquiScore — Response Caching with Content-Hash Keys
+
+LRU in-memory cache for aquifer scoring results. Thread-safe implementation
+using a doubly-linked list for O(1) eviction and a dict for O(1) lookup.
+
+Sibling implementation to GroundTruth pipeline/cache.py.
+Same architecture: "We do not invent signals. We translate them."
+
+Features:
+  - SHA256 content-hash keys derived from sorted, serialized input parameters
+  - TTL-based expiration with lazy eviction
+  - Thread-safe via threading.Lock
+  - Hit/miss statistics for monitoring
+  - Decorator for transparent caching of scoring functions
+
+Usage:
+    from pipeline.cache import ScoreCache, cached_score
+
+    cache = ScoreCache(max_size=1000, ttl_seconds=3600)
+
+    # Manual usage
+    key = cache.make_key(lat=37.5, lon=-122.1, aquifer_type="unconfined_alluvial")
+    result = cache.get(key)
+    if result is None:
+        result = expensive_computation(...)
+        cache.set(key, result)
+
+    # Decorator usage
+    @cached_score
+    def run_aquifer_score(grace, well, substrate, quality, aquifer_type, extraction_regime):
+        ...
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+import json
+import threading
+import time
+from functools import wraps
+from typing import Any, Optional
+
+
+class _Node:
+    """Doubly-linked list node for LRU eviction tracking."""
+
+    __slots__ = ("key", "value", "expires_at", "prev", "next")
+
+    def __init__(self, key: str, value: dict, expires_at: float) -> None:
+        self.key: str = key
+        self.value: dict = value
+        self.expires_at: float = expires_at
+        self.prev: Optional[_Node] = None
+        self.next: Optional[_Node] = None
+
+
+class ScoreCache:
+    """
+    Thread-safe LRU cache with TTL expiration for aquifer scoring results.
+
+    Implements a hash map backed by a doubly-linked list for O(1) operations:
+      - get(): O(1) lookup + move to head
+      - set(): O(1) insert at head + evict tail if at capacity
+      - invalidate(): O(1) removal by key
+      - clear(): O(n) full reset
+
+    All public methods are protected by a threading.Lock.
+
+    Args:
+        max_size: Maximum number of cached entries. When exceeded, the
+                  least-recently-used entry is evicted. Default 1000.
+        ttl_seconds: Time-to-live for each entry in seconds. Expired entries
+                     are lazily evicted on access. Default 3600 (1 hour).
+    """
+
+    def __init__(self, max_size: int = 1000, ttl_seconds: int = 3600) -> None:
+        if max_size < 1:
+            raise ValueError("max_size must be >= 1")
+        if ttl_seconds < 0:
+            raise ValueError("ttl_seconds must be >= 0")
+
+        self._max_size: int = max_size
+        self._ttl_seconds: int = ttl_seconds
+        self._lock: threading.Lock = threading.Lock()
+
+        # Hash map: key -> Node
+        self._store: dict[str, _Node] = {}
+
+        # Doubly-linked list sentinel nodes (head = most recent, tail = least recent)
+        self._head: _Node = _Node("__HEAD__", {}, 0.0)
+        self._tail: _Node = _Node("__TAIL__", {}, 0.0)
+        self._head.next = self._tail
+        self._tail.prev = self._head
+
+        # Statistics
+        self._hits: int = 0
+        self._misses: int = 0
+        self._evictions: int = 0
+        self._expirations: int = 0
+
+    # -- Key Generation ---------------------------------------------------
+
+    @staticmethod
+    def make_key(**kwargs: Any) -> str:
+        """
+        Generate a SHA256 content-hash key from keyword arguments.
+
+        Arguments are sorted by key name and serialized to a canonical
+        JSON string before hashing. This ensures that the same logical
+        inputs always produce the same cache key regardless of argument
+        ordering.
+
+        Returns:
+            A 64-character hex SHA256 digest string.
+        """
+        return ScoreCache._make_key_from_dict(kwargs)
+
+    @staticmethod
+    def _make_key_from_dict(params: dict) -> str:
+        """SHA256 of sorted, serialized input params."""
+        canonical = json.dumps(params, sort_keys=True, default=str, separators=(",", ":"))
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    # -- Linked List Operations (internal, caller must hold lock) ----------
+
+    def _remove_node(self, node: _Node) -> None:
+        """Remove a node from the doubly-linked list."""
+        prev_node = node.prev
+        next_node = node.next
+        if prev_node is not None:
+            prev_node.next = next_node
+        if next_node is not None:
+            next_node.prev = prev_node
+        node.prev = None
+        node.next = None
+
+    def _insert_after_head(self, node: _Node) -> None:
+        """Insert a node right after the head sentinel (most recently used)."""
+        old_first = self._head.next
+        self._head.next = node
+        node.prev = self._head
+        node.next = old_first
+        if old_first is not None:
+            old_first.prev = node
+
+    def _evict_tail(self) -> Optional[str]:
+        """Remove the least-recently-used node (just before tail sentinel)."""
+        victim = self._tail.prev
+        if victim is None or victim is self._head:
+            return None
+        self._remove_node(victim)
+        evicted_key = victim.key
+        self._store.pop(evicted_key, None)
+        self._evictions += 1
+        return evicted_key
+
+    # -- Public API -------------------------------------------------------
+
+    def get(self, key: str) -> Optional[dict]:
+        """
+        Retrieve a cached value by key.
+
+        If the entry exists but has expired, it is removed and None is returned.
+        On a hit, the entry is promoted to most-recently-used position.
+
+        Returns:
+            The cached dict value, or None if not found / expired.
+        """
+        with self._lock:
+            node = self._store.get(key)
+            if node is None:
+                self._misses += 1
+                return None
+
+            # Check TTL expiration
+            if time.monotonic() > node.expires_at:
+                self._remove_node(node)
+                del self._store[key]
+                self._misses += 1
+                self._expirations += 1
+                return None
+
+            # Move to head (most recently used)
+            self._remove_node(node)
+            self._insert_after_head(node)
+            self._hits += 1
+            return node.value
+
+    def set(self, key: str, value: dict) -> None:
+        """
+        Store a value in the cache.
+
+        If the key already exists, its value and TTL are updated and it is
+        promoted to most-recently-used. If the cache is at capacity, the
+        least-recently-used entry is evicted first.
+        """
+        with self._lock:
+            expires_at = time.monotonic() + self._ttl_seconds
+
+            # Update existing entry
+            existing = self._store.get(key)
+            if existing is not None:
+                self._remove_node(existing)
+                existing.value = value
+                existing.expires_at = expires_at
+                self._insert_after_head(existing)
+                return
+
+            # Evict if at capacity
+            if len(self._store) >= self._max_size:
+                self._evict_tail()
+
+            # Insert new entry
+            node = _Node(key, value, expires_at)
+            self._store[key] = node
+            self._insert_after_head(node)
+
+    def invalidate(self, key: str) -> bool:
+        """Remove a specific entry from the cache."""
+        with self._lock:
+            node = self._store.pop(key, None)
+            if node is None:
+                return False
+            self._remove_node(node)
+            return True
+
+    def clear(self) -> int:
+        """Remove all entries from the cache. Returns count cleared."""
+        with self._lock:
+            count = len(self._store)
+            self._store.clear()
+            self._head.next = self._tail
+            self._tail.prev = self._head
+            return count
+
+    def stats(self) -> dict:
+        """Return cache performance statistics."""
+        with self._lock:
+            total = self._hits + self._misses
+            hit_rate = (self._hits / total * 100.0) if total > 0 else 0.0
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "size": len(self._store),
+                "max_size": self._max_size,
+                "hit_rate": round(hit_rate, 2),
+                "evictions": self._evictions,
+                "expirations": self._expirations,
+                "ttl_seconds": self._ttl_seconds,
+            }
+
+    @property
+    def size(self) -> int:
+        """Current number of entries in the cache."""
+        with self._lock:
+            return len(self._store)
+
+    def __repr__(self) -> str:
+        s = self.stats()
+        return (
+            f"ScoreCache(size={s['size']}/{s['max_size']}, "
+            f"hit_rate={s['hit_rate']}%, "
+            f"hits={s['hits']}, misses={s['misses']})"
+        )
+
+
+# -- Module-Level Default Cache -----------------------------------------------
+
+_default_cache = ScoreCache(max_size=1000, ttl_seconds=3600)
+
+
+def get_default_cache() -> ScoreCache:
+    """Return the module-level default ScoreCache singleton."""
+    return _default_cache
+
+
+# -- Decorator ----------------------------------------------------------------
+
+def cached_score(func=None, *, cache: Optional[ScoreCache] = None):
+    """
+    Decorator that caches scoring function results by input content-hash.
+
+    Can be used with or without arguments:
+
+        @cached_score
+        def my_scoring_fn(grace, well, substrate, quality, aquifer_type, extraction_regime):
+            ...
+
+        @cached_score(cache=my_custom_cache)
+        def my_scoring_fn(grace, well, substrate, quality, aquifer_type, extraction_regime):
+            ...
+    """
+    target_cache = cache or _default_cache
+
+    def decorator(fn):
+        sig = inspect.signature(fn)
+
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            all_params = dict(bound.arguments)
+            all_params["__fn__"] = fn.__qualname__
+
+            key = ScoreCache._make_key_from_dict(all_params)
+
+            cached = target_cache.get(key)
+            if cached is not None:
+                return cached
+
+            result = fn(*args, **kwargs)
+
+            if isinstance(result, dict):
+                target_cache.set(key, result)
+            elif hasattr(result, "__dict__"):
+                target_cache.set(key, {"__cached_obj__": True, "__data__": vars(result)})
+
+            return result
+
+        wrapper.cache = target_cache
+        return wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+if __name__ == "__main__":
+    import concurrent.futures
+    import time as _time
+
+    print("=" * 60)
+    print("AquiScore ScoreCache -- Self-Test")
+    print("=" * 60)
+
+    c = ScoreCache(max_size=3, ttl_seconds=2)
+
+    k1 = c.make_key(lat=37.5, lon=-122.1, aquifer_type="unconfined_alluvial")
+    k2 = c.make_key(aquifer_type="unconfined_alluvial", lat=37.5, lon=-122.1)
+    assert k1 == k2, "Key generation must be order-independent"
+    print(f"  Key determinism:      PASS")
+
+    c.set(k1, {"score": 78, "risk_class": "SECURE"})
+    result = c.get(k1)
+    assert result is not None and result["score"] == 78
+    print(f"  Set/Get:              PASS")
+
+    c.set(c.make_key(a=1), {"score": 1})
+    c.set(c.make_key(a=2), {"score": 2})
+    c.set(c.make_key(a=3), {"score": 3})
+    assert c.get(k1) is None
+    print("  LRU eviction:         PASS")
+
+    s = c.stats()
+    assert s["hits"] >= 1 and s["misses"] >= 1
+    print(f"  Stats:                PASS (hit_rate={s['hit_rate']}%)")
+
+    c2 = ScoreCache(max_size=10, ttl_seconds=0)
+    k_ttl = c2.make_key(test="ttl")
+    c2.set(k_ttl, {"score": 50})
+    _time.sleep(0.01)
+    assert c2.get(k_ttl) is None
+    print("  TTL expiration:       PASS")
+
+    c3 = ScoreCache(max_size=10)
+    c3.set(c3.make_key(x=1), {"v": 1})
+    c3.set(c3.make_key(x=2), {"v": 2})
+    cleared = c3.clear()
+    assert cleared == 2 and c3.size == 0
+    print(f"  Clear:                PASS (cleared={cleared})")
+
+    tc = ScoreCache(max_size=100, ttl_seconds=60)
+    errors = []
+
+    def stress_worker(worker_id):
+        try:
+            for i in range(50):
+                k = tc.make_key(worker=worker_id, iteration=i)
+                tc.set(k, {"worker": worker_id, "i": i})
+                r = tc.get(k)
+                if r is None or r["worker"] != worker_id:
+                    errors.append(f"Worker {worker_id} iteration {i}: unexpected result")
+        except Exception as e:
+            errors.append(f"Worker {worker_id}: {e}")
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=8) as pool:
+        futures = [pool.submit(stress_worker, w) for w in range(8)]
+        concurrent.futures.wait(futures)
+
+    assert len(errors) == 0, f"Thread safety errors: {errors}"
+    print("  Thread safety:        PASS (8 workers x 50 ops)")
+
+    print("\n  All tests passed.")
+    print("=" * 60)

pipeline/ccme_wqi.py

@@ -0,0 +1,440 @@
+"""
+AquiScore v2.0 — CCME Water Quality Index Implementation
+
+Implements the Canadian Council of Ministers of the Environment (CCME)
+Water Quality Index, replacing the v1.x linear threshold-based quality
+scoring with a three-dimensional assessment.
+
+============================================================================
+WHY THIS MATTERS (for Environmental Risk Assessors)
+============================================================================
+
+v1.x scored each water quality parameter independently against WHO/EPA
+thresholds and averaged the results. This approach misses two critical
+dimensions of water quality assessment:
+
+  1. SCOPE: How many parameters fail? A site with one parameter slightly
+     over the limit is very different from a site with four parameters
+     over the limit, even if the average "score" is similar.
+
+  2. FREQUENCY: How often do parameters fail? With repeated measurements,
+     a parameter that fails 1 out of 10 times is very different from one
+     that fails 9 out of 10 times.
+
+The CCME WQI captures all three dimensions in a single index:
+  F1 = Scope (% of parameters that fail)
+  F2 = Frequency (% of individual tests that fail)
+  F3 = Amplitude (how far failed tests exceed their guidelines)
+
+  WQI = 100 - (sqrt(F1² + F2² + F3²) / 1.732)
+
+The denominator 1.732 (= sqrt(3)) normalizes so that when all three
+F-values = 100 (worst case), WQI = 0.
+
+============================================================================
+CCME WQI CATEGORIES
+============================================================================
+
+  95-100: EXCELLENT — Water quality is protected with virtually no
+          threat or impairment.
+  80-94:  GOOD — Water quality is protected with only a minor degree
+          of threat or impairment.
+  65-79:  FAIR — Water quality is usually protected but occasionally
+          threatened or impaired.
+  45-64:  MARGINAL — Water quality is frequently threatened or impaired.
+  0-44:   POOR — Water quality is almost always threatened or impaired.
+
+Reference:
+  CCME (2001) Canadian Water Quality Guidelines for the Protection of
+  Aquatic Life: CCME Water Quality Index 1.0, User's Manual.
+  In: Canadian Environmental Quality Guidelines, 1999.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ── GUIDELINE THRESHOLDS ────────────────────────────────────────────────────
+# WHO (2022) Guidelines for Drinking-water Quality, 4th ed.
+# EPA (2024) National Primary Drinking Water Regulations
+
+GUIDELINES = {
+    "nitrate_mg_l": {
+        "objective": 10.0,     # WHO/EPA MCL
+        "direction": "max",    # must not EXCEED
+        "unit": "mg/L",
+        "source": "WHO (2022) / US EPA NPDWR",
+    },
+    "arsenic_ug_l": {
+        "objective": 10.0,     # WHO/EPA MCL
+        "direction": "max",
+        "unit": "µg/L",
+        "source": "WHO (2022) / US EPA NPDWR",
+    },
+    "fluoride_mg_l": {
+        "objective": 1.5,      # WHO guideline
+        "direction": "max",
+        "unit": "mg/L",
+        "source": "WHO (2022)",
+    },
+    "tds_mg_l": {
+        "objective": 500.0,    # EPA SMCL (aesthetic)
+        "direction": "max",
+        "unit": "mg/L",
+        "source": "US EPA SMCL",
+    },
+    "ph_low": {
+        "objective": 6.5,      # EPA SMCL lower bound
+        "direction": "min",    # must not fall BELOW
+        "unit": "pH units",
+        "source": "US EPA SMCL",
+    },
+    "ph_high": {
+        "objective": 8.5,      # EPA SMCL upper bound
+        "direction": "max",
+        "unit": "pH units",
+        "source": "US EPA SMCL",
+    },
+    "e_coli_cfu_100ml": {
+        "objective": 0.0,      # WHO: 0 in drinking water
+        "direction": "max",
+        "unit": "CFU/100mL",
+        "source": "WHO (2022)",
+    },
+}
+
+
+# ── CCME WQI COMPUTATION ───────────────────────────────────────────────────
+
+@dataclass
+class CCMEResult:
+    """
+    CCME Water Quality Index result.
+
+    Attributes:
+        wqi: The CCME WQI score (0-100). Higher = better water quality.
+        category: EXCELLENT / GOOD / FAIR / MARGINAL / POOR.
+        f1_scope: Percentage of parameters that fail (0-100).
+        f2_frequency: Percentage of individual tests that fail (0-100).
+        f3_amplitude: Normalized magnitude of exceedances (0-100, asymptotic).
+        n_variables: Total number of guideline parameters tested.
+        n_failed_variables: Number of parameters with at least one exceedance.
+        n_tests: Total number of individual test results.
+        n_failed_tests: Number of individual tests exceeding guidelines.
+        exceedances: List of parameter-level exceedance details.
+        interpretation: Human-readable interpretation for risk assessors.
+    """
+    wqi: float
+    category: str
+    f1_scope: float
+    f2_frequency: float
+    f3_amplitude: float
+    n_variables: int
+    n_failed_variables: int
+    n_tests: int
+    n_failed_tests: int
+    exceedances: list = field(default_factory=list)
+    interpretation: str = ""
+
+
+def _classify_wqi(wqi: float) -> str:
+    """Classify WQI into CCME categories."""
+    if wqi >= 95:
+        return "EXCELLENT"
+    elif wqi >= 80:
+        return "GOOD"
+    elif wqi >= 65:
+        return "FAIR"
+    elif wqi >= 45:
+        return "MARGINAL"
+    else:
+        return "POOR"
+
+
+def compute_ccme_wqi(
+    measurements: dict,
+    guidelines: Optional[dict] = None,
+) -> CCMEResult:
+    """
+    Compute the CCME Water Quality Index from water quality measurements.
+
+    This implementation supports single-measurement snapshots (typical for
+    AquiScore field assessments) where n_tests = n_variables.
+    For time-series data with multiple measurements per parameter,
+    pass a dict where each value is a list of measurements.
+
+    Args:
+        measurements: Dict mapping parameter names to values or lists of values.
+            Expected keys: nitrate_mg_l, arsenic_ug_l, fluoride_mg_l,
+            tds_mg_l, ph, e_coli_cfu_100ml.
+            Values can be:
+              - float: single measurement (F2 = F1 in this case)
+              - list[float]: multiple measurements over time
+
+        guidelines: Optional custom guideline dict. Defaults to WHO/EPA
+            thresholds defined in GUIDELINES constant.
+
+    Returns:
+        CCMEResult with WQI score, F1/F2/F3 components, and exceedance details.
+    """
+    gl = guidelines or GUIDELINES
+
+    # Expand pH into two directional tests
+    expanded: dict[str, list[float]] = {}
+    for param, value in measurements.items():
+        if param == "ph":
+            vals = value if isinstance(value, list) else [value]
+            expanded["ph_low"] = vals
+            expanded["ph_high"] = vals
+        else:
+            expanded[param] = value if isinstance(value, list) else [value]
+
+    # Count variables and tests
+    n_variables = 0
+    n_tests = 0
+    n_failed_variables = 0
+    n_failed_tests = 0
+    excursion_sum = 0.0
+    exceedances = []
+
+    for param, guideline in gl.items():
+        if param not in expanded:
+            continue
+
+        vals = expanded[param]
+        n_variables += 1
+        n_tests += len(vals)
+
+        objective = guideline["objective"]
+        direction = guideline["direction"]
+        variable_failed = False
+
+        for v in vals:
+            failed = False
+            excursion = 0.0
+
+            if direction == "max" and v > objective:
+                failed = True
+                if objective > 0:
+                    excursion = (v / objective) - 1.0
+                else:
+                    # E. coli: objective is 0, any positive is a failure
+                    excursion = v  # Use absolute value as excursion
+            elif direction == "min" and v < objective:
+                failed = True
+                if v > 0:
+                    excursion = (objective / v) - 1.0
+                else:
+                    excursion = objective  # Avoid division by zero
+
+            if failed:
+                n_failed_tests += 1
+                variable_failed = True
+                excursion_sum += excursion
+
+                exceedances.append({
+                    "parameter": param,
+                    "measured": round(v, 3),
+                    "objective": objective,
+                    "unit": guideline["unit"],
+                    "excursion": round(excursion, 4),
+                    "source": guideline["source"],
+                })
+
+        if variable_failed:
+            n_failed_variables += 1
+
+    # Compute F1, F2, F3
+    f1 = (n_failed_variables / n_variables * 100.0) if n_variables > 0 else 0.0
+    f2 = (n_failed_tests / n_tests * 100.0) if n_tests > 0 else 0.0
+
+    # F3: normalized sum of excursions (asymptotic function)
+    nse = excursion_sum / n_tests if n_tests > 0 else 0.0
+    f3 = (nse / (0.01 * nse + 0.01)) if nse > 0 else 0.0
+
+    # Final WQI
+    magnitude = math.sqrt(f1 ** 2 + f2 ** 2 + f3 ** 2)
+    wqi = max(0.0, min(100.0, 100.0 - magnitude / 1.732))
+
+    category = _classify_wqi(wqi)
+
+    # Interpretation
+    if category == "EXCELLENT":
+        interpretation = (
+            f"CCME WQI = {wqi:.1f} (EXCELLENT). All measured parameters "
+            f"are within WHO/EPA guidelines. Water quality poses virtually "
+            f"no threat to human health or ecosystem function. "
+            f"No quality-related deductions applied to AquiScore."
+        )
+    elif category == "GOOD":
+        interpretation = (
+            f"CCME WQI = {wqi:.1f} (GOOD). Water quality is protected with "
+            f"minor exceedances. {n_failed_variables} of {n_variables} parameters "
+            f"exceeded guidelines. Exceedances are small in magnitude (F3={f3:.1f}). "
+            f"Minor quality deduction applied to AquiScore."
+        )
+    elif category == "FAIR":
+        interpretation = (
+            f"CCME WQI = {wqi:.1f} (FAIR). Water quality is occasionally "
+            f"threatened. {n_failed_variables} of {n_variables} parameters "
+            f"exceeded guidelines (F1={f1:.0f}%). "
+            f"Moderate quality deduction applied to AquiScore."
+        )
+    elif category == "MARGINAL":
+        interpretation = (
+            f"CCME WQI = {wqi:.1f} (MARGINAL). Water quality is frequently "
+            f"threatened or impaired. {n_failed_variables} of {n_variables} "
+            f"parameters exceeded guidelines. Exceedance magnitude is significant "
+            f"(F3={f3:.1f}). Substantial quality deduction applied to AquiScore."
+        )
+    else:
+        interpretation = (
+            f"CCME WQI = {wqi:.1f} (POOR). Water quality is almost always "
+            f"threatened or impaired. {n_failed_variables} of {n_variables} "
+            f"parameters exceeded guidelines with large exceedances "
+            f"(F3={f3:.1f}). Maximum quality deduction applied to AquiScore."
+        )
+
+    return CCMEResult(
+        wqi=round(wqi, 1),
+        category=category,
+        f1_scope=round(f1, 1),
+        f2_frequency=round(f2, 1),
+        f3_amplitude=round(f3, 1),
+        n_variables=n_variables,
+        n_failed_variables=n_failed_variables,
+        n_tests=n_tests,
+        n_failed_tests=n_failed_tests,
+        exceedances=exceedances,
+        interpretation=interpretation,
+    )
+
+
+def ccme_wqi_to_score(wqi: float) -> float:
+    """
+    Convert CCME WQI (0-100) to the AquiScore quality component score (0-100).
+
+    The WQI is already on a 0-100 scale but with different breakpoints
+    than the AquiScore quality component. This function maps:
+      WQI 95-100 → Score 95-100 (EXCELLENT)
+      WQI 80-94  → Score 75-95  (GOOD)
+      WQI 65-79  → Score 50-75  (FAIR)
+      WQI 45-64  → Score 25-50  (MARGINAL)
+      WQI 0-44   → Score 0-25   (POOR)
+
+    The mapping compresses the GOOD and FAIR ranges slightly to make
+    the quality component more sensitive to impairment.
+
+    Args:
+        wqi: CCME Water Quality Index (0-100).
+
+    Returns:
+        AquiScore quality component score (0-100).
+    """
+    if wqi >= 95:
+        return 95.0 + (wqi - 95.0)
+    elif wqi >= 80:
+        return 75.0 + (wqi - 80.0) / 15.0 * 20.0
+    elif wqi >= 65:
+        return 50.0 + (wqi - 65.0) / 15.0 * 25.0
+    elif wqi >= 45:
+        return 25.0 + (wqi - 45.0) / 20.0 * 25.0
+    else:
+        return max(0.0, wqi / 45.0 * 25.0)
+
+
+# ── SELF-TEST ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    print("=" * 72)
+    print("AquiScore v2.0 — CCME Water Quality Index — Self-Test")
+    print("=" * 72)
+
+    # Test 1: Pristine water (all within guidelines)
+    pristine = {
+        "nitrate_mg_l": 2.0,
+        "arsenic_ug_l": 1.0,
+        "fluoride_mg_l": 0.3,
+        "tds_mg_l": 180.0,
+        "ph": 7.1,
+        "e_coli_cfu_100ml": 0.0,
+    }
+    r1 = compute_ccme_wqi(pristine)
+    assert r1.category == "EXCELLENT", f"Pristine should be EXCELLENT: {r1.category}"
+    assert r1.f1_scope == 0.0
+    assert r1.n_failed_variables == 0
+    print(f"  Pristine water:       PASS (WQI={r1.wqi}, category={r1.category})")
+
+    # Test 2: Moderate contamination (nitrate + TDS over limits)
+    moderate = {
+        "nitrate_mg_l": 28.0,
+        "arsenic_ug_l": 5.0,
+        "fluoride_mg_l": 1.0,
+        "tds_mg_l": 650.0,
+        "ph": 7.4,
+        "e_coli_cfu_100ml": 0.0,
+    }
+    r2 = compute_ccme_wqi(moderate)
+    assert r2.n_failed_variables > 0
+    assert r2.wqi < r1.wqi, "Contaminated should score lower"
+    print(f"  Moderate contam:      PASS (WQI={r2.wqi}, category={r2.category}, "
+          f"failed={r2.n_failed_variables}/{r2.n_variables})")
+
+    # Test 3: Severe contamination (multiple exceedances)
+    severe = {
+        "nitrate_mg_l": 42.0,
+        "arsenic_ug_l": 28.0,
+        "fluoride_mg_l": 2.8,
+        "tds_mg_l": 1500.0,
+        "ph": 8.1,
+        "e_coli_cfu_100ml": 3.0,
+    }
+    r3 = compute_ccme_wqi(severe)
+    assert r3.wqi < r2.wqi, "Severe should score lower than moderate"
+    assert r3.category in ("POOR", "MARGINAL")
+    print(f"  Severe contam:        PASS (WQI={r3.wqi}, category={r3.category}, "
+          f"F1={r3.f1_scope}, F2={r3.f2_frequency}, F3={r3.f3_amplitude})")
+
+    # Test 4: F3 asymptotic behavior
+    extreme = {
+        "nitrate_mg_l": 500.0,  # 50x over limit
+        "arsenic_ug_l": 500.0,  # 50x over limit
+        "fluoride_mg_l": 10.0,
+        "tds_mg_l": 10000.0,
+        "ph": 4.0,
+        "e_coli_cfu_100ml": 100.0,
+    }
+    r4 = compute_ccme_wqi(extreme)
+    assert r4.f3_amplitude > 90, f"Extreme exceedances should have high F3: {r4.f3_amplitude}"
+    assert r4.wqi < 15, f"Extreme contamination should be near 0: {r4.wqi}"
+    print(f"  Extreme (asymptotic): PASS (WQI={r4.wqi}, F3={r4.f3_amplitude})")
+
+    # Test 5: Time-series measurements
+    timeseries = {
+        "nitrate_mg_l": [8.0, 9.0, 11.0, 12.0, 7.0, 15.0, 6.0, 8.0, 13.0, 9.0],
+        "arsenic_ug_l": [3.0, 4.0, 5.0, 3.0, 6.0],
+        "fluoride_mg_l": [0.8, 0.9, 1.0, 1.1],
+        "tds_mg_l": [400, 420, 380, 450, 510, 390],
+        "ph": [7.0, 7.1, 7.2, 6.9, 7.3],
+        "e_coli_cfu_100ml": [0, 0, 0, 1, 0],
+    }
+    r5 = compute_ccme_wqi(timeseries)
+    # F2 should be different from F1 because not all tests of a failed parameter fail
+    print(f"  Time-series:          PASS (WQI={r5.wqi}, F1={r5.f1_scope}%, "
+          f"F2={r5.f2_frequency}%, n_tests={r5.n_tests})")
+
+    # Test 6: WQI to AquiScore mapping
+    score_excellent = ccme_wqi_to_score(98.0)
+    score_good = ccme_wqi_to_score(85.0)
+    score_fair = ccme_wqi_to_score(70.0)
+    score_marginal = ccme_wqi_to_score(50.0)
+    score_poor = ccme_wqi_to_score(20.0)
+    assert score_excellent > score_good > score_fair > score_marginal > score_poor
+    print(f"  WQI→Score mapping:    PASS (98→{score_excellent:.0f}, 85→{score_good:.0f}, "
+          f"70→{score_fair:.0f}, 50→{score_marginal:.0f}, 20→{score_poor:.0f})")
+
+    print("\n  All tests passed.")
+    print("=" * 72)

pipeline/drastic_rating.py

@@ -0,0 +1,486 @@
+"""
+AquiScore v2.0 — DRASTIC Groundwater Vulnerability Rating Framework
+
+Implements the US EPA DRASTIC framework (Aller et al. 1987) as a
+documented, auditable vulnerability assessment component for AquiScore.
+
+============================================================================
+WHY THIS MATTERS (for Environmental Data Engineers)
+============================================================================
+
+DRASTIC is the most widely validated groundwater vulnerability index
+globally, cited in over 2,000 peer-reviewed studies. It provides
+documented, reproducible rating tables that map raw hydrogeological
+measurements to standardized 1-10 vulnerability ratings.
+
+v1.x computed substrate and well scores using ad hoc scoring functions
+without standardized rating tables. v2.0 adds DRASTIC as an AUDITABLE
+reference framework with published, peer-reviewed rating breakpoints.
+
+AquiScore does NOT replace its composite scoring model with DRASTIC.
+Instead, DRASTIC serves as:
+  1. A validation reference (does AquiScore agree with DRASTIC rankings?)
+  2. An auditable sub-index that risk assessors can reference
+  3. A standardized rating table for vulnerability reporting
+
+============================================================================
+THE SEVEN DRASTIC PARAMETERS
+============================================================================
+
+| Param | Name                    | Weight | What It Measures                |
+|-------|-------------------------|--------|---------------------------------|
+| D     | Depth to water table    | 5      | Travel time for contaminants    |
+| R     | Net Recharge            | 4      | Volume of water reaching aquifer|
+| A     | Aquifer media           | 3      | Permeability of aquifer material|
+| S     | Soil media              | 2      | Attenuation capacity of soil    |
+| T     | Topography (slope)      | 1      | Surface runoff vs infiltration  |
+| I     | Impact of vadose zone   | 5      | Unsaturated zone permeability   |
+| C     | Hydraulic Conductivity  | 3      | Flow rate through aquifer       |
+
+DRASTIC Index = Σ(Rating_i × Weight_i)
+Range: 23 (minimum vulnerability) to 230 (maximum vulnerability)
+
+Note: DRASTIC measures VULNERABILITY (higher = worse).
+AquiScore measures SECURITY (higher = better).
+The conversion is: security_score = 100 × (1 - (DI - 23) / (230 - 23))
+
+Reference:
+  Aller, L. et al. (1987) DRASTIC: A standardized system for evaluating
+  ground water pollution potential using hydrogeologic settings.
+  US EPA Report 600/2-87-035.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ── DRASTIC RATING TABLES ──────────────────────────────────────────────────
+# Each table maps measurement ranges to ratings (1-10).
+# Source: Aller et al. (1987), Table 1-7.
+
+# D: Depth to Water (meters)
+# Shallower = higher vulnerability (rating 10 = most vulnerable)
+DEPTH_RATINGS = [
+    # (min_m, max_m, rating)
+    (0.0,    1.5,   10),
+    (1.5,    4.6,   9),
+    (4.6,    9.1,   7),
+    (9.1,   15.2,   5),
+    (15.2,  22.9,   3),
+    (22.9,  30.5,   2),
+    (30.5, 9999.0,  1),
+]
+
+# R: Net Recharge (mm/year)
+# Higher recharge = more contaminant transport = higher vulnerability
+RECHARGE_RATINGS = [
+    # (min_mm_yr, max_mm_yr, rating)
+    (0,     50,   1),
+    (50,   100,   3),
+    (100,  175,   6),
+    (175,  250,   8),
+    (250, 9999,   9),
+]
+
+# A: Aquifer Media
+# Rating by aquifer material type (from least to most permeable)
+AQUIFER_MEDIA_RATINGS = {
+    "massive_shale":           2,
+    "metamorphic_igneous":     3,
+    "weathered_metamorphic":   4,
+    "glacial_till":            5,
+    "bedded_sandstone":        6,
+    "massive_limestone":       6,
+    "sand_gravel":             8,
+    "basalt":                  9,
+    "karst_limestone":         10,
+}
+
+# S: Soil Media
+# Rating by soil type (attenuation capacity)
+SOIL_MEDIA_RATINGS = {
+    "thin_absent":             10,
+    "gravel":                  10,
+    "sand":                    9,
+    "peat":                    8,  # High organic content, but permeable
+    "shrinking_clay":          7,
+    "sandy_loam":              6,
+    "loam":                    5,
+    "silty_loam":              4,
+    "clay_loam":               3,
+    "muck":                    2,
+    "non_shrinking_clay":      1,
+}
+
+# T: Topography (% slope)
+# Flatter terrain = more infiltration = higher vulnerability
+TOPOGRAPHY_RATINGS = [
+    # (min_pct, max_pct, rating)
+    (0,    2,   10),
+    (2,    6,   9),
+    (6,   12,   5),
+    (12,  18,   3),
+    (18, 999,   1),
+]
+
+# I: Impact of Vadose Zone Media
+# Rating by vadose zone material (most to least permeable)
+VADOSE_ZONE_RATINGS = {
+    "silt_clay":               1,
+    "shale":                   3,
+    "limestone":               6,
+    "sandstone":               6,
+    "bedded_limestone_sand":   6,
+    "sand_gravel_with_silt":   6,
+    "sand_gravel":             8,
+    "basalt":                  9,
+    "karst_limestone":         10,
+}
+
+# C: Hydraulic Conductivity (m/day)
+# Higher conductivity = faster contaminant transport
+CONDUCTIVITY_RATINGS = [
+    # (min_m_day, max_m_day, rating)
+    (0.0,      4.1,   1),
+    (4.1,     12.2,   2),
+    (12.2,    28.5,   4),
+    (28.5,    40.7,   6),
+    (40.7,    81.5,   8),
+    (81.5,  99999.0,  10),
+]
+
+# DRASTIC Weights (original EPA)
+DRASTIC_WEIGHTS = {
+    "D": 5,  # Depth to water
+    "R": 4,  # Net Recharge
+    "A": 3,  # Aquifer media
+    "S": 2,  # Soil media
+    "T": 1,  # Topography
+    "I": 5,  # Impact of vadose zone
+    "C": 3,  # Hydraulic Conductivity
+}
+
+
+# ── RATING LOOKUP FUNCTIONS ─────────────────────────────────────────────────
+
+def rate_depth(depth_m: float) -> int:
+    """Rate depth to water table (D parameter). Higher rating = more vulnerable."""
+    for lo, hi, rating in DEPTH_RATINGS:
+        if lo <= depth_m < hi:
+            return rating
+    return 1  # Very deep
+
+
+def rate_recharge(recharge_mm_yr: float) -> int:
+    """Rate net recharge (R parameter)."""
+    for lo, hi, rating in RECHARGE_RATINGS:
+        if lo <= recharge_mm_yr < hi:
+            return rating
+    return 9  # Very high recharge
+
+
+def rate_aquifer_media(media_type: str) -> int:
+    """Rate aquifer media (A parameter)."""
+    return AQUIFER_MEDIA_RATINGS.get(media_type, 5)  # Default: moderate
+
+
+def rate_soil_media(soil_type: str) -> int:
+    """Rate soil media (S parameter)."""
+    return SOIL_MEDIA_RATINGS.get(soil_type, 5)  # Default: loam
+
+
+def rate_topography(slope_pct: float) -> int:
+    """Rate topography/slope (T parameter)."""
+    for lo, hi, rating in TOPOGRAPHY_RATINGS:
+        if lo <= slope_pct < hi:
+            return rating
+    return 1  # Very steep
+
+
+def rate_vadose_zone(media_type: str) -> int:
+    """Rate impact of vadose zone (I parameter)."""
+    return VADOSE_ZONE_RATINGS.get(media_type, 5)  # Default: moderate
+
+
+def rate_conductivity(k_m_day: float) -> int:
+    """Rate hydraulic conductivity (C parameter)."""
+    for lo, hi, rating in CONDUCTIVITY_RATINGS:
+        if lo <= k_m_day < hi:
+            return rating
+    return 10  # Very high conductivity
+
+
+def conductivity_m_s_to_m_day(k_m_s: float) -> float:
+    """Convert hydraulic conductivity from m/s to m/day."""
+    return k_m_s * 86400.0
+
+
+# ── DRASTIC INDEX COMPUTATION ──────────────────────────────────────────────
+
+@dataclass
+class DRASTICResult:
+    """
+    DRASTIC vulnerability assessment result.
+
+    Attributes:
+        drastic_index: Raw DRASTIC index (23-230). Higher = more vulnerable.
+        vulnerability_class: LOW / MODERATE / HIGH / VERY_HIGH.
+        security_score: Inverted score for AquiScore (0-100). Higher = more secure.
+        parameter_ratings: Dict of each parameter's rating and weighted contribution.
+        dominant_factor: Parameter contributing most to vulnerability.
+        interpretation: Human-readable interpretation for risk assessors.
+    """
+    drastic_index: int
+    vulnerability_class: str
+    security_score: float
+    parameter_ratings: dict
+    dominant_factor: str
+    interpretation: str
+
+
+def compute_drastic(
+    depth_m: float,
+    recharge_mm_yr: float = 150.0,
+    aquifer_media: str = "sand_gravel",
+    soil_media: str = "loam",
+    slope_pct: float = 3.0,
+    vadose_zone: str = "sand_gravel",
+    conductivity_m_s: float = 1e-5,
+) -> DRASTICResult:
+    """
+    Compute the DRASTIC groundwater vulnerability index.
+
+    All seven parameters are rated on 1-10 scales using published
+    EPA rating tables, then combined with official weights.
+
+    For AquiScore integration: the DRASTIC index is inverted to a
+    security score (0-100) where higher = more secure.
+
+    Args:
+        depth_m: Depth to water table in meters.
+        recharge_mm_yr: Net recharge in mm/year (default 150 = moderate).
+        aquifer_media: Aquifer material type (key from AQUIFER_MEDIA_RATINGS).
+        soil_media: Soil type (key from SOIL_MEDIA_RATINGS).
+        slope_pct: Surface slope in percent.
+        vadose_zone: Vadose zone material (key from VADOSE_ZONE_RATINGS).
+        conductivity_m_s: Hydraulic conductivity in m/s.
+
+    Returns:
+        DRASTICResult with index, vulnerability class, and component breakdown.
+    """
+    k_m_day = conductivity_m_s_to_m_day(conductivity_m_s)
+
+    ratings = {
+        "D": {"rating": rate_depth(depth_m), "weight": DRASTIC_WEIGHTS["D"],
+               "input": f"{depth_m:.1f} m", "param": "Depth to water"},
+        "R": {"rating": rate_recharge(recharge_mm_yr), "weight": DRASTIC_WEIGHTS["R"],
+               "input": f"{recharge_mm_yr:.0f} mm/yr", "param": "Net Recharge"},
+        "A": {"rating": rate_aquifer_media(aquifer_media), "weight": DRASTIC_WEIGHTS["A"],
+               "input": aquifer_media, "param": "Aquifer media"},
+        "S": {"rating": rate_soil_media(soil_media), "weight": DRASTIC_WEIGHTS["S"],
+               "input": soil_media, "param": "Soil media"},
+        "T": {"rating": rate_topography(slope_pct), "weight": DRASTIC_WEIGHTS["T"],
+               "input": f"{slope_pct:.1f}%", "param": "Topography"},
+        "I": {"rating": rate_vadose_zone(vadose_zone), "weight": DRASTIC_WEIGHTS["I"],
+               "input": vadose_zone, "param": "Vadose zone impact"},
+        "C": {"rating": rate_conductivity(k_m_day), "weight": DRASTIC_WEIGHTS["C"],
+               "input": f"{k_m_day:.2f} m/day", "param": "Hydraulic Conductivity"},
+    }
+
+    # Compute weighted contributions
+    drastic_index = 0
+    max_contribution = 0
+    dominant = "D"
+
+    for code, info in ratings.items():
+        contribution = info["rating"] * info["weight"]
+        info["weighted_contribution"] = contribution
+        drastic_index += contribution
+        if contribution > max_contribution:
+            max_contribution = contribution
+            dominant = code
+
+    # Vulnerability classification (based on published DRASTIC interpretations)
+    if drastic_index < 80:
+        vuln_class = "LOW"
+    elif drastic_index < 120:
+        vuln_class = "MODERATE"
+    elif drastic_index < 160:
+        vuln_class = "HIGH"
+    else:
+        vuln_class = "VERY_HIGH"
+
+    # Convert to security score (invert: low vulnerability = high security)
+    # DI range: 23 (min) to 230 (max)
+    security_score = max(0.0, min(100.0, 100.0 * (1.0 - (drastic_index - 23) / (230 - 23))))
+
+    # Interpretation
+    dominant_info = ratings[dominant]
+    interpretation = (
+        f"DRASTIC Index = {drastic_index} ({vuln_class} vulnerability). "
+        f"The dominant vulnerability factor is {dominant_info['param']} "
+        f"({dominant_info['input']}, rating={dominant_info['rating']}, "
+        f"weight={dominant_info['weight']}, contribution={dominant_info['weighted_contribution']}). "
+    )
+
+    if vuln_class == "LOW":
+        interpretation += (
+            "The aquifer is well-protected by natural hydrogeological barriers. "
+            "Low intrinsic vulnerability to surface contamination."
+        )
+    elif vuln_class == "MODERATE":
+        interpretation += (
+            "The aquifer has moderate natural protection. "
+            "Some vulnerability to persistent contaminants with high mobility."
+        )
+    elif vuln_class == "HIGH":
+        interpretation += (
+            "The aquifer is significantly vulnerable to contamination. "
+            "Recommend enhanced monitoring and land use controls in recharge zones."
+        )
+    else:
+        interpretation += (
+            "The aquifer is highly vulnerable to contamination from surface sources. "
+            "Immediate attention required for protection of recharge areas. "
+            "Any contamination event will likely reach groundwater rapidly."
+        )
+
+    return DRASTICResult(
+        drastic_index=drastic_index,
+        vulnerability_class=vuln_class,
+        security_score=round(security_score, 1),
+        parameter_ratings=ratings,
+        dominant_factor=dominant,
+        interpretation=interpretation,
+    )
+
+
+# ── AQUIFER TYPE TO DRASTIC MEDIA MAPPING ──────────────────────────────────
+# Maps AquiScore aquifer_type keys to DRASTIC media types for automated assessment
+
+AQUIFER_TYPE_TO_DRASTIC = {
+    "unconfined_alluvial":  {"aquifer_media": "sand_gravel", "vadose_zone": "sand_gravel", "soil_media": "sandy_loam"},
+    "unconfined_fractured": {"aquifer_media": "weathered_metamorphic", "vadose_zone": "sandstone", "soil_media": "loam"},
+    "semi_confined":        {"aquifer_media": "bedded_sandstone", "vadose_zone": "sand_gravel_with_silt", "soil_media": "silty_loam"},
+    "confined_sedimentary": {"aquifer_media": "bedded_sandstone", "vadose_zone": "silt_clay", "soil_media": "clay_loam"},
+    "confined_crystalline": {"aquifer_media": "metamorphic_igneous", "vadose_zone": "shale", "soil_media": "non_shrinking_clay"},
+    "karst":                {"aquifer_media": "karst_limestone", "vadose_zone": "karst_limestone", "soil_media": "thin_absent"},
+}
+
+
+def compute_drastic_from_aquifer_type(
+    aquifer_type: str,
+    depth_m: float,
+    conductivity_m_s: float = 1e-5,
+    recharge_mm_yr: float = 150.0,
+    slope_pct: float = 3.0,
+) -> DRASTICResult:
+    """
+    Compute DRASTIC using AquiScore aquifer_type to auto-populate media types.
+
+    Convenience function that maps AquiScore's 6 aquifer types to DRASTIC's
+    media rating tables. For full control, use compute_drastic() directly.
+
+    Args:
+        aquifer_type: One of AQUIFER_TYPE_TO_DRASTIC keys.
+        depth_m: Depth to water table in meters.
+        conductivity_m_s: Hydraulic conductivity in m/s.
+        recharge_mm_yr: Net annual recharge in mm.
+        slope_pct: Surface slope in percent.
+
+    Returns:
+        DRASTICResult with full vulnerability assessment.
+    """
+    mapping = AQUIFER_TYPE_TO_DRASTIC.get(aquifer_type, AQUIFER_TYPE_TO_DRASTIC["unconfined_alluvial"])
+
+    return compute_drastic(
+        depth_m=depth_m,
+        recharge_mm_yr=recharge_mm_yr,
+        aquifer_media=mapping["aquifer_media"],
+        soil_media=mapping["soil_media"],
+        slope_pct=slope_pct,
+        vadose_zone=mapping["vadose_zone"],
+        conductivity_m_s=conductivity_m_s,
+    )
+
+
+# ── SELF-TEST ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    print("=" * 72)
+    print("AquiScore v2.0 — DRASTIC Vulnerability Framework — Self-Test")
+    print("=" * 72)
+
+    # Test 1: Low vulnerability (deep, confined, low-K)
+    r1 = compute_drastic(
+        depth_m=40.0,
+        recharge_mm_yr=50.0,
+        aquifer_media="massive_shale",
+        soil_media="non_shrinking_clay",
+        slope_pct=15.0,
+        vadose_zone="silt_clay",
+        conductivity_m_s=1e-8,
+    )
+    assert r1.vulnerability_class == "LOW", f"Expected LOW: {r1.vulnerability_class}"
+    assert r1.security_score > 70
+    print(f"  Low vulnerability:    PASS (DI={r1.drastic_index}, security={r1.security_score})")
+
+    # Test 2: High vulnerability (shallow, karst, high-K)
+    r2 = compute_drastic(
+        depth_m=2.0,
+        recharge_mm_yr=300.0,
+        aquifer_media="karst_limestone",
+        soil_media="thin_absent",
+        slope_pct=1.0,
+        vadose_zone="karst_limestone",
+        conductivity_m_s=1e-3,
+    )
+    assert r2.vulnerability_class == "VERY_HIGH", f"Expected VERY_HIGH: {r2.vulnerability_class}"
+    assert r2.security_score < 30
+    print(f"  High vulnerability:   PASS (DI={r2.drastic_index}, security={r2.security_score})")
+
+    # Test 3: Ordering is correct (low vuln → high security, high vuln → low security)
+    assert r1.security_score > r2.security_score, "Low vulnerability should have higher security"
+    print(f"  Ordering:             PASS ({r1.security_score} > {r2.security_score})")
+
+    # Test 4: Rating tables produce valid ranges
+    for depth in [0.5, 3.0, 7.0, 12.0, 20.0, 25.0, 50.0]:
+        r = rate_depth(depth)
+        assert 1 <= r <= 10, f"Invalid depth rating {r} for {depth}m"
+    print(f"  Depth ratings:        PASS (1-10 range validated)")
+
+    for k_ms in [1e-9, 1e-7, 1e-5, 1e-4, 1e-3, 1e-2]:
+        k_md = conductivity_m_s_to_m_day(k_ms)
+        r = rate_conductivity(k_md)
+        assert 1 <= r <= 10, f"Invalid K rating {r} for {k_ms} m/s"
+    print(f"  Conductivity ratings: PASS (1-10 range validated)")
+
+    # Test 5: Auto-mapping from AquiScore aquifer types
+    for aq_type in AQUIFER_TYPE_TO_DRASTIC:
+        r = compute_drastic_from_aquifer_type(aq_type, depth_m=15.0)
+        assert 23 <= r.drastic_index <= 230
+    print(f"  Aquifer type mapping: PASS (all 6 types produce valid DI)")
+
+    # Test 6: Dominant factor identification
+    r_shallow = compute_drastic(depth_m=0.5, conductivity_m_s=1e-8)
+    # Shallow depth (rating 10 × weight 5 = 50) should dominate
+    assert r_shallow.dominant_factor == "D", f"Expected D dominant: {r_shallow.dominant_factor}"
+    print(f"  Dominant factor:      PASS (shallow water → D dominates)")
+
+    # Test 7: Full parameter breakdown
+    r_full = compute_drastic_from_aquifer_type("unconfined_alluvial", depth_m=10.0, conductivity_m_s=5e-4)
+    for code in "DRASTC":
+        # DRASTIC maps to D, R, A, S, T, I, C but we skip non-codes
+        pass
+    for code in ["D", "R", "A", "S", "T", "I", "C"]:
+        assert code in r_full.parameter_ratings
+        info = r_full.parameter_ratings[code]
+        assert 1 <= info["rating"] <= 10
+        assert info["weight"] == DRASTIC_WEIGHTS[code]
+    print(f"  Full breakdown:       PASS (all 7 parameters rated and weighted)")
+
+    print("\n  All tests passed.")
+    print("=" * 72)