# Remote Peer Configuration

Use `IPeerManagementService` to manage persistent remote peers and their pruning
tracking lifecycle at runtime.

## Supported peer operations

- Add a static remote peer
- Remove a configured peer and tracking
- Remove tracking only (keep static peer config)
- Enable/disable a peer
- List all configured peers

## Add a static peer

```csharp
await peerManagement.AddStaticPeerAsync(
    "branch-2",
    "branch2.example.com:9000",
    cancellationToken);
```

## Peer lifecycle model

Peer management now has two independent dimensions:

- **Remote peer configuration**: whether a static peer exists in remote peer config.
- **Peer confirmation tracking**: whether the peer participates in
  peer-confirmed prune gating.

Common states:

- **Enabled + tracked**: normal operation, peer is eligible for sync and prune gating.
- **Disabled + tracked**: peer config retained, outbound static sync disabled, still
  counted as tracked until tracking is removed/deactivated.
- **Enabled/disabled + untracked**: peer config may remain, but peer is excluded from
  prune confirmation gating.
- **Removed**: peer config removed and tracking removed.

## Remove tracking only (deprecate peer from pruning)

Use this when a peer should no longer gate pruning but you are not removing static
configuration yet.

```csharp
await peerManagement.RemovePeerTrackingAsync(
    nodeId: "branch-2",
    removeRemoteConfig: false,
    cancellationToken);
```

## Remove a peer and tracking (full removal)

`RemoveRemotePeerAsync` performs full cleanup by removing both peer tracking and
static peer configuration.

```csharp
await peerManagement.RemoveRemotePeerAsync("branch-2", cancellationToken);
```

Equivalent explicit call:

```csharp
await peerManagement.RemovePeerTrackingAsync(
    nodeId: "branch-2",
    removeRemoteConfig: true,
    cancellationToken);
```

## Enable or disable a peer

```csharp
await peerManagement.DisablePeerAsync("branch-2", cancellationToken);
await peerManagement.EnablePeerAsync("branch-2", cancellationToken);
```

## List configured peers

```csharp
var peers = await peerManagement.GetAllRemotePeersAsync(cancellationToken);

foreach (var peer in peers)
{
    Console.WriteLine($"{peer.NodeId} @ {peer.Address} ({peer.Type}) Enabled={peer.IsEnabled}");
}
```

## Storage model

Remote peer configuration is persisted in the peer configuration store and synced across nodes as part of CBDDC metadata replication.

Fields stored per peer:
- `NodeId`
- `Address`
- `Type`
- `IsEnabled`
- `InterestingCollections`

## Notes

- Authentication for sync handshakes is based on the cluster shared token (`AuthToken`) from node configuration.
- Disabled peers remain persisted but are excluded from active sync.
- Peer tracking removal is implemented as deactivation in the confirmation store,
  which removes the peer from active prune-gating.
- Re-observed peers can be re-registered and become active for tracking again.
- For rollout steps and production operations, see:
  - [Upgrade: Peer-Confirmed Pruning](upgrade-peer-confirmed-pruning.md)
  - [Peer Deprecation & Removal Runbook](peer-deprecation-removal-runbook.md)