[epic] Seams before records before views: the BESS platform

[dim-sous]

The one current plan. Every other planning-shaped thing (backlog.md, prose roadmaps) either feeds this or is retired against it.

Why this exists

The developer's brief, in their words: "The repository has grown so massive that I lost track. I cannot run experiments freely, I am forgetting commands and capabilities, it is hard to investigate, analyze and compare stuff." And: "If I want to swap out EKF for UKF that should be an easy and fast transaction."

Two facts from the assessment (2026-08-15, read-only) shape everything below:

1. The Lab is the last step, not the first. The RCWS Lab works because a record layer, an experiment registry and a small set of verbs already existed under it — so it could be 1,300 lines of stdlib holding no logic of its own. BESS has none of those layers. Built today, a Lab would have nothing to show and would have to compute what the layers below do not provide, which is the failure that killed RCWS's first Lab (Test coverage inverts the risk: 6 of 8 test files cover v5b markets; plant, EKF, EMS, MPC and ledger share one smoke test #9 there).
2. Half the components already plug in; the other half are hardcoded. Strategy (core/simulator/strategy.py) is a real seam — planner, MPC and bidding tier are Protocols, and v5b was added with zero core edits and a bit-identity test to prove it. Estimator, plant, activation signal and ledger are constructed by hand inside the loop. The estimator swap the developer named touches 6–10 files today.

The one test

A change in A must not require a change in B. When a change forces an edit somewhere it has no business reaching, the coupling is the defect, not the edit. (RCWS #60.) Every issue below is that test on a different surface.

The shape

The layering every scientific platform surveyed converges on, and the one RCWS walked into:

layer	meaning	BESS today
1 components	models / laws / solvers as named plug-ins with provenance	planner, MPC, bidding: yes · estimator, plant, activation, ledger: no
2 engine	the loop, generic over components — never names one	names four of them
3 experiments = config	an experiment is settings, not code; vary one thing = one override	15 positional params, three runner scripts
4 records	every slow-or-random run saves config + code version + results; figures read records	results/ named by version, no provenance
5 views	CLI verbs and the Lab — windows over records + registries, never computing	none

Decisions taken (with the developer, 2026-08-15)

• Ledger → devkit, at least for now: it is the referee, not a player. Settlement math may later split out as a shared pure function — split, not moved wholesale.
• archive/ → out of the import root, at least for now; tag-and-delete is the later option if it still costs attention.
• The physics roadmap (v6 UKF onward) waits on phase 1. v6 is then the first proof that the estimator seam works: one new file.
• Proof-carrying branches: every structural change ships with bit-identical traces before/after. A refactor proves itself by not changing the numbers.
• The Lab gets its own epic when phase 3 lands, as RCWS #70 did. Not before.

The phases

Phase 0 — the net, then the fold

• Test coverage inverts the risk: 6 of 8 test files cover v5b markets; plant, EKF, EMS, MPC and ledger share one smoke test #9 reference-trace regression per strategy on the canonical synthetic day — the instrument every later proof runs on. First.
• The repo has no ships / never-ships boundary: plant, prices, ledger and the loop sit beside the controller in core/ #1 the ships / never-ships boundary: src/bess/ + devkit/; archive/ out of the import root; entry points declared; one-way rule and frozen inventory held by tests. Proof: traces bit-identical.

Phase 1 — every component behind a port, chosen at the edge

• run_simulation takes 15 positional parameters and 9 config dataclasses from one file, with no runtime schema — every caller is welded to the core's shape #5 one experiment config object with a runtime schema; run_simulation(strategy, config); the stray Strategy enum gone
• The estimator has no seam: EKF hardcoded in the loop, EKFParams welded into run_simulation, its name baked into the traces — a UKF touches 6–10 files #2 estimator seam — EstimatorLike, chosen at composition, traces named for the quantity not the algorithm
• The plant is a type switch: BatteryPack if use_pack else BatteryPlant — a third plant model is another branch in the core #3 plant seam — PlantLike, no type switch in the loop
• Activation generator and ledger are hardcoded in the loop; ledger.py and milp_bidding.py import upward from core.simulator #4 activation + ledger seams; the two upward imports fixed
• then v6 UKF as one new file — the proof the phase worked

Phase 2 — records are the currency

• A run does not describe itself: results/ holds 27 files named by version, with no config, seed, conditions or git stamp — two runs of one version overwrite each other #6 a run describes itself: config, metrics, provenance, declared panels; figures read records; one records view

Phase 3 — experiments have names

• An experiment has no name: three runner scripts are the interface; no [project.scripts], no list #7 registry + list run show compare + --set overrides + runtime guard; the three runner scripts become entries

Alongside

• Docs have no assigned roles: 12 markdown files overlap; pyproject claims MHE that does not exist; synthetic_day.py names the removed ems_tracking_mpc #8 docs get one job each; backlog.md retired into issues; drift fixed (MHE, ems_tracking_mpc, orphaned adapter)

Phase 4 — views

• The Lab. Its own epic, opened when phase 3 lands.

Order and gates

0 → 1 → 2 → 3, with 8 alongside and landing before 3. Phase 0's net goes up before any seam is cut. Each phase: one branch per issue, merged --no-ff on its proof; full suite once per phase.