docs(debug-journal): a replay cannot test a fix whose inputs are built in fetch_sensor_data()

tools/debug-journal.md

@@ -25,6 +25,8 @@ Committed examples of the same format live in `coverage/cases/*.yaml`; they run
 
 **A replay cannot reproduce ML-forecast-dependent plan choices.** `--redo` resets the load model, and the live ML forecast cannot be replayed from the dump — so a replay differing from the live plan in exactly the optimiser's marginal ~10p slots is expected, not proof the slot is a bug (GH#5213). Treat "replay doesn't show it" as inconclusive when the candidate choice is worth ~10p; the decisive check is whether the *same version's own* plan in the attached log contains the slot — grep `Best export window`/`Best charge window` lines per version window in their log. The same recipe replays a dump outside `--debug_file`: register a temporary test function in `TEST_REGISTRY` that calls `run_single_debug(..., redo=True)` (`tests/test_single_debug.py`), run via `tools/triage_test.sh` — which is also the only way to exercise the fetch-layer threshold logic (`set_rate_thresholds()` + the `rate_scan_window()` rescan) on a dump's rates, since the dump's stored threshold/windows are live-run end state, useful for the symptom but not for re-derivation (GH#5221).
 
+**A replay only sees state that is in the dump, so it cannot test a fix whose inputs are built inside `fetch_sensor_data()`.** `run_single_debug(..., redo=True)` re-runs `set_rate_thresholds()` and the `rate_scan_window()` rescan on the dump's stored `rate_import`/`rate_export`, but never calls `fetch_sensor_data()`, so nothing that fetch builds alongside the rates is rebuilt. Where the code under test falls back quietly when that state is missing, the replay behaves exactly like the code without the fix, and the outcome looks like "the fix doesn't work". This happened twice on GH#5221 with PR #5163 (still open at the time): its `rate_minmax_excluding_saving()` needs `rate_export_saving_minutes` and `rate_export_pre_saving`, which only fetch fills in, right after `load_axle_slot()`/`load_saving_slot()`. On a replay they are empty, so it drops back to plain `rate_minmax()`, and the Axle-boosted dump still gave main's 20.5p export threshold instead of the 19.9p the fix produces. Established by reading the code, not by a run: the harness path in `tests/test_single_debug.py`, and the empty-`rate_base` fallback in the #5163 diff. Before blaming the fix, check that the replay log shows the value the fix *should* produce. If it shows the pre-fix value, the fix never ran. Prove the fix with a synthetic test that goes through the real fetch sequence, or rebuild the missing state in the replay by hand.
+
 **A v9.1.0+ dump can crash the loader itself before any Predbat code runs.** Dumps written by v9.1.0+ can carry cached `numpy.dtype` objects (`!!python/object/apply:numpy.dtype`, anchored and aliased through `numpy._core.multiarray.scalar` entries), and the harness's `DEBUG_YAML_LOADER` (`userinterface.py`) raises `SystemError ... bad argument to internal function` from `dtype.__setstate__` on the coverage venv's numpy 2.x while loading (GH#5205 replay, verified three times on a 3.2 MB dump). Lossless replay workaround (throwaway edit next to the loader definition): wrap `yaml.constructor.UnsafeConstructor.set_python_instance_state` and skip state application when `type(instance).__module__` starts with `"numpy"` — the dtype is already fully defined by its constructor args, so skipping the legacy state tuple is lossless. Two guard mistakes that each cost a run: the instance type is not named `dtype` on numpy 2.x (`np.dtype('f8')`'s type is `Float64DType`), and the passthrough must use `*args/**kwargs` — this PyYAML version rejects an `unsafe=` kwarg. If this is ever fixed properly it belongs in the loader definition, not in the replay flow.
 
 Two lines in that output are normal and are not the reporter's bug: