# Agent Zones

## Purpose

An Agent Zone is MinerOps' durable network-reachability boundary. A Site is an
operational location and may contain networks that cannot be reached by one
Agent computer. Agent Zones let those networks remain within one Site without
making Site identity determine control routing.

The implemented relationship is:

```text
Site
  -> Agent Zone
     -> Agent installation
     -> miners reachable through that Zone
```

`agent_id` remains the durable Agent-installation identity. Agent Zone identity
is a UUID independent of the Agent computer assigned to it.

## Site, Zone, And Agent

A Site groups rooms and operational records. An Agent Zone groups one or more
CIDR network ranges that are reachable from an Agent installation. The ranges
are factual Zone configuration for future enrollment and do not implement an
arbitrary routing table.

A Site can contain multiple Zones. For example:

```text
Plexus Mining Site
  Main Room       10.30.0.0/24  -> Agent A
  Room 2          10.40.0.0/24  -> Agent B
  Immersion Room  10.50.0.0/24  -> Agent C
```

Zone names are unique case-insensitively among enabled Zones at the same Site.
They are not globally unique. A Zone can contain multiple canonical PostgreSQL
`CIDR` ranges.

## Routing Authority

Miner control resolves only from Hub-owned facts:

```text
miner UUID
  -> miners.agent_zone_id
  -> Agent assigned to that Zone
  -> miner current IP recorded by MinerOps
  -> local API3 operation
```

A control request from a browser contains none of the routing inputs. It cannot
select an IP address, Agent, Agent Zone, raw vendor command, credentials, or a
dry-run mode. MinerOps never falls back to another Agent merely because it is
assigned to the same Site.

A miner without a Zone is unavailable with `agent_zone_unassigned`. A missing
or disabled Zone is unavailable with `agent_zone_disabled`. A Zone without an
assigned Agent is unavailable with `agent_unavailable`.

## Durable Miner Ownership

`miners.agent_zone_id` is the authoritative reachability assignment. Snapshot
and discovery ingestion can assign a currently unassigned miner when the
authenticated Agent has a valid enabled Zone and Site boundaries agree.

An observation from a different Zone does not move an assigned miner. MinerOps
records or returns `agent_zone_conflict` or `site_conflict` while preserving the
existing assignment. Snapshot and discovery payloads may still be staged as
factual observations. Explicit administrative reassignment is deferred.

## Agent Assignment

Agent Zones v1 permits at most one Agent installation per non-null Zone. A Site
can therefore have multiple Agents when they occupy different Zones. Primary
and standby Agents, automatic failover, and Agent high availability are not
implemented.

An enabled Zone is usable for transitional check-in and control routing. A
disabled Zone preserves its durable associations but cannot be selected for a
new check-in and cannot route miner control.

## Check-In Compatibility

The Windows Agent may send `site_id` and optional `agent_zone_id` during
check-in. Existing configurations that omit `agent_zone_id` remain compatible:

- An established valid assignment is preserved.
- An unassigned Agent can resolve automatically only when the supplied Site has
  exactly one enabled Zone.
- Zero enabled Zones returns `agent_zone_unavailable`.
- Multiple enabled Zones returns `agent_zone_ambiguous`.
- MinerOps never chooses the first Zone.

An explicit Zone must exist, be enabled, and belong to the supplied Site. An
Agent cannot move its established Zone or Site through check-in. Later
administrative Agent management will own reassignment.

## Permissions And APIs

The implemented management foundation reuses existing permissions:

- `GET /api/agent-zones` requires `agents.view`.
- `POST /api/agent-zones` requires `agents.manage`.
- `POST /api/agent/checkin` requires authenticated Agent identity.

The existing role matrix grants `agents.view` to Admin, Manager, Technician,
and Read Only. `agents.manage` is granted to Admin and Manager. No Agent Zone UI
is implemented in this milestone.

## Migration Compatibility

Migration 0016 creates one deterministic `Default Zone` for each pre-existing
Site. Existing miners and Agent assignments with a durable `site_id` are
backfilled to that Site's default Zone. Existing snapshots and discoveries are
associated when their durable Agent assignment makes that association factual.
Rows without a safe Site association remain unassigned.

Downgrade to migration 0015 is allowed only when the Zone configuration can be
represented by its one-Agent-per-Site model. Downgrade refuses before
structural changes when a Site has multiple Agents, non-default Zone topology,
custom Zone state, or network ranges.

## Future Relationship

One-time Agent enrollment tokens, Settings -> Agents, installer downloads,
Linux Agents, update management, administrative reassignment, and primary or
standby Agents are future work. An enrollment flow can use a Zone's configured
network ranges, but enrollment tokens and automatic range delivery are not
implemented by Agent Zones v1.