ControllerFiller — declarative/procedural split

[coretl]

Scope

• ControllerFiller mirroring ophyd_async DeviceFiller (core/_device_filler.py — follow its structure; match names only where FastCS vocab fits). Scans class hints for AttrR/W/RW[T], Command[...], sub-Controller/ControllerVector[T]; creates children unfilled; check_filled(source) reports promised-but-missing.
• Rule: at the end of __init__, any Attribute referenced in code (i.e. type-hinted) MUST exist; initialise() may then run in parallel (only __init__ is serial). (0013 L150)
• Support: no-hints-at-all (0013 L139); Optional[X] hints (0013 L153); adding attributes onto a bare Controller from outside — which is what fillers do (0013 L144).
• yields (child, extras) so third-party extras vocabularies work (decision 3); core defines none. Delete HintedAttribute + _validate_type_hints; remove the deepcopy half of _bind_attrs (keep @command/@scan binding). Trailing-underscore name convention.
• Migrate Example 5 (cut-down Eiger, Example 5 — cut-down Eiger: introspectable controller + REST sim #391) to the filler.

⚠️ Investigate

fastcs-catio builds Controller classes at runtime via type(...) from YAML before any instance exists — decide: does the filler support class-level dynamic construction, or must catio move to instance-level dynamic attrs? Record the decision in the PR / an ADR update.

Key files (§9)

controllers/base_controller.py (_bind_attrs, _find_type_hints), + new filler module.

Acceptance

uv run --locked tox -e pre-commit,type-checking,tests green; Example 5 updated + green.

ADR: 0013
Parent: #388
Blocked by: #392, #413

Filler metadata validation — folded in from review

• Hinted children are created unfilled in __init__ (so they exist after __init__, per the ADR 13 rule); initialise() only fills them (+ may add unhinted dynamic attrs).
• When filling from an Annotated[Attr[T], extras] hint, runtime-validate the metadata the extras carries (FloatMeta, or a protocol object's .meta e.g. SCPIParam(...).meta) against datatype T — precision on a str raises. Runtime counterpart to the static Unpack[FloatMeta] check (getter/setter IO rework; remove AttributeIORef and AttributeIO #392).

[coretl]

Blockers are all closed now (#392, #413), so this is unblocked — but I have deliberately left it rather than starting it tonight alongside #397, because it wants to follow #397 rather than race it:

• ADR 0013 and ADR 0018 both say the filler must treat an @attr-decorated attribute as already filled and raise on a clash with an introspected name. That check needs the UnboundAttr declaration that attributes: @attr decorator sugar over the getter/setter constructors #423 (@attr decorator sugar over getter/setter constructors #397) introduces, so building the filler off the current refactor tip would build it without the case it is specified to handle.
• Both changes rewrite BaseController._bind_attrs — attributes: @attr decorator sugar over the getter/setter constructors #423 adds the @attr binding branch, this issue removes the deepcopy branch and HintedAttribute/_validate_type_hints alongside it. Landing them as two independent PRs would not be a small conflict resolution; the second would be a rework.

Nothing needed here — just recording why it was skipped rather than missed. Once #423 merges this is the next one up.

— overnight agent

---

Generated by Claude Code