controllers: ControllerRunner reconnect loop refactor

[shihab-dls]

This issue follows my comment on #420 (comment) and the comment reply (#420 (comment)). This issue should be added as a sub-issue of #388, renamed appropriately, and this issue comment should be amended appropriately with the issue details. The attached markdown file is the proposed solution to resolve the two linked comments.

controller-lifecycle-design(1).md

[coretl]

Opened #424 against refactor with the framework half of the attached design. Green on pre-commit and type-checking, and on the test suite excluding the docs and PVA/p4p paths this sandbox cannot run.

In #424: the Connection base class and Connections registry; Controller.connect/reconnect/disconnect/_connected removed and initialise/post_initialise replaced by build/setup; the runner rewritten to own the startup order (connections opened first, build to a fixpoint, setup, then tasks) with one reconnect task per connection, depends_on awaiting, per-connection retry budgets and the introspection check; scans gated on the connection; IPConnection/SerialConnection moved under the new contract; the demo, all 16 docs snippets and the prose docs migrated, plus a new explanations/connections.md and an ADR 0016 amendment answering the points raised on #420.

Still to do, which is why this issue stays open: the fastcs.yaml connections: block and launcher injection. The design's launcher sketch assumes a single controller: block and instantiate_from_config(spec, connections=...); launch.py here is a typer app over a controllers: list, each entry carrying id/type with its options-type inlined, and _build_entry_model rejecting an __init__ with more than one argument. Two decisions I did not want to guess at:

1. How the registry reaches a controller that also takes an options object — a second parameter excluded from the pydantic model by annotation, or something else.
2. How a connection's type: resolves to a class. Transports use a Transport.subclasses union; connections have no equivalent, and adding one is a public-surface decision of its own.

Until that lands, a registry is built by hand and passed as ControllerRunner(controllers, connections=...); a runner given none collects whatever connections the tree already holds, by identity, so no existing driver is blocked.

Also deliberately left out: a connection-state PV. Controller.connected is the read-through the design asks for, but serving it as a parameter is transport surface and a behaviour addition rather than part of the reconnect loop.

Three trade-offs in #424 worth your eye, all flagged in its "Checks for reviewer": BaseController.connection is typed Any so a driver can narrow it (a mutable attribute is invariant, so Connection | None makes every driver's connection: IPConnection a pyright error); an introspecting build(self, info) needs one # pyright: ignore[reportIncompatibleMethodOverride], since a type checker cannot have both valid signatures; and max_attempts keeps the design's terminal-at-10 rather than the retry-forever default the #420 review asked about.

I have not retitled or relabelled this issue, or filed it under #388 — that tidy-up is yours.

— overnight agent

---

Generated by Claude Code