fix(plan): convert phantom export windows to freeze in clip_export_slots (#4453)

[springfall2008]

Summary

Investigating #4453 (lone/random forced exports on flat export tariffs, e.g. the reporter's 09:55 lone export at 58%): replaying the attached debug capture reproduces the artifact deterministically — a short forced export window (12:35–13:00 at 92%) sandwiched between freeze windows, whose predicted SoC stays completely flat at 96.7% through the window. The commanded drain never happens because PV already saturates the export limit. It moves zero energy in the central forecast, yet it survives the whole pipeline.

Why it exists and why nothing removes it

• Why it wins over freeze (systematic, not a coin flip): a forced export whose target is at/above achievable SoC behaves as demand in the PV10 branch — charging from surplus is allowed — while freeze pins SoC and spills the PV10 surplus to grid. That gives the phantom a ~0.25 × pv10-value edge over freeze (measured +0.455p here) on any surplus-solar day.
• Why "off" (which scores best, +0.67p) is unreachable: removal is gated by metric_min_improvement_export (raised to 1.0p by the reporter to fight churn — scaled ~0.83p for the window; 0.67p < 0.83p).
• The purpose-built removal path is dead code: the drop=True branch of optimise_swap_export has no live caller (only the commented-out early invocation passes it). Its own gate (best_metric_drop <= selected_metric) would have deleted this window.
• Every clip_export_slots branch targets a different failure mode: battery pinned empty (fix(plan): clip export windows with no SoC above reserve #4434), or target unreachable from below. This window has SoC above target, so the clip-up branch fires and actively legitimises it.
• Once installed it is defended: removing it is worth well under metric_min_improvement_plan (2.0p), so should_replace_plan keeps it cycle after cycle.

The fix

In clip_export_slots, a forced export window whose predicted SoC is flat across the window while above the requested limit is converted to freeze export (99) rather than clipped up:

• In the simulation the phantom pinned SoC — exactly what freeze does — so the executed plan stays faithful to the plan that was scored (converting to off would substitute charging where the scored plan simulated a pin).
• The force-export command is dropped: in reality it would genuinely dump the battery to grid whenever live PV dips below the export limit, which is the visible misbehaviour reported in Predbat randomly exports instead of freeze export, often in the peak rate #4453.
• Falls back to off (100) when set_export_freeze is unsupported; manual exports are preserved.
• If conditions worsen toward the PV10 case, a genuine export re-appears on a later recompute from real SoC.

Confirmed on the reporter's capture: the lone export becomes freeze and merges with its neighbours — the recomputed day is clean freeze throughout, which is the plan the reporter expected on a flat rate.

Test plan

• TDD: new tests written first and watched fail — test_normal_export_clipped_to_freeze_when_soc_flat_above_limit, test_normal_export_clipped_off_when_soc_flat_and_freeze_unsupported, test_manual_export_preserved_when_soc_flat_above_limit
• Clip-up fixtures switched from flat to falling SoC traces (flat SoC during a commanded export is precisely the phantom signature; the clip-up tests mean "genuine export above limit") — all 13 clip tests pass
• --quick suite passes; pre-commit passes
• Random benchmark, 20 scenarios vs main: final plan metric and cost identical 20/20 (plan selection scores pre-clip per fix(plan): score plan selection on the plan as optimised, not as clipped #4403, so the prune provably cannot change which plan wins); the conversion fired in 1 scenario with a +0.40p post-clip shift, against a pre-existing post-clip spread of up to +4.25p from the PV10 clip tax; runtime unchanged

Note

cases/predbat_debug_pre_saving1.yaml.expected.json fails on clean main before this change (numeric drift now lands its 22:00 window exactly at reserve, so the existing #4434 branch clips it; CI runs --quick, which skips debug_cases). The actual output under this branch is identical to main's. Expected file to be regenerated on this branch separately.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR addresses “phantom” forced-export windows that move zero energy (flat predicted SoC above the requested export limit) by converting them to freeze export (99) (or off (100) when freeze is unsupported), preventing unintended real-world battery dumps when PV later dips.

Changes:

• Update clip_export_slots to detect flat-SoC, above-limit export windows (non-manual) and convert them to freeze/off.
• Add targeted unit tests for phantom-export conversion, freeze-unsupported fallback, and preservation of manual exports.
• Adjust existing clip-up test fixtures to use falling SoC traces to distinguish “real export” from the phantom signature.

Reviewed changes

Copilot reviewed 2 out of 4 changed files in this pull request and generated 1 comment.

File	Description
apps/predbat/plan.py	Adds phantom-export detection in clip_export_slots and converts such windows to freeze/off.
apps/predbat/tests/test_clip_export_slots.py	Adds new regression tests and updates fixtures to use falling SoC for genuine-export cases.
.gitignore	Ignores coverage/*.py files.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.