Stochastics re-grounding (forecasts-only) + 4.0.5 integration

CHANGELOG.md

@@ -1,5 +1,75 @@
 ## Unreleased
 
+Schema change (adds `solve.stochastic_invest_method`,
+`solve.shared_invest_periods`, `solve.shared_operation_periods`,
+`reserve__upDown__group.reserve_duration`, and per-entity
+`construction_lead_time` / `construction_lead_time_method` on
+`unit`/`connection`/`node`; migrated automatically). The stochastic
+shared-decision window parameters use positive names:
+`shared_invest_periods` / `shared_operation_periods` name the periods
+whose decisions are *shared* (identical) across stochastic branches.
+
+- **Mixed period/time Map shapes within one parameter.** A parameter can
+  now be authored with different Map shapes for different entities (for
+  example a `flowGroup.min_instant_flow` that is a `Map(period)` on one
+  group and a `Map(time)` on another). Each row keeps its own index
+  semantics regardless of the order of rows in the database, instead of
+  being silently misplaced or dropped. As a consequence of classifying
+  every row, a Map shape that a parameter does not accept — for example a
+  time Map (or any other non-accepted shape) on a period-only parameter —
+  now **raises** an error that names the offending entity, instead of
+  being silently ignored. Databases that relied on such input being
+  dropped will stop with a clear message identifying the entity and
+  parameter to fix.
+
+- **Construction lead time.** New per-entity parameters
+  `construction_lead_time` ([years]) and `construction_lead_time_method`
+  (`immediate` / `closest_seam` / `previous_seam` / `next_seam`) model
+  physical build time on `unit`, `connection` and `node` investments.
+  Capacity *ordered* in a period becomes *available* only after the lead
+  time, snapped to a period boundary — the investment decision and its
+  overnight annuity stay in the order period, while balances, flows and
+  reserves see the plant (and its full technical lifetime) only from its
+  commissioning year. It applies to deterministic and stochastic models
+  alike, and composes with the invest non-anticipativity window to stage
+  long- versus short-lead technologies across a stochastic reveal
+  automatically (a long-lead asset serving a post-reveal period must be
+  ordered in a pre-reveal, tied period). Left at the default 0 (or
+  `immediate`) every existing result is byte-identical.
+
+- **Standard two-stage stochastic investment (the main mode).** The new
+  `solve.shared_invest_periods` parameter names the periods over
+  which investment is a single shared *here-and-now* decision: `v_invest` and
+  `v_divest` are tied across the stochastic branches over those periods, while
+  later periods invest per branch (recourse). Compose it with
+  `stochastic_invest_method = recourse` and `shared_operation_periods = []`
+  to get the classic capacity-expansion structure — shared first-period
+  investment, per-scenario recourse investment thereafter, operations free from
+  the first timestep. Both invest and divest are tied so the *net* first-stage
+  capacity is genuinely shared. Left unset (or empty) it adds no tie and every
+  existing result is byte-identical; on a non-`recourse` solve it is a harmless
+  no-op.
+
+- **Per-scenario stochastic investment** (opt-in
+  `solve.stochastic_invest_method = recourse`): each stochastic branch can now
+  make its own investment decisions at and after the branching period, with
+  probability-weighted investment costs and per-scenario investment limits — a
+  wait-and-see analysis giving per-scenario optimal plans and their expected
+  cost. Committed results report the realized scenario; non-realized branch
+  investments are available under the horizon-output debug flag
+  (`model.output_horizon`). Default behaviour (`none`) is unchanged, and the
+  option is rejected in combination with Benders decomposition.
+- **Mid-horizon reveal / hedged two-stage stochastics.** A stochastic branch
+  may now start at any period boundary, not only the solve's first step, so the
+  pre-reveal periods stay a single shared *here-and-now* investment (a genuine
+  first stage) while the branches fan out into per-scenario recourse from the
+  reveal onward. Under `recourse` this makes the objective a real two-stage
+  hedge — strictly between the wait-and-see bound and the deterministic
+  mean-value plan (positive EVPI/VSS). Storage state is carried across the
+  reveal for stochastic-group storage nodes. Mid-horizon reveal is a general
+  stochastics capability; the previous multi-period restriction is lifted. A
+  malformed reveal (analysis time off a period boundary, or a branching period
+  without exactly one realized branch) is now rejected with a clear error.
 - **Minimum load now applies once per unit, on the sum of its outputs.**
   `min_load` × online capacity is a floor on the sum of the outputs that
   define the unit's capacity (outputs with `conversion_flow_coeff ≠ 0`; the

docs/dev/architecture.md

@@ -789,11 +789,28 @@ names as before for debug inspection:
 | `realized_existing` | `p_entity_period_existing_capacity.csv` (existing column) | Cumulative existing capacity history per `(entity, period)`. |
 | `divest_cumulative` | `p_entity_divested.csv` | Cumulative divest per entity carried forward. |
 | `roll_end_state` / `upward_roll_end_state` | `p_roll_continue_state.csv` | `v_state` at the end of the realized window; pins the next roll's first timestep. |
+| `roll_end_online` | *(in-memory only)* | Committed jump-end `v_online` per online process (OC1 Carrier 1); the next roll's `online__startup`/`online__shutdown` first step sees the prior commitment instead of the within-roll cyclic wrap, so a unit that stays committed is not re-charged a startup across the boundary. |
+| `online_history` | *(in-memory only)* | Trailing realized committed `v_startup`/`v_shutdown` window (OC1 Carrier 2); rebuilt into `uptime_carry`/`downtime_carry` at the next roll and injected on the `minimum_uptime` RHS / `minimum_downtime` LHS so an obligation opened in roll N constrains roll N+1's early steps. |
 | `fix_storage_quantity / price / usage` | `fix_storage_*.csv` | Parent-imposed storage quota at the boundary (any subset of the three metrics — each carries its own `(node, period, step)` index, so a separate timesteps carrier is not needed). |
 | `cumulative_co2` | `co2_cum_realized_tonnes.csv` | Running CO2 totals across rolls. |
 | `cumulative_commodity` | `commodity_ladder_cumulative.csv` | Per-tier commodity consumption (ladder pricing). |
 | `cum_sim_hours` | `ladder_cum_sim_hours.csv` | Running simulated-hour total per period. |
 
+Cross-boundary unit-commitment continuity (OC1 Carriers 1 & 2) is
+**hard-enforced** and **period-aware**: a `min_uptime` / `min_downtime`
+obligation opened near a roll's jump-end carries into the next roll's early
+steps *only within the same period*. FlexTool's online dynamics are
+period-cyclic (a period's first step wraps within that period, never to the
+prior period), so a commitment obligation must not propagate across a period
+boundary — the non-contiguous investment years (e.g. 2020 → 2025) do not
+connect, and forcing one across would be a unit-commitment infeasibility no
+node penalty slack can absorb. A node with the default `penalty_method`
+(`regular`) absorbs any forced-on generation through its downward penalty
+(`vq_state_down`, a feasible spill); a hard-balance node (`penalty_method =
+off`) can instead become infeasible when a myopically-committed unit's
+forced generation cannot be absorbed — that is the model correctly refusing
+an un-absorbable commitment, resolved by allowing slack.
+
 `fix_storage_timesteps`, `ed_history_realized_first`, and `edd_history`
 used to be `SolveHandoff` fields too, populated only by the now-removed
 `capture_post_solve()` disk-read constructor. They were retired when the