[ophyd-async] Embedded FastCS connector (fastcs-embed extra)

[coretl]

Scope

• ophyd_async.fastcs embedded_fastcs_connector(controller) behind an ophyd-async[fastcs-embed] extra. create_children_from_annotations via DeviceFiller + FastCSSignalBackend/FastCSCommandBackend factories, filled=False.
• connect_real: start the ControllerRunner (AttrW setpoint cache, native timestamps + severity, ControllerRunner #395), walk the ControllerAPI tree, fill children, check_filled, set_name; idempotent across reconnects. connect_mock never touches the controller.
• Backend mappings per ADR 0019 table (get/set/callback/setpoint/datakey/command).
• Enums: un-hinted → introspect at runtime, drop to string datatype retaining choices as metadata; hinted → require duplication (StrictEnum/Subset/Superset) for now, revisit (0019 L149).
• Table converter IS in scope for the first cut — use it to bring FastCS and ophyd-async Table implementations closer (0019 L153).
• FastCS gains ConnectionFailedError (raised when the device doesn't respond) → connector converts to NotConnectedError and retries in background; all other errors surfaced unconverted (0019 L163).

⚠️ Investigate (needs @shihab-dls)

0019 L159: is @scan just driving updates into Attrs (→ Signals), or is there more to map? Resolve before finalising the backend surface.

Acceptance

uv run --locked tox -e pre-commit,type-checking,tests green (this work lands in the ophyd-async repo / a coordination branch — see #388 §4; scope here is the FastCS-side stable interface + any FastCS additions).

ADR: 0019
Parent: #388
Blocked by: #392, #395, #413

get_datakey source — folded in from review

get_datakey now reads metadata from attr.meta (units/precision/limits) + python-type/enum choices, not from a removed DataType object.

[coretl]

All three blockers (#392, #395, #413) are now closed, so this is unblocked — but I am not opening a PR for it, and I think it should stay open. Recording why, plus an audit of what it still needs from this repo, so the next person does not have to redo it.

The deliverable is not in this repo. ADR 0019's Consequences say it outright: "This is entirely an ophyd-async-side deliverable (§8 items 6-8); fastcs-core work is a dependency, not part of this repo's PRs." embedded_fastcs_connector, the DeviceFiller wiring, FastCSSignalBackend/FastCSCommandBackend and the Table converter all live in ophyd-async, which I have no access to. A Closes #399 PR here would be false, and would then get this issue auto-closed on merge with the actual work undone.

The FastCS side is one item short. I audited ADR 0019's backend-mapping table against refactor at fc746898. Everything the connector imports already exists and is documented in docs/explanations/stable-interface.md:

ADR 0019 row	on refactor today
SignalBackend.get_value	AttrR.readback
SignalBackend.set_callback	AttrR.add_readback_callback(cb, always=True)
SignalBackend.put	AttrW.set(value)
SignalBackend.get_setpoint	AttrW.setpoint
SignalBackend.get_datakey	attr.dtype + attr.meta (units/precision/NumericLimits), enum class direct
CommandBackend.execute / .signature	Command.__call__ / Method.signature
SignalBackend.source	Attribute.full_name
child Device / DeviceVector	sub-Controller / ControllerVector
timestamps + severity	AttrR.timestamp / AttrR.severity, fed by Update
lifecycle	ControllerRunner.setup() / start() / stop()

The one exception is ConnectionFailedError, which appears only in ADR 0019's prose (lines 96 and 164) and in no code — src/fastcs/exceptions.py has just FastCSError and LaunchError.

And that one item is a live design question, not a typing exercise. ADR 0019 wants it raised "when the device doesn't respond", for the connector to convert to NotConnectedError and retry in the background. On today's refactor that would sit on IPConnection.connect, next to the existing DisconnectedError. But #424 rewrites exactly that layer: it gives connections their own health, makes DisconnectedError derive from ConnectionError, and adds a per-connection retry budget with a terminal fatal_error. Whether ADR 0019's error is then a new type, or simply DisconnectedError under #424's model — and whether the retry ADR 0019 asks the connector to do is already the runner's job once #424 lands — depends on whether #424 is accepted. I did not want to guess at that and hand you a merge conflict against a PR that is sitting green awaiting review.

Suggested order: settle #424, then add ConnectionFailedError in whichever shape survives, and let this issue track the ophyd-async connector itself. Happy to do the error in a small follow-up once #424 has a verdict.

One thing that is not outstanding: the "⚠️ Investigate (needs @shihab-dls)" on @scan mapping was answered in review and written into ADR 0019 as resolved question 5 — @scan is purely internal, bound to no Attr, surfaces no Signal, and needs nothing extra. The issue body just predates that.

— overnight agent

---

Generated by Claude Code