Define the top-level public API namespace (flat vs nested)

[coretl]

Spun out of the #388 DataType-drop work — the new *Meta types need a home, but the question is broader than that.

Decision to make

Adopt ophyd-async's big flat namespace (from fastcs import Controller, AttrRW, AttrR, attr, FloatMeta, ControllerFiller, ControllerRunner, ReadWriteIO, ..., mirroring from ophyd_async.core import ...) or keep the current nested structure (fastcs.attributes, fastcs.datatypes, fastcs.controllers, fastcs.methods, ...).

Why now

The refactor introduces a batch of new public names — the *Meta TypedDicts, the attr factory, ReadIO/WriteIO/ReadWriteIO, ControllerFiller, ControllerRunner, ConnectionFailedError, the Array1D/Table hints. Where they are exported from is the moment to settle flat-vs-nested: it is an API-convergence "false friend" surface (#388) and a breaking change best made pre-1.0.

Scope

• Produce an ADR proposing flat vs nested, showing the import surface a downstream driver author sees, with the ophyd-async comparison.
• Decide the canonical public export surface. Feature PRs (getter/setter IO rework; remove AttributeIORef and DataType #392 etc.) may land new names in provisional modules and be re-exported/moved once this is settled — so this gates final module paths but does not block feature work.

Note

Design decision — settle with the team (produces an ADR). Not for the autonomous nightly job to churn import moves before it is decided.

Parent: #388
Blocked by: none

[coretl]

@shihab-dls @tomkane-dls @gilesknap @Tom-Willemsen thoughts?

[Tom-Willemsen]

@Tom-Willemsen thoughts?

I have no strong opinions on import paths; the only driver we have which uses FastCS is fastcs-secop, and this is relatively easy to update imports to whatever the chosen answer is. If you forced me to have an opinion, I slightly prefer a flatter hierarchy than what is currently there.