Third pass

Author: GDYendell

docs/explanations/decisions/0003-controller-initialization-on-main-event-loop.md

@@ -19,13 +19,12 @@ Move initialisation logic into Backend so that it:
 - Runs `controller.initialise()` before creating the Mapping
 - Creates the Mapping from the initialized controller
 - Runs initial tasks including `controller.connect()`
-- Delegates to transport-specific implementations
 
 Controller then has two hooks: `initialise()` for pre-API setup (hardware introspection, dynamic attribute creation) and `connect()` for post-API connection logic.
 
 ## Consequences
 
-The new design the initialisation of the application and makes the API for writing controllers and transports simpler and more flexible.
+The new design the initialisation of the application is easier to understand and makes the API for writing controllers and transports simpler and more flexible.
 
 ### Migration Pattern
 

docs/explanations/decisions/0005-background-thread-removal.md

@@ -10,19 +10,11 @@ Accepted
 
 ## Context
 
-The current FastCS Backend implementation uses `asyncio.run_coroutine_threadsafe()` to execute controller operations on a background event loop thread managed by `AsyncioDispatcher`. This threading model creates several problems:
-
-- **Thread Safety Complexity:** Managing state across thread boundaries introduced race conditions and required careful synchronization
-- **Blocked Main Thread:** Despite using async, the main thread blocked waiting for background thread results via `.result()`
-- **Complex Lifecycle Management:** Starting and stopping the background thread added complexity
-- **Difficult to Test:** Background threads made tests non-deterministic and harder to debug
-- **Unnecessary for Most Transports:** Only EPICS CA softIOC actually needed a background thread; other transports (REST, GraphQL, PVA) could run entirely async
-
-The system needs a simpler concurrency model that uses native async/await patterns and allows transports to manage their own threading if needed.
+The FastCS Backend implementation uses `asyncio.run_coroutine_threadsafe()` to execute controller operations on a background event loop thread managed by `AsyncioDispatcher`. The system needs a simpler concurrency model that uses native async/await patterns and allows transports to manage their own threading if needed.
 
 ## Decision
 
-Remove the background thread from Backend, making it fully async, while allowing specific transports to use a background thread if required. Tango does require this because it does not accept an event loop to run on. Backend now accepts an event loop from the caller and uses native async/await throughout. Transports that need threading (like EPICS CA) manage their own threading explicitly.
+Remove the background thread from Backend, making it fully async, while allowing specific transports to use a background thread if required. Backend should accept an event loop from the caller and use native async/await throughout. Transports that need threading (like Tango) manage their own threading explicitly.
 
 Key architectural changes:
 - Backend receives event loop from caller (no background dispatcher)
@@ -36,50 +28,5 @@ Key architectural changes:
 ### Benefits
 
 - **Simpler Concurrency Model:** Single event loop for most operations, no cross-thread coordination needed
-- **True Async/Await:** Native Python async patterns throughout, no blocking `.result()` calls
-- **Better Testability:** Deterministic execution, easier to debug, no thread scheduling delays
-- **Clearer Responsibility:** Transports explicitly manage threading they need
 - **Task-Based API:** Consistent use of `Task` objects with standard cancellation support
 - **Composability:** `async serve()` can be composed with other async operations
-
-### Migration Pattern
-
-**Before (Background thread in Backend):**
-```python
-class MyTransport(TransportAdapter):
-    def __init__(self, controller_api, loop):
-        self._backend = Backend(controller)  # Creates background thread
-
-    def run(self):
-        self._backend.run()  # Synchronous
-
-# Client code
-asyncio.run_coroutine_threadsafe(coro(), self._loop)  # Cross-thread scheduling
-future.result()  # Main thread blocks
-```
-
-**After (Async-only Backend):**
-```python
-class MyTransport(Transport):
-    def connect(self, controller_api, loop):
-        self._backend = Backend(controller, loop)  # Use caller's loop
-
-    async def serve(self):
-        await self._backend.serve()  # Native async
-
-# Client code
-await self._backend.serve()  # Direct await, no threading
-```
-
-**For transports needing threads (EPICS CA):**
-```python
-class EpicsCATransport(Transport):
-    def __init__(self):
-        self._dispatcher = AsyncioDispatcher()  # Transport manages its own thread
-
-    def connect(self, controller_api, loop):
-        self._backend = Backend(controller, self._dispatcher.loop)
-
-    async def serve(self):
-        await self._backend.serve()  # Bridge to threaded environment
-```

docs/explanations/decisions/0006-controller-api-abstraction-layer.md

@@ -10,11 +10,11 @@ Accepted
 
 ## Context
 
-Transports currently access `Controller` instances directly to extract attributes, methods, and metadata for serving over their protocols. This tight coupling creates a few problems:
+Transports currently access `Controller` instances directly to extract attributes, methods, and metadata for serving over their protocols. This creates a few problems:
 
 - **Tight Coupling:** Transports are coupled to internal Controller structure, making evolution difficult
 - **Code Duplication:** Every transport re-implemented similar traversal logic for discovering attributes and methods
-- **No Encapsulation:** Transports had direct access to mutable controller state
+- **No Encapsulation:** Transports have direct access to mutable controller state
 - **No Static View:** No complete, immutable snapshot of controller API after initialization
 
 ## Decision
@@ -27,7 +27,7 @@ Key architectural changes:
 - `ControllerAPI` dataclass represents the complete, hierarchical structure of what a controller exposes
 - Separate dictionaries for attributes, command_methods, put_methods, and scan_methods
 - `walk_api()` method provides depth-first traversal of the API tree
-- Backend creates ControllerAPI once during initialization, before passing to transports
+- Backend creates ControllerAPI during initialization and passes to transports
 
 ## Consequences
 

docs/explanations/decisions/0007-transport-consolidation.md

@@ -25,10 +25,8 @@ All transports should follow a unified pattern: configuration fields are datacla
 
 Key architectural changes:
 - All transports use `@dataclass` decorator combining configuration and implementation
-- Standardized `connect(controller_api, loop)` method for deferred initialization
-- Standardized `async serve()` method for running the transport
-- Removed pattern matching logic from FastCS
-- Configuration fields are direct attributes (not nested in options object)
+- Standardized `connect(controller_api, loop)` method to load controller API into transport
+- Standardized `async serve()` method for running the transport service
 
 ## Consequences
 
@@ -37,9 +35,6 @@ Key architectural changes:
 - **Reduced API Surface:** 5 classes instead of 10 (one Transport per protocol)
 - **Simpler Mental Model:** Configuration and implementation in one place
 - **Consistent Interface:** All transports follow same initialization pattern
-- **Less Boilerplate:** No pattern matching needed in FastCS
-- **Easier Maintenance:** Transport parameters defined once in dataclass fields
-- **Better Type Safety:** Consistent constructor signatures across all transports
 
 ### Migration Pattern
 

docs/explanations/decisions/0009-handler-to-attribute-io-pattern.md

@@ -19,22 +19,17 @@ Currently the `Handler` pattern is used to manage attribute I/O operations. This
 
 There are a few limitations with this architecture:
 
-1. **Handler Instance per Attribute:** Every attribute needed its own Handler instance because that's where the specification connecting the attribute to a unique resource live is defined. This means redundant Handler instances when multiple attributes use the same I/O pattern
+1. **Handler Instance per Attribute:** Every attribute needs its own Handler instance because that's where the specification connecting the attribute to a unique resource is defined. This means redundant Handler instances when multiple attributes use the same I/O pattern.
 
-2. **Circular Reference Loop:** The architecture has circular dependencies:
+2. **Circular Reference Loop:**
    - Controller → Attributes (controller owns attributes)
    - Attributes → Handlers (each attribute has a handler)
    - Handlers → Controller (handlers need controller reference to communicate with device)
 
 3. **Tight Coupling to Controllers:** Handlers need direct references to Controllers, coupling I/O logic to the controller structure rather than just to the underlying connections (e.g., hardware interfaces, network connections)
 
-4. **Mixed Concerns:** Handlers combine resource specification (what to connect to) with I/O behavior (how to read/write), making both harder to reason about
-
 The system needs a more flexible way to:
-- Share a single AttributeIO instance across multiple attributes
-- Use lightweight AttributeIORef instances to specify resource connections per-attribute
 - Break the circular dependency chain
-- Validate that Controllers have exactly one AttributeIO to handle each Attribute
 - Separate resource specification from I/O behavior
 
 ## Decision
@@ -45,7 +40,7 @@ Key architectural changes:
 
 1. **AttributeIORef** - Lightweight resource specification per-attribute:
    - Lightweight dataclass specifying resource connection details
-   - Can be subclassed to add fields like resource names, register addresses, etc.
+   - Containers static fields like resource names, register addresses, etc.
    - Attributes have unique AttributeIORef instances
    - Dynamically connected to a single AttributeIO instance at runtime
 
@@ -59,7 +54,7 @@ Key architectural changes:
    - Attributes are now parameterized with `AttributeIORef` types
    - `AttrR[T, AttributeIORefT]` - Read-only attribute with typed I/O reference
    - `AttrRW[T, AttributeIORefT]` - Read-write attribute with typed I/O reference
-   - Type system ensures matching between AttributeIO and AttributeIORef
+   - Type system and programmatic validation ensures matching between AttributeIO and AttributeIORef
 
 4. **Initialization Validation:**
    - Controller validates at initialization that it has exactly one AttributeIO to handle each Attribute
@@ -69,9 +64,7 @@ Key architectural changes:
 
 ### Migration Impact
 
-Users and developers need to:
-
-**Before (Handler pattern - one instance per attribute):**
+**Before:**
 ```python
 # Temperature controller that communicates via TCP/IP
 class TempControllerHandler(AttrHandlerRW):
@@ -101,7 +94,7 @@ power = AttrR(Float(), handler=TempControllerHandler("P", controller))
 setpoint = AttrRW(Float(), handler=TempControllerHandler("S", controller))
 ```
 
-**After (AttributeIO pattern - shared instance):**
+**After:**
 ```python
 @dataclass
 class TempControllerIORef(AttributeIORef):

docs/explanations/decisions/0010-subcontroller-removal.md

@@ -10,10 +10,10 @@ Accepted
 
 ## Context
 
-FastCS provides two separate classes for building controller hierarchies: `Controller` for top-level controllers and `SubController` for nested components. This has become a purely philosophical distinction and now just adds limitations for now benefit:
+FastCS provides two separate classes for building controller hierarchies: `Controller` for top-level controllers and `SubController` for nested components. This has become a purely philosophical distinction and now just adds limitations for no benefit:
 
-- **Design-Time Commitment:** Developers had to choose class at definition time, before knowing all contexts where components might be used
-- **Reduced Reusability:** A component designed as `SubController` couldn't be reused as a top-level controller without changing its base class
+- **Design-Time Commitment:** Developers have to choose class at definition time, before knowing all contexts where components might be used
+- **Reduced Reusability:** A component designed as `SubController` can't be reused as a top-level controller without changing its base class
 
 ## Decision
 
@@ -22,7 +22,6 @@ Unify `Controller` and `SubController` into a single `Controller` class that can
 Key architectural changes:
 - Remove `SubController` class entirely
 - Move `root_attribute` property to `Controller`
-- Rename `register_sub_controller()` to `add_sub_controller()` for consistency
 - Any Controller instance can now be nested in any other Controller
 
 ## Consequences

docs/explanations/decisions/0011-controller-vector-implementation.md

@@ -10,7 +10,7 @@ Accepted
 
 ## Context
 
-Many devices have multiple identical components that need individual control: multi-axis motion stages, multi-channel power supplies, camera ROI regions, etc. Before ControllerVector, developers manually registered each indexed controller with string-based names:
+Many devices have multiple identical components that need individual control: multi-axis motion stages, multi-channel power supplies, multiple file writers, etc. Developers must manually register each indexed controller with string-based names and check for this pattern throughout the code to perform different logic
 
 ```python
 for i in range(num_axes):
@@ -24,7 +24,7 @@ This approach lacks collection semantics. Accessing controllers requires string
 
 Introduce `ControllerVector`, a specialized controller type for managing collections of indexed sub-controllers with dict-like semantics.
 
-ControllerVector implements `MutableMapping` with integer-only keys, providing natural indexing, iteration, and length operations. It supports non-contiguous indices and can have shared attributes alongside the indexed sub-controllers.
+`ControllerVector` implements `MutableMapping` with integer-only keys, providing natural indexing, iteration, and length operations. It supports non-contiguous indices and can have shared attributes alongside the indexed sub-controllers.
 
 Key architectural changes:
 - `ControllerVector` implements `__getitem__`, `__setitem__`, `__iter__`, `__len__`
@@ -74,17 +74,3 @@ class StageController(Controller):
         for i, motor in self.axes.items():
             print(f"Motor {i}: {motor}")
 ```
-
-**With Shared Attributes:**
-```python
-class AxesVector(ControllerVector):
-    enabled = AttrRW(Bool())  # Shared across all axes
-
-class StageController(Controller):
-    def __init__(self, num_axes: int):
-        super().__init__()
-        self.axes = AxesVector(
-            {i: MotorController() for i in range(num_axes)},
-            description="Motor axes"
-        )
-```