[taddyb]

Adds gridded (ISIMIP DDM30) routing to ddrs as a data source, mirroring DeepGroundwater/ddr#194, plus the ddrs-run skill and three code fixes that writing it turned up.

ddrs has no engine/ module and this does not add one. DDR#194 is a data-preparation feature (its own summary: "the routing engine, mmc.py, merit.py and the MERIT/Lynker paths are untouched"), so ddrs consumes its products and ports none of the raster aggregation or Q′ regridding.

1. Gridded routing

The key observation is that ddrs already had the right abstraction. Reach subdivision (params.subdivision) models exactly the structure a DDM30 sub-reach network has, so the whole routing / training / eval / baseline path is untouched and only the builder input is new:

Gridded sub-reach zarr (DDR)	ddrs subdivided store
parent_cell per row, contiguous, upstream-first	order, parent_order, parent_offset
attributes looked up by parent cell	AttributesStore::open(…, parent_order)
Q′ per cell ÷ k_per_node	pieces_per_row_divisor
gauge outlet = cell's last sub-reach	outlet(p) = parent_offset[p+1] − 1

New data_sources.gridded_network names DDR's sub-reach adjacency zarr; ddrs plan relabels it into that layout and cuts the gauge subgraphs (src/adjacency/gridded.rs, cache::resolve_or_build_gridded). The gauge CSV's cell column is a serde alias of COMID. The key is mutually exclusive with geospatial_fabric and the explicit adjacency pair, and params.subdivision.enabled is rejected alongside it because the store arrives already split.

Results on the committed examples/juniata_gridded/ bundle (byte-identical to DDR's, CPU, 30 epochs):

	NSE	KGE
summed-Q′ baseline, ddrs / DDR	0.594 / 0.594	0.672 / 0.671
routed, seed 42	0.751	0.730
routed, seeds {42, 7, 123}	0.744–0.758	0.728–0.732
routed, DDR Python	0.795	0.737

The baseline is deterministic and matches DDR to rounding through independent readers, which makes it a live cross-implementation check. The routed gap has two known causes, both recorded in the spec: different RNG window streams, and ddrs running the KAN head per cell where DDR runs it per sub-reach with an accumulated log10_uparea. ddrs also applies no da_ratio output correction.

CONUS is wired up too (config/sources/conus-gridded.yaml, config/experiments/gridded_conus.yaml, scripts/snap_gridded_gauges.py reproducing DDR's 620-gauge population). plan builds 5,198 cells into 91,867 sub-reaches in 0.6 s; baseline median NSE 0.354. Training beyond a mechanics smoke was not run.

Two bugs this exposed

• upstream_comids was per-piece on subdivided stores, so the summed-Q′ baseline counted each divide once per sub-reach. This also affected MERIT params.subdivision baselines.
• DDR's gridded Q′ stores are Qr(time, divide_id), the transpose of the contract, and zarrs answers an out-of-range subset with fill values rather than an error, so the fixed-axis reader silently produced an all-NaN baseline. The reader now sniffs the axis order from dimension names, falls back to shape, and refuses a shape matching neither. Fixture: tests/fixtures/qr_daily_time_major.ic.

2. ddrs-run skill

A third repo skill covering launching, watching, resuming and auditing runs, and every ddrs subcommand, split from ddrs-dev (build/code/test) and ddrs-eval-plots (visualize). Written against the binary and source rather than from memory, and tested with a subagent doing a realistic task with and without it.

3. Three code fixes

That testing found five documentation defects; three were real code bugs, now fixed:

• ddrs show printed no metrics in text mode. They lived only in --json, so ddrs show <id> | grep nse came back empty on a healthy run and read like a failure — and ddrs-eval-plots recommended exactly that grep. Text mode now prints the metrics block and, for a train-and-test run, reduces the baseline (whose entries are per-gauge arrays, not medians) to a median per metric beside the routed value and delta, flagging when routed loses:

baseline (summed Q', median over gauges)
  NSE                    0.5943   routed 0.7511   Δ +0.1568

• geodataset: was validated by nothing. Being provenance-only is what made a wrong value dangerous: the run succeeds and its audit trail names the wrong network, and ddrs sources use swaps only the data_sources block so a stale label survives a dataset switch. Absent is now inferred from the adjacency source; contradicting is a load error; explicit adjacency paths stay unconstrained because a pre-built store can be either network.
• A typo'd config key silently took its default, the documented single most common cause of "my config change did nothing". All seven remaining config structs now set deny_unknown_fields.

Gates

Gate	Result
cargo test	630 passed / 0 failed, 101 binaries
compare_ddr_sandbox	ABSOLUTE MATCH
juniata_acceptance	NSE 0.7903 / KGE 0.8810
gridded_acceptance	NSE 0.7511 / KGE 0.7299

Both acceptance figures are identical to their pre-fix values, which is the evidence that the routing path is untouched. Invariants 1–7 are unaffected.

Review notes

• deny_unknown_fields is the one change with real blast radius. Every shipped config and all 630 tests pass, but a personal ddrs.yaml or an old run snapshot carrying a stray or removed key will now fail to load instead of ignoring it. Intended, and loud rather than silent, but it is a behaviour change.
• Only DDR's sub-reach network is supported. The unsplit cell adjacency (no parent_cell) is rejected with a message naming the script that produces a sub-reach store.
• Design, assumptions and deviations: docs/superpowers/specs/2026-09-08-ddrs-gridded-routing-design.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EqnrtmU91yzuVpGnADnXLP