Advisory: integration branch for the multi-commodity + commitments PR family

[Flix6x]

Purpose — do not merge

This was a mock-main integration branch combining the open PRs of the multi-commodity/commitments family, opened to advise on merge order and cross-PR interactions.

Its advice has been carried out. Seven of the eight PRs it tracked are merged, and the branch itself is stale (last updated 2026-07-20). It is kept only as a record of the interactions found, which are noted below with how each was resolved.

Status of the family

PR	Status
#2218 — coupling primitive (CHP)	merged 2026-08-03
#2289 — balance groups (internal commodity nodes)	open, now based on main, green
#2272 — commodity-context smart defaults	merged 2026-07-17
#2295 — sensor-scoped commitments	merged 2026-08-01
#2281 → #2284 → #2287 — UI stack	merged 2026-07-17 / 07-24 / 07-24
#2285 — namespace user commitment names	closed, not merged

The recommended merge order was followed, with #2289 the only piece left.

How each interaction turned out

a) #2272 × #2289 — #2272's smart defaults fill in zero prices for bare commodity contexts, defeating #2289's internal-node detection. This was the real one. #2272 landed first, so #2289 carries the fix: fill_grid_connection_defaults records an is_internal_node flag, and _prepare treats a commodity as internal only when the user gave no grid-connection signal at all — neither prices nor capacity fields. A commodity given a capacity but no price still carries smart-defaulted zero prices, and still declares a grid connection, so it is not an internal node.

b) #2285 × #2287 — moot. #2285 was closed without merging, so there is no custom: prefix and no test to adapt.

c) #2289 base — resolved; the balance rule sums plain ems_power, and this is part of #2289.

d) Squash-merging stacked branches conflicts spuriously — confirmed in practice, and the advice here was superseded by something better.

When #2218 was squash-merged, #2289 conflicted across 11 files, because main held #2218's content as one commit with no shared history while #2289 carried its original commits. The recommendation above (rebase each branch on main after its base merges) works, but rewrites a branch that already has review history and needs a force-push.

The approach actually used, which needs neither:

1. Restore the base branch from its deleted tip.
2. Merge into it the state of main from just before the squash-merge commit.
3. Merge the base into the stacked branch, so it holds the full unsquashed lineage.
4. Merge origin/main into the stacked branch with -X ours.

Step 4 is safe by construction: every conflict is then between two representations of the same content, so taking the stacked branch's side is correct rather than a judgement call. Verify by measuring the stacked branch's unique content before starting (git diff <old stack base> <tip> --stat) and confirming the post-merge git diff origin/main --stat matches — it did exactly, at 13 files / +405 −16.

What has changed underneath the family since

Worth knowing for anyone reading this branch as a guide, as it predates all of the following:

• Add a Pyomo-free scheduling backend (direct highspy model construction) #2364 added a second, Pyomo-free scheduling backend and made it the default. Any scheduling constraint must now be modelled in both backends; arguments reach the direct backend by name, so an unimplemented one raises rather than being silently dropped.
• Fix EMS-level flow commitment constraints #2355 made EMS-level flow commitments actually bind, and skips commitments that are already device-scoped.
• Bind a regular commitment to its commodity's aggregate, not each device (fixes #2379) #2380 binds an unscoped commitment to its commodity's aggregate rather than to each device.
• Require new tests to be proven capable of failing #2384 / Add an advisory agent hook for mid-phrase line breaks #2386 added the mutation-test convention and an advisory hook for docstring line breaks.

Not included

• The paper-mill plugin PRs (SeitaBV/simulations [Scheduling] convert the units of inflexible power sensors MW #1007/Update toy tutorial: Add parent asset & show status page #1015) consume this family; Update toy tutorial: Add parent asset & show status page #1015 additionally requires Commitments can be scoped to specific sensors, binding their aggregate flow #2295, which is now merged.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33548882 | 📁 Comparing e937064 against latest (79f8dc8)

  🔍 Preview build  

29 files changed · + 3 added · ± 26 modified

+ Added

• _autodoc/COMMODITIES.html
• _autodoc/COUPLING.html
• _autodoc/COUPLING_COEFFICIENT.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• index.html
• _autodoc/COMMITMENTS.html
• _autosummary/flexmeasures.data.models.forecasting.pipelines.predict.html
• _autosummary/flexmeasures.data.models.forecasting.utils.html
• _autosummary/flexmeasures.data.models.planning.html
• _autosummary/flexmeasures.data.models.planning.linear_optimization.html
• and 16 more...

[Flix6x]

Consolidation status update (main has since absorbed the solver rewrite #2282/#2321/#2322/#2325 and merged #2272 + #2281):

Done — rebased onto current main, tested, pushed (fast-forward, no history rewrite):

• Combined Heat and Power (CHP) #2218 (feat/chp) — merged current main in. Beyond textual conflicts, main's group-indexed stock recursion (Speed up device_scheduler with a recursive stock balance #2282/Share storage-efficiency per stock group and index solver stock by group #2325) assumed each device belongs to ≤1 stock group, which silently broke commodity converters (a device bridging two nodes, e.g. CHP/steamer): the CHP dispatched to zero. Fixed by preserving overlapping group_to_devices membership while keeping the Share storage-efficiency per stock group and index solver stock by group #2325 namespaced-key collision fix. All planning + schema tests green; test_factory_chp_dispatch restored.
• Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289 (feat/internal-commodity-balance) — merged the updated feat/chp in. The Smarter commodity-context defaults and Commitment commodity field #2272×Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289 interaction bit as predicted here: Smarter commodity-context defaults and Commitment commodity field #2272's smart defaults fill a zero price into a bare {commodity: steam} context, so the internal-node detection missed it and the steam balance group vanished. Ported the combo-branch prices_are_defaulted fix upstream. 186 planning + schema tests green; test_factory_chp_dispatch_through_storage_scheduler passes through compute().

Remaining: #2295 (scoped commitments), UI #2284→#2287, #2285, then a refresh of this integration branch onto current main. The two fixes above are the ones flagged in the interaction notes — now landed on their respective PR branches.

🤖 update via Claude Code

[Flix6x]

Closing this advisory now that only #2289 needs to land.