minerops/docs/design/AGENT_ZONES.md

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:

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:

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:

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.