# Specification Considerations

This document provides context, assumptions, and constraints for the Nanocore specifications defined in `325.spec.results.md`.

## 1. Architectural Considerations

### Worker-Broker Pattern
The choice of a Worker-Broker architecture is central to the "dispatch message core" concept.
- **Decoupling**: The Broker decouples the message producers from the consumers (Workers). This allows the system to scale the number of workers without changing the producer logic.
- **Async Event Loop**: The restriction to a single thread (using `asyncio`) simplifies state management and avoids the complexities of multi-threading (locks, race conditions) but requires non-blocking I/O for performance.
- **Signal Mechanism**: The "signal" mentioned in specs likely refers to an `asyncio.Event` or similar primitive to wake up workers, rather than OS-level signals, to maintain the single-loop paradigm.

### Client-Server Split
- **TUI Client**: A Terminal User Interface suggests a tool for developers or power users, likely running in a separate process or machine.
- **WebSockets**: Chosen for real-time bidirectional communication, essential for the heartbeat mechanism and immediate command feedback.

## 2. Assumptions

- **Primary Language**: While `cargo` (Rust) is listed in the tools, the core architectural descriptions (asyncio, FastAPI, Pytest config in root) strongly imply **Python** is the primary language for this iteration. Rust tools might be intended for future performance-critical extensions or this is a hybrid project setup.
- **Environment**: It is assumed that the `workspace` concept maps to a local filesystem directory, and "launching multiple times" implies running separate OS processes pointing to different or shared workspace folders.
- **Heartbeat**: The strict 5s/10s heartbeat rule assumes a stable network for the Client-Server connection. Handling network jitter or temporary drops might need retries, but the current spec is strict.

## 3. Constraints

- **Single Threaded**: The core must run in a single thread. CPU-bound tasks in Workers will block the Broker and other Workers. Heavy computation must be offloaded or broken into small chunks.
- **Message Queue**: In-memory queues (fast lists) imply that if the process crashes, unprocessed messages are lost unless a persistence layer (not yet specified) is added.
- **Folder-based Workspace**: The application state or configuration is tied to a specific directory. The system must handle path resolution robustness.

## 4. Dependencies

- **Python Ecosystem**: `asyncio` (std lib), `fastapi`, `uv` (for project management).
- **Virtualization**: `docker` and `docker-compose` are required for the standard development and deployment lifecycle described.
- **Testing**: High coverage requirements (>90%) and fuzzing imply a need for robust test suites (likely `pytest` based on the file structure `conftest.py` in root).

## 5. Development Strategy

- The inclusion of `uv`, `cargo`, and `docker-compose` as parallel toolchains suggests a flexible developer experience. The CI/CD pipeline must abstract these differences to provide a uniform interface (`ci`, `cd`, `test` commands).
- The "RPN Calculator" test case serves as the MVP (Minimum Viable Product) to validate the Broker-Worker logic before building complex features.