# Specification Considerations (Iteration 02)

## 1. Service Discovery & Catalog

### 1.1. Goal
The primary goal of this iteration is to allow clients to "see" what the system can do. Instead of sending messages blindly, a client should be able to query the Broker for a "Service Catalog".

### 1.2. Definition of "Service"
In the context of Nanocore, a "Service" is defined by the **Groups** and **Capabilities** (Handlers) that workers provide.
- **Granularity**: The catalog will primarily list active **Worker Groups** (e.g., "math", "text-processing").
- **Detail**: Ideally, it should also list specific **Message Types** that are accepted by those groups, if that metadata is available during registration.

### 1.3. Implementation Approach
- **Introspection**: The Broker already holds a registry of workers (`_workers` dict) and groups (`_groups` dict).
- **Mechanism**:
    1.  The Broker will implement a method `get_catalog()` that aggregates the keys of `_groups` and counts the workers in each.
    2.  A new system-level message type (e.g., `sys_catalog`) will be reserved.
    3.  When the Broker receives a `sys_catalog` message (or via a specific API endpoint), it returns the registry data.

### 1.4. Constraints & Assumptions
- **Assumption**: Workers report their groups correctly upon registration.
- **Constraint**: The catalog is a snapshot in time. Since workers are asynchronous, a worker might disconnect immediately after the catalog is requested.
- **Constraint**: This is a read-only view. Clients cannot modify the catalog directly.

## 2. API Extensions

### 2.1. New Message Types
To support the catalog feature without breaking existing logic, we introduce:
- `catalog_req`: Request from Client to Server.
- `catalog_resp`: Response from Server to Client containing the list.

### 2.2. CLI Updates
The CLI needs a dedicated command `catalog` that sends `catalog_req` and formats the JSON `catalog_resp` into a readable table or list for the user.

## 3. Backward Compatibility
- Existing RPN and Echo functionality must remain unaffected.
- The Heartbeat mechanism continues to run in parallel.
