Port ddrs ddr_match corrections: outflow_idx fix, neg-solve counter, signed tau, β + Cunge X

[taddyb]

Summary

Ports the corrections the ddrs repo developed behind its ddr_match config flag (where ddr_match: true reproduced this repo bit-for-bit and false enabled corrected behavior — all ddrs production configs now run false). This lands as a clean break: no compatibility flag; old results reproduce from old commit hashes.

Sources of truth: ddrs .claude/PHYSICS-CORRECTIONS.md, docs/2026-08-03-ddr-match-findings.md, docs/2026-08-06-tau-sweep-pilot-findings.md §5i. Spec and plan are committed under docs/superpowers/.

Changes (one commit per stage, in dependency order)

1. fix(merit): gauge-reach outflow_idx extraction — the MERIT collate summed a gauge's upstream columns, dropping the gauge reach's own local drainage (0.215× observed on the worst small basins; 26/1841 gauges below 0.5× baseline). The MC solve at the gauge reach already carries upstream flow plus its own lateral inflow. Side effect: partial-area flow_scale corrections now actually reach MERIT predictions.
2. feat(routing): negative-solve counter — counts solve output < 0 before the discharge_lb clamp rewrites it (mass creation), logs the per-forward rate. Tripwire for stage 4 (~0.1% expected, ddrs-measured).
3. feat(tau)!: signed-at-zero tau convention, default 9 — slice [tau : -(24−tau)], pooled day i scored against obs day i (tau=0 day-aligned). The shipped legacy tau=3 was signed −8, mis-set in the wrong direction; ddrs measured the fix alone at +0.086 median NSE, flipping routing from losing to the summed-Q' baseline to beating it. Also unifies train.py's inconsistent inline slice ([13 : -11+tau], a fractional-day window) with the shared helper. Legacy pin: new tau=16 cuts the same hour window as legacy tau=3.
4. feat(routing)!: trapezoid-exact celerity + Cunge-derived X — c = v·β with β = 5/3 − (4/3)·A·√(1+z²)/(T·P) (the hardcoded 5/3 is the wide-rectangular limit, 22–27% high on real channels), and X = clamp(0.5·(1 − Q/(T·S·c·L)), 0, 0.5) computed per timestep, replacing the static per-reach x (MERIT constant 0.3, Lynker zarr) whose plumbing is removed end to end. Autograd supplies the backward.

Deliberately not ported (measured NO-GOs in ddrs): enforce_positivity, reach subdivision, Courant sub-stepping, slope-floor removal, leakance.

Breaking changes

• All pre-port checkpoints are invalidated (trained on legacy physics and the legacy tau window); config tau values do not carry across the convention change.
• RoutingDataclass.x is removed.

Known trade

Cunge X ≈ 0.5 on most CONUS reaches narrows the non-negative-coefficient window 2X ≤ Cr ≤ 2(1−X); negative Muskingum coefficients rise (artifacts), while negative solves stayed ~0.1% in ddrs. The stage-2 counter reports the rate every forward — a retrain showing a rate far above ~0.1% is a stop-and-investigate signal.

Test plan

• Full unit suite: 643 passed, 1 skipped
• New gates: β limits + finite-difference dQ/dA (1e-6), Cunge diffusion-matching identity, c1+c2+c3 = 1, gradient flow through the X path, tau legacy-equivalence pin, gauge-reach extraction
• User-run: MERIT retrain — expect routing to beat the summed-Q' baseline directionally (ddrs: 0.706 vs 0.642 median NSE); retrains at the stage-3 vs stage-4 commits attribute tau vs physics separately

🤖 Generated with Claude Code