[GP-02] Sequential mode: configurable carry-over-length, correct stitching for block-overlap != 1

[aoustry]

Process ID

Process: GP-02

Description

Closes #271.

In sequential-subproblems mode, the carry-over that stitches block N to block N+1 was hardcoded: it extracted block N's last timestep and pinned it to block N+1's first timestep. That pairing only refers to the same absolute timestep when block-overlap == 1; for block-overlap >= 2 it silently pinned the wrong pair of timesteps.

This PR makes the carry-over an explicit resolution setting and fixes the absolute-timestep alignment:

• carry-over-length added to ResolutionConfig (optional; omitted → defaults to block-overlap, i.e. full pin of the overlap zone). Explicit 0 is legal and distinct from unset: blocks overlap for lag-constraint history but are not stitched at all.
• Validation: 0 <= carry-over-length <= block-overlap (no special case at block-overlap == 0), plus the previously missing range check 0 <= block-overlap < block-length.
• Runtime: _extract_carry_over now extracts effective_carry_over_length values starting at the earliest shared timestep (local index block_length - block_overlap) instead of always the last one; Phase 5 pins the next block's first k timesteps against them (clamped for truncated final blocks). Scalar initial_values keep the legacy single-timestep pin for direct build_problem callers.
• Docs: docs/user-guide/optim-config.md documents the three parameters with an annotated timeline diagram (from the issue discussion), defaults, validation, and a breaking-change warning; docs/CHANGELOG.md gains a BREAKING entry with the migration note.

Breaking change: with block-overlap: 0 (the default) nothing is carried between blocks any more — the previous implicit single-timestep seeding is gone. Configs relying on state continuity (e.g. storage state-of-charge) must set block-overlap: 1 (and optionally carry-over-length: 1).

Impact Analysis

Affected modules:

• optim_config/ — ResolutionConfig schema: new field + validators (src/gems_craft/optim_config/parsing.py).
• gems_runner/session/ — _run_sequential / _extract_carry_over generalized to a multi-timestep window.
• gems_runner/simulation/ — optimization.py Phase 5 carry-over constraints generalized; build_problem docstring updated.
• docs/ — user guide + changelog.

Solver output values expected to change: yes, for sequential mode only:

• block-overlap >= 2: outputs change because the previous stitching was incorrect (wrong absolute timestep pinned); the new behaviour pins each shared timestep to its matching absolute timestep.
• block-overlap: 0: outputs change because blocks no longer inherit the previous block's final state (breaking change above).
• block-overlap: 1: no change — the new default is identical to the old hardcoded single-timestep pin; the existing e2e tests (test_rolling_horizon_suboptimality.py, test_optim_modes.py) pass unmodified.
• frontal / parallel-subproblems / benders-decomposition: unaffected.

Test coverage: 13 new unit tests for the validators and default resolution; new e2e module test_sequential_carry_over_length.py (block-length 6, block-overlap 3, carry-over 3/1/0 over an aperiodic 12-step demand) asserting every pinned shared timestep is identical in both blocks — all four cases fail against the previous runtime behaviour and pass with the fix.

Checklist

• Unit tests pass (pytest) — 604 passed, 6 skipped, 2 xfailed
• Type checking passes (mypy)
• Formatting passes (black, isort)
• pyproject.toml version bumped if applicable — not applicable (version bumps are handled via the feat(release): workflow)
• AGENTS.md reviewed for impact and updated if needed — no update needed (resolution-mode internals are not described there)