feat: Mae Ngat dam features — built, evaluated, defaulted OFF

src/ml/dam.py loads rid_reservoir_daily into a leakage-safe hourly frame
(daily row visible from 07:00 its own date, ffill capped at 48 h) and is
plumbed through features/train/predict/evaluate exactly like rain, gated
to the six mainstem stations below the Mae Ngat confluence.

The experiment concludes as a documented NEGATIVE result: on the 2024
record-flood backtest every dam-feature subset costs 1-3 h of first-alert
lead (13h -> 10-12h) for <=3 cm of peak-error gain, because the daily RID
report lags up to 31 h and describes yesterday's benign absorbing
reservoir during fast onset. Features therefore default OFF (--dam
opt-in on the training and backtest CLIs; rise_rain_dam/rise_dam harness
variants, excluded from the default variant set). The ablation also
isolated the HII gap-fill as lead-neutral: the acceptance gate holds at
13 h with fill enabled, and docs/img charts are regenerated with the
shipping configuration. Full table in docs/FLOOD_FORECASTING.md §5.

Review-swarm fixes: evaluate.py skips variants whose feature family is
absent instead of crashing the run; --dam forwards --db-url and warns
loudly when no dam history loads; an empty DB result can no longer wipe
a good dam cache; run-level metrics version claims v4 only when a dam
station is actually in the set.

scripts/backtest_render.py

@@ -45,19 +45,23 @@ AMBER = "#c07d10"
 RED = "#d9534f"
 
 
-def fit_backtest_model(df_long: pd.DataFrame, train_end: str):
+def fit_backtest_model(df_long: pd.DataFrame, train_end: str, use_dam: bool = False):
     """Train the 24 h regression + warning heads on rows <= train_end only.
 
     Mirrors the deployed hgb-v3 pipeline: the regression head learns the RISE
     over the current level, with Open-Meteo catchment-rain features (trailing
     sums + the forward-24h forecast sum); label statistics are bounded to the
-    training cutoff.
+    training cutoff. use_dam=True adds the Mae Ngat reservoir columns — an
+    ablation-only configuration (2026-08-13 result: costs 1-3 h of lead).
     """
+    from src.ml import dam as dam_mod
     from src.ml import rain as rain_mod
 
     rain_series = rain_mod.catchment_mean(rain_mod.load_history())
+    dam_frame = dam_mod.load_history() if use_dam else None
     X, Y, _meta = features.build_matrix(
-        df_long, STATION, (HORIZON,), stats_end=train_end, rain=rain_series
+        df_long, STATION, (HORIZON,), stats_end=train_end, rain=rain_series,
+        dam=dam_frame,
     )
     train_mask = X.index <= pd.Timestamp(train_end)
     X_train, Y_train = X.loc[train_mask], Y.loc[train_mask]
@@ -200,16 +204,23 @@ def main(argv=None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--db-url", default=None)
     parser.add_argument("--out-dir", default=os.path.join("docs", "img"))
+    parser.add_argument("--dam", action="store_true",
+                        help="ablation: include Mae Ngat reservoir features "
+                             "(2026-08 result: costs 1-3 h of alert lead)")
+    parser.add_argument("--no-hii-fill", action="store_true",
+                        help="ablation: load without the HII gap-fill merge")
     args = parser.parse_args(argv)
 
-    df = data.load_measurements(db_url=args.db_url)
+    df = data.load_measurements(
+        db_url=args.db_url, hii_fill=not args.no_hii_fill
+    )
     if df.empty:
         print("no measurement data available", file=sys.stderr)
         return 1
     os.makedirs(args.out_dir, exist_ok=True)
 
     # --- October 2024 record flood: trained only on data before 1 Sep 2024 ---
-    X, reg, clf = fit_backtest_model(df, "2024-08-31")
+    X, reg, clf = fit_backtest_model(df, "2024-08-31", use_dam=args.dam)
     obs, fc, flood_start, first_alert = event_series(
         df, X, reg, clf, "2024-09-10", "2024-10-14 23:00")
     peak = float(obs.max())
@@ -235,7 +246,7 @@ def main(argv=None) -> int:
            detail=True)
 
     # --- September 2025 flood: the deployed configuration (trained <= 2024) ---
-    X25, reg25, clf25 = fit_backtest_model(df, "2024-12-31")
+    X25, reg25, clf25 = fit_backtest_model(df, "2024-12-31", use_dam=args.dam)
     obs25, fc25, flood25, alert25 = event_series(
         df, X25, reg25, clf25, "2025-09-22", "2025-10-02 12:00")
     pred_at_alert = float(fc25.loc[alert25:, "pred_max"].iloc[:24].max()) if alert25 is not None else None