# Specification Results (Iteration 02)

## 1. Core System Architecture
### 1.1. Broker
The central component responsible for managing workers and routing messages.
- [ ] **Worker Registration**:
    - [ ] Maintain a registry of active workers.
    - [ ] Support grouping of workers (e.g., "math", "code_ops").
- [ ] **Message Dispatching**:
    - [ ] **Direct**: Route to a specific worker ID.
    - [ ] **Broadcast**: Route to all workers in a specific group.
    - [ ] **Round-Robin**: Route to one worker in a group (load balancing).
- [ ] **Service Discovery (New)**:
    - [ ] **Catalog Generation**: dynamically generate a catalog of available services based on registered workers.
    - [ ] **Introspection**: Inspect workers to identify their capabilities (registered handlers/groups).
    - [ ] **Query API**: Provide a mechanism (internal method or message handler) to return the current catalog of services.

### 1.2. Worker
The unit of execution that processes messages.
- [ ] **Event Loop**: Run an asynchronous event loop to process messages from a local queue.
- [ ] **Handler Management**:
    - [ ] Register specific functions as message handlers.
    - [ ] (Implicit) Report capabilities/groups to Broker upon registration.
- [ ] **Queueing**: Implement a memory-efficient queue for incoming messages.
- [ ] **Lifecycle**: Start, Stop, and Signal handling.

## 2. API & Communication
### 2.1. Server (FastAPI)
- [ ] **WebSockets**:
    - [ ] Endpoint `/ws` for client connections.
    - [ ] Handle JSON-formatted messages.
- [ ] **Health Check**: Endpoint `/health` to report system status and worker counts.

### 2.2. Protocol
- [ ] **Heartbeat**:
    - [ ] Server sends `ping` every 5 seconds.
    - [ ] Client expects `ping` and sends `pong`.
    - [ ] Timeout threshold: 10 seconds.
- [ ] **Message Structure**: Standardized JSON envelope (Header + Body).

## 3. Client Interface (CLI)
### 3.1. Connection Management
- [ ] `connect <url>`: Establish WebSocket connection to the server.
- [ ] `disconnect`: Close the connection.

### 3.2. Interaction
- [ ] **Shell Loop**: Interactive REPL for sending commands.
- [ ] **Commands**:
    - [ ] `push`, `add` (Legacy/RPN support).
    - [ ] **`catalog` (New)**: Request and display the list of available services from the Broker.
    - [ ] `help`: Show available commands.

## 4. Workspace & Configuration
- [ ] **Isolation**: All file operations restricted to `WORKSPACE_DIR`.
- [ ] **Environment**: Load settings from `.env` files.
- [ ] **Path Resolution**: Securely resolve paths to prevent traversal attacks.

## 5. Development & QA
- [ ] **Testing**:
    - [ ] Unit tests for all components.
    - [ ] Integration tests for Broker-Worker communication.
    - [ ] Fuzz testing for Broker routing and RPN logic.
- [ ] **Code Quality**:
    - [ ] Linting (Ruff).
    - [ ] Type checking.
- [ ] **Documentation**: Maintain up-to-date architectural and usage docs.
