feat: add agent zones

docs/design/AGENT_ZONES.md

@@ -0,0 +1,132 @@
+# 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.