docs: Rust rewrite assessment + forecast parity spike

spikes/rust-forecast ports build_features (P.1 path) and HistGradientBoosting
inference to Rust and checks them against the pandas/sklearn output on two
fixtures (2024 record flood, summer 2026): 244,800 feature cells and every
regression prediction bit-identical, classifier heads to the last ulp;
0.25 ms vs 158 ms per station. docs/RUST_REWRITE.md: what a rewrite would
mean (Rust service, Python training), costs, phased plan, Python alternative.

spikes/rust-forecast/export/export_fixture.py

@@ -0,0 +1,132 @@
+"""Export a trained flood bundle + a feature/prediction fixture for the Rust spike.
+
+Run from the monitor repo's environment:
+    uv run --project ../../.. python export_fixture.py   (from this directory)
+
+Writes ../data/model_<station>.json (all heads as flat tree arrays) and
+../data/fixture_<name>.json (observed hourly grid + rain, the Python feature
+matrix, and every head's Python prediction for every row).
+"""
+
+import json
+import math
+import sys
+from pathlib import Path
+
+import joblib
+import numpy as np
+import pandas as pd
+
+REPO = Path(__file__).resolve().parents[3]  # repo root
+sys.path.insert(0, str(REPO))
+
+from src.ml import features  # noqa: E402
+
+OUT = Path(__file__).resolve().parent.parent / "data"
+OUT.mkdir(exist_ok=True)
+STATION = "P.1"
+WINDOWS = {
+    "flood2024": ("2024-08-15", "2024-10-31"),  # record flood, high-level paths
+    "recent2026": ("2026-06-01", "2026-08-13"),  # latest cached data
+}
+
+
+def clean(values):
+    return [None if (v is None or (isinstance(v, float) and math.isnan(v))) else float(v) for v in values]
+
+
+def export_head(est):
+    preds = est._predictors
+    assert all(len(it) == 1 for it in preds), "multiclass not expected"
+    trees = []
+    for (tp,) in preds:
+        n = tp.nodes
+        assert not n["is_categorical"].any()
+        assert np.isfinite(n["value"]).all() and not np.isneginf(n["num_threshold"]).any()
+        assert not np.isnan(n["num_threshold"]).any()
+        trees.append(
+            {
+                "feature": n["feature_idx"].astype(int).tolist(),
+                # +inf thresholds (a "missing vs everything" split) are not
+                # valid JSON: written as null, read back as +inf in Rust
+                "threshold": [
+                    None if np.isposinf(t) else float(t) for t in n["num_threshold"]
+                ],
+                "missing_left": n["missing_go_to_left"].astype(bool).tolist(),
+                "left": n["left"].astype(int).tolist(),
+                "right": n["right"].astype(int).tolist(),
+                "leaf": n["is_leaf"].astype(bool).tolist(),
+                "value": n["value"].astype(float).tolist(),
+            }
+        )
+    kind = "classifier" if hasattr(est, "predict_proba") else "regressor"
+    return {
+        "kind": kind,
+        "baseline": float(np.ravel(est._baseline_prediction)[0]),
+        "trees": trees,
+    }
+
+
+bundle = joblib.load(REPO / "models" / f"flood_{STATION}.joblib")
+model = {
+    "station_code": STATION,
+    "model_version": bundle["model_version"],
+    "regression_target": bundle.get("regression_target"),
+    "feature_names": bundle["feature_names"],
+    "horizons": bundle["horizons"],
+    "sigma": {str(k): float(v) for k, v in bundle["sigma"].items()},
+    "thresholds": bundle["thresholds"],
+    "heads": {name: export_head(est) for name, est in bundle["heads"].items()},
+}
+(OUT / f"model_{STATION}.json").write_text(json.dumps(model))
+n_nodes = sum(len(t["value"]) for h in model["heads"].values() for t in h["trees"])
+print(f"model {model['model_version']}: {len(model['heads'])} heads, {n_nodes} nodes")
+
+stations = [STATION] + [u for u, _ in features.UPSTREAM_LEADS[STATION]]
+long = pd.concat(
+    pd.read_csv(REPO / "models" / "cache" / f"{s}.csv.gz", parse_dates=["timestamp"])
+    for s in stations
+)
+rain_all = pd.read_csv(REPO / "models" / "cache" / "rain_openmeteo.csv.gz")
+print("rain columns:", list(rain_all.columns))
+ts_col = rain_all.columns[0]
+rain_all[ts_col] = pd.to_datetime(rain_all[ts_col])
+rain_all = rain_all.set_index(ts_col)[rain_all.columns[1]].astype(float)
+
+for name, (start, end) in WINDOWS.items():
+    df = long[(long.timestamp >= start) & (long.timestamp < end)]
+    grid = features.make_hourly_grid(df)
+    idx = grid.observed.index
+    rain = rain_all.reindex(idx)
+    # punch deterministic holes so NaN handling of the rolling sums is exercised
+    rain.iloc[::97] = np.nan
+    feats = features.build_features(grid, STATION, rain=rain)[model["feature_names"]]
+
+    preds = {}
+    for head_name, est in bundle["heads"].items():
+        if hasattr(est, "predict_proba"):
+            preds[head_name] = est.predict_proba(feats)[:, 1].tolist()
+        else:
+            preds[head_name] = est.predict(feats).tolist()
+
+    fixture = {
+        "station": STATION,
+        "timestamps": [t.strftime("%Y-%m-%dT%H:%M:%S") for t in idx],
+        "observed": {
+            s: {
+                "water_level": clean(grid.observed[(s, "water_level")].tolist()),
+                "discharge": clean(grid.observed[(s, "discharge")].tolist()),
+            }
+            for s in stations
+            if (s, "water_level") in grid.observed.columns
+        },
+        "rain": clean(rain.tolist()),
+        "feature_names": model["feature_names"],
+        "features": [clean(row) for row in feats.to_numpy().tolist()],
+        "predictions": preds,
+    }
+    (OUT / f"fixture_{name}.json").write_text(json.dumps(fixture))
+    print(
+        f"{name}: {len(idx)} hours, {len(fixture['observed'])} stations, "
+        f"P.1 max {np.nanmax(grid.observed[(STATION, 'water_level')]):.2f} m"
+    )

spikes/rust-forecast/export/time_python.py

@@ -0,0 +1,38 @@
+"""Python timing for the same serving-shaped work as the Rust spike."""
+
+import sys
+import time
+from pathlib import Path
+
+import joblib
+import numpy as np
+import pandas as pd
+
+REPO = Path(__file__).resolve().parents[3]  # repo root
+sys.path.insert(0, str(REPO))
+from src.ml import features  # noqa: E402
+
+bundle = joblib.load(REPO / "models" / "flood_P.1.joblib")
+stations = ["P.1"] + [u for u, _ in features.UPSTREAM_LEADS["P.1"]]
+long = pd.concat(
+    pd.read_csv(REPO / "models" / "cache" / f"{s}.csv.gz", parse_dates=["timestamp"])
+    for s in stations
+)
+df = long[(long.timestamp >= "2026-07-30") & (long.timestamp < "2026-08-13")]
+rain_all = pd.read_csv(REPO / "models" / "cache" / "rain_openmeteo.csv.gz", parse_dates=["timestamp"])
+rain_all = rain_all.set_index("timestamp")["chiang_dao"].astype(float)
+
+reps = 20
+t = time.perf_counter()
+for _ in range(reps):
+    grid = features.make_hourly_grid(df)
+    rain = rain_all.reindex(grid.observed.index)
+    row = features.build_features(grid, "P.1", rain=rain)[bundle["feature_names"]].iloc[[-1]]
+    out = {
+        k: (h.predict_proba(row)[0, 1] if hasattr(h, "predict_proba") else h.predict(row)[0])
+        for k, h in bundle["heads"].items()
+    }
+print(f"python: grid + features + 9 heads for the last hour: {(time.perf_counter() - t) / reps * 1000:.1f} ms per station")
+t = time.perf_counter()
+joblib.load(REPO / "models" / "flood_P.1.joblib")
+print(f"python: bundle load {(time.perf_counter() - t) * 1000:.0f} ms")