# API Overview

## Orchestrator Service (`FabricManagerService`)

| RPC | Description |
|-----|-------------|
| `QueryPhysicalTopology` | Returns the aggregated physical topology (all ASICs, connectivity graph, host-to-rank mapping) from healthy agents. Request may set `hosts` to restrict to specific host IDs; empty means all healthy hosts. `topo_source` selects the connectivity source: PSD (default) uses the connectivity discovered by the agents, FSD derives connectivity from the controller-configured Factory System Descriptor ("golden state") while keeping ASIC descriptors from the live PSD |
| `GetValidPlacementsMGD` | Accepts a Mesh Graph Descriptor (MGD textproto) and returns valid host-to-ASIC assignments using CSP-based mapping. Supports constraints: host ID filtering and ASIC pinning. `topo_source` selects whether placement uses the discovered Physical System Descriptor (PSD, default) or the configured Factory System Descriptor (FSD, "golden state") for connectivity |

## Daemon Service (`DaemonService`)

| RPC | Description |
|-----|-------------|
| `RegisterDaemon` | Agent registers its host physical topology (ASICs, local connections, exit nodes) with the controller |
| `HeartbeatStream` | Bidirectional streaming RPC for keepalive. Controller NACKs trigger re-registration. Hosts are marked offline after timeout |