# Contracts: PD / Placement RPCs (Multi-Raft)

Source of truth: `rdb-proto/src/pdpb.proto`

## Services

- **Pd**
  - `RegisterStore(RegisterStoreRequest) -> RegisterStoreResponse`
  - `GetRegion(GetRegionRequest) -> GetRegionResponse`
  - `ListRegions(ListRegionsRequest) -> ListRegionsResponse`
  - `MoveRegion(MoveRegionRequest) -> MoveRegionResponse`

## Messages (selected)

- `Region`:
  - `id: u64`
  - `start_key: bytes`
  - `end_key: bytes` (empty = infinity)
  - `peers: repeated u64` (store IDs)
  - `leader_id: u64`

- `Store`:
  - `id: u64`
  - `addr: string`

- `MoveRegionRequest`:
  - `region_id: u64`
  - `from_store: u64`
  - `to_store: u64`

## Behaviors / Expectations

- `ListRegions` is used at bootstrap and periodic refresh to populate routing.
- `MoveRegion` directs a leader to add a replica on `to_store` (ConfChange Add) and, after catch-up, remove `from_store` (ConfChange Remove). Current implementation keeps source online; removal can be triggered separately.
- Region key ranges returned by PD must be non-overlapping; nodes validate and fail startup on overlap.
- Heartbeat: nodes periodically refresh routing via `ListRegions` (30s). A dedicated heartbeat RPC can replace this in a future phase.