merge: promote Internal Alpha

.env.dev.example

@@ -0,0 +1,20 @@
+# Copying this file is optional. scripts/dev-env-init.sh generates strong secrets.
+APP_ENV=development
+APP_TIMEZONE=America/Winnipeg
+POSTGRES_DB=minerops_dev
+POSTGRES_USER=minerops_dev
+POSTGRES_PASSWORD=replace-with-a-random-local-only-secret
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+DATABASE_URL=postgresql://minerops_dev:replace-with-a-random-local-only-secret@postgres:5432/minerops_dev
+REDIS_URL=redis://redis:6379/0
+JWT_SECRET_KEY=replace-with-a-random-local-only-secret
+MINEROPS_AGENT_SHARED_SECRET=replace-with-a-random-local-only-secret
+MINEROPS_DEV_PORT=18000
+
+# Safety interlocks: keep these values disabled for development.
+SCHEDULED_SCAN_ENABLED=false
+MINEROPS_HUB_MODE=true
+MINEROPS_DISABLE_LOCAL_SCANNER=true
+MINEROPS_ENABLE_REAL_REBOOT=false
+MINEROPS_ENABLE_REAL_POWER_CONTROL=false

.gitignore

@@ -2,6 +2,8 @@
 .env
 .env.*
 *.env
+!.env.example
+!.env.dev.example
 
 # Backups / dumps / generated data
 backups/
@@ -13,6 +15,8 @@ imports/
 *.dump
 *.bak
 *.csv
+!sql/
+!sql/*.sql
 
 # Python
 __pycache__/

ARCHITECTURE.md

@@ -0,0 +1,64 @@
+# MinerOps Target Architecture
+
+MinerOps will move from its current working checkpoint toward a modular
+operations platform without a big-bang rewrite. Every milestone must leave the
+production application deployable and preserve verified workflows.
+
+## Boundaries
+
+- The hub owns users, authorization, fleet inventory, repairs, locations,
+  reporting, command policy, audit history, and long-term telemetry.
+- Site agents own network-local discovery, polling, and miner command
+  execution.
+- The hub must not require a route to miner VLANs.
+- WhatsMiner protocols are adapters behind one capability-based interface.
+
+## Backend
+
+The target backend is organized into FastAPI routers, domain services, and
+database repositories for:
+
+- identity and access
+- fleet inventory
+- telemetry and retention
+- repairs and parts
+- locations
+- agents and command queues
+- WhatsMiner protocol capabilities
+- system health
+
+Alembic is the only authority for persistent schema changes. Runtime table
+creation remains temporarily for backward compatibility and will be removed
+after migrations and tests cover every current path.
+
+## Frontend
+
+The target frontend is a typed, responsive application with a shared design
+system. Authentication is established before protected pages render. Views
+adapt to desktop, tablet, and phone layouts and expose actions according to
+server-enforced permissions.
+
+## Identity
+
+MinerOps application accounts are distinct from WhatsMiner device accounts.
+The default application roles will be Admin, Manager, Technician, and Read
+Only. Authorization is permission-based and enforced by backend endpoints.
+
+## Safety
+
+- Scanning and real controls are disabled by default in development.
+- Site-agent commands are authenticated, durable, expiring, idempotent, and
+  audited.
+- Destructive operations support dry-run behavior and explicit authorization.
+- Protocol adapters are tested with sanitized fixtures before real controls are
+  enabled.
+
+## Migration Order
+
+1. Reproducible schema and development baseline.
+2. Accounts, roles, secure sessions, and login gate.
+3. Responsive application shell and shared UI components.
+4. Optimized dashboard loading.
+5. WhatsMiner 4028 and 4433 protocol adapters.
+6. Incremental extraction of repairs, locations, agents, commands, and health
+   from the legacy application module.

backend/.dockerignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.bak
+*.bak.*
+.pytest_cache/
+.mypy_cache/

backend/alembic/versions/0006_operational_schema_baseline.py

@@ -0,0 +1,478 @@
+"""capture the operational schema baseline
+
+Revision ID: 0006_operational_schema_baseline
+Revises: 0005_miner_inventory
+Create Date: 2026-07-27
+
+This migration adopts tables that older MinerOps builds created at runtime.
+The IF NOT EXISTS clauses allow it to run against both an existing deployment
+and a new database.
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = "0006_operational_schema_baseline"
+down_revision: Union[str, None] = "0005_miner_inventory"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        ALTER TABLE miners
+            ADD COLUMN IF NOT EXISTS manual_details JSONB NOT NULL DEFAULT '{}'::jsonb,
+            ADD COLUMN IF NOT EXISTS manual_details_updated_at TIMESTAMPTZ,
+            ADD COLUMN IF NOT EXISTS manual_details_updated_by TEXT,
+            ADD COLUMN IF NOT EXISTS psu_model TEXT,
+            ADD COLUMN IF NOT EXISTS customer_sn TEXT,
+            ADD COLUMN IF NOT EXISTS api3_supported BOOLEAN,
+            ADD COLUMN IF NOT EXISTS api3_api_version TEXT,
+            ADD COLUMN IF NOT EXISTS api3_api_switch TEXT,
+            ADD COLUMN IF NOT EXISTS api3_last_seen_at TIMESTAMPTZ,
+            ADD COLUMN IF NOT EXISTS api3_last_error TEXT,
+            ADD COLUMN IF NOT EXISTS configured_performance_mode TEXT,
+            ADD COLUMN IF NOT EXISTS configured_performance_mode_source TEXT,
+            ADD COLUMN IF NOT EXISTS configured_performance_mode_updated_at TIMESTAMPTZ;
+
+        ALTER TABLE miner_status_snapshots
+            ADD COLUMN IF NOT EXISTS ip_address INET,
+            ADD COLUMN IF NOT EXISTS mac_address TEXT,
+            ADD COLUMN IF NOT EXISTS fan_speed_in DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS fan_speed_out DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS elapsed_seconds DOUBLE PRECISION;
+        """
+    )
+
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS miner_maintenance_events (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            miner_id UUID NOT NULL REFERENCES miners(id) ON DELETE CASCADE,
+            event_type TEXT NOT NULL,
+            event_status TEXT NOT NULL DEFAULT 'completed',
+            event_title TEXT NOT NULL,
+            description TEXT,
+            event_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            old_mac TEXT,
+            new_mac TEXT,
+            old_ip INET,
+            new_ip INET,
+            component_type TEXT,
+            component_slot TEXT,
+            component_serial TEXT,
+            cost_amount NUMERIC(12, 2),
+            downtime_minutes INTEGER,
+            created_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_maintenance_events_miner_id
+            ON miner_maintenance_events(miner_id);
+        CREATE INDEX IF NOT EXISTS idx_miner_maintenance_events_event_at
+            ON miner_maintenance_events(event_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_miner_maintenance_events_event_type
+            ON miner_maintenance_events(event_type);
+
+        CREATE TABLE IF NOT EXISTS location_positions (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            room_id UUID REFERENCES rooms(id) ON DELETE SET NULL,
+            room_name TEXT NOT NULL,
+            rack_name TEXT NOT NULL,
+            shelf_name TEXT NOT NULL,
+            shelf_index INTEGER,
+            position_index INTEGER NOT NULL,
+            position_label TEXT,
+            position_kind TEXT NOT NULL DEFAULT 'miner_slot',
+            position_status TEXT NOT NULL DEFAULT 'available',
+            expected_mac TEXT,
+            miner_id UUID REFERENCES miners(id) ON DELETE SET NULL,
+            equipment_label TEXT,
+            notes TEXT,
+            source_file TEXT,
+            source_sheet TEXT,
+            source_cell TEXT,
+            raw_value TEXT,
+            conflict_reason TEXT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        DO $$
+        BEGIN
+            ALTER TABLE location_positions
+                ADD CONSTRAINT uq_location_positions_slot
+                UNIQUE (room_name, rack_name, shelf_name, position_index);
+        EXCEPTION
+            WHEN duplicate_object OR duplicate_table THEN NULL;
+        END $$;
+
+        CREATE INDEX IF NOT EXISTS idx_location_positions_room
+            ON location_positions(room_name);
+        CREATE INDEX IF NOT EXISTS idx_location_positions_rack
+            ON location_positions(room_name, rack_name);
+        CREATE INDEX IF NOT EXISTS idx_location_positions_expected_mac
+            ON location_positions(expected_mac);
+        CREATE INDEX IF NOT EXISTS idx_location_positions_miner_id
+            ON location_positions(miner_id);
+
+        CREATE TABLE IF NOT EXISTS miner_location_states (
+            miner_id UUID PRIMARY KEY REFERENCES miners(id) ON DELETE CASCADE,
+            asset_state TEXT NOT NULL DEFAULT 'waiting_placement',
+            location_position_id UUID REFERENCES location_positions(id) ON DELETE SET NULL,
+            state_notes TEXT,
+            updated_by_user_id UUID REFERENCES users(id) ON DELETE SET NULL,
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_location_states_asset_state
+            ON miner_location_states(asset_state);
+
+        CREATE TABLE IF NOT EXISTS location_import_issues (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            import_batch_id UUID NOT NULL,
+            issue_type TEXT NOT NULL,
+            severity TEXT NOT NULL DEFAULT 'warning',
+            message TEXT NOT NULL,
+            mac_address TEXT,
+            room_name TEXT,
+            rack_name TEXT,
+            shelf_name TEXT,
+            position_index INTEGER,
+            source_file TEXT,
+            source_cell TEXT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            resolved_at TIMESTAMPTZ
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_location_import_issues_batch
+            ON location_import_issues(import_batch_id);
+        CREATE INDEX IF NOT EXISTS idx_location_import_issues_mac
+            ON location_import_issues(mac_address);
+        """
+    )
+
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS miner_command_events (
+            id TEXT PRIMARY KEY,
+            miner_id TEXT NOT NULL,
+            command_type TEXT NOT NULL,
+            command_status TEXT NOT NULL,
+            dry_run BOOLEAN NOT NULL DEFAULT true,
+            requested_by_user_id TEXT,
+            requested_by_username TEXT,
+            target_ip TEXT,
+            target_mac TEXT,
+            request_payload JSONB,
+            response_payload JSONB,
+            error_message TEXT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            completed_at TIMESTAMPTZ
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_command_events_miner_id_created
+            ON miner_command_events(miner_id, created_at DESC);
+
+        CREATE TABLE IF NOT EXISTS miner_api_credentials (
+            miner_id TEXT PRIMARY KEY,
+            api_account TEXT NOT NULL DEFAULT 'super',
+            api_password TEXT NOT NULL,
+            password_source TEXT NOT NULL DEFAULT 'minerops',
+            updated_by_username TEXT,
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        CREATE TABLE IF NOT EXISTS minerops_site_agents (
+            agent_id TEXT PRIMARY KEY,
+            site_name TEXT NOT NULL,
+            hostname TEXT,
+            version TEXT,
+            ip_address TEXT,
+            last_checkin_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            last_payload JSONB NOT NULL DEFAULT '{}'::jsonb
+        );
+
+        CREATE TABLE IF NOT EXISTS minerops_agent_snapshots (
+            id BIGSERIAL PRIMARY KEY,
+            agent_id TEXT NOT NULL,
+            site_name TEXT NOT NULL,
+            snapshot_kind TEXT NOT NULL DEFAULT 'miner_poll',
+            received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            miner_count INTEGER NOT NULL DEFAULT 0,
+            payload JSONB NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_minerops_agent_snapshots_received
+            ON minerops_agent_snapshots(received_at DESC);
+
+        CREATE TABLE IF NOT EXISTS minerops_agent_command_results (
+            id BIGSERIAL PRIMARY KEY,
+            agent_id TEXT NOT NULL,
+            site_name TEXT NOT NULL,
+            command_id TEXT,
+            received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            status TEXT NOT NULL,
+            payload JSONB NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_minerops_agent_command_results_received
+            ON minerops_agent_command_results(received_at DESC);
+
+        CREATE TABLE IF NOT EXISTS minerops_agent_command_queue (
+            id TEXT PRIMARY KEY,
+            agent_id TEXT NOT NULL,
+            command_type TEXT NOT NULL,
+            command_status TEXT NOT NULL DEFAULT 'pending',
+            requested_by_user_id TEXT,
+            requested_by_username TEXT,
+            request_payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+            result_payload JSONB,
+            error_message TEXT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            claimed_at TIMESTAMPTZ,
+            completed_at TIMESTAMPTZ
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_minerops_agent_command_queue_agent_status
+            ON minerops_agent_command_queue(agent_id, command_status, created_at);
+
+        CREATE TABLE IF NOT EXISTS minerops_agent_discoveries (
+            id TEXT PRIMARY KEY,
+            agent_id TEXT NOT NULL,
+            site_name TEXT NOT NULL,
+            room_name TEXT,
+            ip_address INET,
+            mac_address TEXT,
+            model TEXT,
+            hostname TEXT,
+            miner_sn TEXT,
+            raw_payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+            discovery_status TEXT NOT NULL DEFAULT 'new',
+            matched_miner_id UUID,
+            first_seen_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            last_seen_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_minerops_agent_discoveries_mac
+            ON minerops_agent_discoveries(mac_address);
+        CREATE INDEX IF NOT EXISTS idx_minerops_agent_discoveries_ip
+            ON minerops_agent_discoveries(ip_address);
+        """
+    )
+
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS minerops_scheduled_bulk_actions (
+            id TEXT PRIMARY KEY,
+            name TEXT,
+            target_type TEXT NOT NULL,
+            target_value TEXT,
+            action TEXT NOT NULL DEFAULT 'performance_mode',
+            performance_mode TEXT,
+            repeat_rule TEXT NOT NULL DEFAULT 'once',
+            scheduled_for TIMESTAMPTZ NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            agent_id TEXT NOT NULL DEFAULT 'plexus-windows-agent',
+            requested_by_user_id TEXT,
+            requested_by_username TEXT,
+            queued_command_count INTEGER NOT NULL DEFAULT 0,
+            last_queued_command_count INTEGER NOT NULL DEFAULT 0,
+            run_count INTEGER NOT NULL DEFAULT 0,
+            last_error TEXT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            processed_at TIMESTAMPTZ
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_minerops_scheduled_bulk_actions_due
+            ON minerops_scheduled_bulk_actions(status, scheduled_for);
+        CREATE INDEX IF NOT EXISTS idx_minerops_scheduled_bulk_actions_created
+            ON minerops_scheduled_bulk_actions(created_at DESC);
+
+        CREATE TABLE IF NOT EXISTS miner_pool_snapshots (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            miner_id UUID,
+            ip_address INET,
+            mac_address TEXT,
+            model TEXT,
+            pool_index INTEGER,
+            url TEXT,
+            worker_user TEXT,
+            pool_status TEXT,
+            stratum_active BOOLEAN,
+            accepted DOUBLE PRECISION,
+            rejected DOUBLE PRECISION,
+            stale DOUBLE PRECISION,
+            get_failures DOUBLE PRECISION,
+            remote_failures DOUBLE PRECISION,
+            pool_rejected_percent DOUBLE PRECISION,
+            pool_stale_percent DOUBLE PRECISION,
+            last_share_time_epoch DOUBLE PRECISION,
+            raw_pool_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+            agent_id TEXT,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        ALTER TABLE miner_pool_snapshots
+            ADD COLUMN IF NOT EXISTS model TEXT,
+            ADD COLUMN IF NOT EXISTS pool_index INTEGER,
+            ADD COLUMN IF NOT EXISTS url TEXT,
+            ADD COLUMN IF NOT EXISTS worker_user TEXT,
+            ADD COLUMN IF NOT EXISTS pool_status TEXT,
+            ADD COLUMN IF NOT EXISTS stratum_active BOOLEAN,
+            ADD COLUMN IF NOT EXISTS accepted DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS rejected DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS stale DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS get_failures DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS remote_failures DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS pool_rejected_percent DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS pool_stale_percent DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS last_share_time_epoch DOUBLE PRECISION,
+            ADD COLUMN IF NOT EXISTS raw_pool_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+            ADD COLUMN IF NOT EXISTS agent_id TEXT;
+
+        DO $$
+        DECLARE
+            id_type TEXT;
+        BEGIN
+            SELECT data_type INTO id_type
+            FROM information_schema.columns
+            WHERE table_schema = current_schema()
+              AND table_name = 'miner_pool_snapshots'
+              AND column_name = 'id';
+
+            IF id_type = 'text' THEN
+                ALTER TABLE miner_pool_snapshots
+                    ALTER COLUMN id SET DEFAULT (gen_random_uuid())::text;
+            ELSIF id_type = 'uuid' THEN
+                ALTER TABLE miner_pool_snapshots
+                    ALTER COLUMN id SET DEFAULT gen_random_uuid();
+            END IF;
+        END $$;
+
+        CREATE INDEX IF NOT EXISTS idx_miner_pool_snapshots_miner_created
+            ON miner_pool_snapshots(miner_id, created_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_miner_pool_snapshots_ip_created
+            ON miner_pool_snapshots(ip_address, created_at DESC);
+
+        CREATE TABLE IF NOT EXISTS miner_api3_enrichment_snapshots (
+            id BIGSERIAL PRIMARY KEY,
+            miner_id UUID,
+            agent_id TEXT,
+            site_name TEXT,
+            ip_address INET,
+            mac_address TEXT,
+            api_supported BOOLEAN,
+            api_error TEXT,
+            api_version TEXT,
+            api_switch TEXT,
+            model TEXT,
+            miner_sn TEXT,
+            power_sn TEXT,
+            psu_model TEXT,
+            device_info JSONB,
+            miner_setting JSONB,
+            miner_status JSONB,
+            fan_setting JSONB,
+            custom_data JSONB,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_api3_enrichment_miner_created
+            ON miner_api3_enrichment_snapshots(miner_id, created_at DESC);
+
+        CREATE TABLE IF NOT EXISTS miner_api3_hashboard_snapshots (
+            id BIGSERIAL PRIMARY KEY,
+            miner_id UUID,
+            ip_address INET,
+            mac_address TEXT,
+            slot INTEGER,
+            pcb_sn TEXT,
+            hash_average_ths DOUBLE PRECISION,
+            factory_hash_ths DOUBLE PRECISION,
+            freq DOUBLE PRECISION,
+            effective_chips INTEGER,
+            chip_temp_min_c DOUBLE PRECISION,
+            chip_temp_avg_c DOUBLE PRECISION,
+            chip_temp_max_c DOUBLE PRECISION,
+            raw_hashboard_json JSONB,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_api3_hashboards_miner_created
+            ON miner_api3_hashboard_snapshots(miner_id, created_at DESC);
+        """
+    )
+
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS miner_status_hourly_rollups (
+            miner_id UUID NOT NULL REFERENCES miners(id) ON DELETE CASCADE,
+            bucket_at TIMESTAMPTZ NOT NULL,
+            sample_count BIGINT NOT NULL,
+            avg_mhs_av DOUBLE PRECISION,
+            max_mhs_av DOUBLE PRECISION,
+            avg_power_w DOUBLE PRECISION,
+            max_chip_temp_c DOUBLE PRECISION,
+            avg_chip_temp_c DOUBLE PRECISION,
+            avg_pool_rejected_percent DOUBLE PRECISION,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (miner_id, bucket_at)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_status_hourly_bucket
+            ON miner_status_hourly_rollups(bucket_at);
+
+        CREATE TABLE IF NOT EXISTS miner_status_daily_rollups (
+            miner_id UUID NOT NULL REFERENCES miners(id) ON DELETE CASCADE,
+            bucket_date DATE NOT NULL,
+            sample_count BIGINT NOT NULL,
+            avg_mhs_av DOUBLE PRECISION,
+            max_mhs_av DOUBLE PRECISION,
+            avg_power_w DOUBLE PRECISION,
+            max_chip_temp_c DOUBLE PRECISION,
+            avg_chip_temp_c DOUBLE PRECISION,
+            avg_pool_rejected_percent DOUBLE PRECISION,
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (miner_id, bucket_date)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_miner_status_daily_bucket
+            ON miner_status_daily_rollups(bucket_date);
+
+        CREATE TABLE IF NOT EXISTS minerops_retention_runs (
+            id BIGSERIAL PRIMARY KEY,
+            mode TEXT NOT NULL,
+            raw_status_retention_days INTEGER NOT NULL,
+            hourly_rollup_rows_before BIGINT NOT NULL DEFAULT 0,
+            hourly_rollup_rows_after BIGINT NOT NULL DEFAULT 0,
+            daily_rollup_rows_before BIGINT NOT NULL DEFAULT 0,
+            daily_rollup_rows_after BIGINT NOT NULL DEFAULT 0,
+            raw_status_rows_before BIGINT NOT NULL DEFAULT 0,
+            raw_status_rows_after BIGINT NOT NULL DEFAULT 0,
+            raw_status_rows_eligible_delete BIGINT NOT NULL DEFAULT 0,
+            raw_status_rows_deleted BIGINT NOT NULL DEFAULT 0,
+            started_at TIMESTAMPTZ NOT NULL,
+            finished_at TIMESTAMPTZ NOT NULL,
+            notes TEXT
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_minerops_retention_runs_started
+            ON minerops_retention_runs(started_at DESC);
+        """
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError(
+        "0006 adopts pre-existing operational tables and is intentionally irreversible"
+    )

backend/alembic/versions/0007_identity_and_roles.py

@@ -0,0 +1,161 @@
+"""add application roles and permission matrix
+
+Revision ID: 0007_identity_and_roles
+Revises: 0006_operational_schema_baseline
+Create Date: 2026-07-27
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = "0007_identity_and_roles"
+down_revision: Union[str, None] = "0006_operational_schema_baseline"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+PERMISSIONS = (
+    ("dashboard.view", "View fleet dashboards"),
+    ("miners.view", "View miners and telemetry"),
+    ("miners.update", "Update miner inventory and details"),
+    ("miners.control", "Run approved miner control operations"),
+    ("repairs.view", "View repair queues and history"),
+    ("repairs.manage", "Manage repairs, notes, parts, and status"),
+    ("locations.view", "View rooms, racks, shelves, and placements"),
+    ("locations.manage", "Manage layouts and miner placements"),
+    ("agents.view", "View site agents and command status"),
+    ("agents.manage", "Queue and manage site-agent work"),
+    ("system_health.view", "View system health and retention status"),
+    ("users.manage", "Create and manage MinerOps accounts"),
+    ("credentials.manage", "Manage protected miner credentials"),
+    ("scan_ranges.manage", "Manage scan ranges"),
+    ("scans.run", "Run discovery and polling operations"),
+    ("exports.create", "Export operational data"),
+    ("audit.view", "View audit history"),
+)
+
+ROLE_PERMISSIONS = {
+    "Manager": (
+        "dashboard.view",
+        "miners.view",
+        "miners.update",
+        "miners.control",
+        "repairs.view",
+        "repairs.manage",
+        "locations.view",
+        "locations.manage",
+        "agents.view",
+        "agents.manage",
+        "system_health.view",
+        "scan_ranges.manage",
+        "scans.run",
+        "exports.create",
+        "audit.view",
+    ),
+    "Technician": (
+        "dashboard.view",
+        "miners.view",
+        "miners.update",
+        "miners.control",
+        "repairs.view",
+        "repairs.manage",
+        "locations.view",
+        "locations.manage",
+        "agents.view",
+        "scans.run",
+        "exports.create",
+    ),
+    "Read Only": (
+        "dashboard.view",
+        "miners.view",
+        "repairs.view",
+        "locations.view",
+        "agents.view",
+        "system_health.view",
+    ),
+}
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+
+    for key, description in PERMISSIONS:
+        connection.exec_driver_sql(
+            """
+            INSERT INTO permissions (key, description)
+            VALUES (%s, %s)
+            ON CONFLICT (key) DO UPDATE
+            SET description = EXCLUDED.description
+            """,
+            (key, description),
+        )
+
+    connection.exec_driver_sql(
+        """
+        INSERT INTO roles (name, description)
+        VALUES
+            ('Manager', 'Operational manager with fleet and workflow control'),
+            ('Read Only', 'Read-only access to operational views')
+        ON CONFLICT (name) DO UPDATE
+        SET description = EXCLUDED.description
+        """
+    )
+
+    connection.exec_driver_sql(
+        """
+        UPDATE roles
+        SET description = CASE name
+            WHEN 'Admin' THEN 'Full MinerOps administrator'
+            WHEN 'Technician' THEN 'Technician for repair and fleet operations'
+            ELSE description
+        END
+        WHERE name IN ('Admin', 'Technician')
+        """
+    )
+
+    connection.exec_driver_sql(
+        """
+        UPDATE users
+        SET role_id = (SELECT id FROM roles WHERE name = 'Read Only')
+        WHERE role_id IN (
+            SELECT id FROM roles WHERE name IN ('Viewer', 'Auditor')
+        )
+        """
+    )
+    connection.exec_driver_sql(
+        "DELETE FROM role_permissions WHERE role_id IN (SELECT id FROM roles WHERE name IN ('Viewer', 'Auditor'))"
+    )
+    connection.exec_driver_sql("DELETE FROM roles WHERE name IN ('Viewer', 'Auditor')")
+
+    connection.exec_driver_sql(
+        "DELETE FROM role_permissions WHERE role_id IN (SELECT id FROM roles WHERE name IN ('Admin', 'Manager', 'Technician', 'Read Only'))"
+    )
+    connection.exec_driver_sql(
+        """
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id
+        FROM roles
+        CROSS JOIN permissions
+        WHERE roles.name = 'Admin'
+        ON CONFLICT DO NOTHING
+        """
+    )
+
+    for role_name, keys in ROLE_PERMISSIONS.items():
+        connection.exec_driver_sql(
+            """
+            INSERT INTO role_permissions (role_id, permission_id)
+            SELECT roles.id, permissions.id
+            FROM roles
+            JOIN permissions ON permissions.key = ANY(%s)
+            WHERE roles.name = %s
+            ON CONFLICT DO NOTHING
+            """,
+            (list(keys), role_name),
+        )
+
+
+def downgrade() -> None:
+    raise RuntimeError("0007 changes live role assignments and is intentionally irreversible")

backend/alembic/versions/0008_manual_miner_inventory.py

@@ -0,0 +1,193 @@
+"""add manual miner inventory schema
+
+Revision ID: 0008_manual_miner_inventory
+Revises: 0007_identity_and_roles
+Create Date: 2026-07-28
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "0008_manual_miner_inventory"
+down_revision: Union[str, None] = "0007_identity_and_roles"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+TAG_TRIMMED_NAME_SQL = (
+    "regexp_replace(name, '^[[:space:]]+|[[:space:]]+$', '', 'g')"
+)
+
+
+def upgrade() -> None:
+    op.add_column("miners", sa.Column("control_board_sn", sa.Text(), nullable=True))
+    op.add_column(
+        "miners",
+        sa.Column(
+            "lifecycle_status",
+            sa.Text(),
+            nullable=False,
+            server_default=sa.text("'active'"),
+        ),
+    )
+    op.create_check_constraint(
+        "ck_miners_lifecycle_status",
+        "miners",
+        "lifecycle_status IN ('active', 'spare', 'retired')",
+    )
+
+    op.execute(
+        """
+        DO $$
+        DECLARE
+            conflicting_asset_ids TEXT;
+        BEGIN
+            SELECT string_agg(
+                format('%L (%s records)', normalized_asset_id, record_count),
+                ', ' ORDER BY normalized_asset_id
+            )
+            INTO conflicting_asset_ids
+            FROM (
+                SELECT
+                    lower(trim(asset_tag)) AS normalized_asset_id,
+                    COUNT(*) AS record_count
+                FROM miners
+                WHERE asset_tag IS NOT NULL
+                  AND trim(asset_tag) <> ''
+                GROUP BY lower(trim(asset_tag))
+                HAVING COUNT(*) > 1
+            ) conflicts;
+
+            IF conflicting_asset_ids IS NOT NULL THEN
+                RAISE EXCEPTION USING
+                    MESSAGE = 'Cannot enforce globally unique Asset IDs. '
+                        || 'Conflicting normalized values: '
+                        || conflicting_asset_ids,
+                    HINT = 'Correct the conflicting miners.asset_tag values '
+                        || 'before upgrading, then run the migration again.';
+            END IF;
+        END
+        $$;
+        """
+    )
+    op.create_index(
+        "uq_miners_asset_tag_ci",
+        "miners",
+        [sa.text("lower(trim(asset_tag))")],
+        unique=True,
+        postgresql_where=sa.text("asset_tag IS NOT NULL AND trim(asset_tag) <> ''"),
+    )
+
+    op.create_table(
+        "tags",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column("name", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.CheckConstraint(
+            f"{TAG_TRIMMED_NAME_SQL} <> ''",
+            name="ck_tags_name_not_blank",
+        ),
+    )
+    op.create_index(
+        "uq_tags_name_ci",
+        "tags",
+        [sa.text(f"lower({TAG_TRIMMED_NAME_SQL})")],
+        unique=True,
+    )
+
+    op.create_table(
+        "miner_tags",
+        sa.Column(
+            "miner_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("miners.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "tag_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("tags.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("miner_id", "tag_id", name="pk_miner_tags"),
+    )
+    op.create_index("idx_miner_tags_tag_id", "miner_tags", ["tag_id"])
+
+    # Discovery continues to receive now() defaults. Manual creation can
+    # explicitly store NULL to represent an asset that has never been observed.
+    op.alter_column(
+        "miners",
+        "first_seen_at",
+        existing_type=sa.DateTime(timezone=True),
+        existing_server_default=sa.text("now()"),
+        nullable=True,
+    )
+    op.alter_column(
+        "miners",
+        "last_seen_at",
+        existing_type=sa.DateTime(timezone=True),
+        existing_server_default=sa.text("now()"),
+        nullable=True,
+    )
+
+
+def downgrade() -> None:
+    # created_at is non-null in the pre-0008 schema, making this deterministic.
+    op.execute(
+        """
+        UPDATE miners
+        SET first_seen_at = COALESCE(first_seen_at, created_at),
+            last_seen_at = COALESCE(last_seen_at, created_at)
+        WHERE first_seen_at IS NULL
+           OR last_seen_at IS NULL;
+        """
+    )
+    op.alter_column(
+        "miners",
+        "last_seen_at",
+        existing_type=sa.DateTime(timezone=True),
+        existing_server_default=sa.text("now()"),
+        nullable=False,
+    )
+    op.alter_column(
+        "miners",
+        "first_seen_at",
+        existing_type=sa.DateTime(timezone=True),
+        existing_server_default=sa.text("now()"),
+        nullable=False,
+    )
+
+    op.drop_index("idx_miner_tags_tag_id", table_name="miner_tags")
+    op.drop_table("miner_tags")
+    op.drop_index("uq_tags_name_ci", table_name="tags")
+    op.drop_table("tags")
+
+    op.drop_index("uq_miners_asset_tag_ci", table_name="miners")
+    op.drop_constraint("ck_miners_lifecycle_status", "miners", type_="check")
+    op.drop_column("miners", "lifecycle_status")
+    op.drop_column("miners", "control_board_sn")

backend/alembic/versions/0009_inventory_asset_id_history.py

@@ -0,0 +1,81 @@
+"""add inventory Asset ID history
+
+Revision ID: 0009_inventory_asset_id_history
+Revises: 0008_manual_miner_inventory
+Create Date: 2026-07-28
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "0009_inventory_asset_id_history"
+down_revision: Union[str, None] = "0008_manual_miner_inventory"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "miner_asset_id_history",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "miner_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("miners.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column("old_asset_id", sa.Text(), nullable=True),
+        sa.Column("new_asset_id", sa.Text(), nullable=False),
+        sa.Column(
+            "changed_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "changed_by",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.CheckConstraint(
+            "old_asset_id IS NULL OR "
+            "(old_asset_id = trim(old_asset_id) AND old_asset_id <> '')",
+            name="ck_miner_asset_id_history_old_normalized",
+        ),
+        sa.CheckConstraint(
+            "new_asset_id = trim(new_asset_id) AND new_asset_id <> ''",
+            name="ck_miner_asset_id_history_new_normalized",
+        ),
+    )
+    op.create_index(
+        "idx_miner_asset_id_history_miner_changed_at",
+        "miner_asset_id_history",
+        ["miner_id", "changed_at", "id"],
+    )
+    op.create_index(
+        "idx_miner_asset_id_history_changed_by",
+        "miner_asset_id_history",
+        ["changed_by"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "idx_miner_asset_id_history_changed_by",
+        table_name="miner_asset_id_history",
+    )
+    op.drop_index(
+        "idx_miner_asset_id_history_miner_changed_at",
+        table_name="miner_asset_id_history",
+    )
+    op.drop_table("miner_asset_id_history")

backend/alembic/versions/0010_begin_repair.py

@@ -0,0 +1,322 @@
+"""add begin repair workflow
+
+Revision ID: 0010_begin_repair
+Revises: 0009_inventory_asset_id_history
+Create Date: 2026-07-29
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "0010_begin_repair"
+down_revision: Union[str, None] = "0009_inventory_asset_id_history"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+REPAIR_STATUSES = (
+    "OPEN",
+    "IN_PROGRESS",
+    "WAITING_FOR_PARTS",
+    "READY_FOR_TEST",
+    "COMPLETED",
+    "CANCELLED",
+)
+ACTIVE_REPAIR_STATUSES = (
+    "OPEN",
+    "IN_PROGRESS",
+    "WAITING_FOR_PARTS",
+    "READY_FOR_TEST",
+)
+REPAIR_REASONS = (
+    "HARDWARE_FAILURE",
+    "LOW_HASHRATE",
+    "CONTROL_BOARD",
+    "HASHBOARD",
+    "PSU",
+    "FAN",
+    "OVERHEATING",
+    "NETWORKING",
+    "PREVENTIVE_MAINTENANCE",
+    "INSPECTION",
+    "OTHER",
+)
+REPAIR_EVENT_TYPES = ("REPAIR_STARTED", "INITIAL_NOTE")
+
+
+def _quoted(values: Sequence[str]) -> str:
+    return ", ".join(f"'{value}'" for value in values)
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+
+    op.drop_constraint("ck_miners_lifecycle_status", "miners", type_="check")
+    op.create_check_constraint(
+        "ck_miners_lifecycle_status",
+        "miners",
+        "lifecycle_status IN ('active', 'spare', 'retired', 'in_repair')",
+    )
+
+    connection.exec_driver_sql(
+        """
+        INSERT INTO permissions (key, description)
+        VALUES ('repairs.create', 'Begin repairs for miner assets')
+        ON CONFLICT (key) DO UPDATE
+        SET description = EXCLUDED.description
+        """
+    )
+    connection.exec_driver_sql(
+        """
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id
+        FROM roles
+        JOIN permissions ON permissions.key = 'repairs.create'
+        WHERE roles.name IN ('Admin', 'Manager', 'Technician')
+        ON CONFLICT DO NOTHING
+        """
+    )
+
+    op.create_table(
+        "repairs",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "miner_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("miners.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column(
+            "status",
+            sa.Text(),
+            nullable=False,
+            server_default=sa.text("'OPEN'"),
+        ),
+        sa.Column("reason", sa.Text(), nullable=False),
+        sa.Column(
+            "opened_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "opened_by",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column(
+            "completed_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+        ),
+        sa.Column(
+            "completed_by",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"),
+            nullable=True,
+        ),
+        sa.CheckConstraint(
+            f"status IN ({_quoted(REPAIR_STATUSES)})",
+            name="ck_repairs_status",
+        ),
+        sa.CheckConstraint(
+            f"reason IN ({_quoted(REPAIR_REASONS)})",
+            name="ck_repairs_reason",
+        ),
+        sa.CheckConstraint(
+            "(completed_at IS NULL AND completed_by IS NULL) OR "
+            "(completed_at IS NOT NULL AND completed_by IS NOT NULL)",
+            name="ck_repairs_completion_pair",
+        ),
+        sa.CheckConstraint(
+            "(status = 'COMPLETED') = (completed_at IS NOT NULL)",
+            name="ck_repairs_completed_state",
+        ),
+    )
+    op.create_index(
+        "idx_repairs_miner_opened_at",
+        "repairs",
+        ["miner_id", "opened_at", "id"],
+    )
+    op.create_index("idx_repairs_opened_by", "repairs", ["opened_by"])
+    op.create_index("idx_repairs_completed_by", "repairs", ["completed_by"])
+    op.create_index(
+        "uq_repairs_one_active_per_miner",
+        "repairs",
+        ["miner_id"],
+        unique=True,
+        postgresql_where=sa.text(
+            f"status IN ({_quoted(ACTIVE_REPAIR_STATUSES)})"
+        ),
+    )
+
+    op.create_table(
+        "repair_events",
+        sa.Column(
+            "id",
+            postgresql.UUID(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "repair_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("repairs.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column("sequence", sa.Integer(), nullable=False),
+        sa.Column("event_type", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "created_by",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column(
+            "payload",
+            postgresql.JSONB(),
+            nullable=False,
+        ),
+        sa.CheckConstraint(
+            f"event_type IN ({_quoted(REPAIR_EVENT_TYPES)})",
+            name="ck_repair_events_type",
+        ),
+        sa.CheckConstraint(
+            "sequence > 0",
+            name="ck_repair_events_sequence_positive",
+        ),
+        sa.CheckConstraint(
+            "jsonb_typeof(payload) = 'object'",
+            name="ck_repair_events_payload_object",
+        ),
+        sa.CheckConstraint(
+            "("
+            "event_type = 'REPAIR_STARTED' "
+            "AND payload ?& ARRAY['reason', 'from_lifecycle', 'to_lifecycle'] "
+            f"AND payload ->> 'reason' IN ({_quoted(REPAIR_REASONS)}) "
+            "AND payload ->> 'from_lifecycle' IN ('active', 'spare') "
+            "AND payload ->> 'to_lifecycle' = 'in_repair'"
+            ") OR ("
+            "event_type = 'INITIAL_NOTE' "
+            "AND jsonb_typeof(payload -> 'note') = 'string' "
+            "AND trim(payload ->> 'note') <> ''"
+            ")",
+            name="ck_repair_events_payload_shape",
+        ),
+        sa.UniqueConstraint(
+            "repair_id",
+            "sequence",
+            name="uq_repair_events_repair_sequence",
+        ),
+    )
+    op.create_index(
+        "idx_repair_events_repair_created",
+        "repair_events",
+        ["repair_id", "created_at", "sequence", "id"],
+    )
+    op.create_index(
+        "idx_repair_events_created_by",
+        "repair_events",
+        ["created_by"],
+    )
+
+
+def downgrade() -> None:
+    connection = op.get_bind()
+
+    connection.exec_driver_sql(
+        f"""
+        DO $$
+        DECLARE
+            invalid_miner_ids TEXT;
+        BEGIN
+            SELECT string_agg(miner.id::text, ', ' ORDER BY miner.id::text)
+            INTO invalid_miner_ids
+            FROM miners AS miner
+            LEFT JOIN LATERAL (
+                SELECT count(*) AS started_event_count
+                FROM repairs AS repair
+                JOIN repair_events AS event
+                  ON event.repair_id = repair.id
+                 AND event.event_type = 'REPAIR_STARTED'
+                WHERE repair.miner_id = miner.id
+                  AND repair.status IN ({_quoted(ACTIVE_REPAIR_STATUSES)})
+            ) AS history ON TRUE
+            WHERE miner.lifecycle_status = 'in_repair'
+              AND history.started_event_count <> 1;
+
+            IF invalid_miner_ids IS NOT NULL THEN
+                RAISE EXCEPTION USING
+                    MESSAGE = format(
+                        'Cannot downgrade Begin Repair: miners %s do not have exactly one active REPAIR_STARTED event',
+                        invalid_miner_ids
+                    ),
+                    HINT = 'Repair the affected lifecycle history before downgrading; MinerOps will not invent a prior lifecycle value.';
+            END IF;
+        END
+        $$;
+        """
+    )
+    connection.exec_driver_sql(
+        f"""
+        UPDATE miners AS miner
+        SET lifecycle_status = history.from_lifecycle,
+            updated_at = now()
+        FROM (
+            SELECT
+                repair.miner_id,
+                event.payload ->> 'from_lifecycle' AS from_lifecycle
+            FROM repairs AS repair
+            JOIN repair_events AS event
+              ON event.repair_id = repair.id
+             AND event.event_type = 'REPAIR_STARTED'
+            WHERE repair.status IN ({_quoted(ACTIVE_REPAIR_STATUSES)})
+        ) AS history
+        WHERE miner.id = history.miner_id
+          AND miner.lifecycle_status = 'in_repair'
+        """
+    )
+
+    op.drop_index("idx_repair_events_created_by", table_name="repair_events")
+    op.drop_index("idx_repair_events_repair_created", table_name="repair_events")
+    op.drop_table("repair_events")
+
+    op.drop_index("uq_repairs_one_active_per_miner", table_name="repairs")
+    op.drop_index("idx_repairs_completed_by", table_name="repairs")
+    op.drop_index("idx_repairs_opened_by", table_name="repairs")
+    op.drop_index("idx_repairs_miner_opened_at", table_name="repairs")
+    op.drop_table("repairs")
+
+    connection.exec_driver_sql(
+        """
+        DELETE FROM role_permissions
+        WHERE permission_id = (
+            SELECT id FROM permissions WHERE key = 'repairs.create'
+        )
+        """
+    )
+    connection.exec_driver_sql(
+        "DELETE FROM permissions WHERE key = 'repairs.create'"
+    )
+
+    op.drop_constraint("ck_miners_lifecycle_status", "miners", type_="check")
+    op.create_check_constraint(
+        "ck_miners_lifecycle_status",
+        "miners",
+        "lifecycle_status IN ('active', 'spare', 'retired')",
+    )

backend/alembic/versions/0011_repair_timeline.py

@@ -0,0 +1,55 @@
+"""add repair timeline read permission
+
+Revision ID: 0011_repair_timeline
+Revises: 0010_begin_repair
+Create Date: 2026-07-29
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = "0011_repair_timeline"
+down_revision: Union[str, None] = "0010_begin_repair"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+
+    connection.exec_driver_sql(
+        """
+        INSERT INTO permissions (key, description)
+        VALUES ('repairs.read', 'View repair details and timeline events')
+        ON CONFLICT (key) DO UPDATE
+        SET description = EXCLUDED.description
+        """
+    )
+    connection.exec_driver_sql(
+        """
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id
+        FROM roles
+        JOIN permissions ON permissions.key = 'repairs.read'
+        WHERE roles.name IN ('Admin', 'Manager', 'Technician', 'Read Only')
+        ON CONFLICT DO NOTHING
+        """
+    )
+
+
+def downgrade() -> None:
+    connection = op.get_bind()
+
+    connection.exec_driver_sql(
+        """
+        DELETE FROM role_permissions
+        WHERE permission_id = (
+            SELECT id FROM permissions WHERE key = 'repairs.read'
+        )
+        """
+    )
+    connection.exec_driver_sql(
+        "DELETE FROM permissions WHERE key = 'repairs.read'"
+    )

backend/alembic/versions/0012_return_to_service.py

@@ -0,0 +1,253 @@
+"""add return to service workflow
+
+Revision ID: 0012_return_to_service
+Revises: 0011_repair_timeline
+Create Date: 2026-07-29
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "0012_return_to_service"
+down_revision: Union[str, None] = "0011_repair_timeline"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+REPAIR_REASONS = (
+    "HARDWARE_FAILURE",
+    "LOW_HASHRATE",
+    "CONTROL_BOARD",
+    "HASHBOARD",
+    "PSU",
+    "FAN",
+    "OVERHEATING",
+    "NETWORKING",
+    "PREVENTIVE_MAINTENANCE",
+    "INSPECTION",
+    "OTHER",
+)
+
+
+def _quoted(values: Sequence[str]) -> str:
+    return ", ".join(f"'{value}'" for value in values)
+
+
+def _create_event_constraints() -> None:
+    op.create_check_constraint(
+        "ck_repair_events_type",
+        "repair_events",
+        "event_type IN ('REPAIR_STARTED', 'INITIAL_NOTE', "
+        "'REPAIR_COMPLETED')",
+    )
+    op.create_check_constraint(
+        "ck_repair_events_payload_shape",
+        "repair_events",
+        "("
+        "event_type = 'REPAIR_STARTED' "
+        "AND payload ?& ARRAY['reason', 'from_lifecycle', 'to_lifecycle'] "
+        f"AND payload ->> 'reason' IN ({_quoted(REPAIR_REASONS)}) "
+        "AND payload ->> 'from_lifecycle' IN ('active', 'spare') "
+        "AND payload ->> 'to_lifecycle' = 'in_repair'"
+        ") OR ("
+        "event_type = 'INITIAL_NOTE' "
+        "AND jsonb_typeof(payload -> 'note') = 'string' "
+        "AND trim(payload ->> 'note') <> ''"
+        ") OR ("
+        "event_type = 'REPAIR_COMPLETED' "
+        "AND payload ?& ARRAY["
+        "'previous_miner_lifecycle', 'resulting_miner_lifecycle'"
+        "] "
+        "AND payload ->> 'previous_miner_lifecycle' = 'in_repair' "
+        "AND payload ->> 'resulting_miner_lifecycle' "
+        "IN ('active', 'spare') "
+        "AND (NOT payload ? 'pre_repair_lifecycle' "
+        "OR payload ->> 'pre_repair_lifecycle' IN ('active', 'spare')) "
+        "AND (NOT payload ? 'completion_summary' OR ("
+        "jsonb_typeof(payload -> 'completion_summary') = 'string' "
+        "AND trim(payload ->> 'completion_summary') <> '' "
+        "AND char_length(payload ->> 'completion_summary') <= 4000"
+        "))"
+        ")",
+    )
+
+
+def _create_previous_event_constraints() -> None:
+    op.create_check_constraint(
+        "ck_repair_events_type",
+        "repair_events",
+        "event_type IN ('REPAIR_STARTED', 'INITIAL_NOTE')",
+    )
+    op.create_check_constraint(
+        "ck_repair_events_payload_shape",
+        "repair_events",
+        "("
+        "event_type = 'REPAIR_STARTED' "
+        "AND payload ?& ARRAY['reason', 'from_lifecycle', 'to_lifecycle'] "
+        f"AND payload ->> 'reason' IN ({_quoted(REPAIR_REASONS)}) "
+        "AND payload ->> 'from_lifecycle' IN ('active', 'spare') "
+        "AND payload ->> 'to_lifecycle' = 'in_repair'"
+        ") OR ("
+        "event_type = 'INITIAL_NOTE' "
+        "AND jsonb_typeof(payload -> 'note') = 'string' "
+        "AND trim(payload ->> 'note') <> ''"
+        ")",
+    )
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+
+    connection.exec_driver_sql(
+        """
+        INSERT INTO permissions (key, description)
+        VALUES ('repairs.complete', 'Return repaired miners to service')
+        ON CONFLICT (key) DO UPDATE
+        SET description = EXCLUDED.description
+        """
+    )
+    connection.exec_driver_sql(
+        """
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id
+        FROM roles
+        JOIN permissions ON permissions.key = 'repairs.complete'
+        WHERE roles.name IN ('Admin', 'Manager', 'Technician')
+        ON CONFLICT DO NOTHING
+        """
+    )
+
+    op.add_column(
+        "repairs",
+        sa.Column("completion_summary", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "repairs",
+        sa.Column("resulting_lifecycle", sa.Text(), nullable=True),
+    )
+    op.create_check_constraint(
+        "ck_repairs_resulting_lifecycle",
+        "repairs",
+        "resulting_lifecycle IS NULL "
+        "OR resulting_lifecycle IN ('active', 'spare')",
+    )
+    op.create_check_constraint(
+        "ck_repairs_completion_summary",
+        "repairs",
+        "completion_summary IS NULL OR ("
+        "trim(completion_summary) <> '' "
+        "AND char_length(completion_summary) <= 4000"
+        ")",
+    )
+    # NOT VALID preserves truthful legacy COMPLETED rows whose destination was
+    # never recorded, while PostgreSQL still enforces the check for every new
+    # or updated row after this migration.
+    connection.exec_driver_sql(
+        """
+        ALTER TABLE repairs
+        ADD CONSTRAINT ck_repairs_completion_metadata_state
+        CHECK (
+            (
+                status = 'COMPLETED'
+                AND resulting_lifecycle IS NOT NULL
+            )
+            OR (
+                status <> 'COMPLETED'
+                AND completion_summary IS NULL
+                AND resulting_lifecycle IS NULL
+            )
+        )
+        NOT VALID
+        """
+    )
+
+    op.drop_constraint(
+        "ck_repair_events_payload_shape",
+        "repair_events",
+        type_="check",
+    )
+    op.drop_constraint(
+        "ck_repair_events_type",
+        "repair_events",
+        type_="check",
+    )
+    _create_event_constraints()
+
+
+def downgrade() -> None:
+    connection = op.get_bind()
+
+    connection.exec_driver_sql(
+        """
+        DO $$
+        DECLARE
+            completion_count BIGINT;
+        BEGIN
+            SELECT count(*)
+            INTO completion_count
+            FROM repairs
+            WHERE resulting_lifecycle IS NOT NULL
+               OR completion_summary IS NOT NULL;
+
+            completion_count := completion_count + (
+                SELECT count(*)
+                FROM repair_events
+                WHERE event_type = 'REPAIR_COMPLETED'
+            );
+
+            IF completion_count > 0 THEN
+                RAISE EXCEPTION USING
+                    MESSAGE = format(
+                        'Cannot downgrade Return to Service: %s completion records or events would lose authoritative history',
+                        completion_count
+                    ),
+                    HINT = 'Preserve or explicitly migrate Return to Service history before downgrading; MinerOps will not invent or discard lifecycle, actor, summary, or event values.';
+            END IF;
+        END
+        $$;
+        """
+    )
+
+    op.drop_constraint(
+        "ck_repair_events_payload_shape",
+        "repair_events",
+        type_="check",
+    )
+    op.drop_constraint(
+        "ck_repair_events_type",
+        "repair_events",
+        type_="check",
+    )
+    _create_previous_event_constraints()
+
+    op.drop_constraint(
+        "ck_repairs_completion_metadata_state",
+        "repairs",
+        type_="check",
+    )
+    op.drop_constraint(
+        "ck_repairs_completion_summary",
+        "repairs",
+        type_="check",
+    )
+    op.drop_constraint(
+        "ck_repairs_resulting_lifecycle",
+        "repairs",
+        type_="check",
+    )
+    op.drop_column("repairs", "resulting_lifecycle")
+    op.drop_column("repairs", "completion_summary")
+
+    connection.exec_driver_sql(
+        """
+        DELETE FROM role_permissions
+        WHERE permission_id = (
+            SELECT id FROM permissions WHERE key = 'repairs.complete'
+        )
+        """
+    )
+    connection.exec_driver_sql(
+        "DELETE FROM permissions WHERE key = 'repairs.complete'"
+    )

backend/alembic/versions/0013_control_board_replacement.py

@@ -0,0 +1,436 @@
+"""add control board replacement workflow
+
+Revision ID: 0013_control_board_replacement
+Revises: 0012_return_to_service
+Create Date: 2026-08-02
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "0013_control_board_replacement"
+down_revision: Union[str, None] = "0012_return_to_service"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+REPAIR_REASONS = (
+    "HARDWARE_FAILURE", "LOW_HASHRATE", "CONTROL_BOARD", "HASHBOARD",
+    "PSU", "FAN", "OVERHEATING", "NETWORKING",
+    "PREVENTIVE_MAINTENANCE", "INSPECTION", "OTHER",
+)
+REPLACEMENT_REASONS = (
+    "failed", "upgrade", "diagnostic_swap", "preventive_maintenance",
+    "temporary_donor", "unknown",
+)
+DISPOSITIONS = (
+    "repair_inventory", "sent_for_repair", "scrapped",
+    "retained_for_diagnosis", "returned_to_vendor", "unknown",
+)
+
+
+def _quoted(values: Sequence[str]) -> str:
+    return ", ".join(f"'{value}'" for value in values)
+
+
+def _create_event_constraints(include_replacement: bool) -> None:
+    event_types = ["REPAIR_STARTED", "INITIAL_NOTE", "REPAIR_COMPLETED"]
+    if include_replacement:
+        event_types.append("CONTROL_BOARD_REPLACED")
+    op.create_check_constraint(
+        "ck_repair_events_type",
+        "repair_events",
+        f"event_type IN ({_quoted(event_types)})",
+    )
+    replacement_clause = ""
+    if include_replacement:
+        replacement_clause = (
+            ") OR (event_type = 'CONTROL_BOARD_REPLACED' "
+            "AND payload ?& ARRAY['old_mac_address', 'new_mac_address', "
+            "'old_control_board_serial', 'new_control_board_serial', "
+            "'replacement_reason', 'removed_board_disposition'] "
+            "AND jsonb_typeof(payload -> 'old_mac_address') IN ('string', 'null') "
+            "AND jsonb_typeof(payload -> 'new_mac_address') = 'string' "
+            "AND payload ->> 'new_mac_address' ~ '^([0-9A-F]{2}:){5}[0-9A-F]{2}$' "
+            "AND regexp_replace(lower(payload ->> 'new_mac_address'), '[^0-9a-f]', '', 'g') "
+            "NOT IN ('000000000000', 'ffffffffffff') "
+            "AND get_byte(decode(regexp_replace(lower(payload ->> 'new_mac_address'), "
+            "'[^0-9a-f]', '', 'g'), 'hex'), 0) % 2 = 0 "
+            "AND (jsonb_typeof(payload -> 'old_control_board_serial') = 'null' OR ("
+            "jsonb_typeof(payload -> 'old_control_board_serial') = 'string' "
+            "AND trim(payload ->> 'old_control_board_serial') <> '' "
+            "AND char_length(payload ->> 'old_control_board_serial') <= 255)) "
+            "AND (jsonb_typeof(payload -> 'new_control_board_serial') = 'null' OR ("
+            "jsonb_typeof(payload -> 'new_control_board_serial') = 'string' "
+            "AND trim(payload ->> 'new_control_board_serial') <> '' "
+            "AND char_length(payload ->> 'new_control_board_serial') <= 255)) "
+            f"AND payload ->> 'replacement_reason' IN ({_quoted(REPLACEMENT_REASONS)}) "
+            f"AND payload ->> 'removed_board_disposition' IN ({_quoted(DISPOSITIONS)}) "
+            "AND (NOT payload ? 'notes' OR jsonb_typeof(payload -> 'notes') = 'null' OR ("
+            "jsonb_typeof(payload -> 'notes') = 'string' "
+            "AND trim(payload ->> 'notes') <> '' "
+            "AND char_length(payload ->> 'notes') <= 4000))"
+        )
+    op.create_check_constraint(
+        "ck_repair_events_payload_shape",
+        "repair_events",
+        "(event_type = 'REPAIR_STARTED' "
+        "AND payload ?& ARRAY['reason', 'from_lifecycle', 'to_lifecycle'] "
+        f"AND payload ->> 'reason' IN ({_quoted(REPAIR_REASONS)}) "
+        "AND payload ->> 'from_lifecycle' IN ('active', 'spare') "
+        "AND payload ->> 'to_lifecycle' = 'in_repair') OR ("
+        "event_type = 'INITIAL_NOTE' "
+        "AND jsonb_typeof(payload -> 'note') = 'string' "
+        "AND trim(payload ->> 'note') <> '') OR ("
+        "event_type = 'REPAIR_COMPLETED' "
+        "AND payload ?& ARRAY['previous_miner_lifecycle', 'resulting_miner_lifecycle'] "
+        "AND payload ->> 'previous_miner_lifecycle' = 'in_repair' "
+        "AND payload ->> 'resulting_miner_lifecycle' IN ('active', 'spare') "
+        "AND (NOT payload ? 'pre_repair_lifecycle' "
+        "OR payload ->> 'pre_repair_lifecycle' IN ('active', 'spare')) "
+        "AND (NOT payload ? 'completion_summary' OR ("
+        "jsonb_typeof(payload -> 'completion_summary') = 'string' "
+        "AND trim(payload ->> 'completion_summary') <> '' "
+        "AND char_length(payload ->> 'completion_summary') <= 4000))"
+        f"{replacement_clause})",
+    )
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+    connection.exec_driver_sql(
+        """
+        DO $$
+        DECLARE conflicts TEXT;
+        BEGIN
+          WITH identities AS (
+            SELECT regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') AS mac,
+                   miner_id
+            FROM miner_network_identities
+            WHERE length(regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g')) = 12
+            UNION ALL
+            SELECT regexp_replace(lower(current_mac), '[^0-9a-f]', '', 'g'), id
+            FROM miners
+            WHERE length(regexp_replace(lower(current_mac), '[^0-9a-f]', '', 'g')) = 12
+          ), duplicate_owners AS (
+            SELECT mac
+            FROM identities
+            GROUP BY mac
+            HAVING count(DISTINCT miner_id) > 1
+          )
+          SELECT string_agg(mac, ', ' ORDER BY mac) INTO conflicts FROM duplicate_owners;
+          IF conflicts IS NOT NULL THEN
+            RAISE EXCEPTION USING
+              MESSAGE = 'Cannot upgrade Control Board Replacement: normalized MAC values have multiple miner owners: ' || conflicts,
+              HINT = 'Correct the conflicting miner and network-identity records before upgrading; MinerOps will not transfer, merge, or delete MAC history automatically.';
+          END IF;
+
+          SELECT string_agg(mac, ', ' ORDER BY mac) INTO conflicts
+          FROM (
+            SELECT regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') AS mac
+            FROM miner_network_identities
+            WHERE length(regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g')) = 12
+            GROUP BY regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g')
+            HAVING count(*) > 1
+          ) AS duplicate_identity_mac;
+          IF conflicts IS NOT NULL THEN
+            RAISE EXCEPTION USING
+              MESSAGE = 'Cannot upgrade Control Board Replacement: duplicate normalized network-identity MAC values: ' || conflicts,
+              HINT = 'Correct duplicate identity rows before upgrading; MinerOps will not delete or merge history automatically.';
+          END IF;
+
+          SELECT string_agg(miner_id::text, ', ' ORDER BY miner_id::text)
+          INTO conflicts
+          FROM (
+            SELECT miner_id FROM miner_network_identities
+            WHERE is_current GROUP BY miner_id HAVING count(*) > 1
+          ) AS duplicate_current;
+          IF conflicts IS NOT NULL THEN
+            RAISE EXCEPTION USING
+              MESSAGE = 'Cannot upgrade Control Board Replacement: miners have multiple current network identities: ' || conflicts,
+              HINT = 'Choose one current network identity for each listed miner before upgrading.';
+          END IF;
+        END $$;
+        """
+    )
+
+    connection.exec_driver_sql(
+        """
+        INSERT INTO permissions (key, description)
+        VALUES ('miners.replace_control_board', 'Replace miner control boards during repair')
+        ON CONFLICT (key) DO UPDATE SET description = EXCLUDED.description;
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id FROM roles
+        JOIN permissions ON permissions.key = 'miners.replace_control_board'
+        WHERE roles.name IN ('Admin', 'Manager', 'Technician')
+        ON CONFLICT DO NOTHING;
+        """
+    )
+
+    op.add_column(
+        "miner_network_identities",
+        sa.Column("associated_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.alter_column("miner_network_identities", "first_seen_at", nullable=True)
+    op.alter_column("miner_network_identities", "last_seen_at", nullable=True)
+    connection.exec_driver_sql(
+        """
+        CREATE UNIQUE INDEX uq_miner_network_identities_normalized_mac
+        ON miner_network_identities (
+          regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g')
+        )
+        WHERE length(regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g')) = 12;
+        CREATE UNIQUE INDEX uq_miner_network_identities_one_current_per_miner
+        ON miner_network_identities (miner_id) WHERE is_current;
+        CREATE UNIQUE INDEX uq_miners_current_normalized_mac
+        ON miners (regexp_replace(lower(current_mac), '[^0-9a-f]', '', 'g'))
+        WHERE length(regexp_replace(lower(current_mac), '[^0-9a-f]', '', 'g')) = 12;
+        ALTER TABLE miner_network_identities
+        ADD CONSTRAINT ck_miner_network_identities_mac_valid
+        CHECK (
+          source NOT IN ('control_board_replacement', 'legacy_projection') OR (
+            mac_address ~ '^([0-9A-F]{2}:){5}[0-9A-F]{2}$'
+            AND regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') NOT IN ('000000000000', 'ffffffffffff')
+            AND get_byte(decode(regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g'), 'hex'), 0) %% 2 = 0
+          )
+        ) NOT VALID;
+        """
+    )
+
+    op.create_table(
+        "miner_mac_ownerships",
+        sa.Column("normalized_mac", sa.Text(), primary_key=True),
+        sa.Column(
+            "miner_id", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("miners.id", ondelete="RESTRICT"), nullable=False,
+        ),
+        sa.Column("claimed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "claimed_by", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"), nullable=True,
+        ),
+        sa.CheckConstraint(
+            "normalized_mac ~ '^[0-9a-f]{12}$' "
+            "AND normalized_mac NOT IN ('000000000000', 'ffffffffffff') "
+            "AND get_byte(decode(normalized_mac, 'hex'), 0) % 2 = 0",
+            name="ck_miner_mac_ownerships_valid",
+        ),
+    )
+    op.create_index("idx_miner_mac_ownerships_miner_id", "miner_mac_ownerships", ["miner_id"])
+    connection.exec_driver_sql(
+        """
+        INSERT INTO miner_mac_ownerships (normalized_mac, miner_id)
+        SELECT mac, min(miner_id::text)::uuid FROM (
+          SELECT regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') AS mac, miner_id
+          FROM miner_network_identities
+          UNION ALL
+          SELECT regexp_replace(lower(current_mac), '[^0-9a-f]', '', 'g'), id FROM miners
+        ) AS known
+        WHERE length(mac) = 12 AND mac NOT IN ('000000000000', 'ffffffffffff')
+          AND get_byte(decode(mac, 'hex'), 0) %% 2 = 0
+        GROUP BY mac;
+        """
+    )
+
+    op.create_table(
+        "miner_control_board_installations",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("miner_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("miners.id", ondelete="RESTRICT"), nullable=False),
+        sa.Column("record_origin", sa.Text(), nullable=False),
+        sa.Column("installed_repair_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("repairs.id", ondelete="RESTRICT"), nullable=True),
+        sa.Column("removed_repair_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("repairs.id", ondelete="RESTRICT"), nullable=True),
+        sa.Column("mac_address", sa.Text(), nullable=True),
+        sa.Column("normalized_mac", sa.Text(), nullable=True),
+        sa.Column("board_serial", sa.Text(), nullable=True),
+        sa.Column("board_model", sa.Text(), nullable=True),
+        sa.Column("board_revision", sa.Text(), nullable=True),
+        sa.Column("firmware_version", sa.Text(), nullable=True),
+        sa.Column("replacement_reason", sa.Text(), nullable=True),
+        sa.Column("installed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("installed_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="RESTRICT"), nullable=True),
+        sa.Column("removed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("removed_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="RESTRICT"), nullable=True),
+        sa.Column("removed_disposition", sa.Text(), nullable=True),
+        sa.Column("notes", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.CheckConstraint("(mac_address IS NULL) = (normalized_mac IS NULL)", name="ck_control_board_installations_mac_pair"),
+        sa.CheckConstraint(
+            "normalized_mac IS NULL OR ("
+            "mac_address ~ '^([0-9A-F]{2}:){5}[0-9A-F]{2}$' "
+            "AND regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') = normalized_mac "
+            "AND normalized_mac ~ '^[0-9a-f]{12}$' "
+            "AND normalized_mac NOT IN ('000000000000', 'ffffffffffff') "
+            "AND get_byte(decode(normalized_mac, 'hex'), 0) % 2 = 0)",
+            name="ck_control_board_installations_mac_normalized",
+        ),
+        sa.CheckConstraint("board_serial IS NULL OR (trim(board_serial) <> '' AND char_length(board_serial) <= 255)", name="ck_control_board_installations_serial"),
+        sa.CheckConstraint("board_model IS NULL OR (trim(board_model) <> '' AND char_length(board_model) <= 255)", name="ck_control_board_installations_model"),
+        sa.CheckConstraint("board_revision IS NULL OR (trim(board_revision) <> '' AND char_length(board_revision) <= 255)", name="ck_control_board_installations_revision"),
+        sa.CheckConstraint("firmware_version IS NULL OR (trim(firmware_version) <> '' AND char_length(firmware_version) <= 255)", name="ck_control_board_installations_firmware"),
+        sa.CheckConstraint(f"replacement_reason IS NULL OR replacement_reason IN ({_quoted(REPLACEMENT_REASONS)})", name="ck_control_board_installations_reason"),
+        sa.CheckConstraint(f"removed_disposition IS NULL OR removed_disposition IN ({_quoted(DISPOSITIONS)})", name="ck_control_board_installations_disposition"),
+        sa.CheckConstraint("notes IS NULL OR (trim(notes) <> '' AND char_length(notes) <= 4000)", name="ck_control_board_installations_notes"),
+        sa.CheckConstraint("(removed_at IS NULL AND removed_by IS NULL AND removed_repair_id IS NULL AND removed_disposition IS NULL) OR (removed_at IS NOT NULL AND removed_by IS NOT NULL AND removed_repair_id IS NOT NULL AND removed_disposition IS NOT NULL)", name="ck_control_board_installations_removed_state"),
+        sa.CheckConstraint("installed_at IS NULL OR removed_at IS NULL OR removed_at >= installed_at", name="ck_control_board_installations_chronology"),
+        sa.CheckConstraint(
+            "(record_origin = 'legacy_projection' AND installed_repair_id IS NULL "
+            "AND installed_at IS NULL AND installed_by IS NULL "
+            "AND replacement_reason IS NULL) OR "
+            "(record_origin = 'replacement' AND installed_repair_id IS NOT NULL "
+            "AND installed_at IS NOT NULL AND installed_by IS NOT NULL "
+            "AND replacement_reason IS NOT NULL)",
+            name="ck_control_board_installations_install_state",
+        ),
+    )
+    op.create_index("uq_control_board_installations_current_miner", "miner_control_board_installations", ["miner_id"], unique=True, postgresql_where=sa.text("removed_at IS NULL"))
+    op.create_index("uq_control_board_installations_current_mac", "miner_control_board_installations", ["normalized_mac"], unique=True, postgresql_where=sa.text("removed_at IS NULL AND normalized_mac IS NOT NULL"))
+    op.create_index("idx_control_board_installations_miner_history", "miner_control_board_installations", ["miner_id", "installed_at", "created_at", "id"])
+    op.create_index("idx_control_board_installations_mac_history", "miner_control_board_installations", ["normalized_mac", "created_at", "id"])
+    op.create_index("idx_control_board_installations_installed_repair", "miner_control_board_installations", ["installed_repair_id"])
+    op.create_index("idx_control_board_installations_removed_repair", "miner_control_board_installations", ["removed_repair_id"])
+
+    connection.exec_driver_sql(
+        """
+        CREATE FUNCTION minerops_claim_mac_owner() RETURNS trigger LANGUAGE plpgsql AS $$
+        DECLARE mac text; existing_owner uuid; target_owner uuid; row_data jsonb;
+        BEGIN
+          row_data := to_jsonb(NEW);
+          mac := regexp_replace(lower(CASE WHEN TG_TABLE_NAME = 'miners' THEN row_data ->> 'current_mac' ELSE row_data ->> 'mac_address' END), '[^0-9a-f]', '', 'g');
+          target_owner := (CASE WHEN TG_TABLE_NAME = 'miners' THEN row_data ->> 'id' ELSE row_data ->> 'miner_id' END)::uuid;
+          IF mac IS NULL OR length(mac) <> 12 OR mac IN ('000000000000', 'ffffffffffff') OR get_byte(decode(mac, 'hex'), 0) %% 2 <> 0 THEN RETURN NEW; END IF;
+          INSERT INTO miner_mac_ownerships (normalized_mac, miner_id, claimed_at)
+          VALUES (mac, target_owner, now())
+          ON CONFLICT (normalized_mac) DO NOTHING;
+          SELECT miner_id INTO existing_owner FROM miner_mac_ownerships WHERE normalized_mac = mac FOR UPDATE;
+          IF existing_owner <> (target_owner) THEN
+            RAISE EXCEPTION 'MAC %% is historically owned by miner %%', mac, existing_owner USING ERRCODE = '23505', CONSTRAINT = 'uq_miner_mac_ownerships_owner';
+          END IF;
+          RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_miners_claim_mac_owner AFTER INSERT OR UPDATE OF current_mac ON miners FOR EACH ROW EXECUTE FUNCTION minerops_claim_mac_owner();
+        CREATE TRIGGER trg_network_identities_claim_mac_owner BEFORE INSERT OR UPDATE OF mac_address, miner_id ON miner_network_identities FOR EACH ROW EXECUTE FUNCTION minerops_claim_mac_owner();
+        CREATE FUNCTION minerops_protect_mac_ownership() RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN
+          RAISE EXCEPTION 'Historical MAC ownership is immutable; use an explicit transfer workflow';
+        END $$;
+        CREATE TRIGGER trg_protect_mac_ownership BEFORE UPDATE OR DELETE ON miner_mac_ownerships FOR EACH ROW EXECUTE FUNCTION minerops_protect_mac_ownership();
+
+
+        CREATE FUNCTION minerops_protect_network_identity_history() RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN
+          IF TG_OP = 'DELETE' THEN
+            RAISE EXCEPTION 'Network identity history is immutable';
+          END IF;
+          IF NEW.miner_id <> OLD.miner_id
+             OR regexp_replace(lower(NEW.mac_address), '[^0-9a-f]', '', 'g')
+                <> regexp_replace(lower(OLD.mac_address), '[^0-9a-f]', '', 'g') THEN
+            RAISE EXCEPTION 'Network identity owner and normalized MAC are immutable';
+          END IF;
+          RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_protect_network_identity_history BEFORE UPDATE OF miner_id, mac_address OR DELETE ON miner_network_identities FOR EACH ROW EXECUTE FUNCTION minerops_protect_network_identity_history();
+
+
+        CREATE FUNCTION minerops_check_current_board_projection() RETURNS trigger LANGUAGE plpgsql AS $$
+        DECLARE target_miner uuid; mismatch boolean; row_data jsonb;
+        BEGIN
+          IF TG_OP = 'DELETE' THEN
+            row_data := to_jsonb(OLD);
+          ELSE
+            row_data := to_jsonb(NEW);
+          END IF;
+          target_miner := (CASE WHEN TG_TABLE_NAME = 'miners' THEN row_data ->> 'id' ELSE row_data ->> 'miner_id' END)::uuid;
+          SELECT EXISTS (
+            SELECT 1 FROM miner_control_board_installations
+            WHERE miner_id = target_miner
+          ) AND NOT EXISTS (
+            SELECT 1
+            FROM miner_control_board_installations board
+            JOIN miners miner ON miner.id = board.miner_id
+            JOIN miner_network_identities identity
+              ON identity.miner_id = board.miner_id AND identity.is_current
+            WHERE board.miner_id = target_miner AND board.removed_at IS NULL
+              AND regexp_replace(lower(COALESCE(miner.current_mac, '')), '[^0-9a-f]', '', 'g') = COALESCE(board.normalized_mac, '')
+              AND miner.control_board_sn IS NOT DISTINCT FROM board.board_serial
+              AND regexp_replace(lower(identity.mac_address), '[^0-9a-f]', '', 'g') = COALESCE(board.normalized_mac, '')
+          ) INTO mismatch;
+          IF mismatch THEN RAISE EXCEPTION 'Current control-board projection does not match installation history for miner %%', target_miner USING ERRCODE = '23514', CONSTRAINT = 'ck_current_control_board_projection'; END IF;
+          RETURN NULL;
+        END $$;
+        CREATE CONSTRAINT TRIGGER trg_miners_check_current_board_projection AFTER INSERT OR UPDATE ON miners DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION minerops_check_current_board_projection();
+        CREATE CONSTRAINT TRIGGER trg_installations_check_current_board_projection AFTER INSERT OR UPDATE OR DELETE ON miner_control_board_installations DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION minerops_check_current_board_projection();
+        CREATE CONSTRAINT TRIGGER trg_identities_check_current_board_projection AFTER INSERT OR UPDATE OR DELETE ON miner_network_identities DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION minerops_check_current_board_projection();
+
+        CREATE FUNCTION minerops_protect_control_board_history() RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN
+          IF TG_OP = 'DELETE' THEN RAISE EXCEPTION 'Control-board installation history is immutable'; END IF;
+          IF OLD.removed_at IS NOT NULL THEN RAISE EXCEPTION 'Removed control-board installation history is immutable'; END IF;
+          IF NEW.id <> OLD.id OR NEW.miner_id <> OLD.miner_id OR NEW.record_origin <> OLD.record_origin OR NEW.installed_repair_id IS DISTINCT FROM OLD.installed_repair_id OR NEW.mac_address IS DISTINCT FROM OLD.mac_address OR NEW.normalized_mac IS DISTINCT FROM OLD.normalized_mac OR NEW.board_serial IS DISTINCT FROM OLD.board_serial OR NEW.board_model IS DISTINCT FROM OLD.board_model OR NEW.board_revision IS DISTINCT FROM OLD.board_revision OR NEW.firmware_version IS DISTINCT FROM OLD.firmware_version OR NEW.replacement_reason IS DISTINCT FROM OLD.replacement_reason OR NEW.installed_at IS DISTINCT FROM OLD.installed_at OR NEW.installed_by IS DISTINCT FROM OLD.installed_by OR NEW.notes IS DISTINCT FROM OLD.notes OR NEW.created_at <> OLD.created_at THEN
+            RAISE EXCEPTION 'Control-board installation identity is immutable';
+          END IF;
+          RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_protect_control_board_history BEFORE UPDATE OR DELETE ON miner_control_board_installations FOR EACH ROW EXECUTE FUNCTION minerops_protect_control_board_history();
+        """
+    )
+
+    op.drop_constraint("ck_repair_events_payload_shape", "repair_events", type_="check")
+    op.drop_constraint("ck_repair_events_type", "repair_events", type_="check")
+    _create_event_constraints(True)
+
+
+def downgrade() -> None:
+    connection = op.get_bind()
+    connection.exec_driver_sql(
+        """
+        DO $$ DECLARE history_count bigint; BEGIN
+          SELECT count(*) INTO history_count FROM miner_control_board_installations;
+          history_count := history_count + (SELECT count(*) FROM repair_events WHERE event_type = 'CONTROL_BOARD_REPLACED');
+          IF history_count > 0 THEN
+            RAISE EXCEPTION USING MESSAGE = format('Cannot downgrade Control Board Replacement: %s authoritative installation records or events would be destroyed', history_count), HINT = 'Preserve or explicitly migrate control-board history before downgrading; MinerOps will not discard or invent component, MAC, actor, or timestamp history.';
+          END IF;
+          IF EXISTS (SELECT 1 FROM miner_network_identities WHERE first_seen_at IS NULL OR last_seen_at IS NULL) THEN
+            RAISE EXCEPTION USING MESSAGE = 'Cannot downgrade Control Board Replacement: network identities contain unknown observation timestamps', HINT = 'Do not invent discovery timestamps; preserve or explicitly migrate these associations before downgrading.';
+          END IF;
+          IF EXISTS (SELECT 1 FROM miner_network_identities WHERE associated_at IS NOT NULL)
+             OR EXISTS (SELECT 1 FROM miner_mac_ownerships WHERE claimed_at IS NOT NULL) THEN
+            RAISE EXCEPTION USING MESSAGE = 'Cannot downgrade Control Board Replacement: authoritative MAC association or ownership history would be destroyed', HINT = 'Preserve or explicitly migrate MAC association and ownership history before downgrading.';
+          END IF;
+        END $$;
+        """
+    )
+    op.drop_constraint("ck_repair_events_payload_shape", "repair_events", type_="check")
+    op.drop_constraint("ck_repair_events_type", "repair_events", type_="check")
+    _create_event_constraints(False)
+    connection.exec_driver_sql(
+        """
+        DROP TRIGGER trg_protect_control_board_history ON miner_control_board_installations;
+        DROP FUNCTION minerops_protect_control_board_history();
+        DROP TRIGGER trg_installations_check_current_board_projection ON miner_control_board_installations;
+        DROP TRIGGER trg_identities_check_current_board_projection ON miner_network_identities;
+        DROP TRIGGER trg_miners_check_current_board_projection ON miners;
+        DROP FUNCTION minerops_check_current_board_projection();
+        DROP TRIGGER trg_protect_mac_ownership ON miner_mac_ownerships;
+        DROP FUNCTION minerops_protect_mac_ownership();
+        DROP TRIGGER trg_protect_network_identity_history ON miner_network_identities;
+        DROP FUNCTION minerops_protect_network_identity_history();
+        DROP TRIGGER trg_network_identities_claim_mac_owner ON miner_network_identities;
+        DROP TRIGGER trg_miners_claim_mac_owner ON miners;
+        DROP FUNCTION minerops_claim_mac_owner();
+        """
+    )
+    op.drop_table("miner_control_board_installations")
+    op.drop_index("idx_miner_mac_ownerships_miner_id", table_name="miner_mac_ownerships")
+    op.drop_table("miner_mac_ownerships")
+    op.drop_constraint("ck_miner_network_identities_mac_valid", "miner_network_identities", type_="check")
+    op.drop_index("uq_miners_current_normalized_mac", table_name="miners")
+    op.drop_index("uq_miner_network_identities_one_current_per_miner", table_name="miner_network_identities")
+    op.drop_index("uq_miner_network_identities_normalized_mac", table_name="miner_network_identities")
+    op.alter_column("miner_network_identities", "last_seen_at", nullable=False)
+    op.alter_column("miner_network_identities", "first_seen_at", nullable=False)
+    op.drop_column("miner_network_identities", "associated_at")
+    connection.exec_driver_sql("DELETE FROM role_permissions WHERE permission_id = (SELECT id FROM permissions WHERE key = 'miners.replace_control_board')")
+    connection.exec_driver_sql("DELETE FROM permissions WHERE key = 'miners.replace_control_board'")

backend/alembic/versions/0014_repair_parts_tracking.py

@@ -0,0 +1,590 @@
+"""add repair parts tracking
+
+Revision ID: 0014_repair_parts_tracking
+Revises: 0013_control_board_replacement
+Create Date: 2026-08-02
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "0014_repair_parts_tracking"
+down_revision: Union[str, None] = "0013_control_board_replacement"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+COMPONENT_TYPES = ("control_board", "hashboard", "power_supply", "fan")
+CONSUMABLE_UNITS = ("each", "gram", "millilitre", "metre", "centimetre")
+REPAIR_REASONS = (
+    "HARDWARE_FAILURE", "LOW_HASHRATE", "CONTROL_BOARD", "HASHBOARD",
+    "PSU", "FAN", "OVERHEATING", "NETWORKING",
+    "PREVENTIVE_MAINTENANCE", "INSPECTION", "OTHER",
+)
+REPLACEMENT_REASONS = (
+    "failed", "upgrade", "diagnostic_swap", "preventive_maintenance",
+    "temporary_donor", "unknown",
+)
+DISPOSITIONS = (
+    "repair_inventory", "sent_for_repair", "scrapped",
+    "retained_for_diagnosis", "returned_to_vendor", "unknown",
+)
+
+
+def _quoted(values: Sequence[str]) -> str:
+    return ", ".join(f"'{value}'" for value in values)
+
+
+def _create_event_constraints(include_parts: bool) -> None:
+    event_types = [
+        "REPAIR_STARTED",
+        "INITIAL_NOTE",
+        "REPAIR_COMPLETED",
+        "CONTROL_BOARD_REPLACED",
+    ]
+    if include_parts:
+        event_types.extend(("REPAIR_PART_RECORDED", "REPAIR_PART_VOIDED"))
+
+    op.create_check_constraint(
+        "ck_repair_events_type",
+        "repair_events",
+        f"event_type IN ({_quoted(event_types)})",
+    )
+
+    parts_clause = ""
+    if include_parts:
+        parts_clause = (
+            ") OR (event_type = 'REPAIR_PART_RECORDED' "
+            "AND payload ?& ARRAY['repair_part_id', 'entry_kind', 'notes'] "
+            "AND payload ->> 'repair_part_id' ~ "
+            "'^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-"
+            "[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$' "
+            "AND (jsonb_typeof(payload -> 'notes') = 'null' OR ("
+            "jsonb_typeof(payload -> 'notes') = 'string' "
+            "AND trim(payload ->> 'notes') <> '' "
+            "AND char_length(payload ->> 'notes') <= 4000)) "
+            "AND ((payload ->> 'entry_kind' = 'consumable' "
+            "AND payload ?& ARRAY['description', 'quantity', 'unit'] "
+            "AND NOT payload ? 'component_id' "
+            "AND jsonb_typeof(payload -> 'description') = 'string' "
+            "AND trim(payload ->> 'description') <> '' "
+            "AND char_length(payload ->> 'description') <= 255 "
+            "AND jsonb_typeof(payload -> 'quantity') = 'string' "
+            "AND payload ->> 'quantity' ~ '^[0-9]{1,9}(\\.[0-9]{1,3})?$' "
+            "AND (payload ->> 'quantity')::numeric > 0 "
+            f"AND payload ->> 'unit' IN ({_quoted(CONSUMABLE_UNITS)}) "
+            "AND (payload ->> 'unit' <> 'each' OR "
+            "(payload ->> 'quantity')::numeric = "
+            "trunc((payload ->> 'quantity')::numeric))) OR ("
+            "payload ->> 'entry_kind' = 'tracked_component' "
+            "AND payload ?& ARRAY['component_id', 'component_type', "
+            "'component_asset_id', 'component_manufacturer', "
+            "'component_model', 'component_manufacturer_serial'] "
+            "AND NOT payload ? 'description' "
+            "AND NOT payload ? 'quantity' "
+            "AND NOT payload ? 'unit' "
+            "AND payload ->> 'component_id' ~ "
+            "'^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-"
+            "[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$' "
+            f"AND payload ->> 'component_type' IN ({_quoted(COMPONENT_TYPES)}) "
+            "AND jsonb_typeof(payload -> 'component_asset_id') IN ('string', 'null') "
+            "AND jsonb_typeof(payload -> 'component_manufacturer') IN ('string', 'null') "
+            "AND jsonb_typeof(payload -> 'component_model') IN ('string', 'null') "
+            "AND jsonb_typeof(payload -> 'component_manufacturer_serial') "
+            "IN ('string', 'null'))))"
+            " OR (event_type = 'REPAIR_PART_VOIDED' "
+            "AND payload ?& ARRAY['repair_part_id', 'reason'] "
+            "AND payload ->> 'repair_part_id' ~ "
+            "'^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-"
+            "[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$' "
+            "AND jsonb_typeof(payload -> 'reason') = 'string' "
+            "AND trim(payload ->> 'reason') <> '' "
+            "AND char_length(payload ->> 'reason') <= 1000"
+        )
+
+    op.create_check_constraint(
+        "ck_repair_events_payload_shape",
+        "repair_events",
+        "(event_type = 'REPAIR_STARTED' "
+        "AND payload ?& ARRAY['reason', 'from_lifecycle', 'to_lifecycle'] "
+        f"AND payload ->> 'reason' IN ({_quoted(REPAIR_REASONS)}) "
+        "AND payload ->> 'from_lifecycle' IN ('active', 'spare') "
+        "AND payload ->> 'to_lifecycle' = 'in_repair') OR ("
+        "event_type = 'INITIAL_NOTE' "
+        "AND jsonb_typeof(payload -> 'note') = 'string' "
+        "AND trim(payload ->> 'note') <> '') OR ("
+        "event_type = 'REPAIR_COMPLETED' "
+        "AND payload ?& ARRAY['previous_miner_lifecycle', 'resulting_miner_lifecycle'] "
+        "AND payload ->> 'previous_miner_lifecycle' = 'in_repair' "
+        "AND payload ->> 'resulting_miner_lifecycle' IN ('active', 'spare') "
+        "AND (NOT payload ? 'pre_repair_lifecycle' "
+        "OR payload ->> 'pre_repair_lifecycle' IN ('active', 'spare')) "
+        "AND (NOT payload ? 'completion_summary' OR ("
+        "jsonb_typeof(payload -> 'completion_summary') = 'string' "
+        "AND trim(payload ->> 'completion_summary') <> '' "
+        "AND char_length(payload ->> 'completion_summary') <= 4000))) OR ("
+        "event_type = 'CONTROL_BOARD_REPLACED' "
+        "AND payload ?& ARRAY['old_mac_address', 'new_mac_address', "
+        "'old_control_board_serial', 'new_control_board_serial', "
+        "'replacement_reason', 'removed_board_disposition'] "
+        "AND jsonb_typeof(payload -> 'old_mac_address') IN ('string', 'null') "
+        "AND jsonb_typeof(payload -> 'new_mac_address') = 'string' "
+        "AND payload ->> 'new_mac_address' ~ '^([0-9A-F]{2}:){5}[0-9A-F]{2}$' "
+        "AND regexp_replace(lower(payload ->> 'new_mac_address'), '[^0-9a-f]', '', 'g') "
+        "NOT IN ('000000000000', 'ffffffffffff') "
+        "AND get_byte(decode(regexp_replace(lower(payload ->> 'new_mac_address'), "
+        "'[^0-9a-f]', '', 'g'), 'hex'), 0) % 2 = 0 "
+        "AND (jsonb_typeof(payload -> 'old_control_board_serial') = 'null' OR ("
+        "jsonb_typeof(payload -> 'old_control_board_serial') = 'string' "
+        "AND trim(payload ->> 'old_control_board_serial') <> '' "
+        "AND char_length(payload ->> 'old_control_board_serial') <= 255)) "
+        "AND (jsonb_typeof(payload -> 'new_control_board_serial') = 'null' OR ("
+        "jsonb_typeof(payload -> 'new_control_board_serial') = 'string' "
+        "AND trim(payload ->> 'new_control_board_serial') <> '' "
+        "AND char_length(payload ->> 'new_control_board_serial') <= 255)) "
+        f"AND payload ->> 'replacement_reason' IN ({_quoted(REPLACEMENT_REASONS)}) "
+        f"AND payload ->> 'removed_board_disposition' IN ({_quoted(DISPOSITIONS)}) "
+        "AND (NOT payload ? 'notes' OR jsonb_typeof(payload -> 'notes') = 'null' OR ("
+        "jsonb_typeof(payload -> 'notes') = 'string' "
+        "AND trim(payload ->> 'notes') <> '' "
+        "AND char_length(payload ->> 'notes') <= 4000))"
+        f"{parts_clause})",
+    )
+
+
+def upgrade() -> None:
+    connection = op.get_bind()
+
+    connection.exec_driver_sql(
+        """
+        INSERT INTO permissions (key, description)
+        VALUES
+          ('components.read', 'View tracked component identity'),
+          ('components.create', 'Register tracked component identity'),
+          ('repairs.parts.manage', 'Record and void repair-part usage')
+        ON CONFLICT (key) DO UPDATE SET description = EXCLUDED.description;
+
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id
+        FROM roles
+        JOIN permissions ON permissions.key IN (
+          'components.read', 'components.create', 'repairs.parts.manage'
+        )
+        WHERE roles.name IN ('Admin', 'Manager', 'Technician')
+        ON CONFLICT DO NOTHING;
+
+        INSERT INTO role_permissions (role_id, permission_id)
+        SELECT roles.id, permissions.id
+        FROM roles
+        JOIN permissions ON permissions.key = 'components.read'
+        WHERE roles.name = 'Read Only'
+        ON CONFLICT DO NOTHING;
+        """
+    )
+
+    op.create_table(
+        "components",
+        sa.Column(
+            "id", postgresql.UUID(as_uuid=True), primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column("component_type", sa.Text(), nullable=False),
+        sa.Column("asset_id", sa.Text(), nullable=True),
+        sa.Column("manufacturer", sa.Text(), nullable=True),
+        sa.Column("model", sa.Text(), nullable=True),
+        sa.Column("manufacturer_serial", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "created_by", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"), nullable=False,
+        ),
+        sa.CheckConstraint(
+            f"component_type IN ({_quoted(COMPONENT_TYPES)})",
+            name="ck_components_type",
+        ),
+        sa.CheckConstraint(
+            "asset_id IS NULL OR (trim(asset_id) <> '' "
+            "AND asset_id = trim(asset_id) AND char_length(asset_id) <= 255)",
+            name="ck_components_asset_id",
+        ),
+        sa.CheckConstraint(
+            "manufacturer IS NULL OR (trim(manufacturer) <> '' "
+            "AND manufacturer = trim(manufacturer) "
+            "AND char_length(manufacturer) <= 255)",
+            name="ck_components_manufacturer",
+        ),
+        sa.CheckConstraint(
+            "model IS NULL OR (trim(model) <> '' AND model = trim(model) "
+            "AND char_length(model) <= 255)",
+            name="ck_components_model",
+        ),
+        sa.CheckConstraint(
+            "manufacturer_serial IS NULL OR (trim(manufacturer_serial) <> '' "
+            "AND manufacturer_serial = trim(manufacturer_serial) "
+            "AND char_length(manufacturer_serial) <= 255)",
+            name="ck_components_manufacturer_serial",
+        ),
+    )
+    op.create_index("idx_components_created_by", "components", ["created_by"])
+    op.create_index("idx_components_type", "components", ["component_type"])
+    op.create_index(
+        "uq_components_normalized_asset_id",
+        "components",
+        [sa.text("lower(trim(asset_id))")],
+        unique=True,
+        postgresql_where=sa.text("asset_id IS NOT NULL"),
+    )
+
+    op.create_table(
+        "repair_parts",
+        sa.Column(
+            "id", postgresql.UUID(as_uuid=True), primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column(
+            "repair_id", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("repairs.id", ondelete="RESTRICT"), nullable=False,
+        ),
+        sa.Column("consumable_description", sa.Text(), nullable=True),
+        sa.Column("quantity", sa.Numeric(precision=12, scale=3), nullable=True),
+        sa.Column("unit", sa.Text(), nullable=True),
+        sa.Column(
+            "component_id", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("components.id", ondelete="RESTRICT"), nullable=True,
+        ),
+        sa.Column("component_type_snapshot", sa.Text(), nullable=True),
+        sa.Column("component_asset_id_snapshot", sa.Text(), nullable=True),
+        sa.Column("component_manufacturer_snapshot", sa.Text(), nullable=True),
+        sa.Column("component_model_snapshot", sa.Text(), nullable=True),
+        sa.Column("component_manufacturer_serial_snapshot", sa.Text(), nullable=True),
+        sa.Column("notes", sa.Text(), nullable=True),
+        sa.Column(
+            "recorded_by", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"), nullable=False,
+        ),
+        sa.Column(
+            "recorded_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "recorded_event_id", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("repair_events.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column(
+            "voided_by", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="RESTRICT"), nullable=True,
+        ),
+        sa.Column("voided_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("void_reason", sa.Text(), nullable=True),
+        sa.Column(
+            "void_event_id", postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("repair_events.id", ondelete="RESTRICT"),
+            nullable=True,
+        ),
+        sa.CheckConstraint(
+            "((consumable_description IS NOT NULL AND quantity IS NOT NULL "
+            "AND unit IS NOT NULL AND component_id IS NULL "
+            "AND component_type_snapshot IS NULL "
+            "AND component_asset_id_snapshot IS NULL "
+            "AND component_manufacturer_snapshot IS NULL "
+            "AND component_model_snapshot IS NULL "
+            "AND component_manufacturer_serial_snapshot IS NULL) OR "
+            "(consumable_description IS NULL AND quantity IS NULL "
+            "AND unit IS NULL AND component_id IS NOT NULL "
+            "AND component_type_snapshot IS NOT NULL))",
+            name="ck_repair_parts_entry_xor",
+        ),
+        sa.CheckConstraint(
+            "quantity IS NULL OR quantity > 0",
+            name="ck_repair_parts_quantity_positive",
+        ),
+        sa.CheckConstraint(
+            "unit IS NULL OR unit <> 'each' OR quantity = trunc(quantity)",
+            name="ck_repair_parts_each_whole",
+        ),
+        sa.CheckConstraint(
+            f"unit IS NULL OR unit IN ({_quoted(CONSUMABLE_UNITS)})",
+            name="ck_repair_parts_unit",
+        ),
+        sa.CheckConstraint(
+            f"component_type_snapshot IS NULL OR "
+            f"component_type_snapshot IN ({_quoted(COMPONENT_TYPES)})",
+            name="ck_repair_parts_component_type",
+        ),
+        sa.CheckConstraint(
+            "consumable_description IS NULL OR ("
+            "consumable_description = trim(consumable_description) "
+            "AND trim(consumable_description) <> '' "
+            "AND char_length(consumable_description) <= 255)",
+            name="ck_repair_parts_description",
+        ),
+        sa.CheckConstraint(
+            "component_asset_id_snapshot IS NULL OR ("
+            "component_asset_id_snapshot = trim(component_asset_id_snapshot) "
+            "AND trim(component_asset_id_snapshot) <> '' "
+            "AND char_length(component_asset_id_snapshot) <= 255)",
+            name="ck_repair_parts_asset_snapshot",
+        ),
+        sa.CheckConstraint(
+            "component_manufacturer_snapshot IS NULL OR ("
+            "component_manufacturer_snapshot = trim(component_manufacturer_snapshot) "
+            "AND trim(component_manufacturer_snapshot) <> '' "
+            "AND char_length(component_manufacturer_snapshot) <= 255)",
+            name="ck_repair_parts_manufacturer_snapshot",
+        ),
+        sa.CheckConstraint(
+            "component_model_snapshot IS NULL OR ("
+            "component_model_snapshot = trim(component_model_snapshot) "
+            "AND trim(component_model_snapshot) <> '' "
+            "AND char_length(component_model_snapshot) <= 255)",
+            name="ck_repair_parts_model_snapshot",
+        ),
+        sa.CheckConstraint(
+            "component_manufacturer_serial_snapshot IS NULL OR ("
+            "component_manufacturer_serial_snapshot = "
+            "trim(component_manufacturer_serial_snapshot) "
+            "AND trim(component_manufacturer_serial_snapshot) <> '' "
+            "AND char_length(component_manufacturer_serial_snapshot) <= 255)",
+            name="ck_repair_parts_serial_snapshot",
+        ),
+        sa.CheckConstraint(
+            "notes IS NULL OR (notes = trim(notes) AND trim(notes) <> '' "
+            "AND char_length(notes) <= 4000)",
+            name="ck_repair_parts_notes",
+        ),
+        sa.CheckConstraint(
+            "(voided_by IS NULL AND voided_at IS NULL AND void_reason IS NULL "
+            "AND void_event_id IS NULL) OR "
+            "(voided_by IS NOT NULL AND voided_at IS NOT NULL "
+            "AND void_reason IS NOT NULL AND void_event_id IS NOT NULL)",
+            name="ck_repair_parts_void_state",
+        ),
+        sa.CheckConstraint(
+            "void_reason IS NULL OR (void_reason = trim(void_reason) "
+            "AND trim(void_reason) <> '' AND char_length(void_reason) <= 1000)",
+            name="ck_repair_parts_void_reason",
+        ),
+        sa.CheckConstraint(
+            "voided_at IS NULL OR voided_at >= recorded_at",
+            name="ck_repair_parts_void_chronology",
+        ),
+    )
+    op.create_index(
+        "idx_repair_parts_repair",
+        "repair_parts",
+        ["repair_id", "recorded_event_id", "id"],
+    )
+    op.create_index("idx_repair_parts_component", "repair_parts", ["component_id"])
+    op.create_index("idx_repair_parts_recorded_by", "repair_parts", ["recorded_by"])
+    op.create_index("idx_repair_parts_voided_by", "repair_parts", ["voided_by"])
+    op.create_index(
+        "uq_repair_parts_recorded_event",
+        "repair_parts",
+        ["recorded_event_id"],
+        unique=True,
+    )
+    op.create_index(
+        "uq_repair_parts_void_event",
+        "repair_parts",
+        ["void_event_id"],
+        unique=True,
+        postgresql_where=sa.text("void_event_id IS NOT NULL"),
+    )
+
+    op.drop_constraint("ck_repair_events_payload_shape", "repair_events", type_="check")
+    op.drop_constraint("ck_repair_events_type", "repair_events", type_="check")
+    _create_event_constraints(True)
+
+    connection.exec_driver_sql(
+        """
+        CREATE FUNCTION minerops_protect_component_identity()
+        RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN
+          IF TG_OP = 'DELETE' THEN
+            RAISE EXCEPTION 'Durable component identity cannot be deleted';
+          END IF;
+          IF NEW.id <> OLD.id
+             OR NEW.component_type <> OLD.component_type
+             OR NEW.created_at <> OLD.created_at
+             OR NEW.created_by <> OLD.created_by THEN
+            RAISE EXCEPTION 'Component identity, type, and creation provenance are immutable';
+          END IF;
+          RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_protect_component_identity
+        BEFORE UPDATE OR DELETE ON components
+        FOR EACH ROW EXECUTE FUNCTION minerops_protect_component_identity();
+
+        CREATE FUNCTION minerops_protect_repair_event_history()
+        RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN
+          RAISE EXCEPTION 'Repair event history is immutable';
+        END $$;
+        CREATE TRIGGER trg_protect_repair_event_history
+        BEFORE UPDATE OR DELETE ON repair_events
+        FOR EACH ROW EXECUTE FUNCTION minerops_protect_repair_event_history();
+
+        CREATE FUNCTION minerops_protect_repair_part_history()
+        RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN
+          IF TG_OP = 'DELETE' THEN
+            RAISE EXCEPTION 'Repair-part history is immutable';
+          END IF;
+          IF NEW.id <> OLD.id
+             OR NEW.repair_id <> OLD.repair_id
+             OR NEW.consumable_description IS DISTINCT FROM OLD.consumable_description
+             OR NEW.quantity IS DISTINCT FROM OLD.quantity
+             OR NEW.unit IS DISTINCT FROM OLD.unit
+             OR NEW.component_id IS DISTINCT FROM OLD.component_id
+             OR NEW.component_type_snapshot IS DISTINCT FROM OLD.component_type_snapshot
+             OR NEW.component_asset_id_snapshot IS DISTINCT FROM OLD.component_asset_id_snapshot
+             OR NEW.component_manufacturer_snapshot IS DISTINCT FROM OLD.component_manufacturer_snapshot
+             OR NEW.component_model_snapshot IS DISTINCT FROM OLD.component_model_snapshot
+             OR NEW.component_manufacturer_serial_snapshot IS DISTINCT FROM OLD.component_manufacturer_serial_snapshot
+             OR NEW.notes IS DISTINCT FROM OLD.notes
+             OR NEW.recorded_by <> OLD.recorded_by
+             OR NEW.recorded_at <> OLD.recorded_at
+             OR NEW.recorded_event_id <> OLD.recorded_event_id THEN
+            RAISE EXCEPTION 'Original repair-part fields are immutable';
+          END IF;
+          IF OLD.voided_by IS NOT NULL OR OLD.voided_at IS NOT NULL
+             OR OLD.void_reason IS NOT NULL OR OLD.void_event_id IS NOT NULL THEN
+            RAISE EXCEPTION 'Voided repair-part history is immutable';
+          END IF;
+          IF NEW.voided_by IS NULL OR NEW.voided_at IS NULL
+             OR NEW.void_reason IS NULL OR NEW.void_event_id IS NULL THEN
+            RAISE EXCEPTION 'Repair-part void metadata must be written atomically';
+          END IF;
+          RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_protect_repair_part_history
+        BEFORE UPDATE OR DELETE ON repair_parts
+        FOR EACH ROW EXECUTE FUNCTION minerops_protect_repair_part_history();
+
+        CREATE FUNCTION minerops_validate_repair_part_history()
+        RETURNS trigger LANGUAGE plpgsql AS $$
+        DECLARE recorded repair_events%%ROWTYPE;
+        DECLARE voided repair_events%%ROWTYPE;
+        DECLARE component components%%ROWTYPE;
+        BEGIN
+          IF TG_OP = 'INSERT' AND (
+             NEW.voided_by IS NOT NULL OR NEW.voided_at IS NOT NULL
+             OR NEW.void_reason IS NOT NULL OR NEW.void_event_id IS NOT NULL) THEN
+            RAISE EXCEPTION 'A repair part must be recorded before it can be voided';
+          END IF;
+          SELECT * INTO recorded FROM repair_events WHERE id = NEW.recorded_event_id;
+          IF recorded.id IS NULL
+             OR recorded.repair_id <> NEW.repair_id
+             OR recorded.event_type <> 'REPAIR_PART_RECORDED'
+             OR recorded.created_by <> NEW.recorded_by
+             OR recorded.created_at <> NEW.recorded_at
+             OR recorded.payload ->> 'repair_part_id' <> NEW.id::text THEN
+            RAISE EXCEPTION 'Recorded repair-part event does not match its entry';
+          END IF;
+
+          IF TG_OP = 'INSERT' AND NEW.component_id IS NOT NULL THEN
+            SELECT * INTO component FROM components WHERE id = NEW.component_id;
+            IF component.id IS NULL
+               OR component.component_type <> NEW.component_type_snapshot
+               OR component.asset_id IS DISTINCT FROM NEW.component_asset_id_snapshot
+               OR component.manufacturer IS DISTINCT FROM NEW.component_manufacturer_snapshot
+               OR component.model IS DISTINCT FROM NEW.component_model_snapshot
+               OR component.manufacturer_serial IS DISTINCT FROM NEW.component_manufacturer_serial_snapshot THEN
+              RAISE EXCEPTION 'Tracked-component snapshot does not match the component';
+            END IF;
+          END IF;
+
+          IF NEW.void_event_id IS NOT NULL THEN
+            SELECT * INTO voided FROM repair_events WHERE id = NEW.void_event_id;
+            IF voided.id IS NULL
+               OR voided.repair_id <> NEW.repair_id
+               OR voided.event_type <> 'REPAIR_PART_VOIDED'
+               OR voided.created_by <> NEW.voided_by
+               OR voided.created_at <> NEW.voided_at
+               OR voided.payload ->> 'repair_part_id' <> NEW.id::text
+               OR voided.payload ->> 'reason' <> NEW.void_reason THEN
+              RAISE EXCEPTION 'Voided repair-part event does not match its entry';
+            END IF;
+          END IF;
+          RETURN NEW;
+        END $$;
+        CREATE TRIGGER trg_validate_repair_part_history
+        BEFORE INSERT OR UPDATE ON repair_parts
+        FOR EACH ROW EXECUTE FUNCTION minerops_validate_repair_part_history();
+        """
+    )
+
+
+def downgrade() -> None:
+    connection = op.get_bind()
+    connection.exec_driver_sql(
+        """
+        DO $$
+        DECLARE history_count bigint;
+        BEGIN
+          SELECT count(*) INTO history_count FROM components;
+          history_count := history_count + (SELECT count(*) FROM repair_parts);
+          history_count := history_count + (
+            SELECT count(*) FROM repair_events
+            WHERE event_type IN ('REPAIR_PART_RECORDED', 'REPAIR_PART_VOIDED')
+          );
+          IF history_count > 0 THEN
+            RAISE EXCEPTION USING
+              MESSAGE = format(
+                'Cannot downgrade Repair Parts Tracking: %s component, repair-part, or event records would be destroyed',
+                history_count
+              ),
+              HINT = 'Preserve or explicitly migrate Task 005 identity and history before downgrading; MinerOps will not delete or invent component, actor, timestamp, snapshot, or repair-part history.';
+          END IF;
+        END $$;
+        """
+    )
+
+    connection.exec_driver_sql(
+        """
+        DROP TRIGGER trg_validate_repair_part_history ON repair_parts;
+        DROP FUNCTION minerops_validate_repair_part_history();
+        DROP TRIGGER trg_protect_repair_part_history ON repair_parts;
+        DROP FUNCTION minerops_protect_repair_part_history();
+        DROP TRIGGER trg_protect_repair_event_history ON repair_events;
+        DROP FUNCTION minerops_protect_repair_event_history();
+        DROP TRIGGER trg_protect_component_identity ON components;
+        DROP FUNCTION minerops_protect_component_identity();
+        """
+    )
+
+    op.drop_constraint("ck_repair_events_payload_shape", "repair_events", type_="check")
+    op.drop_constraint("ck_repair_events_type", "repair_events", type_="check")
+    _create_event_constraints(False)
+
+    op.drop_index("uq_repair_parts_void_event", table_name="repair_parts")
+    op.drop_index("uq_repair_parts_recorded_event", table_name="repair_parts")
+    op.drop_index("idx_repair_parts_voided_by", table_name="repair_parts")
+    op.drop_index("idx_repair_parts_recorded_by", table_name="repair_parts")
+    op.drop_index("idx_repair_parts_component", table_name="repair_parts")
+    op.drop_index("idx_repair_parts_repair", table_name="repair_parts")
+    op.drop_table("repair_parts")
+
+    op.drop_index("uq_components_normalized_asset_id", table_name="components")
+    op.drop_index("idx_components_type", table_name="components")
+    op.drop_index("idx_components_created_by", table_name="components")
+    op.drop_table("components")
+
+    connection.exec_driver_sql(
+        """
+        DELETE FROM role_permissions
+        WHERE permission_id IN (
+          SELECT id FROM permissions
+          WHERE key IN ('components.read', 'components.create', 'repairs.parts.manage')
+        );
+        DELETE FROM permissions
+        WHERE key IN ('components.read', 'components.create', 'repairs.parts.manage');
+        """
+    )

backend/app/components/__init__.py

@@ -0,0 +1 @@
+"""Minimal durable component registry for repair-part references."""

backend/app/components/dependencies.py

@@ -0,0 +1,8 @@
+"""Dependency construction for the Components domain."""
+
+from app.components.repository import ComponentRepository
+from app.components.service import ComponentService
+
+
+def get_component_service() -> ComponentService:
+    return ComponentService(ComponentRepository())

backend/app/components/exceptions.py

@@ -0,0 +1,32 @@
+"""Domain exceptions for the minimal component registry."""
+
+
+class ComponentError(Exception):
+    """Base exception for component operations."""
+
+
+class ComponentNotFound(ComponentError):
+    """Raised when a component UUID does not exist."""
+
+    def __init__(self, component_id: object):
+        self.component_id = component_id
+        super().__init__(f"Component not found: {component_id}")
+
+
+class DuplicateComponentAssetID(ComponentError):
+    """Raised when a normalized component Asset ID already exists."""
+
+    def __init__(self, asset_id: str):
+        self.asset_id = asset_id
+        super().__init__(f"Component Asset ID already exists: {asset_id}")
+
+
+class ComponentValidationError(ComponentError):
+    """Raised when component metadata violates a domain rule."""
+
+
+class ComponentActorRequired(ComponentError):
+    """Raised when component creation lacks an authenticated actor."""
+
+    def __init__(self):
+        super().__init__("An authenticated actor is required to create a component")

backend/app/components/models.py

@@ -0,0 +1,36 @@
+"""Typed contracts for the minimal component registry."""
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+
+ComponentType = Literal["control_board", "hashboard", "power_supply", "fan"]
+
+
+class ComponentCreateRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    component_type: ComponentType
+    asset_id: str | None = Field(default=None, max_length=255)
+    manufacturer: str | None = Field(default=None, max_length=255)
+    model: str | None = Field(default=None, max_length=255)
+    manufacturer_serial: str | None = Field(default=None, max_length=255)
+
+
+class ComponentDetail(BaseModel):
+    component_id: UUID
+    component_type: ComponentType
+    asset_id: str | None = None
+    manufacturer: str | None = None
+    model: str | None = None
+    manufacturer_serial: str | None = None
+    created_at: AwareDatetime
+    created_by: UUID
+
+
+class ComponentResponse(BaseModel):
+    data: ComponentDetail
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None

backend/app/components/repository.py

@@ -0,0 +1,143 @@
+"""PostgreSQL persistence for the minimal component registry."""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from uuid import UUID
+
+import psycopg
+from psycopg.errors import UniqueViolation
+from psycopg.rows import dict_row
+
+from app.components.exceptions import DuplicateComponentAssetID
+from app.config import settings
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+COMPONENT_ASSET_ID_CONSTRAINT = "uq_components_normalized_asset_id"
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+class ComponentRepository:
+    """Persistence boundary for minimal component identity."""
+
+    def __init__(
+        self,
+        connection_factory: ConnectionFactory | None = None,
+        *,
+        connection: psycopg.Connection | None = None,
+    ):
+        self._connection_factory = connection_factory or default_connection_factory
+        self._connection = connection
+
+    @contextmanager
+    def transaction(self) -> Iterator["ComponentRepository"]:
+        if self._connection is not None:
+            yield self
+            return
+
+        connection = self._connection_factory()
+        repository = ComponentRepository(
+            self._connection_factory,
+            connection=connection,
+        )
+        try:
+            yield repository
+            connection.commit()
+        except UniqueViolation as exc:
+            connection.rollback()
+            if exc.diag.constraint_name == COMPONENT_ASSET_ID_CONSTRAINT:
+                raise DuplicateComponentAssetID("normalized Asset ID") from exc
+            raise
+        except Exception:
+            connection.rollback()
+            raise
+        finally:
+            connection.close()
+
+    @contextmanager
+    def _connection_scope(self) -> Iterator[psycopg.Connection]:
+        if self._connection is not None:
+            yield self._connection
+            return
+
+        connection = self._connection_factory()
+        try:
+            yield connection
+        finally:
+            connection.close()
+
+    def create_component(
+        self,
+        *,
+        component_type: str,
+        asset_id: str | None,
+        manufacturer: str | None,
+        model: str | None,
+        manufacturer_serial: str | None,
+        created_by: UUID,
+    ) -> dict:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO components (
+                        component_type,
+                        asset_id,
+                        manufacturer,
+                        model,
+                        manufacturer_serial,
+                        created_by
+                    )
+                    VALUES (%s, %s, %s, %s, %s, %s)
+                    RETURNING
+                        id AS component_id,
+                        component_type,
+                        asset_id,
+                        manufacturer,
+                        model,
+                        manufacturer_serial,
+                        created_at,
+                        created_by
+                    """,
+                    (
+                        component_type,
+                        asset_id,
+                        manufacturer,
+                        model,
+                        manufacturer_serial,
+                        created_by,
+                    ),
+                )
+                return dict(cur.fetchone())
+
+    def get_component(self, component_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        id AS component_id,
+                        component_type,
+                        asset_id,
+                        manufacturer,
+                        model,
+                        manufacturer_serial,
+                        created_at,
+                        created_by
+                    FROM components
+                    WHERE id = %s
+                    """,
+                    (component_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None

backend/app/components/router.py

@@ -0,0 +1,80 @@
+"""HTTP mapping for the minimal component registry."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.components.dependencies import get_component_service
+from app.components.exceptions import (
+    ComponentActorRequired,
+    ComponentNotFound,
+    ComponentValidationError,
+    DuplicateComponentAssetID,
+)
+from app.components.models import (
+    ComponentCreateRequest,
+    ComponentResponse,
+)
+from app.components.service import ComponentService
+from app.identity import require_permission
+
+
+router = APIRouter(prefix="/api/components", tags=["components"])
+require_component_read = require_permission("components.read")
+require_component_create = require_permission("components.create")
+
+ComponentServiceDependency = Annotated[
+    ComponentService,
+    Depends(get_component_service),
+]
+ComponentReadUser = Annotated[dict, Depends(require_component_read)]
+ComponentCreateUser = Annotated[dict, Depends(require_component_create)]
+
+
+@router.post(
+    "",
+    response_model=ComponentResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_component(
+    request: ComponentCreateRequest,
+    service: ComponentServiceDependency,
+    current_user: ComponentCreateUser,
+) -> ComponentResponse:
+    try:
+        component = service.create_component(
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except DuplicateComponentAssetID as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except (ComponentActorRequired, ComponentValidationError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+    return ComponentResponse(data=component)
+
+
+@router.get(
+    "/{component_id}",
+    response_model=ComponentResponse,
+)
+def get_component(
+    component_id: UUID,
+    service: ComponentServiceDependency,
+    current_user: ComponentReadUser,
+) -> ComponentResponse:
+    del current_user
+    try:
+        component = service.get_component(component_id)
+    except ComponentNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Component not found",
+        ) from exc
+    return ComponentResponse(data=component)

backend/app/components/service.py

@@ -0,0 +1,75 @@
+"""Business rules for the minimal component registry."""
+
+from uuid import UUID
+
+from app.components.exceptions import (
+    ComponentActorRequired,
+    ComponentNotFound,
+    ComponentValidationError,
+    DuplicateComponentAssetID,
+)
+from app.components.models import ComponentCreateRequest, ComponentDetail
+from app.components.repository import ComponentRepository
+
+
+class ComponentService:
+    """Minimal component workflows independent of FastAPI."""
+
+    def __init__(self, repository: ComponentRepository):
+        self.repository = repository
+
+    @staticmethod
+    def _normalize_optional_text(value: str | None, field_name: str) -> str | None:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        if not normalized:
+            raise ComponentValidationError(
+                f"{field_name} must not be blank when supplied"
+            )
+        if len(normalized) > 255:
+            raise ComponentValidationError(
+                f"{field_name} must not exceed 255 characters"
+            )
+        return normalized
+
+    @staticmethod
+    def _map_component(component: dict) -> ComponentDetail:
+        return ComponentDetail(**component)
+
+    def create_component(
+        self,
+        request: ComponentCreateRequest,
+        *,
+        actor_user_id: UUID | None,
+    ) -> ComponentDetail:
+        if actor_user_id is None:
+            raise ComponentActorRequired()
+
+        asset_id = self._normalize_optional_text(request.asset_id, "asset_id")
+        values = {
+            "manufacturer": self._normalize_optional_text(
+                request.manufacturer, "manufacturer"
+            ),
+            "model": self._normalize_optional_text(request.model, "model"),
+            "manufacturer_serial": self._normalize_optional_text(
+                request.manufacturer_serial, "manufacturer_serial"
+            ),
+        }
+        try:
+            with self.repository.transaction() as repository:
+                component = repository.create_component(
+                    component_type=request.component_type,
+                    asset_id=asset_id,
+                    created_by=actor_user_id,
+                    **values,
+                )
+        except DuplicateComponentAssetID as exc:
+            raise DuplicateComponentAssetID(asset_id or "") from exc
+        return self._map_component(component)
+
+    def get_component(self, component_id: UUID) -> ComponentDetail:
+        component = self.repository.get_component(component_id)
+        if component is None:
+            raise ComponentNotFound(component_id)
+        return self._map_component(component)

backend/app/dashboard/__init__.py

@@ -0,0 +1 @@
+"""Permission-aware operational Dashboard read model."""

backend/app/dashboard/dependencies.py

@@ -0,0 +1,14 @@
+"""Dependency construction for the Dashboard composition service."""
+
+from app.dashboard.service import DashboardService
+from app.inventory.dependencies import get_inventory_service
+from app.locations.dependencies import get_location_map_service
+from app.repairs.dependencies import get_repair_center_service
+
+
+def get_dashboard_service() -> DashboardService:
+    return DashboardService(
+        inventory_service=get_inventory_service(),
+        repair_center_service=get_repair_center_service(),
+        location_service=get_location_map_service(),
+    )

backend/app/dashboard/models.py

@@ -0,0 +1,32 @@
+"""Typed contracts for the operational Dashboard overview."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from app.inventory.models import InventoryFleetSummary
+from app.locations.models import LocationSummary
+from app.repairs.models import ActiveRepairSummary
+
+
+class DashboardAccess(BaseModel):
+    can_view_miners: bool = False
+    can_view_repairs: bool = False
+    can_view_locations: bool = False
+
+
+class DashboardOverviewData(BaseModel):
+    fleet: InventoryFleetSummary | None = None
+    repairs: ActiveRepairSummary | None = None
+    locations: LocationSummary | None = None
+    generated_at: datetime
+
+
+class DashboardOverviewMeta(BaseModel):
+    available_sections: list[str] = Field(default_factory=list)
+
+
+class DashboardOverviewResponse(BaseModel):
+    data: DashboardOverviewData
+    meta: DashboardOverviewMeta = Field(default_factory=DashboardOverviewMeta)
+    error: None = None

backend/app/dashboard/router.py

@@ -0,0 +1,40 @@
+"""HTTP boundary for the operational Dashboard overview."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Response
+
+from app.dashboard.dependencies import get_dashboard_service
+from app.dashboard.models import (
+    DashboardAccess,
+    DashboardOverviewResponse,
+)
+from app.dashboard.service import DashboardService
+from app.identity import require_permission, user_has_permission
+
+
+router = APIRouter(prefix="/api/dashboard", tags=["dashboard"])
+DashboardUser = Annotated[dict, Depends(require_permission("dashboard.view"))]
+DashboardServiceDependency = Annotated[
+    DashboardService,
+    Depends(get_dashboard_service),
+]
+
+
+@router.get("/overview", response_model=DashboardOverviewResponse)
+def get_dashboard_overview(
+    current_user: DashboardUser,
+    service: DashboardServiceDependency,
+    response: Response,
+) -> DashboardOverviewResponse:
+    response.headers["Cache-Control"] = "no-store"
+    return service.get_overview(
+        DashboardAccess(
+            can_view_miners=user_has_permission(current_user, "miners.view"),
+            can_view_repairs=user_has_permission(current_user, "repairs.view"),
+            can_view_locations=user_has_permission(
+                current_user,
+                "locations.view",
+            ),
+        )
+    )

backend/app/dashboard/service.py

@@ -0,0 +1,64 @@
+"""Composition service for permission-aware Dashboard summaries."""
+
+from datetime import datetime, timezone
+
+from app.dashboard.models import (
+    DashboardAccess,
+    DashboardOverviewData,
+    DashboardOverviewMeta,
+    DashboardOverviewResponse,
+)
+from app.inventory.service import InventoryService
+from app.locations.service import LocationMapService
+from app.repairs.center_service import RepairCenterService
+
+
+class DashboardService:
+    """Coordinate domain-owned summaries without introducing new rules."""
+
+    def __init__(
+        self,
+        inventory_service: InventoryService,
+        repair_center_service: RepairCenterService,
+        location_service: LocationMapService,
+    ):
+        self.inventory_service = inventory_service
+        self.repair_center_service = repair_center_service
+        self.location_service = location_service
+
+    def get_overview(self, access: DashboardAccess) -> DashboardOverviewResponse:
+        fleet = (
+            self.inventory_service.summarize_fleet()
+            if access.can_view_miners
+            else None
+        )
+        repairs = (
+            self.repair_center_service.summarize_active_repairs()
+            if access.can_view_repairs
+            else None
+        )
+        locations = (
+            self.location_service.summarize_locations(
+                include_miner_counts=access.can_view_miners
+            )
+            if access.can_view_locations
+            else None
+        )
+        available_sections = [
+            name
+            for name, value in (
+                ("fleet", fleet),
+                ("repairs", repairs),
+                ("locations", locations),
+            )
+            if value is not None
+        ]
+        return DashboardOverviewResponse(
+            data=DashboardOverviewData(
+                fleet=fleet,
+                repairs=repairs,
+                locations=locations,
+                generated_at=datetime.now(timezone.utc),
+            ),
+            meta=DashboardOverviewMeta(available_sections=available_sections),
+        )

backend/app/frontend/__init__.py

@@ -0,0 +1 @@
+"""Server-rendered frontend foundation for MinerOps."""

backend/app/frontend/miner_detail_view.py

@@ -0,0 +1,77 @@
+"""Semantic HTML for the Internal Alpha Miner Detail page."""
+
+
+def miner_detail_content() -> str:
+    return """
+<div class="state-message" id="minerDetailLoading" role="status">
+    <strong>Loading miner</strong>
+    <span>Requesting current identity and operational context.</span>
+</div>
+<div class="state-message" id="minerDetailError" data-kind="error" role="alert" hidden>
+    <strong>Miner detail unavailable</strong>
+    <span id="minerDetailErrorText">The miner could not be loaded.</span>
+    <button class="command-button" id="minerDetailRetry" type="button">Retry</button>
+</div>
+<div id="minerDetailContent" hidden>
+    <section class="miner-detail-hero" aria-labelledby="minerIdentityTitle">
+        <div>
+            <p class="eyebrow">Durable miner identity</p>
+            <h2 id="minerIdentityTitle">Miner</h2>
+            <p id="minerDetailModel" class="panel-copy">Model unavailable</p>
+            <p id="minerDetailUuid" class="miner-detail-uuid"></p>
+        </div>
+        <div class="miner-detail-state">
+            <strong id="minerDetailOperational">Operational state unknown</strong>
+            <span id="minerDetailLifecycle">Lifecycle unavailable</span>
+            <span id="minerDetailLocationSummary">Location unavailable</span>
+        </div>
+        <nav class="miner-detail-actions" aria-label="Miner destinations">
+            <a class="quiet-link" id="minerDetailReturn" href="/assets/miners" hidden>Return</a>
+            <a class="quiet-link" href="/assets/miners">Back to Fleet</a>
+            <a class="quiet-link" id="minerDetailMap" href="/monitoring/map" hidden>View on Mine Map</a>
+            <a class="quiet-link" id="minerDetailTrends" href="/monitoring/analytics">View trends</a>
+            <a class="quiet-link" id="minerDetailRepairs" href="/operations/repairs" hidden>Open filtered Repair Center</a>
+            <button class="quiet-button" id="minerDetailRefresh" type="button">Refresh</button>
+        </nav>
+    </section>
+    <div class="miner-detail-grid">
+        <section class="panel" aria-labelledby="minerIdentitySectionTitle">
+            <div class="panel-head"><div><p class="eyebrow">Asset record</p>
+                <h2 id="minerIdentitySectionTitle">Identity</h2></div></div>
+            <dl class="definition-list" id="minerIdentityDetails"></dl>
+            <div id="minerTags" class="tag-list" aria-label="Miner tags"></div>
+        </section>
+        <section class="panel" aria-labelledby="minerCurrentStateTitle">
+            <div class="panel-head"><div><p class="eyebrow">Latest facts</p>
+                <h2 id="minerCurrentStateTitle">Current state</h2></div>
+                <span class="freshness" id="minerTelemetryAge">No observation</span></div>
+            <dl class="metric-grid" id="minerTelemetryDetails"></dl>
+        </section>
+    </div>
+    <section class="panel" id="minerLocationSection" aria-labelledby="minerLocationTitle">
+        <div class="panel-head"><div><p class="eyebrow">Physical context</p>
+            <h2 id="minerLocationTitle">Location</h2></div></div>
+        <div id="minerLocationBody"></div>
+    </section>
+    <section class="panel" id="minerRepairSection" aria-labelledby="minerRepairTitle">
+        <div class="panel-head"><div><p class="eyebrow">Work context</p>
+            <h2 id="minerRepairTitle">Repair context</h2></div></div>
+        <div id="minerRepairBody"></div>
+        <div id="minerRepairEpisodes" class="disclosure-list"></div>
+    </section>
+    <section class="panel" aria-labelledby="minerHistoryTitle">
+        <div class="panel-head"><div><p class="eyebrow">Recorded facts</p>
+            <h2 id="minerHistoryTitle">History</h2></div></div>
+        <div class="disclosure-list">
+            <details id="minerIdentityHistory">
+                <summary>Identity history</summary>
+                <div class="lazy-content" id="minerIdentityHistoryBody" aria-live="polite">Open to load Asset ID and network identity history.</div>
+            </details>
+            <details id="minerObservations">
+                <summary>Recent observations</summary>
+                <div class="lazy-content" id="minerObservationsBody" aria-live="polite">Open to load up to 100 recent factual observations.</div>
+            </details>
+        </div>
+    </section>
+</div>
+"""

backend/app/frontend/monitoring_trends_view.py

@@ -0,0 +1,52 @@
+"""Semantic HTML for the Internal Alpha Monitoring Trends page."""
+
+
+def monitoring_trends_content(can_view_locations: bool) -> str:
+    location_options = (
+        '<option value="site">Site</option><option value="room">Room</option>'
+        if can_view_locations
+        else ""
+    )
+    return f"""
+<section class="trend-controls panel" aria-labelledby="trendControlsTitle">
+    <div class="panel-head"><div><p class="eyebrow">Historical scope</p>
+        <h2 id="trendControlsTitle">Trend controls</h2></div>
+        <p class="freshness" id="trendFreshness">Not loaded</p></div>
+    <form id="trendControls">
+        <label for="trendScope">Scope
+            <select id="trendScope">
+                <option value="fleet">Fleet</option>{location_options}
+            </select>
+        </label>
+        <label for="trendSite" id="trendSiteLabel" hidden>Site
+            <select id="trendSite"></select>
+        </label>
+        <label for="trendRoom" id="trendRoomLabel" hidden>Room
+            <select id="trendRoom"></select>
+        </label>
+        <fieldset class="trend-ranges">
+            <legend>Time range</legend>
+            <label><input type="radio" name="trendRange" value="6h">6 hours</label>
+            <label><input type="radio" name="trendRange" value="24h" checked>24 hours</label>
+            <label><input type="radio" name="trendRange" value="7d">7 days</label>
+        </fieldset>
+        <button class="command-button" type="submit">Apply</button>
+    </form>
+    <p class="panel-copy" id="trendScopeNote">Fleet trends use current miner inventory.</p>
+</section>
+<div class="state-message" id="trendLoading" role="status">
+    <strong>Loading trends</strong><span>Aggregating bounded raw telemetry.</span>
+</div>
+<div class="state-message" id="trendError" data-kind="error" role="alert" hidden>
+    <strong>Trends unavailable</strong><span id="trendErrorText">The request failed.</span>
+    <button class="command-button" id="trendRetry" type="button">Retry</button>
+</div>
+<section id="trendContent" aria-label="Historical telemetry trends" hidden>
+    <div class="trend-summary" aria-live="polite">
+        <p><strong id="trendScopeLabel">Fleet</strong></p>
+        <p id="trendRangeSummary"></p>
+        <p id="trendTimezone"></p>
+    </div>
+    <div id="trendCharts" class="trend-charts"></div>
+</section>
+"""

backend/app/frontend/router.py

@@ -0,0 +1,141 @@
+"""HTTP routes for the MinerOps Internal Alpha application shell."""
+
+from pathlib import Path
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+from fastapi.responses import HTMLResponse, Response
+
+from app.frontend.views import render_app_page
+from app.identity import require_permission, safe_next_path, user_has_permission
+
+
+router = APIRouter(tags=["frontend"])
+STATIC_ROOT = Path(__file__).with_name("static")
+
+DashboardUser = Annotated[dict, Depends(require_permission("dashboard.view"))]
+MapUser = Annotated[dict, Depends(require_permission("locations.view"))]
+RepairUser = Annotated[dict, Depends(require_permission("repairs.view"))]
+MinerUser = Annotated[dict, Depends(require_permission("miners.view"))]
+
+
+def render_page(view: str, current_user: dict, **context) -> str:
+    return render_app_page(
+        view,
+        current_user,
+        lambda permission: user_has_permission(current_user, permission),
+        **context,
+    )
+
+
+@router.get("/assets/minerops-app.css", include_in_schema=False)
+def frontend_styles() -> Response:
+    return Response(
+        (STATIC_ROOT / "app.css").read_text(encoding="utf-8"),
+        media_type="text/css",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/assets/minerops-app.js", include_in_schema=False)
+def frontend_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "app.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/assets/minerops-dashboard.js", include_in_schema=False)
+def dashboard_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "dashboard.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/assets/minerops-mine-map.js", include_in_schema=False)
+def mine_map_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "mine-map.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/assets/minerops-fleet.js", include_in_schema=False)
+def fleet_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "fleet.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+
+@router.get("/assets/minerops-repair-center.js", include_in_schema=False)
+def repair_center_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "repair-center.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/assets/minerops-miner-detail.js", include_in_schema=False)
+def miner_detail_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "miner-detail.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+@router.get("/dashboard", response_class=HTMLResponse, include_in_schema=False)
+def dashboard_page(current_user: DashboardUser) -> str:
+    return render_page("dashboard", current_user)
+
+
+@router.get(
+    "/monitoring/map",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+def mine_map_page(current_user: MapUser) -> str:
+    return render_page("map", current_user)
+
+
+@router.get(
+    "/operations/repairs",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+def repair_center_page(current_user: RepairUser) -> str:
+    return render_page("repairs", current_user)
+
+
+@router.get(
+    "/assets/miners",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+def miners_page(current_user: MinerUser) -> str:
+    return render_page("miners", current_user)
+
+
+@router.get(
+    "/miners/{miner_id}/detail",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+def miner_detail_page(
+    miner_id: UUID,
+    current_user: MinerUser,
+    return_to: Annotated[str | None, Query(max_length=2048)] = None,
+) -> str:
+    safe_return = safe_next_path(return_to) if return_to else None
+    if safe_return != return_to:
+        safe_return = None
+    return render_page("miner_detail", current_user, miner_id=str(miner_id),
+                       return_to=safe_return)

backend/app/frontend/static/app.js

@@ -0,0 +1,47 @@
+(function () {
+    "use strict";
+
+    function setupShell() {
+        const menu = document.getElementById("menuButton");
+        const nav = document.getElementById("primaryNav");
+        if (menu && nav) {
+            menu.addEventListener("click", function () {
+                const open = nav.dataset.open !== "true";
+                nav.dataset.open = String(open);
+                menu.setAttribute("aria-expanded", String(open));
+            });
+        }
+
+        const search = document.getElementById("globalSearchForm");
+        const searchInput = document.getElementById("globalSearchInput");
+        if (search && searchInput) {
+            search.addEventListener("submit", function (event) {
+                event.preventDefault();
+                const query = searchInput.value.trim();
+                const target = query
+                    ? "/assets/miners?query=" + encodeURIComponent(query)
+                    : "/assets/miners";
+                window.location.assign(target);
+            });
+        }
+
+        const logout = document.getElementById("logoutButton");
+        if (logout) {
+            logout.addEventListener("click", async function () {
+                logout.disabled = true;
+                try {
+                    await fetch("/api/auth/logout", {
+                        method: "POST",
+                        credentials: "same-origin"
+                    });
+                } finally {
+                    window.location.replace("/login");
+                }
+            });
+        }
+    }
+
+
+
+    setupShell();
+})();

backend/app/frontend/static/dashboard.js

@@ -0,0 +1,155 @@
+(function () {
+    "use strict";
+
+    if (document.body.dataset.view !== "dashboard") return;
+
+    const ids = [
+        "dashboardLoading", "dashboardError", "dashboardErrorDetail",
+        "dashboardRetry", "dashboardEmpty", "dashboardContent",
+        "dashboardLoadStatus", "dashboardFleetTotal", "dashboardRuntimeOnline",
+        "dashboardRuntimeOffline", "dashboardRuntimeUnknown",
+        "dashboardLifecycleRepair", "dashboardLifecycleSpare",
+        "dashboardLifecycleRetired", "dashboardAttentionOffline",
+        "dashboardAttentionUnknown", "dashboardAttentionUnstable",
+        "dashboardAttentionRepair", "dashboardActiveRepairs",
+        "dashboardRepairStatuses", "dashboardSites", "dashboardRooms",
+        "dashboardPositions", "dashboardOccupied", "dashboardEmptyPositions",
+        "dashboardMappedMiners", "dashboardUnmappedMiners"
+    ];
+    const el = {};
+    for (const id of ids) el[id] = document.getElementById(id);
+    let controller = null;
+
+    const STATUS_LABELS = {
+        OPEN: "Open",
+        IN_PROGRESS: "In progress",
+        WAITING_FOR_PARTS: "Waiting for parts",
+        READY_FOR_TEST: "Ready for test",
+        open: "Open",
+        diagnosing: "Diagnosing",
+        waiting_parts: "Waiting parts",
+        in_progress: "In progress",
+        testing: "Testing",
+        ready_to_shelf: "Ready to shelf",
+        needs_followup: "Needs follow-up",
+        repair: "In repair",
+        unknown: "Unknown"
+    };
+
+    function setCount(node, value) {
+        if (node) node.textContent = Number.isInteger(value) ? String(value) : "Unavailable";
+    }
+
+    function show(name) {
+        el.dashboardLoading.hidden = name !== "loading";
+        el.dashboardError.hidden = name !== "error";
+        el.dashboardEmpty.hidden = name !== "empty";
+        el.dashboardContent.hidden = name !== "ready";
+    }
+
+    function statusLabel(value) {
+        if (Object.prototype.hasOwnProperty.call(STATUS_LABELS, value)) {
+            return STATUS_LABELS[value];
+        }
+        return String(value || "Unknown").replaceAll("_", " ");
+    }
+
+    function renderFleet(fleet) {
+        if (!fleet || !el.dashboardFleetTotal) return;
+        setCount(el.dashboardFleetTotal, fleet.total);
+        setCount(el.dashboardRuntimeOnline, fleet.runtime_online);
+        setCount(el.dashboardRuntimeOffline, fleet.runtime_offline);
+        setCount(el.dashboardRuntimeUnknown, fleet.runtime_unknown);
+        setCount(el.dashboardLifecycleRepair, fleet.lifecycle_in_repair);
+        setCount(el.dashboardLifecycleSpare, fleet.lifecycle_spare);
+        setCount(el.dashboardLifecycleRetired, fleet.lifecycle_retired);
+        const attention = fleet.attention || {};
+        setCount(el.dashboardAttentionOffline, attention.offline);
+        setCount(el.dashboardAttentionUnknown, attention.unknown);
+        setCount(el.dashboardAttentionUnstable, attention.unstable);
+        setCount(el.dashboardAttentionRepair, attention.repair);
+    }
+
+    function renderRepairs(repairs) {
+        if (!repairs || !el.dashboardActiveRepairs) return;
+        setCount(el.dashboardActiveRepairs, repairs.active);
+        const entries = Object.entries(repairs.status_counts || {}).sort(function (left, right) {
+            return statusLabel(left[0]).localeCompare(statusLabel(right[0]));
+        });
+        el.dashboardRepairStatuses.replaceChildren();
+        if (!entries.length) {
+            const row = document.createElement("div");
+            const term = document.createElement("dt");
+            const value = document.createElement("dd");
+            term.textContent = "No active repair statuses";
+            value.textContent = "0";
+            row.append(term, value);
+            el.dashboardRepairStatuses.appendChild(row);
+            return;
+        }
+        for (const [status, count] of entries) {
+            const row = document.createElement("div");
+            const term = document.createElement("dt");
+            const link = document.createElement("a");
+            const value = document.createElement("dd");
+            const params = new URLSearchParams({ scope: "active", status: status });
+            link.href = "/operations/repairs?" + params.toString();
+            link.textContent = statusLabel(status);
+            term.appendChild(link);
+            value.textContent = Number.isInteger(count) ? String(count) : "Unavailable";
+            row.append(term, value);
+            el.dashboardRepairStatuses.appendChild(row);
+        }
+    }
+
+    function renderLocations(locations) {
+        if (!locations || !el.dashboardSites) return;
+        setCount(el.dashboardSites, locations.sites);
+        setCount(el.dashboardRooms, locations.rooms);
+        setCount(el.dashboardPositions, locations.positions);
+        setCount(el.dashboardOccupied, locations.occupied_positions);
+        setCount(el.dashboardEmptyPositions, locations.empty_positions);
+        setCount(el.dashboardMappedMiners, locations.mapped_miners);
+        setCount(el.dashboardUnmappedMiners, locations.unmapped_miners);
+    }
+
+    async function loadOverview() {
+        if (controller) controller.abort();
+        controller = new AbortController();
+        show("loading");
+        try {
+            const response = await fetch("/api/dashboard/overview", {
+                credentials: "same-origin",
+                headers: { Accept: "application/json" },
+                signal: controller.signal
+            });
+            if (response.status === 401) {
+                window.location.replace("/login?next=" + encodeURIComponent("/dashboard"));
+                return;
+            }
+            if (!response.ok) throw new Error("The overview service returned " + response.status + ".");
+            const payload = await response.json();
+            const data = payload && payload.data ? payload.data : {};
+            const available = payload && payload.meta ? payload.meta.available_sections || [] : [];
+            if (!available.length) {
+                show("empty");
+                return;
+            }
+            renderFleet(data.fleet);
+            renderRepairs(data.repairs);
+            renderLocations(data.locations);
+            const generated = new Date(data.generated_at);
+            el.dashboardLoadStatus.textContent = Number.isNaN(generated.valueOf())
+                ? "Operational summary loaded"
+                : "Operational summary generated " + generated.toLocaleString();
+            show("ready");
+        } catch (error) {
+            if (error.name === "AbortError") return;
+            el.dashboardErrorDetail.textContent = error.message || "The operational overview could not be loaded.";
+            show("error");
+        }
+    }
+
+    el.dashboardRetry.addEventListener("click", loadOverview);
+    loadOverview();
+}());

backend/app/frontend/static/fleet.js

@@ -0,0 +1,359 @@
+(function () {
+    "use strict";
+
+    if (document.body.dataset.view !== "miners") return;
+
+    const canViewLocations = document.body.dataset.canViewLocations === "true";
+    const ids = [
+        "fleetFilters", "fleetQuery", "fleetLifecycle", "fleetModel",
+        "fleetRuntime", "fleetRepair", "fleetOperational", "fleetTags",
+        "fleetProblems", "fleetReset", "fleetRows", "fleetResultSummary",
+        "fleetFreshness", "fleetPrevious", "fleetNext", "fleetLimit"
+    ];
+    const el = {};
+    for (const id of ids) el[id] = document.getElementById(id);
+    if (canViewLocations) {
+        el.fleetSite = document.getElementById("fleetSite");
+        el.fleetRoom = document.getElementById("fleetRoom");
+    }
+
+    const limits = new Set([25, 50, 100, 250]);
+    const state = { offset: 0, limit: 100, returned: 0, locationOptions: null,
+        siteId: "", roomId: "" };
+
+    function display(value, fallback) {
+        if (value === null || value === undefined || String(value).trim() === "") {
+            return fallback || "Unavailable";
+        }
+        return String(value);
+    }
+
+    function words(value) {
+        return display(value, "unknown").replaceAll("_", " ").toLowerCase();
+    }
+
+    function create(tag, className, value) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (value !== undefined) node.textContent = value;
+        return node;
+    }
+
+    function showState(name, message) {
+        for (const node of document.querySelectorAll("[data-view-state]")) {
+            node.hidden = node.dataset.viewState !== name;
+        }
+        const active = document.querySelector('[data-view-state="' + name + '"]');
+        const detail = active && active.querySelector("[data-state-detail]");
+        if (detail && message) detail.textContent = message;
+    }
+
+    function finite(value) {
+        return typeof value === "number" && Number.isFinite(value);
+    }
+
+    function metric(value, suffix) {
+        return finite(value) ? String(value) + suffix : "Unavailable";
+    }
+
+    function age(value) {
+        if (!value) return "Never observed";
+        const time = new Date(value).valueOf();
+        if (Number.isNaN(time)) return "Observation time unavailable";
+        const seconds = Math.max(0, Math.floor((Date.now() - time) / 1000));
+        if (seconds < 60) return seconds + "s ago";
+        if (seconds < 3600) return Math.floor(seconds / 60) + "m ago";
+        if (seconds < 86400) return Math.floor(seconds / 3600) + "h ago";
+        return Math.floor(seconds / 86400) + "d ago";
+    }
+
+    function operational(miner) {
+        if (miner.active_repair || miner.lifecycle_status === "in_repair") {
+            return { key: "repair", label: "In repair", problem: true };
+        }
+        if (miner.lifecycle_status === "retired") {
+            return { key: "retired", label: "Retired", problem: false };
+        }
+        if (miner.lifecycle_status === "spare") {
+            return { key: "spare", label: "Spare", problem: false };
+        }
+        const runtime = words(miner.runtime_status);
+        if (runtime === "offline") {
+            return { key: "offline", label: "Offline", problem: true };
+        }
+        if (miner.hash_stable === false) {
+            return { key: "unstable", label: "Hash unstable", problem: true };
+        }
+        if (runtime === "online") {
+            return { key: "online", label: "Online", problem: false };
+        }
+        return { key: "unknown", label: "Operational state unknown", problem: true };
+    }
+
+    function prefixedLabel(value, prefix) {
+        const label = display(value, "");
+        if (!label) return "";
+        return new RegExp("^" + prefix + "\\b", "i").test(label)
+            ? label : prefix + " " + label;
+    }
+
+    function locationText(miner) {
+        if (!canViewLocations || !miner.location_position_id) return "Not mapped";
+        const parts = [];
+        if (miner.site_name) parts.push(miner.site_name);
+        if (miner.room_name) parts.push(miner.room_name);
+        if (miner.rack_label) parts.push(prefixedLabel(miner.rack_label, "Rack"));
+        if (miner.shelf_label) parts.push(prefixedLabel(miner.shelf_label, "Shelf"));
+        parts.push(display(
+            miner.position_label,
+            miner.position_index === null ? "Position unavailable" : "Position " + miner.position_index
+        ));
+        return parts.join(" / ");
+    }
+
+    function detailLink(miner) {
+        const returnTo = window.location.pathname + window.location.search;
+        const path = "/miners/" + encodeURIComponent(miner.id) + "/detail";
+        return path + "?return_to=" + encodeURIComponent(returnTo);
+    }
+
+    function mapLink(miner) {
+        if (!canViewLocations || !miner.location_position_id) return null;
+        const params = new URLSearchParams({ miner_id: miner.id });
+        if (miner.site_id && miner.room_id) {
+            params.set("site_id", miner.site_id);
+            params.set("room_id", miner.room_id);
+        }
+        return "/monitoring/map?" + params.toString();
+    }
+
+    function addCell(row, label, content, className) {
+        const cell = create("td", className || "");
+        cell.dataset.label = label;
+        if (content instanceof Node) cell.appendChild(content);
+        else cell.textContent = display(content);
+        row.appendChild(cell);
+    }
+
+    function stack(primary, secondary) {
+        const box = create("div", "fleet-stack");
+        box.append(create("span", "fleet-primary", display(primary)));
+        if (secondary) box.append(create("span", "secondary", secondary));
+        return box;
+    }
+
+    function renderRow(miner) {
+        const condition = operational(miner);
+        const row = create("tr", "fleet-row");
+        row.dataset.status = condition.key;
+
+        const identity = create("div", "fleet-stack");
+        const link = create("a", "object-link", display(miner.asset_id, "No Asset ID"));
+        link.href = detailLink(miner);
+        identity.append(link, create("span", "secondary fleet-uuid", miner.id));
+        addCell(row, "Miner", identity, "fleet-identity");
+
+        const status = create("div", "fleet-stack");
+        const marker = create("span", "fleet-status", condition.label);
+        marker.dataset.status = condition.key;
+        status.append(marker, create("span", "secondary", age(miner.observed_at)));
+        addCell(row, "Operational", status);
+        addCell(row, "Model / Serial", stack(miner.model, display(miner.miner_sn)));
+        addCell(row, "Network", stack(miner.current_mac, display(miner.current_ip)));
+        addCell(row, "Location", locationText(miner), "fleet-location");
+        addCell(row, "Hashrate", metric(miner.hashrate_ths, " TH/s"));
+        addCell(row, "Power", metric(miner.power_w, " W"));
+        addCell(row, "Max chip temp", metric(miner.chip_temp_max_c, " C"));
+        const repair = miner.active_repair
+            ? words(miner.active_repair.status) + " / " + display(miner.active_repair.reason)
+            : "No active repair";
+        addCell(row, "Lifecycle / Repair", stack(words(miner.lifecycle_status), repair));
+
+        const actions = create("div", "fleet-actions");
+        const open = create("a", "command-link", "Open miner");
+        open.href = detailLink(miner);
+        actions.appendChild(open);
+        const mapHref = mapLink(miner);
+        if (mapHref) {
+            const map = create("a", "quiet-link", "View on Mine Map");
+            map.href = mapHref;
+            actions.appendChild(map);
+        }
+        addCell(row, "Actions", actions);
+        return row;
+    }
+
+    function option(value, label) {
+        const node = document.createElement("option");
+        node.value = value;
+        node.textContent = label;
+        return node;
+    }
+
+    function syncLocationOptions(selectedSite, selectedRoom) {
+        if (!canViewLocations || !state.locationOptions) return;
+        el.fleetSite.replaceChildren(option("", "All sites"));
+        for (const site of state.locationOptions.sites || []) {
+            el.fleetSite.appendChild(option(String(site.id), site.name));
+        }
+        el.fleetSite.value = Array.from(el.fleetSite.options).some(function (item) {
+            return item.value === selectedSite;
+        }) ? selectedSite : "";
+        el.fleetRoom.replaceChildren(option("", "All rooms"));
+        for (const room of state.locationOptions.rooms || []) {
+            if (!el.fleetSite.value || String(room.site_id) === el.fleetSite.value) {
+                el.fleetRoom.appendChild(option(String(room.id), room.name));
+            }
+        }
+        el.fleetRoom.value = Array.from(el.fleetRoom.options).some(function (item) {
+            return item.value === selectedRoom;
+        }) ? selectedRoom : "";
+        state.siteId = el.fleetSite.value;
+        state.roomId = el.fleetRoom.value;
+    }
+
+    function readUrl() {
+        const params = new URLSearchParams(window.location.search);
+        el.fleetQuery.value = (params.get("query") || "").slice(0, 255);
+        el.fleetLifecycle.value = params.get("lifecycle_status") || "";
+        el.fleetModel.value = (params.get("model") || "").slice(0, 255);
+        el.fleetRuntime.value = params.get("runtime_status") || "";
+        el.fleetRepair.value = params.get("repair") || "";
+        el.fleetOperational.value = params.get("operational_state") || "";
+        el.fleetTags.value = params.getAll("tags").join(", ");
+        el.fleetProblems.checked = params.get("problems") === "1";
+        const requestedLimit = Number(params.get("limit"));
+        state.limit = limits.has(requestedLimit) ? requestedLimit : 100;
+        state.offset = Math.max(0, Number.parseInt(params.get("offset") || "0", 10) || 0);
+        el.fleetLimit.value = String(state.limit);
+        if (canViewLocations) {
+            state.siteId = params.get("site_id") || "";
+            state.roomId = params.get("room_id") || "";
+            syncLocationOptions(state.siteId, state.roomId);
+        }
+    }
+
+    function requestParams() {
+        const params = new URLSearchParams();
+        const values = {
+            query: el.fleetQuery.value.trim(),
+            lifecycle_status: el.fleetLifecycle.value,
+            model: el.fleetModel.value.trim(),
+            runtime_status: el.fleetRuntime.value,
+            repair: el.fleetRepair.value,
+            operational_state: el.fleetOperational.value,
+            problems: el.fleetProblems.checked ? "1" : "",
+            site_id: canViewLocations ? state.siteId : "",
+            room_id: canViewLocations ? state.roomId : "",
+            limit: String(state.limit), offset: String(state.offset)
+        };
+        for (const pair of Object.entries(values)) {
+            if (pair[1]) params.set(pair[0], pair[1]);
+        }
+        for (const tag of el.fleetTags.value.split(",")) {
+            const clean = tag.trim();
+            if (clean) params.append("tags", clean);
+        }
+        return params;
+    }
+
+    function setUrl(mode) {
+        const params = requestParams();
+        window.history[mode === "push" ? "pushState" : "replaceState"](
+            {}, "", "/assets/miners?" + params.toString()
+        );
+    }
+
+    async function load() {
+        showState("loading");
+        const controller = new AbortController();
+        const timer = window.setTimeout(function () { controller.abort(); }, 15000);
+        try {
+            const response = await fetch("/api/inventory/miners?" + requestParams().toString(), {
+                credentials: "same-origin", headers: { Accept: "application/json" },
+                signal: controller.signal
+            });
+            if (response.status === 401) {
+                window.location.replace("/login?next=" + encodeURIComponent(
+                    window.location.pathname + window.location.search
+                ));
+                return;
+            }
+            if (response.status === 403) {
+                const denied = new Error("Your account cannot view this fleet information.");
+                denied.permissionDenied = true;
+                throw denied;
+            }
+            if (!response.ok) throw new Error("The fleet service returned " + response.status + ".");
+            const envelope = await response.json();
+            if (!envelope || !Array.isArray(envelope.data) || !envelope.meta) {
+                throw new Error("MinerOps returned an incomplete fleet response.");
+            }
+            state.returned = envelope.data.length;
+            state.locationOptions = envelope.meta.location_options || null;
+            const selectedSite = canViewLocations ? state.siteId : "";
+            const selectedRoom = canViewLocations ? state.roomId : "";
+            syncLocationOptions(selectedSite, selectedRoom);
+            el.fleetRows.replaceChildren();
+            for (const miner of envelope.data) el.fleetRows.appendChild(renderRow(miner));
+            if (!envelope.data.length) {
+                el.fleetPrevious.disabled = state.offset === 0;
+                el.fleetNext.disabled = true;
+                showState("empty", state.offset
+                    ? "No miners are present on this page. Return to the previous page."
+                    : "No authorized miners match the current filters.");
+                return;
+            }
+            el.fleetPrevious.disabled = state.offset === 0;
+            el.fleetNext.disabled = state.returned < state.limit;
+            const first = state.offset + 1;
+            const last = state.offset + state.returned;
+            el.fleetResultSummary.textContent = "Showing miners " + first + "-" + last +
+                ". Total fleet size is not calculated.";
+            el.fleetFreshness.textContent = state.returned + " miners on this page";
+            showState("ready");
+        } catch (error) {
+            showState(error.permissionDenied ? "denied" : "error",
+                error && error.name === "AbortError"
+                    ? "MinerOps took too long to respond. Retry in a moment."
+                    : display(error && error.message, "The fleet could not be loaded."));
+        } finally {
+            window.clearTimeout(timer);
+        }
+    }
+
+    el.fleetFilters.addEventListener("submit", function (event) {
+        event.preventDefault();
+        if (canViewLocations) {
+            state.siteId = el.fleetSite.value; state.roomId = el.fleetRoom.value;
+        }
+        state.offset = 0; setUrl("push"); load();
+    });
+    el.fleetReset.addEventListener("click", function () {
+        el.fleetFilters.reset(); state.offset = 0; state.limit = 100;
+        state.siteId = ""; state.roomId = "";
+        syncLocationOptions("", ""); setUrl("push"); load();
+    });
+    el.fleetPrevious.addEventListener("click", function () {
+        state.offset = Math.max(0, state.offset - state.limit); setUrl("push"); load();
+    });
+    el.fleetNext.addEventListener("click", function () {
+        state.offset += state.limit; setUrl("push"); load();
+    });
+    el.fleetLimit.addEventListener("change", function () {
+        state.limit = Number(el.fleetLimit.value); state.offset = 0; setUrl("push"); load();
+    });
+    if (canViewLocations) {
+        el.fleetSite.addEventListener("change", function () {
+            state.siteId = el.fleetSite.value; state.roomId = "";
+            syncLocationOptions(state.siteId, "");
+        });
+        el.fleetRoom.addEventListener("change", function () {
+            state.roomId = el.fleetRoom.value;
+        });
+    }
+    window.addEventListener("popstate", function () { readUrl(); load(); });
+
+    readUrl();
+    load();
+}());

backend/app/frontend/static/mine-map.js

@@ -0,0 +1,784 @@
+(function () {
+    "use strict";
+
+    if (document.body.dataset.view !== "map") return;
+
+    const ids = [
+        "mapSite", "mapRoom", "mapLayer", "mapSearch", "mapLifecycle",
+        "mapModel", "mapRepair", "mapStatus", "mapClearFilters",
+        "mapProblemsOnly",
+        "mapFilterCount", "mapScope", "mapSummary", "mapFreshness",
+        "mapCriticalState", "mapCriticalTitle", "mapCriticalDetail",
+        "mapRetry", "mapLoading", "mapWorkspace", "mapLegend", "mapNotice",
+        "mapPermissionNote", "mapViewport", "mapLegacySection",
+        "mapLegacyPositions", "mapUnplacedSection", "mapUnplaced",
+        "mapInspector", "mapInspectorTitle", "mapInspectorStatus",
+        "mapInspectorDetails", "mapInspectorClose", "mapOpenMiner"
+    ];
+    const el = {};
+    for (const id of ids) el[id] = document.getElementById(id);
+
+    const state = {
+        data: null,
+        siteId: "",
+        roomId: "",
+        layer: "status",
+        query: "",
+        lifecycle: "",
+        model: "",
+        repair: "",
+        status: "",
+        problemsOnly: false,
+        minerId: "",
+        minerDetailsIncluded: false
+    };
+
+    function create(tag, className, text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text !== undefined) node.textContent = text;
+        return node;
+    }
+
+    function display(value, fallback) {
+        if (value === null || value === undefined || String(value).trim() === "") {
+            return fallback || "Unavailable";
+        }
+        return String(value);
+    }
+
+    function shelfLabel(value) {
+        const label = display(value, "Unlabelled shelf");
+        return /^shelf\b/i.test(label) ? label : "Shelf " + label;
+    }
+
+    function words(value) {
+        return display(value, "Unknown").replaceAll("_", " ").toLowerCase();
+    }
+
+    function dateTime(value) {
+        if (!value) return "Unavailable";
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.valueOf()) ? "Unavailable" : parsed.toLocaleString();
+    }
+
+    function metric(value, suffix) {
+        return typeof value === "number" && Number.isFinite(value)
+            ? value + suffix : "Unavailable";
+    }
+
+    function age(value) {
+        if (!value) return "Never observed";
+        const time = new Date(value).valueOf();
+        if (Number.isNaN(time)) return "Observation time unavailable";
+        const seconds = Math.max(0, Math.floor((Date.now() - time) / 1000));
+        if (seconds < 60) return seconds + "s ago";
+        if (seconds < 3600) return Math.floor(seconds / 60) + "m ago";
+        if (seconds < 86400) return Math.floor(seconds / 3600) + "h ago";
+        return Math.floor(seconds / 86400) + "d ago";
+    }
+
+    const PROBLEM_KEYS = new Set([
+        "offline", "unknown", "unstable", "repair", "conflict", "blocked",
+        "expected"
+    ]);
+
+    const MEASUREMENT_LAYERS = {
+        temperature: { field: "chip_temp_max_c", suffix: " C max" },
+        hashrate: { field: "hashrate_ths", suffix: " TH/s" },
+        power: { field: "power_w", suffix: " W" }
+    };
+
+    function operational(position) {
+        const kind = words(position.position_kind);
+        const status = words(position.position_status);
+        if (position.conflict_reason || status === "conflict") {
+            return { key: "conflict", label: "Location conflict", mark: "Conflict" };
+        }
+        if (kind === "blocked" || status === "blocked") {
+            return { key: "blocked", label: "Blocked position", mark: "Blocked" };
+        }
+        if (kind === "switch" || status === "switch") {
+            return { key: "switch", label: "Switch / equipment", mark: "Equipment" };
+        }
+        if (!position.occupied) {
+            if (position.expected_mac) {
+                return { key: "expected", label: "Expected miner not resolved", mark: "Expected" };
+            }
+            if (kind === "miner slot" && status === "available") {
+                return { key: "empty", label: "Empty position", mark: "Empty" };
+            }
+            return { key: "unknown", label: "Unknown position state", mark: "Unknown" };
+        }
+        if (!state.minerDetailsIncluded) {
+            return { key: "restricted", label: "Occupied; miner details restricted", mark: "Restricted" };
+        }
+        if (position.active_repair || position.lifecycle_status === "in_repair") {
+            return { key: "repair", label: "In repair", mark: "Repair" };
+        }
+        if (position.lifecycle_status === "retired" || position.asset_state === "decommissioned") {
+            return { key: "retired", label: "Retired / decommissioned", mark: "Retired" };
+        }
+        if (position.lifecycle_status === "spare") {
+            return { key: "spare", label: "Spare inventory", mark: "Spare" };
+        }
+        const runtime = words(position.miner_status);
+        if (runtime === "offline") {
+            return { key: "offline", label: "Offline", mark: "Offline" };
+        }
+        if (position.hash_stable === false) {
+            return { key: "unstable", label: "Hash unstable", mark: "Unstable" };
+        }
+        if (runtime === "online") {
+            return { key: "online", label: "Online", mark: "Online" };
+        }
+        return { key: "unknown", label: "Operational state unknown", mark: "Unknown" };
+    }
+
+    function isProblem(position) {
+        return PROBLEM_KEYS.has(operational(position).key);
+    }
+
+    function measurementScale(positions) {
+        const config = MEASUREMENT_LAYERS[state.layer];
+        if (!config) return null;
+        const values = positions.filter(function (position) {
+            return position.occupied && matches(position) &&
+                (!state.problemsOnly || isProblem(position));
+        }).map(function (position) {
+            return position[config.field];
+        }).filter(function (value) {
+            return typeof value === "number" && Number.isFinite(value);
+        });
+        if (!values.length) return { config: config, min: null, max: null };
+        let min = values[0];
+        let max = values[0];
+        for (const value of values.slice(1)) {
+            min = Math.min(min, value);
+            max = Math.max(max, value);
+        }
+        return {
+            config: config,
+            min: min,
+            max: max
+        };
+    }
+
+    function relativePercent(value, scale) {
+        if (!scale || scale.min === null || scale.max === null ||
+            typeof value !== "number" || !Number.isFinite(value)) return null;
+        if (scale.min === scale.max) return 50;
+        return Math.max(0, Math.min(
+            100,
+            ((value - scale.min) / (scale.max - scale.min)) * 100
+        ));
+    }
+
+    function layerValue(position, condition) {
+        if (!position.occupied) return condition.label;
+        if (!state.minerDetailsIncluded) return condition.label;
+        if (state.layer === "temperature") {
+            return metric(position.chip_temp_max_c, " C max");
+        }
+        if (state.layer === "hashrate") {
+            return metric(position.hashrate_ths, " TH/s");
+        }
+        if (state.layer === "power") {
+            return metric(position.power_w, " W");
+        }
+        if (state.layer === "repair") {
+            if (position.active_repair) return words(position.active_repair.status);
+            if (position.lifecycle_status === "in_repair") return "In-repair lifecycle";
+            if (position.asset_state === "repair") return "Legacy repair location";
+            return "No active repair";
+        }
+        return condition.label;
+    }
+
+    function identity(position) {
+        if (!state.minerDetailsIncluded) return "Miner details restricted";
+        return display(position.asset_id, display(position.current_mac, "Unidentified miner"));
+    }
+
+    function matches(position) {
+        if (!position.occupied) return true;
+        if (!state.minerDetailsIncluded) return true;
+        const condition = operational(position);
+        const haystack = [position.asset_id, position.miner_sn, position.current_mac,
+            position.current_ip, position.model].map(function (value) {
+                return display(value, "").toLowerCase();
+            }).join(" ");
+        return (!state.query || haystack.includes(state.query.toLowerCase())) &&
+            (!state.lifecycle || position.lifecycle_status === state.lifecycle) &&
+            (!state.model || position.model === state.model) &&
+            (!state.status || condition.key === state.status) &&
+            (!state.repair ||
+                (state.repair === "active" && Boolean(position.active_repair)) ||
+                (state.repair === "none" && !position.active_repair) ||
+                (state.repair === "legacy" && position.asset_state === "repair" && !position.active_repair));
+    }
+
+    function option(value, label) {
+        const node = create("option", "", label);
+        node.value = value;
+        return node;
+    }
+
+    function unique(values) {
+        return Array.from(new Set(values.filter(Boolean))).sort(function (a, b) {
+            return String(a).localeCompare(String(b), undefined, { numeric: true });
+        });
+    }
+
+    function syncSelectors() {
+        const sites = state.data.sites;
+        if (!sites.some(function (site) { return String(site.id) === state.siteId; })) {
+            state.siteId = sites.length ? String(sites[0].id) : "";
+        }
+        el.mapSite.replaceChildren();
+        for (const site of sites) el.mapSite.appendChild(option(String(site.id), site.name));
+        el.mapSite.value = state.siteId;
+
+        const rooms = state.data.rooms.filter(function (room) {
+            return String(room.site_id) === state.siteId;
+        });
+        if (!rooms.some(function (room) { return String(room.id) === state.roomId; })) {
+            state.roomId = rooms.length ? String(rooms[0].id) : "";
+        }
+        el.mapRoom.replaceChildren();
+        if (!rooms.length) el.mapRoom.appendChild(option("", "No rooms at this site"));
+        for (const room of rooms) {
+            el.mapRoom.appendChild(option(String(room.id), room.name));
+        }
+        el.mapRoom.value = state.roomId;
+        el.mapRoom.disabled = !rooms.length;
+
+        const site = sites.find(function (item) { return String(item.id) === state.siteId; });
+        const room = rooms.find(function (item) { return String(item.id) === state.roomId; });
+        el.mapScope.textContent = site && room
+            ? site.name + " / " + room.name
+            : site ? site.name + " / No configured rooms" : "No configured sites";
+    }
+
+    function syncPermissionControls() {
+        const allowed = state.minerDetailsIncluded;
+        if (!allowed) {
+            state.layer = "status";
+            state.query = state.lifecycle = state.model = state.repair = state.status = "";
+            state.problemsOnly = false;
+            el.mapSearch.value = "";
+            el.mapRepair.value = "";
+            el.mapProblemsOnly.checked = false;
+        }
+        for (const item of el.mapLayer.options) {
+            item.disabled = !allowed && item.value !== "status";
+        }
+        el.mapLayer.value = state.layer;
+        el.mapSearch.disabled = !allowed;
+        el.mapLifecycle.disabled = !allowed;
+        el.mapModel.disabled = !allowed;
+        el.mapRepair.disabled = !allowed;
+        el.mapStatus.disabled = !allowed;
+        el.mapClearFilters.disabled = !allowed;
+        el.mapProblemsOnly.disabled = !allowed;
+        el.mapSearch.closest(".field").hidden = !allowed;
+        document.getElementById("mapFilters").hidden = !allowed;
+        el.mapPermissionNote.hidden = allowed;
+    }
+
+    function syncFilterOptions() {
+        const positions = state.data.positions.filter(function (position) {
+            return String(position.room_id || "") === state.roomId && position.occupied;
+        });
+        const lifecycle = unique(positions.map(function (item) { return item.lifecycle_status; }));
+        const models = unique(positions.map(function (item) { return item.model; }));
+        const statuses = unique(positions.map(function (item) { return operational(item).key; }));
+        const selectedLifecycle = state.lifecycle;
+        const selectedModel = state.model;
+        const selectedStatus = state.status;
+        el.mapLifecycle.replaceChildren(option("", "All lifecycle states"));
+        lifecycle.forEach(function (value) { el.mapLifecycle.appendChild(option(value, words(value))); });
+        el.mapModel.replaceChildren(option("", "All models"));
+        models.forEach(function (value) { el.mapModel.appendChild(option(value, value)); });
+        el.mapStatus.replaceChildren(option("", "All operational states"));
+        statuses.forEach(function (value) { el.mapStatus.appendChild(option(value, words(value))); });
+        if (lifecycle.includes(selectedLifecycle)) el.mapLifecycle.value = selectedLifecycle;
+        else state.lifecycle = "";
+        if (models.includes(selectedModel)) el.mapModel.value = selectedModel;
+        else state.model = "";
+        if (statuses.includes(selectedStatus)) el.mapStatus.value = selectedStatus;
+        else state.status = "";
+    }
+
+    function stateUrl() {
+        const params = new URLSearchParams();
+        const values = {
+            site_id: state.siteId, room_id: state.roomId,
+            layer: state.layer === "status" ? "" : state.layer,
+            q: state.query, lifecycle: state.lifecycle, model: state.model,
+            repair: state.repair, status: state.status,
+            problems: state.problemsOnly ? "1" : "", miner_id: state.minerId
+        };
+        for (const pair of Object.entries(values)) {
+            if (pair[1]) params.set(pair[0], pair[1]);
+        }
+        return window.location.pathname +
+            (params.size ? "?" + params.toString() : "");
+    }
+
+    function setUrl(mode) {
+        window.history[mode === "push" ? "pushState" : "replaceState"](
+            {}, "", stateUrl()
+        );
+    }
+
+    function readUrl() {
+        const params = new URLSearchParams(window.location.search);
+        state.siteId = params.get("site_id") || "";
+        state.roomId = params.get("room_id") || "";
+        state.layer = ["status", "temperature", "hashrate", "power", "repair"]
+            .includes(params.get("layer")) ? params.get("layer") : "status";
+        state.query = (params.get("q") || "").slice(0, 160);
+        state.lifecycle = params.get("lifecycle") || "";
+        state.model = params.get("model") || "";
+        state.repair = ["active", "none", "legacy"].includes(params.get("repair"))
+            ? params.get("repair") : "";
+        state.status = params.get("status") || "";
+        state.problemsOnly = params.get("problems") === "1";
+        state.minerId = params.get("miner_id") || "";
+        syncPermissionControls();
+        el.mapLayer.value = state.layer;
+        el.mapSearch.value = state.query;
+        el.mapRepair.value = state.repair;
+        el.mapProblemsOnly.checked = state.problemsOnly;
+    }
+
+    function appendLegendItem(key, label, mark) {
+        const item = create("span", "legend-item");
+        const marker = create("span", "legend-marker", mark);
+        marker.dataset.status = key;
+        marker.setAttribute("aria-hidden", "true");
+        item.append(marker, document.createTextNode(label));
+        el.mapLegend.appendChild(item);
+    }
+
+    function legend(scale) {
+        const entries = !state.minerDetailsIncluded
+            ? [["restricted", "Miner details restricted", "Restricted"],
+                ["empty", "Empty position", "Empty"],
+                ["conflict", "Location conflict", "Conflict"],
+                ["blocked", "Blocked position", "Blocked"],
+                ["switch", "Switch or equipment", "Equipment"]]
+            : state.layer === "status"
+            ? [["online", "Online", "Online"], ["offline", "Offline", "Offline"],
+                ["unstable", "Hash unstable", "Unstable"],
+                ["repair", "In repair", "Repair"], ["spare", "Spare", "Spare"],
+                ["retired", "Retired", "Retired"],
+                ["unknown", "Operational state unknown", "Unknown"],
+                ["empty", "Empty position", "Empty"],
+                ["conflict", "Location conflict", "Conflict"]]
+            : [["online", "Online marker", "Online"],
+                ["offline", "Offline marker", "Offline"],
+                ["unstable", "Hash unstable marker", "Unstable"],
+                ["repair", "In-repair marker", "Repair"],
+                ["unknown", "Unknown-state marker", "Unknown"],
+                ["empty", "Empty position", "Empty"]];
+        el.mapLegend.replaceChildren();
+        el.mapLegend.appendChild(create(
+            "strong", "legend-title", el.mapLayer.options[el.mapLayer.selectedIndex].text
+        ));
+        if (scale) {
+            const range = create("span", "relative-scale");
+            if (scale.min === null || scale.max === null) {
+                range.textContent = "Relative range unavailable: no valid displayed readings";
+            } else {
+                const low = metric(scale.min, scale.config.suffix);
+                const high = metric(scale.max, scale.config.suffix);
+                range.setAttribute(
+                    "aria-label",
+                    "Relative range across emphasized miners from " + low + " to " + high
+                );
+                range.append(
+                    create("span", "relative-scale-label", "Relative range (emphasized)"),
+                    create("span", "relative-scale-value", low),
+                    create("span", "relative-scale-track"),
+                    create("span", "relative-scale-value", high)
+                );
+            }
+            el.mapLegend.appendChild(range);
+        }
+        for (const entry of entries) {
+            appendLegendItem(entry[0], entry[1], entry[2]);
+        }
+    }
+
+    function positionTile(position, scale) {
+        const condition = operational(position);
+        const tile = create(position.occupied && position.miner_id ? "button" : "div", "map-position");
+        tile.dataset.status = condition.key;
+        tile.dataset.positionId = position.location_position_id;
+        tile.dataset.occupied = String(position.occupied);
+        tile.dataset.problem = String(isProblem(position));
+        if (position.miner_id) tile.dataset.minerId = position.miner_id;
+        if (position.occupied && !matches(position)) tile.dataset.filtered = "true";
+        if (state.problemsOnly && position.occupied && !isProblem(position)) {
+            tile.dataset.problemsMuted = "true";
+        }
+        if (String(position.miner_id) === state.minerId) tile.dataset.selected = "true";
+        const scaleEligible = position.occupied && matches(position) &&
+            (!state.problemsOnly || isProblem(position));
+        const relative = scale && scaleEligible
+            ? relativePercent(position[scale.config.field], scale) : null;
+        if (relative !== null) {
+            tile.dataset.measurement = "true";
+            tile.style.setProperty("--relative-percent", relative.toFixed(2) + "%");
+        }
+        if (tile.tagName === "BUTTON") {
+            tile.type = "button";
+            tile.tabIndex = -1;
+            tile.setAttribute("aria-pressed", String(String(position.miner_id) === state.minerId));
+            tile.setAttribute("aria-label", display(position.position_label, "Position " + position.position_index) +
+                ", " + identity(position) + ", " + condition.label + ", " + age(position.observed_at));
+        } else {
+            tile.setAttribute("role", "group");
+            tile.setAttribute("aria-label", display(position.position_label, "Position " + position.position_index) +
+                ", " + condition.label);
+        }
+        const head = create("span", "position-head");
+        const marker = create("span", "status-marker", condition.mark);
+        marker.setAttribute("aria-hidden", "true");
+        head.append(create("strong", "position-label", display(position.position_label, "Position " + position.position_index)),
+            marker);
+        const name = create("span", "position-miner", position.occupied ? identity(position) : condition.label);
+        tile.append(head, name);
+        if (position.occupied) {
+            tile.append(
+                create("span", "position-value", layerValue(position, condition)),
+                create("span", "position-freshness", state.minerDetailsIncluded
+                    ? age(position.observed_at) : "Miner details restricted")
+            );
+        }
+        return tile;
+    }
+
+    function renderMap() {
+        syncSelectors();
+        const positions = state.data.positions.filter(function (position) {
+            return String(position.room_id || "") === state.roomId;
+        });
+        if (state.minerId && !state.data.positions.some(function (position) {
+            const visible = String(position.room_id || "") === state.roomId || !position.room_id;
+            return visible && position.miner_id && String(position.miner_id) === state.minerId;
+        })) state.minerId = "";
+        syncPermissionControls();
+        syncFilterOptions();
+        const scale = measurementScale(positions);
+        legend(scale);
+        el.mapViewport.replaceChildren();
+        if (!state.data.sites.length) {
+            el.mapNotice.hidden = false;
+            el.mapNotice.textContent = "No sites are configured. Use location management to create the physical hierarchy.";
+        } else if (!state.roomId) {
+            el.mapNotice.hidden = false;
+            el.mapNotice.textContent = "This site has no configured rooms.";
+        } else if (!positions.length) {
+            el.mapNotice.hidden = false;
+            el.mapNotice.textContent = "No positions are configured for this room.";
+        } else {
+            el.mapNotice.hidden = true;
+        }
+        const racks = new Map();
+        for (const position of positions) {
+            const rack = display(position.rack_name, "Unlabelled rack");
+            const shelf = display(position.shelf_name, "Unlabelled shelf");
+            if (!racks.has(rack)) racks.set(rack, new Map());
+            if (!racks.get(rack).has(shelf)) racks.get(rack).set(shelf, []);
+            racks.get(rack).get(shelf).push(position);
+        }
+        const fragment = document.createDocumentFragment();
+        for (const rackEntry of racks) {
+            const rack = create("section", "map-rack");
+            rack.setAttribute("aria-label", "Rack " + rackEntry[0]);
+            rack.appendChild(create("h2", "rack-title", "Rack " + rackEntry[0]));
+            for (const shelfEntry of rackEntry[1]) {
+                const shelf = create("section", "map-shelf");
+                shelf.setAttribute("aria-label", shelfLabel(shelfEntry[0]));
+                shelf.appendChild(create("h3", "shelf-title", shelfLabel(shelfEntry[0])));
+                const grid = create("div", "position-grid");
+                for (const position of shelfEntry[1]) {
+                    grid.appendChild(positionTile(position, scale));
+                }
+                shelf.appendChild(grid);
+                rack.appendChild(shelf);
+            }
+            fragment.appendChild(rack);
+        }
+        el.mapViewport.appendChild(fragment);
+        renderSummary(positions);
+        renderLegacyPositions();
+        renderUnplaced();
+        renderInspector();
+        syncTileTabStops();
+        const count = [state.query, state.lifecycle, state.model, state.repair,
+            state.status, state.problemsOnly].filter(Boolean).length;
+        el.mapFilterCount.textContent = count ? "(" + count + " active)" : "";
+        el.mapFreshness.textContent = "Map generated " + dateTime(state.meta.generated_at) +
+            (state.minerDetailsIncluded ? ". Telemetry age is shown per miner."
+                : ". Miner details are restricted for this account.");
+    }
+
+    function renderSummary(positions) {
+        const facts = { occupied: 0, empty: 0, conflict: 0, offline: 0,
+            repair: 0, unknown: 0, restricted: 0, problems: 0 };
+        for (const position of positions) {
+            const condition = operational(position);
+            if (position.occupied) facts.occupied += 1;
+            if (condition.key in facts) facts[condition.key] += 1;
+            if (isProblem(position)) facts.problems += 1;
+        }
+        el.mapSummary.replaceChildren();
+        const pairs = [["Positions", positions.length], ["Occupied", facts.occupied],
+            ["Empty", facts.empty], ["Conflicts", facts.conflict]];
+        if (state.minerDetailsIncluded) pairs.splice(3, 0,
+            ["Problems", facts.problems], ["Offline", facts.offline],
+            ["In repair", facts.repair], ["Unknown", facts.unknown]);
+        else pairs.splice(3, 0, ["Restricted", facts.restricted]);
+        for (const pair of pairs) {
+            const item = create("span", "summary-fact");
+            item.append(create("strong", "", String(pair[1])), document.createTextNode(pair[0]));
+            el.mapSummary.appendChild(item);
+        }
+    }
+
+    function renderLegacyPositions() {
+        const positions = state.data.positions.filter(function (position) {
+            return !position.room_id;
+        });
+        el.mapLegacySection.hidden = !positions.length;
+        el.mapLegacyPositions.replaceChildren();
+        for (const position of positions) {
+            const item = create("article", "legacy-position-entry");
+            item.append(create("strong", "", display(position.position_label,
+                "Position " + position.position_index)),
+            create("span", "legacy-position-path", "Unscoped / Room label " +
+                display(position.room_name, "Unavailable") + " / Rack " +
+                display(position.rack_name, "Unavailable") + " / Shelf " +
+                display(position.shelf_name, "Unavailable")),
+            positionTile(position));
+            el.mapLegacyPositions.appendChild(item);
+        }
+    }
+
+    function renderUnplaced() {
+        const miners = state.data.virtual_miners.filter(function (miner) {
+            return (!state.siteId || String(miner.site_id || "") === state.siteId) &&
+                (!state.roomId || !miner.room_id || String(miner.room_id) === state.roomId);
+        });
+        el.mapUnplacedSection.hidden = !miners.length;
+        el.mapUnplaced.replaceChildren();
+        for (const miner of miners) {
+            const item = create("div", "unplaced-miner");
+            item.append(create("strong", "", display(miner.asset_id, display(miner.current_mac, "Unidentified miner"))),
+                create("span", "", words(miner.asset_state) + " / " + words(miner.lifecycle_status)),
+                create("span", "", miner.active_repair
+                    ? "Active repair: " + words(miner.active_repair.status)
+                    : "No active repair record"));
+            el.mapUnplaced.appendChild(item);
+        }
+    }
+
+    function detailRow(term, value) {
+        el.mapInspectorDetails.append(create("dt", "", term), create("dd", "", display(value)));
+    }
+
+    function renderInspector() {
+        const position = state.data.positions.find(function (item) {
+            return item.miner_id && String(item.miner_id) === state.minerId;
+        });
+        if (!position) {
+            el.mapInspector.hidden = true;
+            return;
+        }
+        const condition = operational(position);
+        el.mapInspector.hidden = false;
+        el.mapInspectorTitle.textContent = identity(position);
+        el.mapInspectorStatus.textContent = condition.label + " / " + age(position.observed_at);
+        el.mapInspectorStatus.dataset.status = condition.key;
+        el.mapInspectorDetails.replaceChildren();
+        detailRow("Asset ID", position.asset_id);
+        detailRow("Model", position.model || position.miner_type);
+        detailRow("Serial", position.miner_sn);
+        detailRow("Current MAC", position.current_mac);
+        detailRow("Current IP", position.current_ip);
+        const location = position.room_id
+            ? [position.site_name, position.room_name, "Rack " + position.rack_name,
+                shelfLabel(position.shelf_name), display(position.position_label,
+                    "Position " + position.position_index)].join(" / ")
+            : ["Unscoped", "Room label " + display(position.room_name),
+                "Rack " + display(position.rack_name), shelfLabel(position.shelf_name),
+                display(position.position_label, "Position " + position.position_index)].join(" / ");
+        detailRow("Location", location);
+        detailRow("Lifecycle", words(position.lifecycle_status));
+        detailRow("Runtime", words(position.miner_status));
+        detailRow("Repair", position.active_repair
+            ? words(position.active_repair.status) + " / " + words(position.active_repair.reason)
+            : position.asset_state === "repair" ? "Legacy repair location state" : "No active repair");
+        detailRow("Hashrate", metric(position.hashrate_ths, " TH/s"));
+        detailRow("Power", metric(position.power_w, " W"));
+        detailRow("Chip temperature", metric(position.chip_temp_max_c, " C max"));
+        detailRow("Observed", dateTime(position.observed_at));
+        const returnTo = stateUrl();
+        el.mapOpenMiner.href = "/miners/" + encodeURIComponent(position.miner_id) +
+            "/detail?return_to=" + encodeURIComponent(returnTo);
+    }
+
+    function mapTiles() {
+        return Array.from(el.mapWorkspace.querySelectorAll("button.map-position[data-miner-id]"));
+    }
+
+    function syncTileTabStops() {
+        const tiles = mapTiles();
+        const current = tiles.find(function (tile) {
+            return tile.dataset.minerId === state.minerId;
+        });
+        for (const tile of tiles) tile.tabIndex = tile === current ? 0 : -1;
+        if (!current && tiles.length) tiles[0].tabIndex = 0;
+    }
+
+    function syncSelection() {
+        for (const tile of mapTiles()) {
+            const selected = tile.dataset.minerId === state.minerId;
+            tile.dataset.selected = String(selected);
+            tile.setAttribute("aria-pressed", String(selected));
+        }
+        renderInspector();
+        syncTileTabStops();
+    }
+
+    function bind() {
+        const controls = [el.mapLayer, el.mapSearch, el.mapLifecycle, el.mapModel, el.mapRepair, el.mapStatus];
+        let renderFrame = null;
+        function scheduleRender() {
+            if (renderFrame !== null) window.cancelAnimationFrame(renderFrame);
+            renderFrame = window.requestAnimationFrame(function () {
+                renderFrame = null;
+                renderMap();
+                setUrl("replace");
+            });
+        }
+        el.mapSite.addEventListener("change", function () {
+            state.siteId = el.mapSite.value; state.roomId = ""; state.minerId = "";
+            renderMap(); setUrl("push");
+        });
+        el.mapRoom.addEventListener("change", function () {
+            state.roomId = el.mapRoom.value; state.minerId = ""; renderMap(); setUrl("push");
+        });
+        for (const control of controls) {
+            control.addEventListener(control === el.mapSearch ? "input" : "change", function () {
+                state.layer = el.mapLayer.value; state.query = el.mapSearch.value.trim();
+                state.lifecycle = el.mapLifecycle.value; state.model = el.mapModel.value;
+                state.repair = el.mapRepair.value; state.status = el.mapStatus.value;
+                scheduleRender();
+            });
+        }
+        el.mapProblemsOnly.addEventListener("change", function () {
+            state.problemsOnly = el.mapProblemsOnly.checked;
+            scheduleRender();
+        });
+        el.mapClearFilters.addEventListener("click", function () {
+            state.query = state.lifecycle = state.model = state.repair = state.status = "";
+            state.problemsOnly = false;
+            el.mapSearch.value = ""; el.mapRepair.value = "";
+            el.mapProblemsOnly.checked = false;
+            renderMap(); setUrl("replace");
+        });
+        el.mapWorkspace.addEventListener("click", function (event) {
+            const tile = event.target.closest("button[data-miner-id]");
+            if (!tile || !el.mapWorkspace.contains(tile)) return;
+            state.minerId = tile.dataset.minerId;
+            syncSelection(); setUrl("push");
+            el.mapInspectorClose.focus();
+        });
+        el.mapWorkspace.addEventListener("keydown", function (event) {
+            if (!["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.key)) return;
+            const tile = event.target.closest("button.map-position[data-miner-id]");
+            if (!tile) return;
+            const tiles = mapTiles();
+            const current = tiles.indexOf(tile);
+            const delta = ["ArrowLeft", "ArrowUp"].includes(event.key) ? -1 : 1;
+            const next = tiles[(current + delta + tiles.length) % tiles.length];
+            event.preventDefault();
+            for (const item of tiles) item.tabIndex = item === next ? 0 : -1;
+            next.focus();
+        });
+        el.mapInspectorClose.addEventListener("click", function () {
+            const restoreId = state.minerId; state.minerId = "";
+            syncSelection(); setUrl("push");
+            const restore = mapTiles().find(function (tile) {
+                return tile.dataset.minerId === restoreId;
+            });
+            if (restore) {
+                for (const tile of mapTiles()) tile.tabIndex = -1;
+                restore.tabIndex = 0;
+                restore.focus();
+            }
+        });
+        el.mapRetry.addEventListener("click", load);
+        window.addEventListener("popstate", function () {
+            readUrl(); renderMap(); setUrl("replace");
+        });
+    }
+
+    function validate(envelope) {
+        return envelope && envelope.data && envelope.meta &&
+            Array.isArray(envelope.data.sites) && Array.isArray(envelope.data.rooms) &&
+            Array.isArray(envelope.data.positions) && Array.isArray(envelope.data.virtual_miners) &&
+            envelope.data.positions.every(function (item) {
+                return item && typeof item.location_position_id === "string" &&
+                    typeof item.position_index === "number";
+            });
+    }
+
+    async function load() {
+        el.mapLoading.hidden = false;
+        el.mapCriticalState.hidden = true;
+        el.mapWorkspace.hidden = true;
+        const controller = new AbortController();
+        const timer = window.setTimeout(function () { controller.abort(); }, 15000);
+        try {
+            const response = await fetch("/api/location/map", {
+                credentials: "same-origin", headers: { Accept: "application/json" },
+                signal: controller.signal
+            });
+            if (response.status === 401) {
+                window.location.replace("/login?next=" + encodeURIComponent(window.location.pathname + window.location.search));
+                return;
+            }
+            if (response.status === 403) {
+                el.mapCriticalTitle.textContent = "Map access unavailable";
+                el.mapCriticalDetail.textContent = "Your account cannot view location data.";
+                el.mapCriticalState.hidden = false;
+                return;
+            }
+            if (!response.ok) throw new Error("The map service returned " + response.status + ".");
+            const envelope = await response.json();
+            if (!validate(envelope)) throw new Error("The map response was incomplete.");
+            state.data = envelope.data; state.meta = envelope.meta;
+            state.minerDetailsIncluded = envelope.meta.miner_details_included === true;
+            readUrl(); syncSelectors();
+            el.mapWorkspace.hidden = false;
+            renderMap(); setUrl("replace");
+        } catch (error) {
+            el.mapCriticalTitle.textContent = "Map unavailable";
+            el.mapCriticalDetail.textContent = error && error.name === "AbortError"
+                ? "MinerOps took too long to respond. Retry in a moment."
+                : display(error && error.message, "The map could not be loaded.");
+            el.mapCriticalState.hidden = false;
+        } finally {
+            window.clearTimeout(timer); el.mapLoading.hidden = true;
+        }
+    }
+
+    bind();
+    load();
+}());

backend/app/frontend/static/miner-detail.js

@@ -0,0 +1,425 @@
+(function () {
+    "use strict";
+
+    if (document.body.dataset.view !== "miner_detail") return;
+
+    const minerId = document.body.dataset.minerId;
+    const returnTo = document.body.dataset.returnTo || "";
+    const el = {
+        loading: document.getElementById("minerDetailLoading"),
+        error: document.getElementById("minerDetailError"),
+        errorText: document.getElementById("minerDetailErrorText"),
+        content: document.getElementById("minerDetailContent"),
+        retry: document.getElementById("minerDetailRetry"),
+        refresh: document.getElementById("minerDetailRefresh"),
+        title: document.getElementById("minerIdentityTitle"),
+        model: document.getElementById("minerDetailModel"),
+        uuid: document.getElementById("minerDetailUuid"),
+        operational: document.getElementById("minerDetailOperational"),
+        lifecycle: document.getElementById("minerDetailLifecycle"),
+        locationSummary: document.getElementById("minerDetailLocationSummary"),
+        returnLink: document.getElementById("minerDetailReturn"),
+        mapLink: document.getElementById("minerDetailMap"),
+        trendsLink: document.getElementById("minerDetailTrends"),
+        repairsLink: document.getElementById("minerDetailRepairs"),
+        identity: document.getElementById("minerIdentityDetails"),
+        tags: document.getElementById("minerTags"),
+        telemetry: document.getElementById("minerTelemetryDetails"),
+        telemetryAge: document.getElementById("minerTelemetryAge"),
+        location: document.getElementById("minerLocationBody"),
+        repair: document.getElementById("minerRepairBody"),
+        episodes: document.getElementById("minerRepairEpisodes"),
+        identityHistory: document.getElementById("minerIdentityHistory"),
+        identityHistoryBody: document.getElementById("minerIdentityHistoryBody"),
+        observations: document.getElementById("minerObservations"),
+        observationsBody: document.getElementById("minerObservationsBody")
+    };
+
+    function create(tag, className, text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text !== undefined) node.textContent = text;
+        return node;
+    }
+
+    function display(value, fallback) {
+        if (value === null || value === undefined || value === "") {
+            return fallback === undefined ? "Unavailable" : fallback;
+        }
+        return String(value);
+    }
+
+    function words(value) {
+        const text = display(value, "unknown").replaceAll("_", " ").toLowerCase();
+        return text.charAt(0).toUpperCase() + text.slice(1);
+    }
+
+    function dateTime(value) {
+        if (!value) return "Unavailable";
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? "Unavailable" : parsed.toLocaleString();
+    }
+
+    function age(value) {
+        if (!value) return "No observation available";
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime())) return "Observation time unavailable";
+        const seconds = Math.max(0, Math.floor((Date.now() - parsed.getTime()) / 1000));
+        if (seconds < 60) return seconds + " seconds ago";
+        if (seconds < 3600) return Math.floor(seconds / 60) + " minutes ago";
+        if (seconds < 86400) return Math.floor(seconds / 3600) + " hours ago";
+        return Math.floor(seconds / 86400) + " days ago";
+    }
+
+    function metric(value, suffix) {
+        if (value === null || value === undefined || value === "") return "Unavailable";
+        const number = Number(value);
+        if (!Number.isFinite(number)) return "Unavailable";
+        return String(number) + suffix;
+    }
+
+    function addDefinition(list, label, value) {
+        const row = create("div");
+        row.append(create("dt", "", label), create("dd", "", display(value)));
+        list.appendChild(row);
+    }
+
+    function prefixed(value, prefix) {
+        const label = display(value, "");
+        if (!label) return "";
+        return new RegExp("^" + prefix + "\\b", "i").test(label)
+            ? label : prefix + " " + label;
+    }
+
+    function locationText(location) {
+        if (!location) return "Not mapped";
+        const parts = [location.site_name, location.room_name,
+            prefixed(location.rack_label, "Rack"),
+            prefixed(location.shelf_label, "Shelf"),
+            location.position_label || (location.position_index === null
+                ? "Position unavailable" : "Position " + location.position_index)];
+        return parts.filter(Boolean).join(" / ");
+    }
+
+    async function api(path) {
+        const response = await fetch(path, {
+            credentials: "same-origin",
+            headers: { Accept: "application/json" }
+        });
+        if (response.status === 401) {
+            window.location.assign("/login?next=" + encodeURIComponent(
+                window.location.pathname + window.location.search
+            ));
+            throw new Error("Login required");
+        }
+        let payload = null;
+        try { payload = await response.json(); } catch (_error) { payload = null; }
+        if (!response.ok) {
+            throw new Error(payload && payload.detail
+                ? String(payload.detail) : "Request failed (" + response.status + ")");
+        }
+        return payload ? payload.data : null;
+    }
+
+    function table(headers, rows) {
+        const wrap = create("div", "table-wrap compact-history-table");
+        const tableNode = create("table");
+        const head = create("thead");
+        const headRow = create("tr");
+        headers.forEach(function (header) { headRow.appendChild(create("th", "", header)); });
+        head.appendChild(headRow);
+        const body = create("tbody");
+        rows.forEach(function (values) {
+            const row = create("tr");
+            values.forEach(function (value) { row.appendChild(create("td", "", display(value))); });
+            body.appendChild(row);
+        });
+        tableNode.append(head, body);
+        wrap.appendChild(tableNode);
+        return wrap;
+    }
+
+    function renderIdentity(miner) {
+        const identity = miner.asset_id || miner.current_mac || "Miner " + miner.id.slice(0, 8);
+        el.title.textContent = identity;
+        el.model.textContent = display(miner.model, "Model unavailable");
+        el.uuid.textContent = "Miner UUID: " + miner.id;
+        const pageTitle = document.querySelector(".page-head h1");
+        if (pageTitle) pageTitle.textContent = identity;
+        document.title = identity + " | MinerOps";
+        el.identity.replaceChildren();
+        [
+            ["Asset ID", miner.asset_id], ["Model", miner.model],
+            ["Miner serial", miner.miner_sn], ["Control-board serial", miner.control_board_sn],
+            ["PSU serial", miner.psu_serial], ["Current MAC", miner.current_mac],
+            ["Current IP", miner.current_ip], ["Hostname", miner.hostname],
+            ["Firmware", miner.firmware_version], ["Created", dateTime(miner.created_at)],
+            ["First seen", dateTime(miner.first_seen_at)], ["Last seen", dateTime(miner.last_seen_at)]
+        ].forEach(function (item) { addDefinition(el.identity, item[0], item[1]); });
+        el.tags.replaceChildren();
+        (miner.tags || []).forEach(function (tag) {
+            el.tags.appendChild(create("span", "tag", tag.name));
+        });
+    }
+
+    function renderTelemetry(miner) {
+        el.telemetry.replaceChildren();
+        [
+            ["Runtime", words(miner.runtime_status)],
+            ["Observed", dateTime(miner.observed_at)],
+            ["Hashrate", metric(miner.hashrate_ths, " TH/s")],
+            ["Power", metric(miner.power_w, " W")],
+            ["Max chip temperature", metric(miner.chip_temp_max_c, " C")],
+            ["Hash stability", miner.hash_stable === null || miner.hash_stable === undefined
+                ? "Unavailable" : miner.hash_stable ? "Stable" : "Unstable"]
+        ].forEach(function (item) { addDefinition(el.telemetry, item[0], item[1]); });
+        el.telemetryAge.textContent = age(miner.observed_at);
+    }
+
+    function renderLocation(section, minerIdValue, canViewMap) {
+        el.location.replaceChildren();
+        if (section.restricted) {
+            el.location.appendChild(create("p", "permission-note", "Location information restricted."));
+            el.locationSummary.textContent = "Location restricted";
+            return;
+        }
+        if (!section.location) {
+            el.location.appendChild(create("p", "empty-copy", "Not mapped"));
+            el.locationSummary.textContent = "Not mapped";
+            return;
+        }
+        const location = section.location;
+        const list = create("dl", "definition-list");
+        [["Site", location.site_name], ["Room", location.room_name],
+            ["Rack", prefixed(location.rack_label, "Rack")],
+            ["Shelf", prefixed(location.shelf_label, "Shelf")],
+            ["Position", location.position_label || (location.position_index === null
+                ? null : "Position " + location.position_index)]
+        ].forEach(function (item) { addDefinition(list, item[0], item[1]); });
+        el.location.appendChild(list);
+        const summary = locationText(location);
+        el.locationSummary.textContent = summary;
+        if (canViewMap) {
+            const params = new URLSearchParams({ miner_id: minerIdValue });
+            params.set("site_id", location.site_id);
+            params.set("room_id", location.room_id);
+            el.mapLink.href = "/monitoring/map?" + params.toString();
+            el.mapLink.hidden = false;
+        }
+    }
+
+    function eventPayload(payload) {
+        const list = create("dl", "definition-list event-payload");
+        Object.entries(payload || {}).forEach(function (entry) {
+            const value = typeof entry[1] === "object"
+                ? JSON.stringify(entry[1]) : entry[1];
+            addDefinition(list, words(entry[0]), value);
+        });
+        return list;
+    }
+
+    function renderRepairDetails(target, timeline, parts, canReadComponents) {
+        target.replaceChildren();
+        const events = timeline && timeline.events ? timeline.events : [];
+        const heading = create("h4", "", "Timeline");
+        const timelineList = create("ol", "repair-timeline-list");
+        events.forEach(function (event) {
+            const item = create("li");
+            item.append(create("strong", "", words(event.event_type)),
+                create("span", "secondary", dateTime(event.occurred_at) + " / " +
+                    display(event.actor && event.actor.display_name, "Unknown actor")),
+                eventPayload(event.payload));
+            timelineList.appendChild(item);
+        });
+        if (!events.length) timelineList.appendChild(create("li", "empty-copy", "No timeline events recorded."));
+        target.append(heading, timelineList, create("h4", "", "Parts and components"));
+        const entries = parts && parts.entries ? parts.entries : [];
+        if (!entries.length) {
+            target.appendChild(create("p", "empty-copy", "No parts recorded for this repair."));
+            return;
+        }
+        const rows = entries.map(function (entry) {
+            let description = "Tracked component";
+            if (entry.consumable) {
+                description = entry.consumable.description + " / " +
+                    entry.consumable.quantity + " " + entry.consumable.unit;
+            } else if (entry.component_snapshot) {
+                const snapshot = entry.component_snapshot;
+                description = [words(snapshot.component_type), snapshot.asset_id,
+                    snapshot.manufacturer, snapshot.model, snapshot.manufacturer_serial]
+                    .filter(Boolean).join(" / ");
+                if (canReadComponents && entry.component_id) {
+                    description += " / Component UUID " + entry.component_id;
+                }
+            }
+            return [description, entry.notes, dateTime(entry.recorded_at),
+                entry.voided_at ? "Voided: " + display(entry.void_reason) : "Recorded"];
+        });
+        target.appendChild(table(["Part or component", "Notes", "Recorded", "State"], rows));
+    }
+
+    function repairEpisode(episode, canReadComponents) {
+        const details = create("details");
+        const summary = create("summary", "repair-episode-summary");
+        summary.append(create("strong", "", (episode.source === "legacy" ? "Legacy compatibility" : words(episode.status))),
+            create("span", "secondary", [words(episode.reason), dateTime(episode.opened_at)]
+                .filter(function (value) { return value !== "Unavailable"; }).join(" / ")));
+        details.appendChild(summary);
+        const overview = create("dl", "definition-list");
+        [["Status", words(episode.status)], ["Reason", words(episode.reason)],
+            ["Opened", dateTime(episode.opened_at)], ["Closed", dateTime(episode.closed_at)],
+            ["Latest context", episode.latest_context], ["Parts", episode.parts_count]
+        ].forEach(function (item) { addDefinition(overview, item[0], item[1]); });
+        details.appendChild(overview);
+        if (episode.source === "modular" && episode.repair_id) {
+            const lazy = create("div", "lazy-content", "Open to load timeline and parts.");
+            details.appendChild(lazy);
+            details.addEventListener("toggle", async function () {
+                if (!details.open || details.dataset.loaded || details.dataset.loading) return;
+                details.dataset.loading = "true";
+                lazy.textContent = "Loading repair timeline and parts...";
+                try {
+                    const results = await Promise.all([
+                        api("/api/repairs/" + encodeURIComponent(episode.repair_id) + "/events"),
+                        api("/api/repairs/" + encodeURIComponent(episode.repair_id) + "/parts")
+                    ]);
+                    renderRepairDetails(lazy, results[0], results[1], canReadComponents);
+                    details.dataset.loaded = "true";
+                } catch (error) {
+                    lazy.textContent = "Repair history unavailable: " + error.message;
+                } finally { delete details.dataset.loading; }
+            });
+        } else {
+            details.appendChild(create("p", "permission-note",
+                "Legacy compatibility context has no modular repair timeline."));
+        }
+        return details;
+    }
+
+    function renderRepair(section, capabilities) {
+        el.repair.replaceChildren();
+        el.episodes.replaceChildren();
+        if (section.restricted) {
+            el.repair.appendChild(create("p", "permission-note", "Repair information restricted."));
+            return;
+        }
+        if (section.active_repair) {
+            const active = section.active_repair;
+            const list = create("dl", "definition-list");
+            [["Status", words(active.status)], ["Reason", words(active.reason)],
+                ["Opened", dateTime(active.opened_at)], ["Source", "Modular repair workflow"],
+                ["Latest context", active.latest_context], ["Parts", active.parts_count]
+            ].forEach(function (item) { addDefinition(list, item[0], item[1]); });
+            el.repair.appendChild(list);
+        } else if ((section.episodes || []).some(function (item) { return item.source === "legacy" && item.active; })) {
+            el.repair.appendChild(create("p", "permission-note", "Legacy compatibility repair context is recorded. No modular repair UUID exists."));
+        } else {
+            el.repair.appendChild(create("p", "empty-copy", "No active repair"));
+        }
+        (section.episodes || []).forEach(function (episode) {
+            el.episodes.appendChild(repairEpisode(episode, capabilities.can_read_components));
+        });
+    }
+
+    async function loadIdentityHistory() {
+        if (el.identityHistory.dataset.loaded || el.identityHistory.dataset.loading) return;
+        el.identityHistory.dataset.loading = "true";
+        el.identityHistoryBody.textContent = "Loading identity history...";
+        try {
+            const results = await Promise.all([
+                api("/api/inventory/miners/" + encodeURIComponent(minerId) + "/asset-id-history"),
+                api("/api/miners/" + encodeURIComponent(minerId) + "/network-identities")
+            ]);
+            el.identityHistoryBody.replaceChildren(create("h3", "", "Asset ID history"));
+            const assetRows = (results[0] || []).map(function (entry) {
+                return [entry.old_asset_id, entry.new_asset_id, dateTime(entry.changed_at),
+                    entry.changed_by_display_name];
+            });
+            el.identityHistoryBody.appendChild(assetRows.length
+                ? table(["Previous", "New", "Changed", "Actor"], assetRows)
+                : create("p", "empty-copy", "No Asset ID changes recorded."));
+            el.identityHistoryBody.appendChild(create("h3", "", "Network identity history"));
+            const networkRows = (results[1] || []).map(function (entry) {
+                return [entry.mac_address, entry.ip_address, entry.hostname,
+                    entry.is_current ? "Current" : "Historical", dateTime(entry.last_seen_at)];
+            });
+            el.identityHistoryBody.appendChild(networkRows.length
+                ? table(["MAC", "IP", "Hostname", "State", "Last seen"], networkRows)
+                : create("p", "empty-copy", "No network identity history recorded."));
+            el.identityHistory.dataset.loaded = "true";
+        } catch (error) {
+            el.identityHistoryBody.textContent = "Identity history unavailable: " + error.message;
+        } finally { delete el.identityHistory.dataset.loading; }
+    }
+
+    async function loadObservations() {
+        if (el.observations.dataset.loaded || el.observations.dataset.loading) return;
+        el.observations.dataset.loading = "true";
+        el.observationsBody.textContent = "Loading recent observations...";
+        try {
+            const observations = await api("/api/miners/" + encodeURIComponent(minerId) + "/status-snapshots");
+            const rows = (observations || []).map(function (item) {
+                return [dateTime(item.observed_at), metric(item.mhs_av === null ? null : Number(item.mhs_av) / 1000000, " TH/s"),
+                    metric(item.power_w, " W"), metric(item.chip_temp_max_c, " C"),
+                    item.hash_stable === null || item.hash_stable === undefined
+                        ? "Unavailable" : item.hash_stable ? "Stable" : "Unstable"];
+            });
+            el.observationsBody.replaceChildren(rows.length
+                ? table(["Observed", "Hashrate", "Power", "Max chip temp", "Hash stability"], rows)
+                : create("p", "empty-copy", "No observations recorded."));
+            el.observations.dataset.loaded = "true";
+        } catch (error) {
+            el.observationsBody.textContent = "Recent observations unavailable: " + error.message;
+        } finally { delete el.observations.dataset.loading; }
+    }
+
+    function renderOverview(data) {
+        renderIdentity(data.miner);
+        renderTelemetry(data.miner);
+        el.operational.textContent = words(data.operational_state);
+        el.operational.dataset.status = data.operational_state;
+        el.lifecycle.textContent = "Lifecycle: " + words(data.miner.lifecycle_status);
+        renderLocation(data.location, data.miner.id, data.capabilities.can_view_map);
+        renderRepair(data.repair, data.capabilities);
+        el.trendsLink.href = "/monitoring/analytics?" + new URLSearchParams({
+            scope: "miner", scope_id: data.miner.id, range: "24h"
+        }).toString();
+        if (data.capabilities.can_open_repair_center) {
+            const params = new URLSearchParams({ scope: "all", q: data.miner.id });
+            el.repairsLink.href = "/operations/repairs?" + params.toString();
+            el.repairsLink.hidden = false;
+        }
+        if (returnTo) {
+            el.returnLink.href = returnTo;
+            el.returnLink.textContent = returnTo.startsWith("/monitoring/map")
+                ? "Return to Mine Map" : "Return to previous view";
+            el.returnLink.hidden = false;
+        }
+    }
+
+    async function loadOverview() {
+        el.loading.hidden = false;
+        el.error.hidden = true;
+        el.content.hidden = true;
+        try {
+            const data = await api("/api/miners/" + encodeURIComponent(minerId) + "/overview");
+            renderOverview(data);
+            el.loading.hidden = true;
+            el.content.hidden = false;
+        } catch (error) {
+            el.loading.hidden = true;
+            el.error.hidden = false;
+            el.errorText.textContent = error.message;
+        }
+    }
+
+    el.retry.addEventListener("click", loadOverview);
+    el.refresh.addEventListener("click", loadOverview);
+    el.identityHistory.addEventListener("toggle", function () {
+        if (el.identityHistory.open) loadIdentityHistory();
+    });
+    el.observations.addEventListener("toggle", function () {
+        if (el.observations.open) loadObservations();
+    });
+    loadOverview();
+})();

backend/app/frontend/static/monitoring-trends.css

@@ -0,0 +1,54 @@
+.trend-controls form {
+    display: grid;
+    grid-template-columns: minmax(140px, 0.7fr) minmax(160px, 1fr)
+        minmax(160px, 1fr) auto auto;
+    gap: 12px;
+    align-items: end;
+}
+
+.trend-controls form > label,
+.trend-ranges {
+    display: grid;
+    gap: 5px;
+    margin: 0;
+}
+
+.trend-ranges {
+    grid-auto-flow: column;
+    justify-content: start;
+    border: 0;
+    padding: 0;
+}
+
+.trend-ranges legend { margin-bottom: 5px; font-weight: 700; }
+.trend-ranges label { display: flex; gap: 6px; align-items: center; white-space: nowrap; }
+.trend-summary { display: flex; flex-wrap: wrap; gap: 8px 24px; margin: 0 0 14px; }
+.trend-summary p { margin: 0; }
+.trend-charts { display: grid; gap: 16px; }
+.trend-panel { min-width: 0; }
+.trend-chart { width: 100%; min-height: 220px; overflow: hidden; }
+.trend-chart svg { display: block; width: 100%; height: auto; min-height: 220px; }
+.trend-grid { stroke: #cbd5e1; stroke-width: 1; }
+.trend-line { fill: none; stroke: #c65312; stroke-width: 2.5; stroke-linejoin: round; }
+.trend-point { fill: #ffffff; stroke: #0f172a; stroke-width: 2; }
+.trend-point:focus { outline: none; stroke: #2563eb; stroke-width: 5; }
+.trend-axis-label { fill: #475569; font-size: 11px; }
+.trend-disclosure { color: var(--muted); font-size: 13px; }
+.trend-data-table { margin-top: 12px; }
+.trend-data-table summary { cursor: pointer; font-weight: 700; }
+
+@media (max-width: 900px) {
+    .trend-controls form { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .trend-ranges { grid-column: 1 / -1; }
+}
+
+@media (max-width: 560px) {
+    .trend-controls form { grid-template-columns: 1fr; }
+    .trend-ranges { grid-column: auto; grid-auto-flow: row; }
+    .trend-chart { min-height: 180px; }
+    .trend-chart svg { min-height: 180px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .trend-line, .trend-point { transition: none; animation: none; }
+}

backend/app/frontend/static/monitoring-trends.js

@@ -0,0 +1,344 @@
+(function () {
+    "use strict";
+
+    if (document.body.dataset.view !== "analytics") return;
+
+    const canViewLocations = document.body.dataset.canViewLocations === "true";
+    const allowedScopes = new Set(["fleet", "site", "room", "miner"]);
+    const allowedRanges = new Set(["6h", "24h", "7d"]);
+    const params = new URLSearchParams(window.location.search);
+    const initialScope = allowedScopes.has(params.get("scope"))
+        ? params.get("scope") : "fleet";
+    const state = {
+        scope: initialScope,
+        scopeId: params.get("scope_id") || "",
+        minerId: initialScope === "miner" ? (params.get("scope_id") || "") : "",
+        range: allowedRanges.has(params.get("range")) ? params.get("range") : "24h",
+        available: { sites: [], rooms: [] },
+        controller: null
+    };
+    const el = {
+        form: document.getElementById("trendControls"),
+        scope: document.getElementById("trendScope"),
+        site: document.getElementById("trendSite"),
+        siteLabel: document.getElementById("trendSiteLabel"),
+        room: document.getElementById("trendRoom"),
+        roomLabel: document.getElementById("trendRoomLabel"),
+        loading: document.getElementById("trendLoading"),
+        error: document.getElementById("trendError"),
+        errorText: document.getElementById("trendErrorText"),
+        retry: document.getElementById("trendRetry"),
+        content: document.getElementById("trendContent"),
+        freshness: document.getElementById("trendFreshness"),
+        scopeNote: document.getElementById("trendScopeNote"),
+        scopeLabel: document.getElementById("trendScopeLabel"),
+        rangeSummary: document.getElementById("trendRangeSummary"),
+        timezone: document.getElementById("trendTimezone"),
+        charts: document.getElementById("trendCharts")
+    };
+
+    function create(tag, className, text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text !== undefined) node.textContent = text;
+        return node;
+    }
+
+    function svgNode(tag, attributes) {
+        const node = document.createElementNS("http://www.w3.org/2000/svg", tag);
+        Object.entries(attributes || {}).forEach(function (entry) {
+            node.setAttribute(entry[0], String(entry[1]));
+        });
+        return node;
+    }
+
+    function dateTime(value) {
+        if (!value) return "Unavailable";
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? "Unavailable" : date.toLocaleString();
+    }
+
+    function compactTime(value) {
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? "Unavailable" : date.toLocaleString([], {
+            month: "short", day: "numeric", hour: "2-digit", minute: "2-digit"
+        });
+    }
+
+    function number(value, unit) {
+        if (value === null || value === undefined || !Number.isFinite(Number(value))) {
+            return "Unavailable";
+        }
+        return Number(value).toLocaleString([], { maximumFractionDigits: 2 }) + " " + unit;
+    }
+
+    async function api(url, signal) {
+        const response = await fetch(url, {
+            headers: { Accept: "application/json" }, signal: signal
+        });
+        const payload = await response.json().catch(function () { return {}; });
+        if (!response.ok) {
+            const detail = payload.detail;
+            throw new Error(typeof detail === "string" ? detail : "Request failed (" + response.status + ")");
+        }
+        if (!payload || !payload.data || !payload.meta) {
+            throw new Error("The trends response was incomplete.");
+        }
+        return payload;
+    }
+
+    function replaceOptions(select, options, selected, label) {
+        select.replaceChildren();
+        if (!options.length) {
+            const empty = create("option", "", "No " + label + " available");
+            empty.value = "";
+            select.appendChild(empty);
+            return;
+        }
+        options.forEach(function (item) {
+            const option = create("option", "", item.name);
+            option.value = item.id;
+            option.selected = String(item.id) === String(selected);
+            select.appendChild(option);
+        });
+    }
+
+    function ensureMinerScopeOption() {
+        if (state.scope !== "miner" || el.scope.querySelector('option[value="miner"]')) return;
+        const option = create("option", "", "Miner");
+        option.value = "miner";
+        el.scope.appendChild(option);
+    }
+
+    function renderScopeControls() {
+        ensureMinerScopeOption();
+        el.scope.value = state.scope;
+        const selectedSite = state.scope === "site" ? state.scopeId : el.site.value;
+        let rooms = state.available.rooms || [];
+        if (state.scope === "room") {
+            const selectedRoom = rooms.find(function (room) {
+                return String(room.id) === String(state.scopeId);
+            });
+            if (selectedRoom) replaceOptions(el.site, state.available.sites, selectedRoom.site_id, "sites");
+        } else {
+            replaceOptions(el.site, state.available.sites, selectedSite, "sites");
+        }
+        if (el.site.value) {
+            rooms = rooms.filter(function (room) {
+                return String(room.site_id) === String(el.site.value);
+            });
+        }
+        replaceOptions(el.room, rooms, state.scope === "room" ? state.scopeId : "", "rooms");
+        el.siteLabel.hidden = !canViewLocations || !["site", "room"].includes(state.scope);
+        el.roomLabel.hidden = !canViewLocations || state.scope !== "room";
+        const checked = el.form.querySelector('input[name="trendRange"][value="' + state.range + '"]');
+        if (checked) checked.checked = true;
+    }
+
+    function pointStatus(point) {
+        if (point.observation_count === 0) return "No observations";
+        if (point.metric_sample_count === 0) return "Metric unavailable";
+        return point.incomplete ? "Recorded; current bucket incomplete" : "Recorded";
+    }
+
+    function renderTable(series, tableId) {
+        const details = create("details", "trend-data-table");
+        details.appendChild(create("summary", "", "View " + series.metric + " data table"));
+        const wrapper = create("div", "table-scroll");
+        const table = create("table");
+        table.id = tableId;
+        const caption = create("caption", "", series.label + " bucket values and coverage");
+        const head = create("thead");
+        const headRow = create("tr");
+        ["Bucket start", "Value", "Status", "Samples", "Contributors", "Observed miners", "Scoped miners"]
+            .forEach(function (label) { headRow.appendChild(create("th", "", label)); });
+        head.appendChild(headRow);
+        const body = create("tbody");
+        series.points.forEach(function (point) {
+            const row = create("tr");
+            [dateTime(point.bucket_start), number(point.value, series.unit), pointStatus(point),
+                point.metric_sample_count, point.contributing_miner_count,
+                point.observed_miner_count, point.scoped_miner_count]
+                .forEach(function (value) { row.appendChild(create("td", "", String(value))); });
+            body.appendChild(row);
+        });
+        table.append(caption, head, body);
+        wrapper.appendChild(table);
+        details.appendChild(wrapper);
+        return details;
+    }
+
+    function renderChart(series, index) {
+        const panel = create("section", "panel trend-panel");
+        const headingId = "trendSeriesTitle" + index;
+        const title = create("h2", "", series.label);
+        title.id = headingId;
+        const valid = series.points.filter(function (point) {
+            return point.value !== null && Number.isFinite(Number(point.value));
+        });
+        const rangeCopy = valid.length
+            ? "Observed range " + number(Math.min.apply(null, valid.map(function (p) { return Number(p.value); })), series.unit) +
+                " to " + number(Math.max.apply(null, valid.map(function (p) { return Number(p.value); })), series.unit)
+            : "No valid values in this range";
+        const header = create("div", "panel-head");
+        const heading = create("div");
+        heading.append(create("p", "eyebrow", series.metric === "hashrate" ? "TH/s" : "Watts"), title);
+        header.append(heading, create("p", "freshness", rangeCopy));
+        panel.appendChild(header);
+
+        const chart = create("div", "trend-chart");
+        if (!valid.length) {
+            chart.appendChild(create("p", "empty-copy", "No valid " + series.metric + " observations were recorded."));
+        } else {
+            const width = 800;
+            const height = 250;
+            const left = 72;
+            const right = 20;
+            const top = 20;
+            const bottom = 48;
+            const plotWidth = width - left - right;
+            const plotHeight = height - top - bottom;
+            let minimum = Math.min.apply(null, valid.map(function (point) { return Number(point.value); }));
+            let maximum = Math.max.apply(null, valid.map(function (point) { return Number(point.value); }));
+            if (minimum === maximum) {
+                const padding = Math.max(Math.abs(minimum) * 0.05, 1);
+                minimum -= padding;
+                maximum += padding;
+            }
+            const svg = svgNode("svg", {
+                viewBox: "0 0 " + width + " " + height,
+                role: "img",
+                "aria-labelledby": headingId + " chartDescription" + index
+            });
+            const description = svgNode("desc", { id: "chartDescription" + index });
+            description.textContent = series.label + " in " + series.unit + ". Gaps represent missing values.";
+            svg.appendChild(description);
+            [0, 0.5, 1].forEach(function (ratio) {
+                const y = top + ratio * plotHeight;
+                svg.appendChild(svgNode("line", { x1: left, x2: width - right, y1: y, y2: y, class: "trend-grid" }));
+                const label = svgNode("text", { x: left - 8, y: y + 4, "text-anchor": "end", class: "trend-axis-label" });
+                label.textContent = number(maximum - ratio * (maximum - minimum), series.unit);
+                svg.appendChild(label);
+            });
+            let pathData = "";
+            series.points.forEach(function (point, pointIndex) {
+                const x = left + (series.points.length === 1 ? 0 : pointIndex / (series.points.length - 1)) * plotWidth;
+                if (point.value === null || !Number.isFinite(Number(point.value))) {
+                    pathData += " M " + x + " " + (top + plotHeight);
+                    return;
+                }
+                const y = top + (maximum - Number(point.value)) / (maximum - minimum) * plotHeight;
+                const previous = pointIndex > 0 ? series.points[pointIndex - 1] : null;
+                const command = previous && previous.value !== null && Number.isFinite(Number(previous.value)) ? " L " : " M ";
+                pathData += command + x + " " + y;
+                const marker = svgNode("circle", {
+                    cx: x, cy: y, r: 3.5, class: "trend-point", tabindex: 0,
+                    "aria-label": compactTime(point.bucket_start) + ", " + number(point.value, series.unit) +
+                        ", " + pointStatus(point)
+                });
+                const markerTitle = svgNode("title");
+                markerTitle.textContent = marker.getAttribute("aria-label");
+                marker.appendChild(markerTitle);
+                svg.appendChild(marker);
+            });
+            const path = svgNode("path", { d: pathData, class: "trend-line" });
+            svg.insertBefore(path, svg.querySelector("circle"));
+            const startLabel = svgNode("text", { x: left, y: height - 12, class: "trend-axis-label" });
+            startLabel.textContent = compactTime(series.points[0].bucket_start);
+            const endLabel = svgNode("text", { x: width - right, y: height - 12, "text-anchor": "end", class: "trend-axis-label" });
+            endLabel.textContent = compactTime(series.points[series.points.length - 1].bucket_start);
+            svg.append(startLabel, endLabel);
+            chart.appendChild(svg);
+        }
+        panel.append(chart, create("p", "trend-disclosure", "Gaps indicate no valid metric value. Recorded zero remains zero; values are not interpolated."),
+            renderTable(series, "trendTable" + index));
+        return panel;
+    }
+
+    function render(payload) {
+        state.available = payload.data.available_scopes || { sites: [], rooms: [] };
+        renderScopeControls();
+        el.scopeLabel.textContent = payload.data.scope.label;
+        el.rangeSummary.textContent = payload.meta.range + " range / " +
+            Math.round(payload.meta.bucket_seconds / 60) + " minute buckets / raw snapshots";
+        const zone = Intl.DateTimeFormat().resolvedOptions().timeZone || "browser local time";
+        el.timezone.textContent = "Times shown in " + zone + ". API timestamps use UTC.";
+        el.freshness.textContent = payload.meta.latest_observed_at
+            ? "Latest observation in range: " + dateTime(payload.meta.latest_observed_at)
+            : "No observations in selected range";
+        el.scopeNote.textContent = payload.meta.attribution === "current_placement_cohort"
+            ? "Site and room trends use miners currently assigned to this location. Historical placement is not tracked."
+            : payload.meta.attribution === "miner_identity"
+                ? "Trend values follow this miner's durable UUID."
+                : "Fleet trends use the current miner inventory cohort.";
+        el.charts.replaceChildren();
+        payload.data.series.forEach(function (series, index) {
+            el.charts.appendChild(renderChart(series, index));
+        });
+    }
+
+    function selectedScopeId() {
+        if (state.scope === "fleet") return "";
+        if (state.scope === "site") return el.site.value || state.scopeId;
+        if (state.scope === "room") return el.room.value || state.scopeId;
+        return state.minerId || state.scopeId;
+    }
+
+    function requestUrl() {
+        const query = new URLSearchParams({ scope: state.scope, range: state.range });
+        const scopeId = selectedScopeId();
+        if (state.scope !== "fleet") query.set("scope_id", scopeId);
+        return "/api/monitoring/trends?" + query.toString();
+    }
+
+    async function load() {
+        const scopeId = selectedScopeId();
+        if (state.scope !== "fleet" && !scopeId) {
+            el.error.hidden = false;
+            el.errorText.textContent = "Choose a valid scope before applying filters.";
+            return;
+        }
+        if (state.controller) state.controller.abort();
+        state.controller = new AbortController();
+        el.loading.hidden = false;
+        el.error.hidden = true;
+        try {
+            const payload = await api(requestUrl(), state.controller.signal);
+            state.scopeId = payload.data.scope.id || "";
+            if (state.scope === "miner") state.minerId = state.scopeId;
+            render(payload);
+            const url = new URL(window.location.href);
+            url.search = new URL(requestUrl(), window.location.origin).search;
+            window.history.replaceState({}, "", url.pathname + url.search);
+            el.content.hidden = false;
+        } catch (error) {
+            if (error.name === "AbortError") return;
+            el.errorText.textContent = error.message;
+            el.error.hidden = false;
+        } finally {
+            el.loading.hidden = true;
+        }
+    }
+
+    el.scope.addEventListener("change", function () {
+        state.scope = el.scope.value;
+        if (state.scope !== "miner") state.scopeId = "";
+        renderScopeControls();
+    });
+    el.site.addEventListener("change", function () {
+        if (state.scope === "site") state.scopeId = el.site.value;
+        if (state.scope === "room") state.scopeId = "";
+        renderScopeControls();
+    });
+    el.form.addEventListener("submit", function (event) {
+        event.preventDefault();
+        state.scope = el.scope.value;
+        const selectedRange = el.form.querySelector('input[name="trendRange"]:checked');
+        state.range = selectedRange ? selectedRange.value : "24h";
+        state.scopeId = selectedScopeId();
+        load();
+    });
+    el.retry.addEventListener("click", load);
+    renderScopeControls();
+    load();
+})();

backend/app/frontend/static/repair-center.js

@@ -0,0 +1,612 @@
+(function () {
+    "use strict";
+
+    const optionalFieldIds = ["repairModel", "repairSite", "repairRoom"];
+    const ids = [
+        "repairFilters", "repairQuery", "repairScope", "repairStatus",
+        "repairLifecycle", "repairReset", "repairRows",
+        "repairTotal", "repairActive", "repairHistorical", "repairFreshness",
+        "repairResultSummary", "repairPrevious", "repairNext", "repairLimit",
+        "repairInspector", "repairInspectorTitle", "repairInspectorBody",
+        "repairInspectorClose"
+    ];
+    const el = {};
+    for (const id of ids) el[id] = document.getElementById(id);
+    for (const id of optionalFieldIds) el[id] = document.getElementById(id);
+    if (!el.repairFilters || !el.repairRows) return;
+
+    const STATUS_LABELS = {
+        OPEN: "Open", IN_PROGRESS: "In progress",
+        WAITING_FOR_PARTS: "Waiting for parts", READY_FOR_TEST: "Ready for test",
+        COMPLETED: "Completed", CANCELLED: "Cancelled",
+        open: "Open", diagnosing: "Diagnosing", waiting_parts: "Waiting parts",
+        in_progress: "In progress", testing: "Testing",
+        ready_to_shelf: "Ready to shelf", needs_followup: "Needs follow-up",
+        completed: "Completed", failed: "Failed", cancelled: "Cancelled",
+        repair: "In repair", unknown: "Unknown"
+    };
+    const state = { offset: 0, limit: 50, items: new Map(), rooms: [], opener: null };
+    let controller = null;
+
+    function text(value, fallback) {
+        if (value === null || value === undefined || String(value).trim() === "") {
+            return fallback || "Not available";
+        }
+        return String(value);
+    }
+
+    function create(tag, className, value) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (value !== undefined) node.textContent = value;
+        return node;
+    }
+
+    function button(label, action, className) {
+        const node = create("button", className || "quiet-button", label);
+        node.type = "button";
+        node.dataset.action = action;
+        return node;
+    }
+
+    function showState(name, message) {
+        for (const node of document.querySelectorAll("[data-view-state]")) {
+            node.hidden = node.dataset.viewState !== name;
+        }
+        const active = document.querySelector('[data-view-state="' + name + '"]');
+        const detail = active && active.querySelector("[data-state-detail]");
+        if (detail && message) detail.textContent = message;
+    }
+
+    function friendlyStatus(value) {
+        return STATUS_LABELS[value] || text(value, "Unknown").replaceAll("_", " ");
+    }
+
+    function dateTime(value) {
+        if (!value) return "Not available";
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.valueOf()) ? String(value) : parsed.toLocaleString();
+    }
+
+    function age(value) {
+        if (!value) return "Age unavailable";
+        const milliseconds = Date.now() - new Date(value).valueOf();
+        if (!Number.isFinite(milliseconds) || milliseconds < 0) return "Age unavailable";
+        const hours = Math.floor(milliseconds / 3600000);
+        if (hours < 24) return hours + "h open";
+        return Math.floor(hours / 24) + "d open";
+    }
+
+    function labelPart(prefix, value) {
+        if (!value) return null;
+        const clean = String(value).trim();
+        return clean.toLowerCase().startsWith(prefix.toLowerCase() + " ")
+            ? clean : prefix + " " + clean;
+    }
+
+    function locationText(item) {
+        const parts = [item.site_name, item.room_name,
+            labelPart("Rack", item.rack_label), labelPart("Shelf", item.shelf_label),
+            item.position_label || (item.position_index !== null ? "Position " + item.position_index : null)];
+        return parts.filter(Boolean).join(" / ") || "Unplaced";
+    }
+
+    async function api(path, options) {
+        const response = await fetch(path, Object.assign({
+            credentials: "same-origin", headers: { Accept: "application/json" }
+        }, options || {}));
+        if (response.status === 401) {
+            window.location.replace("/login?next=" + encodeURIComponent(
+                window.location.pathname + window.location.search));
+            throw new Error("Your session expired.");
+        }
+        const payload = await response.json().catch(function () { return null; });
+        if (!response.ok) {
+            const error = new Error(payload && payload.detail
+                ? String(payload.detail) : "The repair request failed.");
+            error.permissionDenied = response.status === 403;
+            throw error;
+        }
+        return payload;
+    }
+
+    function jsonOptions(method, body) {
+        return { method: method, headers: { Accept: "application/json",
+            "Content-Type": "application/json" }, body: JSON.stringify(body) };
+    }
+
+    function readUrl() {
+        const params = new URLSearchParams(window.location.search);
+        el.repairQuery.value = params.get("query") || "";
+        el.repairScope.value = params.get("scope") || "active";
+        el.repairStatus.value = params.get("status") || "";
+        if (el.repairModel) el.repairModel.value = params.get("model") || "";
+        el.repairLifecycle.value = params.get("lifecycle_status") || "";
+        if (el.repairSite) el.repairSite.value = params.get("site_id") || "";
+        state.pendingRoom = params.get("room_id") || "";
+        state.offset = Math.max(0, Number(params.get("offset")) || 0);
+        state.limit = [25, 50, 100, 250].includes(Number(params.get("limit")))
+            ? Number(params.get("limit")) : 50;
+        el.repairLimit.value = String(state.limit);
+    }
+
+    function currentParams(includePaging) {
+        const params = new URLSearchParams();
+        const values = {
+            query: el.repairQuery.value.trim(), scope: el.repairScope.value,
+            status: el.repairStatus.value,
+            model: el.repairModel ? el.repairModel.value.trim() : "",
+            lifecycle_status: el.repairLifecycle.value,
+            site_id: el.repairSite ? el.repairSite.value : "",
+            room_id: el.repairRoom ? el.repairRoom.value : ""
+        };
+        for (const [key, value] of Object.entries(values)) {
+            if (value && !(key === "scope" && value === "active")) params.set(key, value);
+        }
+        if (includePaging) {
+            params.set("limit", String(state.limit));
+            if (state.offset) params.set("offset", String(state.offset));
+        }
+        return params;
+    }
+
+    function syncUrl(mode) {
+        const query = currentParams(true).toString();
+        const target = window.location.pathname + (query ? "?" + query : "");
+        window.history[mode === "replace" ? "replaceState" : "pushState"]({}, "", target);
+    }
+
+    function syncLocationOptions(options) {
+        if (!el.repairSite || !el.repairRoom) return;
+        const selectedSite = el.repairSite.value;
+        const selectedRoom = state.pendingRoom || el.repairRoom.value;
+        el.repairSite.replaceChildren(new Option("All sites", ""));
+        for (const site of options.sites || []) {
+            el.repairSite.appendChild(new Option(site.name, site.id));
+        }
+        if ([...el.repairSite.options].some(function (option) {
+            return option.value === selectedSite;
+        })) el.repairSite.value = selectedSite;
+        state.rooms = options.rooms || [];
+        el.repairRoom.replaceChildren(new Option("All rooms", ""));
+        for (const room of state.rooms) {
+            if (!el.repairSite.value || String(room.site_id) === el.repairSite.value) {
+                el.repairRoom.appendChild(new Option(room.name, room.id));
+            }
+        }
+        if ([...el.repairRoom.options].some(function (option) {
+            return option.value === selectedRoom;
+        })) el.repairRoom.value = selectedRoom;
+        state.pendingRoom = "";
+    }
+
+    function addCell(row, label, content) {
+        const cell = create("td");
+        cell.dataset.label = label;
+        if (content instanceof Node) cell.appendChild(content);
+        else cell.textContent = text(content);
+        row.appendChild(cell);
+    }
+
+    function identityCell(item) {
+        const wrap = create("div", "repair-miner");
+        const label = item.asset_id || item.current_mac || "Miner " + item.miner_id.slice(0, 8);
+        if (item.capabilities.can_open_miner) {
+            const link = create("a", "object-link", label);
+            const returnTo = window.location.pathname + window.location.search;
+            const path = "/miners/" + encodeURIComponent(item.miner_id) + "/detail";
+            link.href = path + "?return_to=" + encodeURIComponent(returnTo);
+            wrap.appendChild(link);
+        } else wrap.appendChild(create("strong", "", label));
+        const details = [item.model, item.miner_sn, item.current_mac, item.current_ip]
+            .filter(Boolean).join(" / ");
+        if (details) wrap.appendChild(create("span", "secondary", details));
+        wrap.appendChild(create("span", "source-label", item.source === "modular"
+            ? "Repair domain" : "Legacy compatibility"));
+        return wrap;
+    }
+
+    function actionCell(item) {
+        const wrap = create("div", "repair-row-actions");
+        if (item.capabilities.can_open_map) {
+            const params = new URLSearchParams({ site_id: item.site_id,
+                room_id: item.room_id, miner_id: item.miner_id });
+            const link = create("a", "quiet-link", "Mine Map");
+            link.href = "/monitoring/map?" + params.toString();
+            wrap.appendChild(link);
+        }
+        if (Object.values(item.capabilities).some(Boolean)) {
+            const details = button("Details", "details");
+            details.dataset.key = item.source + ":" + (item.repair_id || item.miner_id);
+            wrap.appendChild(details);
+        }
+        return wrap;
+    }
+
+    function renderRows(items) {
+        el.repairRows.replaceChildren();
+        state.items.clear();
+        for (const item of items) {
+            const key = item.source + ":" + (item.repair_id || item.miner_id);
+            state.items.set(key, item);
+            const row = create("tr", "repair-row");
+            row.dataset.source = item.source;
+            row.dataset.active = String(item.active);
+            addCell(row, "Miner", identityCell(item));
+            const status = create("span", "repair-status", friendlyStatus(item.repair_status));
+            status.dataset.status = String(item.repair_status).toLowerCase();
+            const stateWrap = create("div");
+            stateWrap.append(status, create("span", "secondary", text(item.lifecycle_status)));
+            addCell(row, "Repair state", stateWrap);
+            addCell(row, "Reported problem", item.reported_problem || item.reason);
+            addCell(row, "Latest context", item.latest_context);
+            addCell(row, "Location", locationText(item));
+            const opened = create("div");
+            opened.append(create("span", "", dateTime(item.opened_at)),
+                create("span", "secondary", item.active ? age(item.opened_at) : "Historical"));
+            addCell(row, "Opened / age", opened);
+            addCell(row, "Parts", item.parts_count === null
+                ? "Legacy record" : item.parts_count + " recorded");
+            addCell(row, "Actions", actionCell(item));
+            el.repairRows.appendChild(row);
+        }
+    }
+
+    function section(title) {
+        const node = create("section", "repair-detail-section");
+        node.appendChild(create("h3", "", title));
+        return node;
+    }
+
+    function renderTimeline(events, legacy) {
+        const node = section(legacy ? "Legacy repair history" : "Repair timeline");
+        if (!events.length) {
+            node.appendChild(create("p", "secondary", "No history entries recorded."));
+            return node;
+        }
+        const list = create("ol", "repair-timeline");
+        for (const event of events) {
+            const entry = create("li");
+            const title = legacy
+                ? text(event.event_title, event.event_type)
+                : friendlyStatus(event.event_type);
+            entry.append(create("strong", "", title),
+                create("span", "secondary", dateTime(event.occurred_at || event.event_at || event.created_at)));
+            const payload = legacy ? event.description : Object.entries(event.payload || {})
+                .map(function (pair) { return pair[0].replaceAll("_", " ") + ": " + pair[1]; })
+                .join(" / ");
+            if (payload) entry.appendChild(create("p", "", String(payload)));
+            list.appendChild(entry);
+        }
+        node.appendChild(list);
+        return node;
+    }
+
+    function partLabel(part) {
+        if (part.consumable) {
+            return part.consumable.quantity + " " + part.consumable.unit + " " +
+                part.consumable.description;
+        }
+        const snapshot = part.component_snapshot || {};
+        return [snapshot.component_type, snapshot.asset_id,
+            snapshot.manufacturer_serial].filter(Boolean).join(" / ") || "Tracked component";
+    }
+
+    function renderParts(item, parts) {
+        const node = section("Parts used");
+        if (!parts.length) node.appendChild(create("p", "secondary", "No parts recorded."));
+        const list = create("ul", "repair-parts-list");
+        for (const part of parts) {
+            const entry = create("li");
+            entry.appendChild(create("span", part.voided_at ? "voided-part" : "", partLabel(part)));
+            if (part.notes) entry.appendChild(create("span", "secondary", part.notes));
+            if (part.voided_at) {
+                entry.appendChild(create("span", "secondary", "Voided: " + text(part.void_reason)));
+            } else if (item.capabilities.can_manage_modular_parts) {
+                const voidButton = button("Void entry", "void-part", "danger-button");
+                voidButton.dataset.partId = part.repair_part_id;
+                entry.appendChild(voidButton);
+            }
+            list.appendChild(entry);
+        }
+        node.appendChild(list);
+        if (item.capabilities.can_manage_modular_parts) {
+            const form = create("form", "repair-action-form");
+            form.dataset.action = "record-part";
+            const kind = create("select");
+            kind.name = "kind";
+            kind.append(new Option("Consumable", "consumable"),
+                new Option("Tracked component", "tracked_component"));
+            const description = create("input");
+            description.name = "description"; description.placeholder = "Consumable description";
+            const quantity = create("input");
+            quantity.name = "quantity"; quantity.type = "number";
+            quantity.min = "0.001"; quantity.step = "0.001"; quantity.value = "1";
+            const unit = create("select"); unit.name = "unit";
+            for (const value of ["each", "gram", "millilitre", "metre", "centimetre"]) {
+                unit.appendChild(new Option(value, value));
+            }
+            const component = create("input");
+            component.name = "component"; component.placeholder = "Tracked component UUID";
+            const notes = create("input"); notes.name = "notes"; notes.placeholder = "Optional notes";
+            form.append(kind, description, quantity, unit, component, notes,
+                create("button", "command-button", "Record part"));
+            form.lastChild.type = "submit";
+            node.appendChild(form);
+        }
+        return node;
+    }
+
+    function modularActions(item) {
+        const node = section("Next action");
+        if (item.capabilities.can_complete_modular_repair) {
+            const form = create("form", "repair-action-form");
+            form.dataset.action = "complete-repair";
+            const target = create("select"); target.name = "target";
+            target.append(new Option("Return active", "active"), new Option("Return as spare", "spare"));
+            const summary = create("textarea"); summary.name = "summary";
+            summary.placeholder = "Optional completion summary";
+            const submit = create("button", "command-button", "Complete repair");
+            submit.type = "submit";
+            form.append(target, summary, submit);
+            node.appendChild(form);
+        } else node.appendChild(create("p", "secondary", "No repair action is available."));
+        return node;
+    }
+
+    function legacyActions(item) {
+        const node = section("Legacy actions");
+        if (!item.capabilities.can_manage_legacy) {
+            node.appendChild(create("p", "secondary", "Legacy repair actions are read-only."));
+            return node;
+        }
+        const form = create("form", "repair-action-form");
+        form.dataset.action = "legacy-update";
+        const status = create("select"); status.name = "status";
+        for (const value of ["open", "diagnosing", "waiting_parts", "in_progress",
+            "testing", "ready_to_shelf", "needs_followup", "completed", "failed", "cancelled"]) {
+            const option = new Option(friendlyStatus(value), value);
+            option.selected = value === item.repair_status;
+            status.appendChild(option);
+        }
+        const note = create("textarea"); note.name = "note"; note.placeholder = "Repair note";
+        const noteButton = create("button", "quiet-button", "Add note");
+        noteButton.type = "submit"; noteButton.value = "note"; noteButton.name = "intent";
+        const statusButton = create("button", "quiet-button", "Save status");
+        statusButton.type = "submit"; statusButton.value = "status"; statusButton.name = "intent";
+        form.append(status, note, noteButton, statusButton);
+        node.append(form, button("Mark repaired", "legacy-repaired", "command-button"),
+            button("Decommission", "legacy-decommission", "danger-button"));
+        return node;
+    }
+
+    function closeInspector() {
+        el.repairInspector.hidden = true;
+        el.repairInspectorBody.replaceChildren();
+        if (state.opener) state.opener.focus();
+    }
+
+    async function openInspector(item, opener) {
+        state.currentItem = item;
+        state.opener = opener;
+        el.repairInspector.hidden = false;
+        el.repairInspectorTitle.textContent = item.asset_id || item.current_mac || "Repair details";
+        el.repairInspectorBody.replaceChildren();
+        const overview = section("Repair overview");
+        overview.append(
+            create("p", "", friendlyStatus(item.repair_status) + " / " + text(item.lifecycle_status)),
+            create("p", "", text(item.reported_problem, "No reported problem")),
+            create("p", "secondary", locationText(item)),
+            create("p", "secondary", "Opened " + dateTime(item.opened_at))
+        );
+        el.repairInspectorBody.appendChild(overview);
+        el.repairInspectorClose.focus();
+
+        try {
+            if (item.source === "modular") {
+                const canRead = item.capabilities.can_read_modular_timeline;
+                const requests = canRead ? [
+                    api("/api/repairs/" + encodeURIComponent(item.repair_id) + "/events"),
+                    api("/api/repairs/" + encodeURIComponent(item.repair_id) + "/parts")
+                ] : [];
+                const results = await Promise.all(requests);
+                if (canRead) {
+                    el.repairInspectorBody.append(
+                        renderTimeline(results[0].data.events || [], false),
+                        renderParts(item, results[1].data.entries || [])
+                    );
+                }
+                el.repairInspectorBody.appendChild(modularActions(item));
+            } else {
+                if (item.capabilities.can_read_legacy_history) {
+                    const history = await api("/api/miners/" +
+                        encodeURIComponent(item.miner_id) + "/maintenance-events");
+                    const events = (history.data || []).filter(function (event) {
+                        return String(event.event_type || "").toLowerCase() === "repair";
+                    });
+                    el.repairInspectorBody.appendChild(renderTimeline(events, true));
+                }
+                el.repairInspectorBody.appendChild(legacyActions(item));
+            }
+        } catch (error) {
+            el.repairInspectorBody.appendChild(create("p", "state-inline-error", error.message));
+        }
+    }
+
+    function selectedItem(target) {
+        const keyNode = target.closest("[data-key]");
+        return keyNode ? state.items.get(keyNode.dataset.key) : null;
+    }
+
+    async function reloadAfterMutation(message) {
+        closeInspector();
+        await load();
+        el.repairResultSummary.textContent = message + " " + el.repairResultSummary.textContent;
+    }
+
+    async function handleInspectorSubmit(event) {
+        event.preventDefault();
+        const form = event.target;
+        const item = state.currentItem;
+        if (!item) return;
+        const data = new FormData(form);
+        try {
+            if (form.dataset.action === "complete-repair") {
+                if (!window.confirm("Complete this repair and change the miner lifecycle?")) return;
+                await api("/api/repairs/" + encodeURIComponent(item.repair_id) + "/complete",
+                    jsonOptions("POST", { target_lifecycle: data.get("target"),
+                        completion_summary: String(data.get("summary") || "").trim() || null }));
+                await reloadAfterMutation("Repair completed.");
+            } else if (form.dataset.action === "record-part") {
+                const kind = data.get("kind");
+                const body = { notes: String(data.get("notes") || "").trim() || null };
+                if (kind === "consumable") {
+                    body.consumable = { description: String(data.get("description") || "").trim(),
+                        quantity: String(data.get("quantity") || ""), unit: data.get("unit") };
+                } else body.tracked_component_uuid = String(data.get("component") || "").trim();
+                await api("/api/repairs/" + encodeURIComponent(item.repair_id) + "/parts",
+                    jsonOptions("POST", body));
+                await openInspector(item, state.opener);
+            } else if (form.dataset.action === "legacy-update") {
+                const intent = event.submitter && event.submitter.value;
+                const note = String(data.get("note") || "").trim();
+                const path = "/api/repairs/" + encodeURIComponent(item.miner_id) +
+                    (intent === "note" ? "/note" : "/status");
+                const body = intent === "note"
+                    ? { note: note, event_status: data.get("status") }
+                    : { event_status: data.get("status"), note: note || null };
+                await api(path, jsonOptions("POST", body));
+                await reloadAfterMutation(intent === "note" ? "Repair note added." : "Repair status updated.");
+            }
+        } catch (error) {
+            form.prepend(create("p", "state-inline-error", error.message));
+        }
+    }
+
+    async function handleInspectorClick(event) {
+        const action = event.target.closest("[data-action]");
+        const item = state.currentItem;
+        if (!action || !item) return;
+        try {
+            if (action.dataset.action === "void-part") {
+                const reason = window.prompt("Reason for voiding this repair-part entry:", "");
+                if (!reason || !reason.trim() || !window.confirm("Void this repair-part entry? Its history will remain recorded.")) return;
+                await api("/api/repairs/" + encodeURIComponent(item.repair_id) + "/parts/" +
+                    encodeURIComponent(action.dataset.partId) + "/void",
+                    jsonOptions("POST", { reason: reason.trim() }));
+                await openInspector(item, state.opener);
+            } else if (action.dataset.action === "legacy-repaired") {
+                if (!window.confirm("Mark this miner repaired and move it to Waiting Placement?")) return;
+                await api("/api/repairs/" + encodeURIComponent(item.miner_id) + "/state",
+                    jsonOptions("POST", { asset_state: "waiting_placement",
+                        note: "Repair marked complete. Miner is waiting for placement." }));
+                await reloadAfterMutation("Miner moved to Waiting Placement.");
+            } else if (action.dataset.action === "legacy-decommission") {
+                const typed = window.prompt("Type DECOMMISSION to confirm:", "");
+                if (typed !== "DECOMMISSION") return;
+                await api("/api/repairs/" + encodeURIComponent(item.miner_id) + "/state",
+                    jsonOptions("POST", { asset_state: "decommissioned",
+                        note: "Miner decommissioned from Repair Center." }));
+                await reloadAfterMutation("Miner decommissioned.");
+            }
+        } catch (error) {
+            el.repairInspectorBody.prepend(create("p", "state-inline-error", error.message));
+        }
+    }
+
+    function populateStatusOptions(counts) {
+        const selected = el.repairStatus.value;
+        const values = Object.keys(counts || {}).sort(function (left, right) {
+            return friendlyStatus(left).localeCompare(friendlyStatus(right));
+        });
+        el.repairStatus.replaceChildren(new Option("All statuses", ""));
+        for (const value of values) {
+            el.repairStatus.appendChild(new Option(
+                friendlyStatus(value) + " (" + counts[value] + ")", value));
+        }
+        if ([...el.repairStatus.options].some(function (option) {
+            return option.value === selected;
+        })) el.repairStatus.value = selected;
+    }
+
+    async function load() {
+        if (controller) controller.abort();
+        controller = new AbortController();
+        showState("loading");
+        el.repairFreshness.textContent = "Loading repair work";
+        try {
+            const params = currentParams(true);
+            const envelope = await api("/api/repairs/queue?" + params.toString(),
+                { signal: controller.signal });
+            if (!envelope || !envelope.data || !Array.isArray(envelope.data.items) ||
+                !envelope.data.summary || !envelope.meta) {
+                throw new Error("MinerOps returned an invalid Repair Center response.");
+            }
+            const items = envelope.data.items;
+            if (!items.every(function (item) {
+                return item && item.miner_id && item.source && item.capabilities;
+            })) throw new Error("MinerOps returned incomplete repair records.");
+            const summary = envelope.data.summary;
+            el.repairTotal.textContent = String(summary.total);
+            el.repairActive.textContent = String(summary.active);
+            el.repairHistorical.textContent = String(summary.historical);
+            populateStatusOptions(summary.status_counts);
+            syncLocationOptions(envelope.meta.location_options || {});
+            renderRows(items);
+            const start = summary.total ? state.offset + 1 : 0;
+            const end = state.offset + items.length;
+            el.repairResultSummary.textContent = "Showing " + start + "-" + end +
+                " of " + summary.total + " matching repairs.";
+            el.repairPrevious.disabled = state.offset === 0;
+            el.repairNext.disabled = end >= summary.total;
+            el.repairFreshness.textContent = "Loaded " + new Date().toLocaleTimeString();
+            showState(items.length ? "ready" : "empty");
+        } catch (error) {
+            if (error.name === "AbortError") return;
+            showState(error.permissionDenied ? "denied" : "error", error.message);
+            el.repairFreshness.textContent = "Repair data unavailable";
+        }
+    }
+
+    el.repairRows.addEventListener("click", function (event) {
+        const action = event.target.closest('[data-action="details"]');
+        const item = selectedItem(event.target);
+        if (!action || !item) return;
+        state.currentItem = item;
+        openInspector(item, action);
+    });
+    el.repairInspectorClose.addEventListener("click", closeInspector);
+    el.repairInspector.addEventListener("submit", handleInspectorSubmit);
+    el.repairInspector.addEventListener("click", handleInspectorClick);
+    document.addEventListener("keydown", function (event) {
+        if (event.key === "Escape" && !el.repairInspector.hidden) closeInspector();
+    });
+    el.repairFilters.addEventListener("submit", function (event) {
+        event.preventDefault(); state.offset = 0; syncUrl("push"); load();
+    });
+    el.repairReset.addEventListener("click", function () {
+        el.repairFilters.reset(); state.offset = 0; state.limit = 50;
+        state.pendingRoom = ""; el.repairLimit.value = "50";
+        syncUrl("push"); load();
+    });
+    if (el.repairSite) el.repairSite.addEventListener("change", function () {
+        state.pendingRoom = "";
+        syncLocationOptions({ sites: [...el.repairSite.options].slice(1).map(function (option) {
+            return { id: option.value, name: option.textContent };
+        }), rooms: state.rooms });
+    });
+    el.repairPrevious.addEventListener("click", function () {
+        state.offset = Math.max(0, state.offset - state.limit); syncUrl("push"); load();
+    });
+    el.repairNext.addEventListener("click", function () {
+        state.offset += state.limit; syncUrl("push"); load();
+    });
+    el.repairLimit.addEventListener("change", function () {
+        state.limit = Number(el.repairLimit.value); state.offset = 0; syncUrl("push"); load();
+    });
+    window.addEventListener("popstate", function () { readUrl(); load(); });
+
+    readUrl();
+    syncUrl("replace");
+    load();
+})();

backend/app/frontend/views.py

@@ -0,0 +1,558 @@
+"""Shared semantic HTML for the MinerOps Internal Alpha shell."""
+
+from html import escape
+from typing import Callable
+
+from app.frontend.miner_detail_view import miner_detail_content
+from app.frontend.monitoring_trends_view import monitoring_trends_content
+
+
+NAVIGATION = (
+    ("dashboard", "Dashboard", "/dashboard", "dashboard.view"),
+    ("map", "Mine Map", "/monitoring/map", "locations.view"),
+    ("analytics", "Trends", "/monitoring/analytics", "miners.view"),
+    ("repairs", "Repair Center", "/operations/repairs", "repairs.view"),
+    ("miners", "Miners", "/assets/miners", "miners.view"),
+)
+
+PAGE_DETAILS = {
+    "dashboard": (
+        "Operational overview",
+        "Dashboard",
+        "A concise starting point for operational state and recent activity.",
+    ),
+    "map": (
+        "Monitoring / Spatial operations",
+        "Mine Map",
+        "Inspect where miners and operational conditions are concentrated.",
+    ),
+    "analytics": (
+        "Monitoring / Analytics",
+        "Trends",
+        "Review bounded historical hashrate and power observations.",
+    ),
+    "repairs": (
+        "Operations",
+        "Repair Center",
+        "Review miners currently represented in the backend repair queue.",
+    ),
+    "miners": (
+        "Assets",
+        "Miners",
+        "Search durable miner inventory and inspect current identity and state.",
+    ),
+    "miner_detail": (
+        "Assets / Miners",
+        "Miner Detail",
+        "Current identity, operating facts, location, and authorized history.",
+    ),
+}
+
+
+def _dashboard_content(
+    can_view_miners: bool,
+    can_view_repairs: bool,
+    can_view_locations: bool,
+) -> str:
+    fleet = """
+    <section class="dashboard-section dashboard-fleet" aria-labelledby="fleetOverviewTitle">
+        <div class="dashboard-section-head"><div><p class="eyebrow">Assets</p>
+            <h2 id="fleetOverviewTitle">Fleet overview</h2></div>
+            <a class="object-link" href="/assets/miners">Open Fleet</a></div>
+        <div class="dashboard-total"><span>Total miners</span>
+            <strong id="dashboardFleetTotal">-</strong></div>
+        <div class="dashboard-dimension-grid">
+            <section aria-labelledby="runtimeTitle"><h3 id="runtimeTitle">Runtime</h3>
+                <dl class="dashboard-count-list">
+                    <div><dt>Online</dt><dd id="dashboardRuntimeOnline">-</dd></div>
+                    <div><dt>Offline</dt><dd id="dashboardRuntimeOffline">-</dd></div>
+                    <div><dt>Unknown</dt><dd id="dashboardRuntimeUnknown">-</dd></div>
+                </dl></section>
+            <section aria-labelledby="lifecycleTitle"><h3 id="lifecycleTitle">Lifecycle</h3>
+                <dl class="dashboard-count-list">
+                    <div><dt>In repair</dt><dd id="dashboardLifecycleRepair">-</dd></div>
+                    <div><dt>Spare</dt><dd id="dashboardLifecycleSpare">-</dd></div>
+                    <div><dt>Retired</dt><dd id="dashboardLifecycleRetired">-</dd></div>
+                </dl></section>
+        </div>
+        <p class="dashboard-boundary">Runtime and lifecycle are separate dimensions and may overlap.</p>
+    </section>
+    <section class="dashboard-section dashboard-attention" aria-labelledby="attentionTitle">
+        <div class="dashboard-section-head"><div><p class="eyebrow">Current state</p>
+            <h2 id="attentionTitle">Needs attention</h2></div></div>
+        <nav class="attention-list" aria-label="Fleet conditions requiring attention">
+            <a href="/assets/miners?operational_state=offline" data-state="offline">
+                <span>Offline</span><strong id="dashboardAttentionOffline">-</strong></a>
+            <a href="/assets/miners?operational_state=unknown" data-state="unknown">
+                <span>Unknown</span><strong id="dashboardAttentionUnknown">-</strong></a>
+            <a href="/assets/miners?operational_state=unstable" data-state="unstable">
+                <span>Hash unstable</span><strong id="dashboardAttentionUnstable">-</strong></a>
+            <a href="/assets/miners?operational_state=repair" data-state="repair">
+                <span>In repair</span><strong id="dashboardAttentionRepair">-</strong></a>
+        </nav>
+    </section>
+    """ if can_view_miners else ""
+    repairs = """
+    <section class="dashboard-section" aria-labelledby="dashboardRepairsTitle">
+        <div class="dashboard-section-head"><div><p class="eyebrow">Operations</p>
+            <h2 id="dashboardRepairsTitle">Repairs</h2></div>
+            <a class="object-link" href="/operations/repairs?scope=active">Open Repair Center</a></div>
+        <div class="dashboard-total"><span>Active repair records</span>
+            <strong id="dashboardActiveRepairs">-</strong></div>
+        <dl class="dashboard-status-list" id="dashboardRepairStatuses"></dl>
+    </section>
+    """ if can_view_repairs else ""
+    mapped_metrics = """
+        <div><dt>Mapped miners</dt><dd id="dashboardMappedMiners">-</dd></div>
+        <div><dt>Unmapped miners</dt><dd id="dashboardUnmappedMiners">-</dd></div>
+    """ if can_view_miners else ""
+    locations = f"""
+    <section class="dashboard-section" aria-labelledby="dashboardLocationsTitle">
+        <div class="dashboard-section-head"><div><p class="eyebrow">Spatial operations</p>
+            <h2 id="dashboardLocationsTitle">Locations</h2></div>
+            <a class="object-link" href="/monitoring/map">Open Mine Map</a></div>
+        <dl class="dashboard-count-list dashboard-location-counts">
+            <div><dt>Sites</dt><dd id="dashboardSites">-</dd></div>
+            <div><dt>Rooms</dt><dd id="dashboardRooms">-</dd></div>
+            <div><dt>Positions</dt><dd id="dashboardPositions">-</dd></div>
+            <div><dt>Occupied</dt><dd id="dashboardOccupied">-</dd></div>
+            <div><dt>Empty</dt><dd id="dashboardEmptyPositions">-</dd></div>
+            {mapped_metrics}
+        </dl>
+    </section>
+    """ if can_view_locations else ""
+    available = sum((can_view_miners, can_view_repairs, can_view_locations))
+    partial = (
+        '<p class="dashboard-permission-note">This overview includes only the '
+        'operational areas available to your account.</p>'
+        if 0 < available < 3 else ""
+    )
+    return f"""
+<div class="state-message" id="dashboardLoading" role="status">
+    <strong>Loading operational overview</strong>
+    <span>Requesting current fleet, repair, and location summaries.</span>
+</div>
+<div class="state-message" id="dashboardError" data-kind="error" role="alert" hidden>
+    <strong>Dashboard unavailable</strong>
+    <span id="dashboardErrorDetail">The operational overview could not be loaded.</span>
+    <button class="command-button" id="dashboardRetry" type="button">Retry</button>
+</div>
+<div class="state-message" id="dashboardEmpty" hidden>
+    <strong>No operational sections available</strong>
+    <span>Your account can open Dashboard but has no additional overview permissions.</span>
+</div>
+<div id="dashboardContent" hidden>
+    <div class="dashboard-status-band">
+        <p id="dashboardLoadStatus" class="freshness" aria-live="polite">Waiting for current summaries</p>
+        {partial}
+    </div>
+    <div class="dashboard-grid">{fleet}{repairs}{locations}</div>
+</div>
+"""
+
+
+def _map_content(can_manage_locations: bool = False) -> str:
+    manage_link = (
+        '<a class="object-link" href="/locations">Manage locations</a>'
+        if can_manage_locations
+        else ""
+    )
+    return f"""
+<section class="map-context" aria-labelledby="mapControlsTitle">
+    <div class="map-context-head">
+        <div>
+            <h2 id="mapControlsTitle">Map context</h2>
+            <p id="mapScope" class="panel-copy">Select a site and room.</p>
+        </div>
+        {manage_link}
+    </div>
+    <div class="map-control-grid">
+        <div class="field"><label for="mapSite">Site</label>
+            <select id="mapSite" aria-describedby="mapScope"><option>Loading sites...</option></select></div>
+        <div class="field"><label for="mapRoom">Room</label>
+            <select id="mapRoom"><option>Loading rooms...</option></select></div>
+        <div class="field"><label for="mapLayer">Layer</label>
+            <select id="mapLayer">
+                <option value="status">Operational Status</option>
+                <option value="temperature">Temperature</option>
+                <option value="hashrate">Hashrate</option>
+                <option value="power">Power</option>
+                <option value="repair">Repair State</option>
+            </select></div>
+        <div class="field map-search"><label for="mapSearch">Find miner</label>
+            <input id="mapSearch" type="search" autocomplete="off"
+                placeholder="Asset ID, serial, MAC, or IP"></div>
+        <label class="map-problems-control" for="mapProblemsOnly">
+            <input id="mapProblemsOnly" type="checkbox">
+            <span>Problems only</span>
+        </label>
+    </div>
+    <details class="map-filters" id="mapFilters">
+        <summary>Filters <span id="mapFilterCount" aria-live="polite"></span></summary>
+        <div class="map-filter-grid">
+            <div class="field"><label for="mapLifecycle">Lifecycle</label>
+                <select id="mapLifecycle"><option value="">All lifecycle states</option></select></div>
+            <div class="field"><label for="mapModel">Model</label>
+                <select id="mapModel"><option value="">All models</option></select></div>
+            <div class="field"><label for="mapRepair">Repair</label>
+                <select id="mapRepair"><option value="">All repair states</option><option value="active">Active repair</option><option value="none">No active repair</option><option value="legacy">Legacy repair location</option></select></div>
+            <div class="field"><label for="mapStatus">Operational status</label>
+                <select id="mapStatus"><option value="">All operational states</option></select></div>
+            <button id="mapClearFilters" class="quiet-button" type="button">Clear filters</button>
+        </div>
+    </details>
+</section>
+<section class="map-status-band" aria-label="Map summary">
+    <div id="mapSummary" class="map-summary" aria-live="polite"></div>
+    <div id="mapFreshness" class="freshness">Waiting for map data</div>
+</section>
+<div id="mapCriticalState" class="state-message" data-kind="error" role="alert" hidden>
+    <strong id="mapCriticalTitle">Map unavailable</strong>
+    <span id="mapCriticalDetail">The map could not be loaded.</span>
+    <button id="mapRetry" class="command-button" type="button">Retry</button>
+</div>
+<div id="mapLoading" class="state-message" role="status">
+    <strong>Loading Mine Map</strong>
+    <span>Requesting the current physical layout and operational observations.</span>
+</div>
+<section class="mine-map-workspace" id="mapWorkspace" hidden>
+    <div class="map-main-column">
+        <div id="mapLegend" class="map-legend" aria-label="Map legend"></div>
+        <p id="mapPermissionNote" class="map-notice" hidden>
+            Miner details require inventory access. Layout and occupancy remain visible.
+        </p>
+        <div id="mapNotice" class="map-notice" role="status" hidden></div>
+        <div id="mapViewport" class="map-viewport-v1"
+            aria-label="Room racks, shelves, and positions"></div>
+        <section id="mapLegacySection" class="unplaced-section" hidden
+            aria-labelledby="mapLegacyTitle">
+            <div class="panel-head"><div><h2 id="mapLegacyTitle">Unscoped legacy positions</h2>
+            <p class="panel-copy">Stored positions without a durable room relationship. They are not assigned to the selected site or room.</p></div></div>
+            <div id="mapLegacyPositions" class="legacy-position-list"></div>
+        </section>
+        <section id="mapUnplacedSection" class="unplaced-section" hidden
+            aria-labelledby="unplacedTitle">
+            <div class="panel-head"><div><h2 id="unplacedTitle">Unplaced and operational areas</h2>
+            <p class="panel-copy">Miner records without a configured rack position.</p></div></div>
+            <div id="mapUnplaced"></div>
+        </section>
+    </div>
+    <aside id="mapInspector" class="map-inspector-v1" aria-labelledby="mapInspectorTitle" hidden>
+        <div class="inspector-head">
+            <div><p class="eyebrow">Selected position</p><h2 id="mapInspectorTitle">Miner details</h2></div>
+            <button id="mapInspectorClose" class="icon-button" type="button" aria-label="Close miner details" title="Close miner details">X</button>
+        </div>
+        <p id="mapInspectorStatus" class="status-callout"></p>
+        <dl id="mapInspectorDetails" class="definition-list inspector-details"></dl>
+        <a id="mapOpenMiner" class="command-link" href="/assets/miners">Open Miner</a>
+    </aside>
+</section>
+"""
+
+
+def _state_messages(noun: str) -> str:
+    return f"""
+<div class="state-message" data-view-state="loading" role="status">
+    <strong>Loading {noun}</strong>
+    <span data-state-detail>Requesting current information from MinerOps.</span>
+</div>
+<div class="state-message" data-view-state="empty" hidden>
+    <strong>No {noun} found</strong>
+    <span data-state-detail>There is no information to show in this view.</span>
+</div>
+<div class="state-message" data-view-state="denied" data-kind="error" hidden>
+    <strong>Access unavailable</strong>
+    <span data-state-detail>Your account cannot view this information.</span>
+</div>
+<div class="state-message" data-view-state="error" data-kind="error" hidden>
+    <strong>Could not load {noun}</strong>
+    <span data-state-detail>Retry after checking the MinerOps connection.</span>
+</div>
+"""
+
+
+def _repairs_content(can_view_locations: bool, can_view_miners: bool) -> str:
+    location_filters = """
+        <div class="field"><label for="repairSite">Site</label>
+            <select id="repairSite"><option value="">All sites</option></select></div>
+        <div class="field"><label for="repairRoom">Room</label>
+            <select id="repairRoom"><option value="">All rooms</option></select></div>
+    """ if can_view_locations else ""
+    search_placeholder = (
+        "Miner, model, status, reason, or context"
+        if can_view_miners else "Repair status, reason, or context"
+    )
+    model_filter = """
+        <div class="field"><label for="repairModel">Model</label>
+            <input id="repairModel" type="text" autocomplete="off" placeholder="Any model"></div>
+    """ if can_view_miners else ""
+    return f"""
+<section class="panel repair-center" aria-labelledby="repairQueueTitle">
+    <div class="panel-head">
+        <div><h2 id="repairQueueTitle">Repair Center</h2>
+            <p class="panel-copy">Active work and historical modular repairs, with legacy queue records clearly identified.</p></div>
+        <span class="freshness" id="repairFreshness">Loading repair work</span>
+    </div>
+    <div class="repair-summary" aria-label="Repair summary">
+        <div><span>Total results</span><strong id="repairTotal">-</strong></div>
+        <div><span>Active</span><strong id="repairActive">-</strong></div>
+        <div><span>Historical</span><strong id="repairHistorical">-</strong></div>
+    </div>
+    <form class="repair-filters" id="repairFilters" role="search">
+        <div class="field repair-search"><label for="repairQuery">Search repairs</label>
+            <input id="repairQuery" type="search" autocomplete="off"
+                placeholder="{search_placeholder}"></div>
+        <div class="field"><label for="repairScope">Scope</label>
+            <select id="repairScope"><option value="active">Active</option>
+                <option value="historical">Historical</option><option value="all">All</option></select></div>
+        <div class="field"><label for="repairStatus">Repair status</label>
+            <select id="repairStatus"><option value="">All statuses</option></select></div>
+        {model_filter}
+        <div class="field"><label for="repairLifecycle">Miner lifecycle</label>
+            <select id="repairLifecycle"><option value="">All lifecycle states</option>
+                <option value="active">Active</option><option value="spare">Spare</option>
+                <option value="in_repair">In repair</option><option value="retired">Retired</option></select></div>
+        {location_filters}
+        <div class="repair-filter-actions">
+            <button class="command-button" type="submit">Apply</button>
+            <button class="quiet-button" id="repairReset" type="button">Reset</button>
+        </div>
+    </form>
+    {_state_messages("repair records")}
+    <div data-view-state="ready" hidden>
+        <p class="repair-result-summary" id="repairResultSummary" aria-live="polite"></p>
+        <div class="table-wrap repair-table-wrap">
+            <table class="repair-table">
+                <thead><tr><th>Miner</th><th>Repair state</th><th>Reported problem</th>
+                    <th>Latest context</th><th>Location</th><th>Opened / age</th>
+                    <th>Parts</th><th>Actions</th></tr></thead>
+                <tbody id="repairRows"></tbody>
+            </table>
+        </div>
+    </div>
+    <nav class="repair-pagination" aria-label="Repair result pages">
+        <button class="quiet-button" id="repairPrevious" type="button" disabled>Previous</button>
+        <label for="repairLimit">Rows per page</label>
+        <select id="repairLimit"><option value="25">25</option><option value="50">50</option>
+            <option value="100">100</option><option value="250">250</option></select>
+        <button class="quiet-button" id="repairNext" type="button" disabled>Next</button>
+    </nav>
+</section>
+<aside class="repair-inspector" id="repairInspector" aria-labelledby="repairInspectorTitle" hidden>
+    <div class="inspector-head"><div><span class="eyebrow">Repair context</span>
+        <h2 id="repairInspectorTitle">Repair details</h2></div>
+        <button class="icon-button" id="repairInspectorClose" type="button" aria-label="Close repair details">X</button></div>
+    <div id="repairInspectorBody"></div>
+</aside>
+"""
+
+
+def _miners_content(can_view_locations: bool) -> str:
+    location_filters = """
+        <div class="field"><label for="fleetSite">Site</label>
+            <select id="fleetSite"><option value="">All sites</option></select></div>
+        <div class="field"><label for="fleetRoom">Room</label>
+            <select id="fleetRoom"><option value="">All rooms</option></select></div>
+    """ if can_view_locations else ""
+    return f"""
+<section class="panel fleet-panel" aria-labelledby="minerListTitle">
+    <div class="panel-head">
+        <div><h2 id="minerListTitle">Fleet</h2>
+            <p class="panel-copy">Current miner identity, operating state, telemetry, and repair context.</p></div>
+        <span class="freshness" id="fleetFreshness">Loading current fleet</span>
+    </div>
+    <form class="fleet-filters" id="fleetFilters" role="search">
+        <div class="field fleet-search"><label for="fleetQuery">Search miners</label>
+            <input id="fleetQuery" type="search" autocomplete="off"
+                placeholder="Asset ID, MAC, IP, model, or serial"></div>
+        <div class="field"><label for="fleetLifecycle">Lifecycle</label>
+            <select id="fleetLifecycle"><option value="">All lifecycle states</option>
+                <option value="active">Active</option><option value="spare">Spare</option>
+                <option value="in_repair">In repair</option><option value="retired">Retired</option></select></div>
+        <div class="field"><label for="fleetModel">Model</label>
+            <input id="fleetModel" type="text" autocomplete="off" placeholder="Any model"></div>
+        <div class="field"><label for="fleetRuntime">Runtime</label>
+            <select id="fleetRuntime"><option value="">All runtime states</option>
+                <option value="online">Online</option><option value="offline">Offline</option>
+                <option value="unknown">Unknown</option></select></div>
+        <div class="field"><label for="fleetRepair">Repair</label>
+            <select id="fleetRepair"><option value="">Any repair state</option>
+                <option value="active">Active repair</option><option value="none">No active repair</option></select></div>
+        <div class="field"><label for="fleetOperational">Operational state</label>
+            <select id="fleetOperational"><option value="">All operational states</option>
+                <option value="online">Online</option><option value="offline">Offline</option>
+                <option value="unstable">Hash unstable</option><option value="repair">In repair</option>
+                <option value="spare">Spare</option><option value="retired">Retired</option>
+                <option value="unknown">Unknown</option></select></div>
+        {location_filters}
+        <div class="field"><label for="fleetTags">Tags</label>
+            <input id="fleetTags" type="text" autocomplete="off" placeholder="Comma separated"></div>
+        <label class="check-control" for="fleetProblems">
+            <input id="fleetProblems" type="checkbox"> Problems only</label>
+        <div class="fleet-filter-actions">
+            <button class="command-button" type="submit">Apply</button>
+            <button class="quiet-button" id="fleetReset" type="button">Reset</button>
+        </div>
+    </form>
+    {_state_messages("miners")}
+    <div data-view-state="ready" hidden>
+        <p class="fleet-result-summary" id="fleetResultSummary" aria-live="polite"></p>
+        <div class="table-wrap fleet-table-wrap">
+            <table class="fleet-table">
+                <thead><tr><th>Miner</th><th>Operational</th><th>Model / Serial</th>
+                    <th>Network</th><th>Location</th><th>Hashrate</th><th>Power</th>
+                    <th>Max chip temp</th><th>Lifecycle / Repair</th><th>Actions</th></tr></thead>
+                <tbody id="fleetRows"></tbody>
+            </table>
+        </div>
+    </div>
+        <nav class="fleet-pagination" aria-label="Fleet pages">
+            <button class="quiet-button" id="fleetPrevious" type="button" disabled>Previous</button>
+            <label for="fleetLimit">Rows per page</label>
+            <select id="fleetLimit"><option value="25">25</option><option value="50">50</option>
+                <option value="100">100</option><option value="250">250</option></select>
+            <button class="quiet-button" id="fleetNext" type="button" disabled>Next</button>
+        </nav>
+</section>
+"""
+
+
+def render_app_page(
+    view: str,
+    current_user: dict,
+    has_permission: Callable[[str], bool],
+    *,
+    miner_id: str | None = None,
+    return_to: str | None = None,
+) -> str:
+    context, title, summary = PAGE_DETAILS[view]
+    display_name = escape(
+        str(
+            current_user.get("display_name")
+            or current_user.get("username")
+            or "MinerOps user"
+        )
+    )
+    role = escape(str(current_user.get("role") or "Authenticated user"))
+    can_view_miners = has_permission("miners.view")
+    active_navigation = "miners" if view == "miner_detail" else view
+    navigation = "".join(
+        (
+            f'<li><a href="{href}" aria-current="page">{escape(label)}</a></li>'
+            if key == active_navigation
+            else f'<li><a href="{href}">{escape(label)}</a></li>'
+        )
+        for key, label, href, permission in NAVIGATION
+        if has_permission(permission)
+    )
+    global_search = (
+        '<form class="global-search" id="globalSearchForm" role="search">'
+        '<label for="globalSearchInput">Search miners</label>'
+        '<input id="globalSearchInput" type="search" autocomplete="off" '
+        'placeholder="Search miners (more sources planned)">'
+        '</form>'
+        if can_view_miners
+        else '<div class="global-search-unavailable" aria-hidden="true"></div>'
+    )
+    content = (
+        miner_detail_content()
+        if view == "miner_detail"
+        else monitoring_trends_content(has_permission("locations.view"))
+        if view == "analytics"
+        else _map_content(has_permission("locations.manage"))
+        if view == "map"
+        else _miners_content(has_permission("locations.view"))
+        if view == "miners"
+        else _repairs_content(
+            has_permission("locations.view"), has_permission("miners.view")
+        )
+        if view == "repairs"
+        else _dashboard_content(
+            has_permission("miners.view"),
+            has_permission("repairs.view"),
+            has_permission("locations.view"),
+        )
+    )
+    page_script = (
+        '<script src="/assets/minerops-miner-detail.js" defer></script>'
+        if view == "miner_detail"
+        else '<script src="/assets/minerops-monitoring-trends.js" defer></script>'
+        if view == "analytics"
+        else '<script src="/assets/minerops-mine-map.js" defer></script>'
+        if view == "map"
+        else '<script src="/assets/minerops-fleet.js" defer></script>'
+        if view == "miners"
+        else '<script src="/assets/minerops-repair-center.js" defer></script>'
+        if view == "repairs"
+        else '<script src="/assets/minerops-dashboard.js" defer></script>'
+        if view == "dashboard"
+        else ""
+    )
+    page_style = (
+        '<link rel="stylesheet" href="/assets/minerops-monitoring-trends.css">'
+        if view == "analytics" else ""
+    )
+    object_attributes = ""
+    if miner_id is not None:
+        object_attributes += f' data-miner-id="{escape(miner_id)}"'
+    if return_to is not None:
+        object_attributes += f' data-return-to="{escape(return_to)}"'
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{escape(title)} | MinerOps</title>
+    <link rel="stylesheet" href="/assets/minerops-app.css">
+    {page_style}
+</head>
+<body data-view="{escape(view)}"
+    data-can-view-miners="{str(can_view_miners).lower()}"
+    data-can-view-locations="{str(has_permission("locations.view")).lower()}"{object_attributes}>
+    <a class="skip-link" href="#mainContent">Skip to main content</a>
+    <div class="app-shell">
+        <header class="topbar">
+            <div class="brand-area">
+                <button class="menu-button" id="menuButton" type="button"
+                    aria-controls="primaryNav" aria-expanded="false">Menu</button>
+                <a class="brand" href="/dashboard">
+                    <span class="brand-name">MinerOps</span>
+                    <span class="brand-tagline">Operational Intelligence for Mining</span>
+                </a>
+            </div>
+            {global_search}
+            <div class="session-tools">
+                <button class="quiet-button" type="button"
+                    aria-label="Alerts are not yet connected"
+                    title="Alerts are not yet connected"
+                    disabled>Alerts: unavailable</button>
+                <div class="session-copy">
+                    <span class="session-user">{display_name}</span>
+                    <span class="session-role">{role}</span>
+                </div>
+                <button class="quiet-button" id="logoutButton"
+                    type="button">Sign out</button>
+            </div>
+        </header>
+        <nav class="primary-nav" id="primaryNav"
+            aria-label="Primary navigation" data-open="false">
+            <ul>{navigation}</ul>
+            <p class="nav-note">Internal Alpha navigation. Additional
+            destinations appear only as working, authorized views.</p>
+        </nav>
+        <main class="main-content" id="mainContent" tabindex="-1">
+            <header class="page-head">
+                <div>
+                    <p class="eyebrow">{escape(context)}</p>
+                    <h1>{escape(title)}</h1>
+                    <p class="page-summary">{escape(summary)}</p>
+                </div>
+                <p class="freshness">Current view: {escape(title)}</p>
+            </header>
+            {content}
+        </main>
+    </div>
+    <script src="/assets/minerops-app.js" defer></script>
+    {page_script}
+</body>
+</html>"""

backend/app/inventory/__init__.py

@@ -0,0 +1,35 @@
+"""Inventory domain models, persistence, and business services."""
+
+from app.inventory.exceptions import (
+    DuplicateAssetID,
+    InventoryError,
+    InventoryValidationError,
+    MinerNotFound,
+)
+from app.inventory.models import (
+    InventoryCreateRequest,
+    InventoryMetadataUpdateRequest,
+    InventoryMinerDetail,
+    InventoryMinerSummary,
+    InventorySearchFilters,
+    InventoryTag,
+    InventoryUpdateRequest,
+)
+from app.inventory.repository import InventoryRepository
+from app.inventory.service import InventoryService
+
+__all__ = [
+    "DuplicateAssetID",
+    "InventoryCreateRequest",
+    "InventoryError",
+    "InventoryMetadataUpdateRequest",
+    "InventoryMinerDetail",
+    "InventoryMinerSummary",
+    "InventoryRepository",
+    "InventorySearchFilters",
+    "InventoryService",
+    "InventoryTag",
+    "InventoryUpdateRequest",
+    "InventoryValidationError",
+    "MinerNotFound",
+]

backend/app/inventory/dependencies.py

@@ -0,0 +1,8 @@
+"""Dependency construction for the Inventory domain."""
+
+from app.inventory.repository import InventoryRepository
+from app.inventory.service import InventoryService
+
+
+def get_inventory_service() -> InventoryService:
+    return InventoryService(InventoryRepository())

backend/app/inventory/exceptions.py

@@ -0,0 +1,25 @@
+"""Inventory domain exceptions."""
+
+
+class InventoryError(Exception):
+    """Base exception for inventory operations."""
+
+
+class InventoryValidationError(InventoryError):
+    """Raised when an inventory business rule is violated."""
+
+
+class DuplicateAssetID(InventoryError):
+    """Raised when an Asset ID is already assigned to another miner."""
+
+    def __init__(self, asset_id: str):
+        self.asset_id = asset_id
+        super().__init__(f"Asset ID already exists: {asset_id}")
+
+
+class MinerNotFound(InventoryError):
+    """Raised when an inventory miner cannot be found."""
+
+    def __init__(self, miner_id: object):
+        self.miner_id = miner_id
+        super().__init__(f"Miner not found: {miner_id}")

backend/app/inventory/models.py

@@ -0,0 +1,191 @@
+"""Pydantic contracts for the inventory domain."""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, IPvAnyAddress
+
+
+LifecycleStatus = Literal["active", "spare", "retired", "in_repair"]
+
+
+class InventoryTag(BaseModel):
+    id: UUID
+    name: str
+    created_at: datetime
+    updated_at: datetime
+
+
+class InventoryActiveRepair(BaseModel):
+    id: UUID
+    status: str
+    reason: str
+
+
+class InventoryMinerSummary(BaseModel):
+    id: UUID
+    asset_id: str | None = None
+    current_mac: str | None = None
+    current_ip: str | None = None
+    model: str | None = None
+    miner_sn: str | None = None
+    lifecycle_status: LifecycleStatus
+    runtime_status: str
+    site_id: UUID | None = None
+    site_name: str | None = None
+    room_id: UUID | None = None
+    room_name: str | None = None
+    location_position_id: UUID | None = None
+    rack_label: str | None = None
+    shelf_label: str | None = None
+    position_label: str | None = None
+    position_index: int | None = None
+    observed_at: datetime | None = None
+    hashrate_ths: float | None = None
+    power_w: float | None = None
+    chip_temp_max_c: float | None = None
+    hash_stable: bool | None = None
+    active_repair: InventoryActiveRepair | None = None
+    tags: list[InventoryTag] = Field(default_factory=list)
+    created_at: datetime
+    updated_at: datetime
+    last_seen_at: datetime | None = None
+
+
+class InventoryMinerDetail(InventoryMinerSummary):
+    hostname: str | None = None
+    control_board_sn: str | None = None
+    psu_serial: str | None = None
+    firmware_version: str | None = None
+    notes: str | None = None
+    first_seen_at: datetime | None = None
+
+
+class InventoryAssetIDHistoryEntry(BaseModel):
+    old_asset_id: str | None = None
+    new_asset_id: str
+    changed_at: datetime
+    changed_by: UUID
+    changed_by_display_name: str
+
+
+class InventoryCreateRequest(BaseModel):
+    asset_id: str = Field(min_length=1, max_length=120)
+    current_mac: str | None = Field(default=None, max_length=64)
+    current_ip: IPvAnyAddress | None = None
+    hostname: str | None = Field(default=None, max_length=255)
+    miner_sn: str | None = Field(default=None, max_length=255)
+    control_board_sn: str | None = Field(default=None, max_length=255)
+    psu_serial: str | None = Field(default=None, max_length=255)
+    model: str | None = Field(default=None, max_length=255)
+    firmware_version: str | None = Field(default=None, max_length=255)
+    lifecycle_status: str = "active"
+    site_id: UUID | None = None
+    room_id: UUID | None = None
+    notes: str | None = None
+    tags: list[str] = Field(default_factory=list)
+
+
+class InventoryMetadataUpdateRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    asset_id: str | None = Field(default=None, max_length=120)
+    miner_sn: str | None = Field(default=None, max_length=255)
+    psu_serial: str | None = Field(default=None, max_length=255)
+    model: str | None = Field(default=None, max_length=255)
+    notes: str | None = None
+
+
+class InventoryUpdateRequest(BaseModel):
+    asset_id: str | None = Field(default=None, max_length=120)
+    current_mac: str | None = Field(default=None, max_length=64)
+    current_ip: IPvAnyAddress | None = None
+    hostname: str | None = Field(default=None, max_length=255)
+    miner_sn: str | None = Field(default=None, max_length=255)
+    control_board_sn: str | None = Field(default=None, max_length=255)
+    psu_serial: str | None = Field(default=None, max_length=255)
+    model: str | None = Field(default=None, max_length=255)
+    firmware_version: str | None = Field(default=None, max_length=255)
+    lifecycle_status: str | None = None
+    site_id: UUID | None = None
+    room_id: UUID | None = None
+    notes: str | None = None
+    tags: list[str] | None = None
+
+
+class InventorySearchFilters(BaseModel):
+    query: str | None = None
+    asset_id: str | None = None
+    lifecycle_status: str | None = None
+    model: str | None = None
+    runtime_status: str | None = None
+    repair: Literal["active", "none"] | None = None
+    operational_state: Literal[
+        "online", "offline", "unknown", "unstable", "repair", "spare", "retired"
+    ] | None = None
+    problems: bool = False
+    site_id: UUID | None = None
+    room_id: UUID | None = None
+    tags: list[str] = Field(default_factory=list)
+    limit: int = Field(default=100, ge=1, le=500)
+    offset: int = Field(default=0, ge=0)
+
+
+class InventorySiteOption(BaseModel):
+    id: UUID
+    name: str
+
+
+class InventoryRoomOption(BaseModel):
+    id: UUID
+    site_id: UUID
+    name: str
+
+
+class InventoryLocationOptions(BaseModel):
+    sites: list[InventorySiteOption] = Field(default_factory=list)
+    rooms: list[InventoryRoomOption] = Field(default_factory=list)
+
+
+class InventoryListMeta(BaseModel):
+    limit: int
+    offset: int
+    returned: int
+    location_options: InventoryLocationOptions = Field(default_factory=InventoryLocationOptions)
+
+
+class InventoryMinerListResponse(BaseModel):
+    data: list[InventoryMinerSummary]
+    meta: InventoryListMeta
+    error: None = None
+
+
+class InventoryMinerDetailResponse(BaseModel):
+    data: InventoryMinerDetail
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class InventoryAssetIDHistoryResponse(BaseModel):
+    data: list[InventoryAssetIDHistoryEntry]
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class InventoryFleetAttentionSummary(BaseModel):
+    offline: int
+    unknown: int
+    unstable: int
+    repair: int
+
+
+class InventoryFleetSummary(BaseModel):
+    total: int
+    runtime_online: int
+    runtime_offline: int
+    runtime_unknown: int
+    lifecycle_in_repair: int
+    lifecycle_spare: int
+    lifecycle_retired: int
+    attention: InventoryFleetAttentionSummary

backend/app/inventory/repository.py

@@ -0,0 +1,714 @@
+"""PostgreSQL persistence for the inventory domain."""
+
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from typing import Any
+from uuid import UUID
+
+import psycopg
+from psycopg.rows import dict_row
+
+from app.config import settings
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+
+TAG_TRIMMED_NAME_SQL = (
+    "regexp_replace(name, '^[[:space:]]+|[[:space:]]+$', '', 'g')"
+)
+
+MINER_SELECT = f"""
+    SELECT
+        miners.id,
+        miners.site_id,
+        miners.room_id,
+        miners.asset_tag,
+        miners.current_mac,
+        host(miners.current_ip) AS current_ip,
+        miners.hostname,
+        miners.miner_sn,
+        miners.control_board_sn,
+        miners.power_sn,
+        miners.model,
+        miners.firmware_version,
+        miners.lifecycle_status,
+        miners.status,
+        miners.notes,
+        miners.first_seen_at,
+        miners.last_seen_at,
+        miners.created_at,
+        miners.updated_at,
+        tag_data.tags
+    FROM miners
+    LEFT JOIN LATERAL (
+        SELECT COALESCE(
+            jsonb_agg(
+                jsonb_build_object(
+                    'id', tags.id,
+                    'name', tags.name,
+                    'created_at', tags.created_at,
+                    'updated_at', tags.updated_at
+                )
+                ORDER BY lower({TAG_TRIMMED_NAME_SQL}), tags.id
+            ),
+            '[]'::jsonb
+        ) AS tags
+        FROM miner_tags
+        JOIN tags ON tags.id = miner_tags.tag_id
+        WHERE miner_tags.miner_id = miners.id
+    ) tag_data ON true
+"""
+
+MINER_CURRENT_SELECT = f"""
+    SELECT
+        miners.id,
+        miners.site_id,
+        miners.room_id,
+        miners.asset_tag,
+        miners.current_mac,
+        host(miners.current_ip) AS current_ip,
+        miners.hostname,
+        miners.miner_sn,
+        miners.control_board_sn,
+        miners.power_sn,
+        miners.model,
+        miners.firmware_version,
+        miners.lifecycle_status,
+        miners.status,
+        miners.notes,
+        miners.first_seen_at,
+        miners.last_seen_at,
+        miners.created_at,
+        miners.updated_at,
+        tag_data.tags,
+        latest.observed_at,
+        latest.hashrate_ths,
+        latest.power_w,
+        latest.chip_temp_max_c,
+        latest.hash_stable
+    FROM miners
+    LEFT JOIN LATERAL (
+        SELECT COALESCE(
+            jsonb_agg(
+                jsonb_build_object(
+                    'id', tags.id,
+                    'name', tags.name,
+                    'created_at', tags.created_at,
+                    'updated_at', tags.updated_at
+                )
+                ORDER BY lower({TAG_TRIMMED_NAME_SQL}), tags.id
+            ),
+            '[]'::jsonb
+        ) AS tags
+        FROM miner_tags
+        JOIN tags ON tags.id = miner_tags.tag_id
+        WHERE miner_tags.miner_id = miners.id
+    ) tag_data ON true
+    LEFT JOIN LATERAL (
+        SELECT snapshots.observed_at,
+            ROUND((snapshots.mhs_av / 1000000.0)::numeric, 2)::float
+                AS hashrate_ths,
+            ROUND(snapshots.power_w::numeric, 2)::float AS power_w,
+            ROUND(snapshots.chip_temp_max_c::numeric, 2)::float
+                AS chip_temp_max_c,
+            snapshots.hash_stable
+        FROM miner_status_snapshots AS snapshots
+        WHERE snapshots.miner_id = miners.id
+        ORDER BY snapshots.observed_at DESC, snapshots.id DESC
+        LIMIT 1
+    ) latest ON true
+"""
+
+ACTIVE_REPAIR_STATUSES = (
+    "OPEN",
+    "IN_PROGRESS",
+    "WAITING_FOR_PARTS",
+    "READY_FOR_TEST",
+)
+
+OPERATIONAL_STATE_SQL = """
+    CASE
+        WHEN active_repair.id IS NOT NULL OR miners.lifecycle_status = 'in_repair'
+            THEN 'repair'
+        WHEN miners.lifecycle_status = 'retired' THEN 'retired'
+        WHEN miners.lifecycle_status = 'spare' THEN 'spare'
+        WHEN lower(trim(miners.status)) = 'offline' THEN 'offline'
+        WHEN latest.hash_stable = false THEN 'unstable'
+        WHEN lower(trim(miners.status)) = 'online' THEN 'online'
+        ELSE 'unknown'
+    END
+"""
+
+FLEET_SELECT = f"""
+    SELECT
+        miners.id, miners.asset_tag, miners.current_mac,
+        host(miners.current_ip) AS current_ip, miners.model, miners.miner_sn,
+        miners.lifecycle_status, miners.status, miners.created_at,
+        miners.updated_at, miners.last_seen_at, tag_data.tags,
+        latest.observed_at, latest.hashrate_ths, latest.power_w,
+        latest.chip_temp_max_c, latest.hash_stable,
+        active_repair.id AS active_repair_id,
+        active_repair.status AS active_repair_status,
+        active_repair.reason AS active_repair_reason,
+        {{location_fields}}
+    FROM miners
+    LEFT JOIN LATERAL (
+        SELECT COALESCE(
+            jsonb_agg(
+                jsonb_build_object(
+                    'id', tags.id, 'name', tags.name,
+                    'created_at', tags.created_at, 'updated_at', tags.updated_at
+                ) ORDER BY lower({TAG_TRIMMED_NAME_SQL}), tags.id
+            ), '[]'::jsonb
+        ) AS tags
+        FROM miner_tags JOIN tags ON tags.id = miner_tags.tag_id
+        WHERE miner_tags.miner_id = miners.id
+    ) tag_data ON true
+    LEFT JOIN LATERAL (
+        SELECT snapshots.observed_at,
+            ROUND((snapshots.mhs_av / 1000000.0)::numeric, 2)::float AS hashrate_ths,
+            ROUND(snapshots.power_w::numeric, 2)::float AS power_w,
+            ROUND(snapshots.chip_temp_max_c::numeric, 2)::float AS chip_temp_max_c,
+            snapshots.hash_stable
+        FROM miner_status_snapshots snapshots
+        WHERE snapshots.miner_id = miners.id
+        ORDER BY snapshots.observed_at DESC, snapshots.id DESC
+        LIMIT 1
+    ) latest ON true
+    LEFT JOIN LATERAL (
+        SELECT repairs.id, repairs.status, repairs.reason
+        FROM repairs
+        WHERE repairs.miner_id = miners.id AND repairs.status = ANY(%s)
+        ORDER BY repairs.opened_at, repairs.id
+        LIMIT 1
+    ) active_repair ON true
+    {{location_join}}
+"""
+
+LOCATION_FIELDS = """
+    mapped.site_id, mapped.site_name, mapped.room_id, mapped.room_name,
+    mapped.location_position_id, mapped.rack_label, mapped.shelf_label,
+    mapped.position_label, mapped.position_index
+"""
+
+REDACTED_LOCATION_FIELDS = """
+    NULL::uuid AS site_id, NULL::text AS site_name,
+    NULL::uuid AS room_id, NULL::text AS room_name,
+    NULL::uuid AS location_position_id, NULL::text AS rack_label,
+    NULL::text AS shelf_label, NULL::text AS position_label,
+    NULL::integer AS position_index
+"""
+
+LOCATION_JOIN = """
+    LEFT JOIN LATERAL (
+        SELECT sites.id AS site_id, sites.name AS site_name, rooms.id AS room_id,
+            COALESCE(rooms.name, lp.room_name) AS room_name,
+            lp.id AS location_position_id, lp.rack_name AS rack_label,
+            lp.shelf_name AS shelf_label, lp.position_label, lp.position_index
+        FROM location_positions lp
+        LEFT JOIN rooms ON rooms.id = lp.room_id
+        LEFT JOIN sites ON sites.id = rooms.site_id
+        WHERE lp.miner_id = miners.id
+        ORDER BY lp.id
+        LIMIT 1
+    ) mapped ON true
+"""
+
+MINER_WRITE_COLUMNS = {
+    "site_id",
+    "room_id",
+    "asset_tag",
+    "current_mac",
+    "current_ip",
+    "hostname",
+    "miner_sn",
+    "control_board_sn",
+    "power_sn",
+    "model",
+    "firmware_version",
+    "lifecycle_status",
+    "status",
+    "notes",
+    "first_seen_at",
+    "last_seen_at",
+}
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+class InventoryRepository:
+    """Database-only inventory persistence with optional transaction binding."""
+
+    def __init__(
+        self,
+        connection_factory: ConnectionFactory | None = None,
+        *,
+        connection: psycopg.Connection | None = None,
+    ):
+        self._connection_factory = connection_factory or default_connection_factory
+        self._connection = connection
+
+    @contextmanager
+    def transaction(self) -> Iterator["InventoryRepository"]:
+        if self._connection is not None:
+            yield self
+            return
+
+        connection = self._connection_factory()
+        transaction_repository = InventoryRepository(
+            self._connection_factory,
+            connection=connection,
+        )
+        try:
+            yield transaction_repository
+            connection.commit()
+        except Exception:
+            connection.rollback()
+            raise
+        finally:
+            connection.close()
+
+    @contextmanager
+    def _connection_scope(
+        self,
+        *,
+        write: bool = False,
+    ) -> Iterator[psycopg.Connection]:
+        if self._connection is not None:
+            yield self._connection
+            return
+
+        connection = self._connection_factory()
+        try:
+            yield connection
+            if write:
+                connection.commit()
+        except Exception:
+            if write:
+                connection.rollback()
+            raise
+        finally:
+            connection.close()
+
+    @staticmethod
+    def _fetch_miner(
+        cur,
+        where_sql: str,
+        params: Sequence[Any],
+        *,
+        for_update: bool = False,
+    ) -> dict | None:
+        lock_sql = " FOR UPDATE OF miners" if for_update else ""
+        cur.execute(
+            f"{MINER_SELECT} WHERE {where_sql}{lock_sql}",
+            params,
+        )
+        row = cur.fetchone()
+        return dict(row) if row else None
+
+    def get_miner_by_id(self, miner_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                return self._fetch_miner(cur, "miners.id = %s", (miner_id,))
+
+    def get_current_miner_by_id(self, miner_id: UUID) -> dict | None:
+        """Return Inventory identity with its latest factual telemetry."""
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"{MINER_CURRENT_SELECT} WHERE miners.id = %s",
+                    (miner_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def get_miner_by_id_for_update(self, miner_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                return self._fetch_miner(
+                    cur,
+                    "miners.id = %s",
+                    (miner_id,),
+                    for_update=True,
+                )
+
+    def get_miner_by_asset_id(self, asset_id: str) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                return self._fetch_miner(
+                    cur,
+                    "lower(trim(miners.asset_tag)) = lower(trim(%s))",
+                    (asset_id,),
+                )
+
+    def list_miners(
+        self,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+        include_location_details: bool = False,
+    ) -> list[dict]:
+        return self.search_miners(
+            limit=limit,
+            offset=offset,
+            include_location_details=include_location_details,
+        )
+
+    def summarize_fleet(self) -> dict[str, Any]:
+        """Return exact fleet-wide counts using Inventory state semantics."""
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    WITH fleet_state AS (
+                        SELECT miners.status, miners.lifecycle_status,
+                            ({OPERATIONAL_STATE_SQL}) AS operational_state
+                        FROM miners
+                        LEFT JOIN LATERAL (
+                            SELECT snapshots.hash_stable
+                            FROM miner_status_snapshots AS snapshots
+                            WHERE snapshots.miner_id = miners.id
+                            ORDER BY snapshots.observed_at DESC, snapshots.id DESC
+                            LIMIT 1
+                        ) AS latest ON true
+                        LEFT JOIN LATERAL (
+                            SELECT repairs.id
+                            FROM repairs
+                            WHERE repairs.miner_id = miners.id
+                              AND repairs.status = ANY(%s)
+                            ORDER BY repairs.opened_at, repairs.id
+                            LIMIT 1
+                        ) AS active_repair ON true
+                    )
+                    SELECT count(*)::integer AS total,
+                        count(*) FILTER (
+                            WHERE lower(trim(status)) = 'online'
+                        )::integer AS runtime_online,
+                        count(*) FILTER (
+                            WHERE lower(trim(status)) = 'offline'
+                        )::integer AS runtime_offline,
+                        count(*) FILTER (
+                            WHERE lower(trim(status)) NOT IN ('online', 'offline')
+                               OR status IS NULL
+                        )::integer AS runtime_unknown,
+                        count(*) FILTER (
+                            WHERE lifecycle_status = 'in_repair'
+                        )::integer AS lifecycle_in_repair,
+                        count(*) FILTER (
+                            WHERE lifecycle_status = 'spare'
+                        )::integer AS lifecycle_spare,
+                        count(*) FILTER (
+                            WHERE lifecycle_status = 'retired'
+                        )::integer AS lifecycle_retired,
+                        count(*) FILTER (
+                            WHERE operational_state = 'offline'
+                        )::integer AS attention_offline,
+                        count(*) FILTER (
+                            WHERE operational_state = 'unknown'
+                        )::integer AS attention_unknown,
+                        count(*) FILTER (
+                            WHERE operational_state = 'unstable'
+                        )::integer AS attention_unstable,
+                        count(*) FILTER (
+                            WHERE operational_state = 'repair'
+                        )::integer AS attention_repair
+                    FROM fleet_state
+                    """,
+                    (list(ACTIVE_REPAIR_STATUSES),),
+                )
+                return dict(cur.fetchone())
+
+    def search_miners(
+        self,
+        *,
+        query: str | None = None,
+        asset_id: str | None = None,
+        lifecycle_status: str | None = None,
+        model: str | None = None,
+        runtime_status: str | None = None,
+        repair: str | None = None,
+        operational_state: str | None = None,
+        problems: bool = False,
+        site_id: UUID | None = None,
+        room_id: UUID | None = None,
+        tag_names: Sequence[str] = (),
+        limit: int = 100,
+        offset: int = 0,
+        include_location_details: bool = False,
+    ) -> list[dict]:
+        conditions: list[str] = []
+        params: list[Any] = [list(ACTIVE_REPAIR_STATUSES)]
+
+        if query:
+            pattern = f"%{query}%"
+            conditions.append(
+                """
+                (
+                    miners.asset_tag ILIKE %s
+                    OR miners.current_mac ILIKE %s
+                    OR host(miners.current_ip) ILIKE %s
+                    OR miners.model ILIKE %s
+                    OR miners.miner_sn ILIKE %s
+                    OR miners.control_board_sn ILIKE %s
+                    OR miners.power_sn ILIKE %s
+                    OR miners.notes ILIKE %s
+                )
+                """
+            )
+            params.extend([pattern] * 8)
+        if asset_id:
+            conditions.append("lower(trim(miners.asset_tag)) = lower(trim(%s))")
+            params.append(asset_id)
+        if lifecycle_status:
+            conditions.append("miners.lifecycle_status = %s")
+            params.append(lifecycle_status)
+        if model:
+            conditions.append("lower(trim(miners.model)) = lower(trim(%s))")
+            params.append(model)
+        if runtime_status:
+            conditions.append("lower(trim(miners.status)) = lower(trim(%s))")
+            params.append(runtime_status)
+        if repair == "active":
+            conditions.append("active_repair.id IS NOT NULL")
+        elif repair == "none":
+            conditions.append("active_repair.id IS NULL")
+        if operational_state:
+            conditions.append(f"({OPERATIONAL_STATE_SQL}) = %s")
+            params.append(operational_state)
+        if problems:
+            conditions.append(
+                f"({OPERATIONAL_STATE_SQL}) = ANY(%s)"
+            )
+            params.append(["offline", "unknown", "unstable", "repair"])
+        if site_id:
+            conditions.append("mapped.site_id = %s")
+            params.append(site_id)
+        if room_id:
+            conditions.append("mapped.room_id = %s")
+            params.append(room_id)
+        for tag_name in tag_names:
+            conditions.append(
+                f"""
+                EXISTS (
+                    SELECT 1
+                    FROM miner_tags search_miner_tags
+                    JOIN tags search_tags ON search_tags.id = search_miner_tags.tag_id
+                    WHERE search_miner_tags.miner_id = miners.id
+                      AND lower({TAG_TRIMMED_NAME_SQL.replace("name", "search_tags.name")})
+                          = %s
+                )
+                """
+            )
+            params.append(tag_name)
+
+        location_fields = (
+            LOCATION_FIELDS if include_location_details else REDACTED_LOCATION_FIELDS
+        )
+        location_join = LOCATION_JOIN if include_location_details else ""
+        select_sql = FLEET_SELECT.format(
+            location_fields=location_fields,
+            location_join=location_join,
+        )
+        where_sql = " AND ".join(conditions) if conditions else "true"
+        params.extend([limit, offset])
+
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    {select_sql}
+                    WHERE {where_sql}
+                    ORDER BY lower(trim(miners.asset_tag)) NULLS LAST,
+                        miners.created_at, miners.id
+                    LIMIT %s OFFSET %s
+                    """,
+                    params,
+                )
+                return [dict(row) for row in cur.fetchall()]
+
+    def list_location_filter_options(self) -> dict[str, list[dict]]:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT sites.id, sites.name
+                    FROM location_positions lp
+                    JOIN miners ON miners.id = lp.miner_id
+                    JOIN rooms ON rooms.id = lp.room_id
+                    JOIN sites ON sites.id = rooms.site_id
+                    GROUP BY sites.id, sites.name
+                    ORDER BY lower(sites.name), sites.id
+                    """
+                )
+                sites = [dict(row) for row in cur.fetchall()]
+                cur.execute(
+                    """
+                    SELECT rooms.id, rooms.site_id, rooms.name
+                    FROM location_positions lp
+                    JOIN miners ON miners.id = lp.miner_id
+                    JOIN rooms ON rooms.id = lp.room_id
+                    GROUP BY rooms.id, rooms.site_id, rooms.name
+                    ORDER BY lower(rooms.name), rooms.id
+                    """
+                )
+                rooms = [dict(row) for row in cur.fetchall()]
+        return {"sites": sites, "rooms": rooms}
+
+    def create_miner(self, values: Mapping[str, Any]) -> dict:
+        clean_values = {
+            key: value for key, value in values.items() if key in MINER_WRITE_COLUMNS
+        }
+        columns = list(clean_values)
+        params = [clean_values[column] for column in columns]
+
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                if columns:
+                    placeholders = ", ".join(["%s"] * len(columns))
+                    cur.execute(
+                        f"""
+                        INSERT INTO miners ({", ".join(columns)})
+                        VALUES ({placeholders})
+                        RETURNING id
+                        """,
+                        params,
+                    )
+                else:
+                    cur.execute("INSERT INTO miners DEFAULT VALUES RETURNING id")
+                miner_id = cur.fetchone()["id"]
+                return self._fetch_miner(cur, "miners.id = %s", (miner_id,))
+
+    def update_miner(self, miner_id: UUID, values: Mapping[str, Any]) -> dict | None:
+        clean_values = {
+            key: value for key, value in values.items() if key in MINER_WRITE_COLUMNS
+        }
+        if not clean_values:
+            return self.get_miner_by_id(miner_id)
+
+        assignments = [f"{column} = %s" for column in clean_values]
+        params = list(clean_values.values())
+        params.append(miner_id)
+
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    UPDATE miners
+                    SET {", ".join(assignments)}, updated_at = now()
+                    WHERE id = %s
+                    RETURNING id
+                    """,
+                    params,
+                )
+                row = cur.fetchone()
+                if not row:
+                    return None
+                return self._fetch_miner(cur, "miners.id = %s", (miner_id,))
+
+    def add_asset_id_history(
+        self,
+        miner_id: UUID,
+        old_asset_id: str | None,
+        new_asset_id: str,
+        changed_by: UUID,
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO miner_asset_id_history (
+                        miner_id,
+                        old_asset_id,
+                        new_asset_id,
+                        changed_by
+                    )
+                    VALUES (%s, %s, %s, %s)
+                    RETURNING
+                        id,
+                        miner_id,
+                        old_asset_id,
+                        new_asset_id,
+                        changed_at,
+                        changed_by
+                    """,
+                    (miner_id, old_asset_id, new_asset_id, changed_by),
+                )
+                return dict(cur.fetchone())
+
+    def list_asset_id_history(self, miner_id: UUID) -> list[dict]:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        history.id,
+                        history.miner_id,
+                        history.old_asset_id,
+                        history.new_asset_id,
+                        history.changed_at,
+                        history.changed_by,
+                        changed_by_user.display_name
+                            AS changed_by_display_name
+                    FROM miner_asset_id_history AS history
+                    JOIN users AS changed_by_user
+                      ON changed_by_user.id = history.changed_by
+                    WHERE history.miner_id = %s
+                    ORDER BY history.changed_at, history.id
+                    """,
+                    (miner_id,),
+                )
+                return [dict(row) for row in cur.fetchall()]
+
+    def list_tags(self) -> list[dict]:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    SELECT id, name, created_at, updated_at
+                    FROM tags
+                    ORDER BY lower({TAG_TRIMMED_NAME_SQL}), id
+                    """
+                )
+                return [dict(row) for row in cur.fetchall()]
+
+    def add_tag(self, miner_id: UUID, tag_name: str) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    INSERT INTO tags (name)
+                    VALUES (%s)
+                    ON CONFLICT (lower({TAG_TRIMMED_NAME_SQL}))
+                    DO UPDATE SET updated_at = tags.updated_at
+                    RETURNING id, name, created_at, updated_at
+                    """,
+                    (tag_name,),
+                )
+                tag = dict(cur.fetchone())
+                cur.execute(
+                    """
+                    INSERT INTO miner_tags (miner_id, tag_id)
+                    VALUES (%s, %s)
+                    ON CONFLICT (miner_id, tag_id) DO NOTHING
+                    """,
+                    (miner_id, tag["id"]),
+                )
+                return tag
+
+    def remove_tag(self, miner_id: UUID, tag_id: UUID) -> bool:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    "DELETE FROM miner_tags WHERE miner_id = %s AND tag_id = %s",
+                    (miner_id, tag_id),
+                )
+                return cur.rowcount > 0

backend/app/inventory/router.py

@@ -0,0 +1,175 @@
+"""Read-only HTTP routes for the Inventory domain."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.identity import require_permission, user_has_permission
+from app.inventory.dependencies import get_inventory_service
+from app.inventory.exceptions import (
+    DuplicateAssetID,
+    InventoryValidationError,
+    MinerNotFound,
+)
+from app.inventory.models import (
+    InventoryAssetIDHistoryResponse,
+    InventoryCreateRequest,
+    InventoryListMeta,
+    InventoryLocationOptions,
+    InventoryMetadataUpdateRequest,
+    InventoryMinerDetailResponse,
+    InventoryMinerListResponse,
+    InventorySearchFilters,
+)
+from app.inventory.service import InventoryService
+
+
+router = APIRouter(prefix="/api/inventory/miners", tags=["inventory"])
+require_inventory_read = require_permission("miners.view")
+require_inventory_write = require_permission("miners.update")
+
+InventoryServiceDependency = Annotated[
+    InventoryService,
+    Depends(get_inventory_service),
+]
+InventoryReadUser = Annotated[dict, Depends(require_inventory_read)]
+InventoryWriteUser = Annotated[dict, Depends(require_inventory_write)]
+InventoryQuery = Annotated[InventorySearchFilters, Query()]
+
+
+@router.post(
+    "",
+    response_model=InventoryMinerDetailResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_inventory_miner(
+    request: InventoryCreateRequest,
+    service: InventoryServiceDependency,
+    current_user: InventoryWriteUser,
+) -> InventoryMinerDetailResponse:
+    del current_user
+    try:
+        miner = service.create_miner(request)
+    except DuplicateAssetID as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except InventoryValidationError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+
+    return InventoryMinerDetailResponse(data=miner)
+
+
+@router.patch("/{miner_id}", response_model=InventoryMinerDetailResponse)
+def update_inventory_miner_metadata(
+    miner_id: UUID,
+    request: InventoryMetadataUpdateRequest,
+    service: InventoryServiceDependency,
+    current_user: InventoryWriteUser,
+) -> InventoryMinerDetailResponse:
+    try:
+        miner = service.update_metadata(
+            miner_id,
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except MinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Miner not found",
+        ) from exc
+    except DuplicateAssetID as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except InventoryValidationError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+
+    return InventoryMinerDetailResponse(data=miner)
+
+
+@router.get("", response_model=InventoryMinerListResponse)
+def list_inventory_miners(
+    filters: InventoryQuery,
+    service: InventoryServiceDependency,
+    current_user: InventoryReadUser,
+) -> InventoryMinerListResponse:
+    include_location_details = user_has_permission(current_user, "locations.view")
+    if (filters.site_id or filters.room_id) and not include_location_details:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Location viewing permission is required for location filters",
+        )
+    try:
+        miners = service.search_miners(
+            filters,
+            include_location_details=include_location_details,
+        )
+    except InventoryValidationError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+
+    location_options = InventoryLocationOptions()
+    if include_location_details:
+        location_options = InventoryLocationOptions.model_validate(
+            service.list_location_filter_options()
+        )
+    return InventoryMinerListResponse(
+        data=miners,
+        meta=InventoryListMeta(
+            limit=filters.limit,
+            offset=filters.offset,
+            returned=len(miners),
+            location_options=location_options,
+        ),
+    )
+
+
+@router.get(
+    "/{miner_id}/asset-id-history",
+    response_model=InventoryAssetIDHistoryResponse,
+)
+def get_inventory_miner_asset_id_history(
+    miner_id: UUID,
+    service: InventoryServiceDependency,
+    current_user: InventoryReadUser,
+) -> InventoryAssetIDHistoryResponse:
+    del current_user
+    try:
+        history = service.get_asset_id_history(miner_id)
+    except MinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Miner not found",
+        ) from exc
+
+    return InventoryAssetIDHistoryResponse(data=history)
+
+
+@router.get("/{miner_id}", response_model=InventoryMinerDetailResponse)
+def get_inventory_miner(
+    miner_id: UUID,
+    service: InventoryServiceDependency,
+    current_user: InventoryReadUser,
+) -> InventoryMinerDetailResponse:
+    del current_user
+    try:
+        miner = service.get_miner(miner_id)
+    except MinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Miner not found",
+        ) from exc
+
+    return InventoryMinerDetailResponse(data=miner)

backend/app/inventory/service.py

@@ -0,0 +1,451 @@
+"""Business rules and orchestration for manual miner inventory."""
+
+from collections.abc import Iterable
+from typing import Any
+from uuid import UUID
+
+from psycopg.errors import UniqueViolation
+
+from app.inventory.exceptions import (
+    DuplicateAssetID,
+    InventoryValidationError,
+    MinerNotFound,
+)
+from app.inventory.models import (
+    InventoryAssetIDHistoryEntry,
+    InventoryCreateRequest,
+    InventoryFleetAttentionSummary,
+    InventoryFleetSummary,
+    InventoryMetadataUpdateRequest,
+    InventoryMinerDetail,
+    InventoryMinerSummary,
+    InventorySearchFilters,
+    InventoryTag,
+    InventoryUpdateRequest,
+)
+from app.inventory.repository import InventoryRepository
+
+
+ALLOWED_LIFECYCLE_STATUSES = frozenset(
+    {"active", "spare", "retired", "in_repair"}
+)
+
+
+class InventoryService:
+    """Inventory business rules independent of FastAPI and other transports."""
+
+    def __init__(self, repository: InventoryRepository):
+        self.repository = repository
+
+    @staticmethod
+    def normalize_asset_id(asset_id: str) -> str:
+        normalized = str(asset_id or "").strip()
+        if not normalized:
+            raise InventoryValidationError("Asset ID cannot be blank")
+        return normalized
+
+    @staticmethod
+    def validate_lifecycle_status(lifecycle_status: str) -> str:
+        normalized = str(lifecycle_status or "").strip().lower()
+        if normalized not in ALLOWED_LIFECYCLE_STATUSES:
+            allowed = ", ".join(sorted(ALLOWED_LIFECYCLE_STATUSES))
+            raise InventoryValidationError(
+                f"Lifecycle status must be one of: {allowed}"
+            )
+        return normalized
+
+    @staticmethod
+    def normalize_tags(tags: Iterable[str]) -> list[str]:
+        normalized: list[str] = []
+        seen: set[str] = set()
+        for raw_tag in tags:
+            tag = str(raw_tag or "").strip()
+            if not tag:
+                raise InventoryValidationError("Tag names cannot be blank")
+            key = tag.casefold()
+            if key not in seen:
+                normalized.append(tag)
+                seen.add(key)
+        return normalized
+
+    @staticmethod
+    def _clean_optional_text(value: str | None) -> str | None:
+        if value is None:
+            return None
+        cleaned = str(value).strip()
+        return cleaned or None
+
+    @staticmethod
+    def _tag_model(row: dict) -> InventoryTag:
+        return InventoryTag.model_validate(row)
+
+    @classmethod
+    def _summary_model(cls, row: dict) -> InventoryMinerSummary:
+        active_repair = None
+        if row.get("active_repair_id") is not None:
+            active_repair = {
+                "id": row["active_repair_id"],
+                "status": row["active_repair_status"],
+                "reason": row["active_repair_reason"],
+            }
+        return InventoryMinerSummary(
+            id=row["id"],
+            asset_id=row.get("asset_tag"),
+            current_mac=row.get("current_mac"),
+            current_ip=row.get("current_ip"),
+            model=row.get("model"),
+            miner_sn=row.get("miner_sn"),
+            lifecycle_status=row["lifecycle_status"],
+            runtime_status=row["status"],
+            site_id=row.get("site_id"),
+            site_name=row.get("site_name"),
+            room_id=row.get("room_id"),
+            room_name=row.get("room_name"),
+            location_position_id=row.get("location_position_id"),
+            rack_label=row.get("rack_label"),
+            shelf_label=row.get("shelf_label"),
+            position_label=row.get("position_label"),
+            position_index=row.get("position_index"),
+            observed_at=row.get("observed_at"),
+            hashrate_ths=row.get("hashrate_ths"),
+            power_w=row.get("power_w"),
+            chip_temp_max_c=row.get("chip_temp_max_c"),
+            hash_stable=row.get("hash_stable"),
+            active_repair=active_repair,
+            tags=[cls._tag_model(tag) for tag in row.get("tags") or []],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            last_seen_at=row.get("last_seen_at"),
+        )
+
+    @classmethod
+    def _detail_model(cls, row: dict) -> InventoryMinerDetail:
+        summary = cls._summary_model(row)
+        return InventoryMinerDetail(
+            **summary.model_dump(),
+            hostname=row.get("hostname"),
+            control_board_sn=row.get("control_board_sn"),
+            psu_serial=row.get("power_sn"),
+            firmware_version=row.get("firmware_version"),
+            notes=row.get("notes"),
+            first_seen_at=row.get("first_seen_at"),
+        )
+
+    def get_miner(self, miner_id: UUID) -> InventoryMinerDetail:
+        row = self.repository.get_miner_by_id(miner_id)
+        if not row:
+            raise MinerNotFound(miner_id)
+        return self._detail_model(row)
+
+    def get_current_miner(self, miner_id: UUID) -> InventoryMinerDetail:
+        """Return current Inventory identity and the latest observation."""
+        row = self.repository.get_current_miner_by_id(miner_id)
+        if not row:
+            raise MinerNotFound(miner_id)
+        return self._detail_model(row)
+
+    def get_asset_id_history(
+        self,
+        miner_id: UUID,
+    ) -> list[InventoryAssetIDHistoryEntry]:
+        if not self.repository.get_miner_by_id(miner_id):
+            raise MinerNotFound(miner_id)
+        return [
+            InventoryAssetIDHistoryEntry.model_validate(row)
+            for row in self.repository.list_asset_id_history(miner_id)
+        ]
+
+    def list_miners(
+        self,
+        *,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[InventoryMinerSummary]:
+        return [
+            self._summary_model(row)
+            for row in self.repository.list_miners(limit=limit, offset=offset)
+        ]
+
+    def summarize_fleet(self) -> InventoryFleetSummary:
+        row = self.repository.summarize_fleet()
+        return InventoryFleetSummary(
+            total=row["total"],
+            runtime_online=row["runtime_online"],
+            runtime_offline=row["runtime_offline"],
+            runtime_unknown=row["runtime_unknown"],
+            lifecycle_in_repair=row["lifecycle_in_repair"],
+            lifecycle_spare=row["lifecycle_spare"],
+            lifecycle_retired=row["lifecycle_retired"],
+            attention=InventoryFleetAttentionSummary(
+                offline=row["attention_offline"],
+                unknown=row["attention_unknown"],
+                unstable=row["attention_unstable"],
+                repair=row["attention_repair"],
+            ),
+        )
+
+    def search_miners(
+        self,
+        filters: InventorySearchFilters,
+        *,
+        include_location_details: bool = False,
+    ) -> list[InventoryMinerSummary]:
+        lifecycle_status = None
+        if filters.lifecycle_status:
+            lifecycle_status = self.validate_lifecycle_status(
+                filters.lifecycle_status
+            )
+        if (filters.site_id or filters.room_id) and not include_location_details:
+            raise InventoryValidationError(
+                "Location filters require location viewing permission"
+            )
+        asset_id = None
+        if filters.asset_id:
+            asset_id = self.normalize_asset_id(filters.asset_id)
+        tag_names = [
+            tag.casefold() for tag in self.normalize_tags(filters.tags)
+        ]
+        return [
+            self._summary_model(row)
+            for row in self.repository.search_miners(
+                query=self._clean_optional_text(filters.query),
+                asset_id=asset_id,
+                lifecycle_status=lifecycle_status,
+                model=self._clean_optional_text(filters.model),
+                runtime_status=self._clean_optional_text(filters.runtime_status),
+                repair=filters.repair,
+                operational_state=filters.operational_state,
+                problems=filters.problems,
+                site_id=filters.site_id,
+                room_id=filters.room_id,
+                tag_names=tag_names,
+                limit=filters.limit,
+                offset=filters.offset,
+                include_location_details=include_location_details,
+            )
+        ]
+
+    def list_location_filter_options(self) -> dict[str, list[dict]]:
+        return self.repository.list_location_filter_options()
+
+    def create_miner(
+        self,
+        request: InventoryCreateRequest,
+    ) -> InventoryMinerDetail:
+        asset_id = self.normalize_asset_id(request.asset_id)
+        lifecycle_status = self.validate_lifecycle_status(
+            request.lifecycle_status
+        )
+        tags = self.normalize_tags(request.tags)
+
+        if self.repository.get_miner_by_asset_id(asset_id):
+            raise DuplicateAssetID(asset_id)
+
+        values: dict[str, Any] = {
+            "asset_tag": asset_id,
+            "current_mac": self._clean_optional_text(request.current_mac),
+            "current_ip": str(request.current_ip) if request.current_ip else None,
+            "hostname": self._clean_optional_text(request.hostname),
+            "miner_sn": self._clean_optional_text(request.miner_sn),
+            "control_board_sn": self._clean_optional_text(
+                request.control_board_sn
+            ),
+            "power_sn": self._clean_optional_text(request.psu_serial),
+            "model": self._clean_optional_text(request.model),
+            "firmware_version": self._clean_optional_text(
+                request.firmware_version
+            ),
+            "lifecycle_status": lifecycle_status,
+            "site_id": request.site_id,
+            "room_id": request.room_id,
+            "notes": self._clean_optional_text(request.notes),
+            "status": "unknown",
+            "first_seen_at": None,
+            "last_seen_at": None,
+        }
+
+        try:
+            with self.repository.transaction() as repository:
+                row = repository.create_miner(values)
+                for tag in tags:
+                    repository.add_tag(row["id"], tag)
+                row = repository.get_miner_by_id(row["id"])
+                self._after_create(row)
+        except UniqueViolation as exc:
+            raise DuplicateAssetID(asset_id) from exc
+
+        return self._detail_model(row)
+
+    def update_metadata(
+        self,
+        miner_id: UUID,
+        request: InventoryMetadataUpdateRequest,
+        *,
+        actor_user_id: UUID,
+    ) -> InventoryMinerDetail:
+        fields_set = request.model_fields_set
+        if not fields_set:
+            raise InventoryValidationError(
+                "At least one metadata field must be provided"
+            )
+
+        requested_asset_id = None
+        if "asset_id" in fields_set:
+            if request.asset_id is None:
+                raise InventoryValidationError("Asset ID cannot be cleared")
+            requested_asset_id = self.normalize_asset_id(request.asset_id)
+
+        requested_values: dict[str, Any] = {}
+        field_map = {
+            "miner_sn": "miner_sn",
+            "psu_serial": "power_sn",
+            "model": "model",
+            "notes": "notes",
+        }
+        for model_field, database_column in field_map.items():
+            if model_field in fields_set:
+                requested_values[database_column] = self._clean_optional_text(
+                    getattr(request, model_field)
+                )
+
+        try:
+            with self.repository.transaction() as repository:
+                existing = repository.get_miner_by_id_for_update(miner_id)
+                if not existing:
+                    raise MinerNotFound(miner_id)
+
+                previous_asset_id = (
+                    str(existing.get("asset_tag") or "").strip() or None
+                )
+                asset_id_changed = (
+                    requested_asset_id is not None
+                    and requested_asset_id != previous_asset_id
+                )
+
+                values = {
+                    key: value
+                    for key, value in requested_values.items()
+                    if existing.get(key) != value
+                }
+                if asset_id_changed:
+                    duplicate = repository.get_miner_by_asset_id(
+                        requested_asset_id
+                    )
+                    if duplicate and duplicate["id"] != miner_id:
+                        raise DuplicateAssetID(requested_asset_id)
+                    values["asset_tag"] = requested_asset_id
+
+                if not values:
+                    return self._detail_model(existing)
+
+                self._before_update(existing, values)
+                row = repository.update_miner(miner_id, values)
+                if asset_id_changed:
+                    repository.add_asset_id_history(
+                        miner_id,
+                        previous_asset_id,
+                        requested_asset_id,
+                        actor_user_id,
+                    )
+                row = repository.get_miner_by_id(miner_id)
+                self._after_update(row)
+        except UniqueViolation as exc:
+            asset_id = requested_asset_id or "unknown"
+            raise DuplicateAssetID(asset_id) from exc
+
+        return self._detail_model(row)
+
+    def update_miner(
+        self,
+        miner_id: UUID,
+        request: InventoryUpdateRequest,
+    ) -> InventoryMinerDetail:
+        existing = self.repository.get_miner_by_id(miner_id)
+        if not existing:
+            raise MinerNotFound(miner_id)
+
+        values: dict[str, Any] = {}
+        fields_set = request.model_fields_set
+
+        if "asset_id" in fields_set:
+            if request.asset_id is None:
+                raise InventoryValidationError("Asset ID cannot be cleared")
+            asset_id = self.normalize_asset_id(request.asset_id)
+            existing_asset_id = (
+                str(existing.get("asset_tag") or "").strip() or None
+            )
+            if asset_id != existing_asset_id:
+                raise InventoryValidationError(
+                    "Asset ID changes require actor-attributed metadata update"
+                )
+        else:
+            asset_id = existing["asset_tag"]
+
+        if "lifecycle_status" in fields_set:
+            if request.lifecycle_status is None:
+                raise InventoryValidationError(
+                    "Lifecycle status cannot be cleared"
+                )
+            values["lifecycle_status"] = self.validate_lifecycle_status(
+                request.lifecycle_status
+            )
+
+        field_map = {
+            "current_mac": "current_mac",
+            "current_ip": "current_ip",
+            "hostname": "hostname",
+            "miner_sn": "miner_sn",
+            "control_board_sn": "control_board_sn",
+            "psu_serial": "power_sn",
+            "model": "model",
+            "firmware_version": "firmware_version",
+            "site_id": "site_id",
+            "room_id": "room_id",
+            "notes": "notes",
+        }
+        for model_field, database_column in field_map.items():
+            if model_field not in fields_set:
+                continue
+            value = getattr(request, model_field)
+            if model_field == "current_ip":
+                values[database_column] = str(value) if value else None
+            elif isinstance(value, str) or value is None:
+                values[database_column] = self._clean_optional_text(value)
+            else:
+                values[database_column] = value
+
+        desired_tags = None
+        if "tags" in fields_set:
+            desired_tags = self.normalize_tags(request.tags or [])
+
+        try:
+            with self.repository.transaction() as repository:
+                self._before_update(existing, values)
+                row = repository.update_miner(miner_id, values)
+                if desired_tags is not None:
+                    existing_tags = {
+                        str(tag["name"]).strip().casefold(): tag
+                        for tag in row.get("tags") or []
+                    }
+                    desired_keys = {tag.casefold() for tag in desired_tags}
+                    for key, tag in existing_tags.items():
+                        if key not in desired_keys:
+                            repository.remove_tag(miner_id, tag["id"])
+                    for tag in desired_tags:
+                        if tag.casefold() not in existing_tags:
+                            repository.add_tag(miner_id, tag)
+                    row = repository.get_miner_by_id(miner_id)
+                self._after_update(row)
+        except UniqueViolation as exc:
+            raise DuplicateAssetID(asset_id) from exc
+
+        return self._detail_model(row)
+
+    def _after_create(self, miner: dict) -> None:
+        """Extension point for later inventory integrations."""
+
+    def _before_update(self, existing: dict, changes: dict[str, Any]) -> None:
+        """Extension point for later inventory integrations."""
+
+    def _after_update(self, miner: dict) -> None:
+        """Extension point for later inventory integrations."""

backend/app/locations/__init__.py

@@ -0,0 +1,7 @@
+"""Mine Map location read domain."""
+
+from app.locations.models import MineMapResponse
+from app.locations.repository import LocationMapRepository
+from app.locations.service import LocationMapService
+
+__all__ = ["LocationMapRepository", "LocationMapService", "MineMapResponse"]

backend/app/locations/dependencies.py

@@ -0,0 +1,8 @@
+"""Dependency construction for the location read domain."""
+
+from app.locations.repository import LocationMapRepository
+from app.locations.service import LocationMapService
+
+
+def get_location_map_service() -> LocationMapService:
+    return LocationMapService(LocationMapRepository())

backend/app/locations/models.py

@@ -0,0 +1,140 @@
+"""Typed contracts for the read-only Mine Map."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class MapSite(BaseModel):
+    id: UUID
+    name: str
+
+
+class MapRoom(BaseModel):
+    id: UUID
+    site_id: UUID
+    site_name: str
+    name: str
+    sort_order: int
+
+
+class MapActiveRepair(BaseModel):
+    id: UUID
+    status: str
+    reason: str
+
+
+class MapPosition(BaseModel):
+    location_position_id: UUID
+    site_id: UUID | None = None
+    site_name: str | None = None
+    room_id: UUID | None = None
+    room_name: str
+    rack_name: str
+    shelf_name: str
+    shelf_index: int | None = None
+    position_index: int
+    position_label: str | None = None
+    position_kind: str
+    position_status: str
+    occupied: bool
+    expected_mac: str | None = None
+    equipment_label: str | None = None
+    notes: str | None = None
+    source_file: str | None = None
+    source_cell: str | None = None
+    conflict_reason: str | None = None
+    miner_id: UUID | None = None
+    asset_id: str | None = None
+    current_mac: str | None = None
+    current_ip: str | None = None
+    miner_status: str | None = None
+    hostname: str | None = None
+    miner_sn: str | None = None
+    power_sn: str | None = None
+    model: str | None = None
+    miner_type: str | None = None
+    firmware_version: str | None = None
+    lifecycle_status: str | None = None
+    last_seen_at: datetime | None = None
+    asset_state: str | None = None
+    observed_at: datetime | None = None
+    hashrate_ths: float | None = None
+    power_w: float | None = None
+    chip_temp_max_c: float | None = None
+    chip_temp_avg_c: float | None = None
+    hash_stable: bool | None = None
+    pool_rejected_percent: float | None = None
+    active_repair: MapActiveRepair | None = None
+
+
+class MapVirtualMiner(BaseModel):
+    miner_id: UUID | None = None
+    site_id: UUID | None = None
+    room_id: UUID | None = None
+    asset_id: str | None = None
+    asset_state: str
+    current_mac: str | None = None
+    current_ip: str | None = None
+    miner_status: str | None = None
+    status: str | None = None
+    hostname: str | None = None
+    miner_sn: str | None = None
+    power_sn: str | None = None
+    model: str | None = None
+    miner_type: str | None = None
+    firmware_version: str | None = None
+    lifecycle_status: str | None = None
+    last_seen_at: datetime | None = None
+    observed_at: datetime | None = None
+    hashrate_ths: float | None = None
+    power_w: float | None = None
+    chip_temp_max_c: float | None = None
+    chip_temp_avg_c: float | None = None
+    hash_stable: bool | None = None
+    active_repair: MapActiveRepair | None = None
+
+
+class MineMapData(BaseModel):
+    sites: list[MapSite]
+    rooms: list[MapRoom]
+    positions: list[MapPosition]
+    virtual_miners: list[MapVirtualMiner]
+
+
+class MineMapMeta(BaseModel):
+    generated_at: datetime
+    site_id: UUID | None = None
+    room_id: UUID | None = None
+    position_count: int
+    virtual_miner_count: int
+    miner_details_included: bool
+
+
+class MineMapResponse(BaseModel):
+    data: MineMapData
+    meta: MineMapMeta
+    error: None = None
+
+
+class MinerLocationDetail(BaseModel):
+    site_id: UUID | None = None
+    site_name: str | None = None
+    room_id: UUID | None = None
+    room_name: str | None = None
+    position_id: UUID
+    rack_label: str | None = None
+    shelf_label: str | None = None
+    position_label: str | None = None
+    position_index: int | None = None
+
+
+class LocationSummary(BaseModel):
+    sites: int
+    rooms: int
+    positions: int
+    occupied_positions: int
+    empty_positions: int
+    mapped_miners: int | None = None
+    unmapped_miners: int | None = None

backend/app/locations/repository.py

@@ -0,0 +1,257 @@
+"""Set-based PostgreSQL reads for Mine Map v1."""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any
+from uuid import UUID
+
+import psycopg
+from psycopg.rows import dict_row
+
+from app.config import settings
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+ACTIVE_REPAIR_STATUSES = (
+    "OPEN",
+    "IN_PROGRESS",
+    "WAITING_FOR_PARTS",
+    "READY_FOR_TEST",
+)
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+LATEST_TELEMETRY_SQL = """
+    LEFT JOIN LATERAL (
+        SELECT snapshots.observed_at,
+            ROUND((snapshots.mhs_av / 1000000.0)::numeric, 2)::float
+                AS hashrate_ths,
+            ROUND(snapshots.power_w::numeric, 2)::float AS power_w,
+            ROUND(snapshots.chip_temp_max_c::numeric, 2)::float
+                AS chip_temp_max_c,
+            ROUND(snapshots.chip_temp_avg_c::numeric, 2)::float
+                AS chip_temp_avg_c,
+            snapshots.hash_stable, snapshots.pool_rejected_percent
+        FROM miner_status_snapshots snapshots
+        WHERE snapshots.miner_id = miners.id
+        ORDER BY snapshots.observed_at DESC, snapshots.id DESC
+        LIMIT 1
+    ) latest ON true
+"""
+
+ACTIVE_REPAIR_SQL = """
+    LEFT JOIN LATERAL (
+        SELECT repairs.id, repairs.status, repairs.reason
+        FROM repairs
+        WHERE repairs.miner_id = miners.id AND repairs.status = ANY(%s)
+        ORDER BY repairs.opened_at, repairs.id
+        LIMIT 1
+    ) active_repair ON true
+"""
+
+
+class LocationMapRepository:
+    """Own all persistence used by the Mine Map read model."""
+
+    def __init__(
+        self,
+        connection_factory: ConnectionFactory | None = None,
+        *,
+        connection: psycopg.Connection | None = None,
+    ):
+        self._connection_factory = connection_factory or default_connection_factory
+        self._connection = connection
+
+    @contextmanager
+    def _connection_scope(self) -> Iterator[psycopg.Connection]:
+        if self._connection is not None:
+            yield self._connection
+            return
+        connection = self._connection_factory()
+        try:
+            yield connection
+        finally:
+            connection.close()
+
+    def read_map(
+        self,
+        *,
+        site_id: UUID | None = None,
+        room_id: UUID | None = None,
+    ) -> dict[str, list[dict[str, Any]]]:
+        position_where = []
+        position_params: list[Any] = [list(ACTIVE_REPAIR_STATUSES)]
+        virtual_where = [
+            "COALESCE(mls.asset_state, 'waiting_placement') = ANY(%s)",
+            "NOT EXISTS (SELECT 1 FROM location_positions assigned "
+            "WHERE assigned.miner_id = miners.id)",
+        ]
+        virtual_params: list[Any] = [
+            list(ACTIVE_REPAIR_STATUSES),
+            ["waiting_placement", "storage", "repair", "decommissioned"],
+        ]
+        if site_id is not None:
+            position_where.append("rooms.site_id = %s")
+            position_params.append(site_id)
+            virtual_where.append("miners.site_id = %s")
+            virtual_params.append(site_id)
+        if room_id is not None:
+            position_where.append("lp.room_id = %s")
+            position_params.append(room_id)
+            virtual_where.append("miners.room_id = %s")
+            virtual_params.append(room_id)
+        position_filter = (
+            "WHERE " + " AND ".join(position_where) if position_where else ""
+        )
+        virtual_filter = "WHERE " + " AND ".join(virtual_where)
+
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute("SELECT id, name FROM sites ORDER BY lower(name), id")
+                sites = [dict(row) for row in cur.fetchall()]
+                cur.execute(
+                    """
+                    SELECT rooms.id, rooms.site_id, sites.name AS site_name,
+                           rooms.name, rooms.sort_order
+                    FROM rooms JOIN sites ON sites.id = rooms.site_id
+                    ORDER BY lower(sites.name), rooms.sort_order,
+                             lower(rooms.name), rooms.id
+                    """
+                )
+                rooms = [dict(row) for row in cur.fetchall()]
+                cur.execute(
+                    f"""
+                    SELECT lp.id AS location_position_id, sites.id AS site_id,
+                        sites.name AS site_name, rooms.id AS room_id,
+                        COALESCE(rooms.name, lp.room_name) AS room_name,
+                        lp.rack_name, lp.shelf_name, lp.shelf_index,
+                        lp.position_index, lp.position_label, lp.position_kind,
+                        lp.position_status, (miners.id IS NOT NULL) AS occupied,
+                        lp.expected_mac, lp.equipment_label, lp.notes,
+                        lp.source_file, lp.source_cell, lp.conflict_reason,
+                        miners.id AS miner_id, miners.asset_tag AS asset_id,
+                        miners.current_mac, host(miners.current_ip) AS current_ip,
+                        miners.status AS miner_status, miners.hostname,
+                        miners.miner_sn, miners.power_sn, miners.model,
+                        miners.miner_type, miners.firmware_version,
+                        miners.lifecycle_status, miners.last_seen_at,
+                        COALESCE(mls.asset_state, 'unassigned') AS asset_state,
+                        latest.observed_at, latest.hashrate_ths, latest.power_w,
+                        latest.chip_temp_max_c, latest.chip_temp_avg_c,
+                        latest.hash_stable, latest.pool_rejected_percent,
+                        active_repair.id AS active_repair_id,
+                        active_repair.status AS active_repair_status,
+                        active_repair.reason AS active_repair_reason
+                    FROM location_positions lp
+                    LEFT JOIN rooms ON rooms.id = lp.room_id
+                    LEFT JOIN sites ON sites.id = rooms.site_id
+                    LEFT JOIN miners ON miners.id = lp.miner_id
+                    LEFT JOIN miner_location_states mls ON mls.miner_id = miners.id
+                    {LATEST_TELEMETRY_SQL}
+                    {ACTIVE_REPAIR_SQL}
+                    {position_filter}
+                    ORDER BY lower(sites.name) NULLS LAST,
+                        rooms.sort_order NULLS LAST,
+                        lower(COALESCE(rooms.name, lp.room_name)),
+                        lower(lp.rack_name), lp.shelf_index NULLS LAST,
+                        lower(lp.shelf_name), lp.position_index, lp.id
+                    """,
+                    position_params,
+                )
+                positions = [dict(row) for row in cur.fetchall()]
+                cur.execute(
+                    f"""
+                    SELECT miners.id AS miner_id, miners.site_id, miners.room_id,
+                        miners.asset_tag AS asset_id,
+                        COALESCE(mls.asset_state, 'waiting_placement') AS asset_state,
+                        miners.current_mac, host(miners.current_ip) AS current_ip,
+                        miners.status AS miner_status, miners.status, miners.hostname,
+                        miners.miner_sn, miners.power_sn, miners.model,
+                        miners.miner_type, miners.firmware_version,
+                        miners.lifecycle_status, miners.last_seen_at,
+                        latest.observed_at, latest.hashrate_ths, latest.power_w,
+                        latest.chip_temp_max_c, latest.chip_temp_avg_c,
+                        latest.hash_stable,
+                        active_repair.id AS active_repair_id,
+                        active_repair.status AS active_repair_status,
+                        active_repair.reason AS active_repair_reason
+                    FROM miners
+                    LEFT JOIN miner_location_states mls ON mls.miner_id = miners.id
+                    {LATEST_TELEMETRY_SQL}
+                    {ACTIVE_REPAIR_SQL}
+                    {virtual_filter}
+                    ORDER BY asset_state, lower(miners.asset_tag), miners.id
+                    """,
+                    virtual_params,
+                )
+                virtual_miners = [dict(row) for row in cur.fetchall()]
+        return {
+            "sites": sites,
+            "rooms": rooms,
+            "positions": positions,
+            "virtual_miners": virtual_miners,
+        }
+
+    def summarize_locations(self, *, include_miner_counts: bool) -> dict[str, Any]:
+        miner_counts = (
+            "count(DISTINCT lp.miner_id)::integer AS mapped_miners, "
+            "(SELECT count(*)::integer FROM miners WHERE NOT EXISTS ("
+            "SELECT 1 FROM location_positions assigned "
+            "WHERE assigned.miner_id = miners.id)) AS unmapped_miners"
+            if include_miner_counts
+            else "NULL::integer AS mapped_miners, NULL::integer AS unmapped_miners"
+        )
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    SELECT (SELECT count(*)::integer FROM sites) AS sites,
+                        (SELECT count(*)::integer FROM rooms) AS rooms,
+                        count(lp.id)::integer AS positions,
+                        count(lp.id) FILTER (
+                            WHERE lp.miner_id IS NOT NULL
+                        )::integer AS occupied_positions,
+                        count(lp.id) FILTER (
+                            WHERE lp.miner_id IS NULL
+                        )::integer AS empty_positions,
+                        {miner_counts}
+                    FROM location_positions AS lp
+                    """
+                )
+                return dict(cur.fetchone())
+
+    def get_miner_location(self, miner_id: UUID) -> dict[str, Any] | None:
+        """Return the one current physical position assigned to a miner."""
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT sites.id AS site_id, sites.name AS site_name,
+                        rooms.id AS room_id,
+                        COALESCE(rooms.name, position.room_name) AS room_name,
+                        position.id AS position_id,
+                        position.rack_name AS rack_label,
+                        position.shelf_name AS shelf_label,
+                        position.position_label,
+                        position.position_index
+                    FROM location_positions AS position
+                    LEFT JOIN rooms ON rooms.id = position.room_id
+                    LEFT JOIN sites ON sites.id = rooms.site_id
+                    WHERE position.miner_id = %s
+                    ORDER BY position.id
+                    LIMIT 1
+                    """,
+                    (miner_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None

backend/app/locations/router.py

@@ -0,0 +1,30 @@
+"""HTTP boundary for the read-only Mine Map API."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+
+from app.identity import require_permission, user_has_permission
+from app.locations.dependencies import get_location_map_service
+from app.locations.models import MineMapResponse
+from app.locations.service import LocationMapService
+
+
+router = APIRouter(prefix="/api/location", tags=["locations"])
+MapUser = Annotated[dict, Depends(require_permission("locations.view"))]
+MapService = Annotated[LocationMapService, Depends(get_location_map_service)]
+
+
+@router.get("/map", response_model=MineMapResponse)
+def get_mine_map(
+    current_user: MapUser,
+    service: MapService,
+    site_id: Annotated[UUID | None, Query()] = None,
+    room_id: Annotated[UUID | None, Query()] = None,
+) -> MineMapResponse:
+    return service.get_map(
+        site_id=site_id,
+        room_id=room_id,
+        include_miner_details=user_has_permission(current_user, "miners.view"),
+    )

backend/app/locations/service.py

@@ -0,0 +1,102 @@
+"""Mine Map read-model composition independent of HTTP."""
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import UUID
+
+from app.locations.models import (
+    LocationSummary,
+    MapActiveRepair,
+    MapPosition,
+    MapRoom,
+    MapSite,
+    MapVirtualMiner,
+    MineMapData,
+    MineMapMeta,
+    MineMapResponse,
+    MinerLocationDetail,
+)
+from app.locations.repository import LocationMapRepository
+
+
+MINER_FIELDS = {
+    "miner_id", "asset_id", "current_mac", "expected_mac", "current_ip", "miner_status",
+    "status",
+    "hostname", "miner_sn", "power_sn", "model", "miner_type",
+    "firmware_version", "lifecycle_status", "last_seen_at", "asset_state",
+    "observed_at", "hashrate_ths", "power_w", "chip_temp_max_c",
+    "chip_temp_avg_c", "hash_stable", "pool_rejected_percent",
+}
+
+
+class LocationMapService:
+    def __init__(self, repository: LocationMapRepository):
+        self.repository = repository
+
+    @staticmethod
+    def _repair(row: dict[str, Any]) -> MapActiveRepair | None:
+        repair_id = row.pop("active_repair_id", None)
+        status = row.pop("active_repair_status", None)
+        reason = row.pop("active_repair_reason", None)
+        if repair_id is None:
+            return None
+        return MapActiveRepair(id=repair_id, status=status, reason=reason)
+
+    @classmethod
+    def _redact(cls, row: dict[str, Any]) -> dict[str, Any]:
+        redacted = dict(row)
+        for field in MINER_FIELDS:
+            redacted[field] = None
+        redacted["active_repair_id"] = None
+        redacted["active_repair_status"] = None
+        redacted["active_repair_reason"] = None
+        return redacted
+
+    def get_map(
+        self,
+        *,
+        site_id: UUID | None = None,
+        room_id: UUID | None = None,
+        include_miner_details: bool,
+    ) -> MineMapResponse:
+        rows = self.repository.read_map(site_id=site_id, room_id=room_id)
+        positions = []
+        for source in rows["positions"]:
+            row = dict(source) if include_miner_details else self._redact(source)
+            row["active_repair"] = self._repair(row)
+            positions.append(MapPosition.model_validate(row))
+        virtual_miners = []
+        if include_miner_details:
+            for source in rows["virtual_miners"]:
+                row = dict(source)
+                row["active_repair"] = self._repair(row)
+                virtual_miners.append(MapVirtualMiner.model_validate(row))
+        return MineMapResponse(
+            data=MineMapData(
+                sites=[MapSite.model_validate(row) for row in rows["sites"]],
+                rooms=[MapRoom.model_validate(row) for row in rows["rooms"]],
+                positions=positions,
+                virtual_miners=virtual_miners,
+            ),
+            meta=MineMapMeta(
+                generated_at=datetime.now(timezone.utc),
+                site_id=site_id,
+                room_id=room_id,
+                position_count=len(positions),
+                virtual_miner_count=len(virtual_miners),
+                miner_details_included=include_miner_details,
+            ),
+        )
+
+    def get_miner_location(self, miner_id: UUID) -> MinerLocationDetail | None:
+        row = self.repository.get_miner_location(miner_id)
+        if row is None:
+            return None
+        return MinerLocationDetail.model_validate(row)
+
+    def summarize_locations(self, *, include_miner_counts: bool) -> LocationSummary:
+        return LocationSummary.model_validate(
+            self.repository.summarize_locations(
+                include_miner_counts=include_miner_counts
+            )
+        )

backend/app/miner_detail/__init__.py

@@ -0,0 +1 @@
+"""Permission-aware Miner Detail read model."""

backend/app/miner_detail/dependencies.py

@@ -0,0 +1,14 @@
+"""Dependency construction for the Miner Detail composition service."""
+
+from app.inventory.dependencies import get_inventory_service
+from app.locations.dependencies import get_location_map_service
+from app.miner_detail.service import MinerDetailService
+from app.repairs.dependencies import get_repair_center_service
+
+
+def get_miner_detail_service() -> MinerDetailService:
+    return MinerDetailService(
+        inventory_service=get_inventory_service(),
+        location_service=get_location_map_service(),
+        repair_service=get_repair_center_service(),
+    )

backend/app/miner_detail/models.py

@@ -0,0 +1,76 @@
+"""Typed contracts for the Internal Alpha Miner Detail overview."""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from app.inventory.models import InventoryMinerDetail
+from app.locations.models import MinerLocationDetail
+
+
+OperationalState = Literal[
+    "online", "offline", "unknown", "unstable", "repair", "spare", "retired"
+]
+
+
+class MinerDetailAccess(BaseModel):
+    can_view_locations: bool = False
+    can_read_repairs: bool = False
+    can_view_repairs: bool = False
+    can_read_components: bool = False
+
+
+class MinerDetailLocationSection(BaseModel):
+    available: bool
+    restricted: bool
+    location: MinerLocationDetail | None = None
+
+
+class MinerDetailRepairEpisode(BaseModel):
+    repair_id: UUID | None = None
+    source: Literal["modular", "legacy"]
+    active: bool
+    status: str
+    reason: str | None = None
+    opened_at: datetime | None = None
+    closed_at: datetime | None = None
+    latest_context: str | None = None
+    latest_context_at: datetime | None = None
+    parts_count: int | None = None
+    parts_summary: list[str] = Field(default_factory=list)
+
+
+class MinerDetailRepairSection(BaseModel):
+    available: bool
+    restricted: bool
+    active_repair: MinerDetailRepairEpisode | None = None
+    episodes: list[MinerDetailRepairEpisode] = Field(default_factory=list)
+
+
+class MinerDetailCapabilities(BaseModel):
+    can_view_map: bool = False
+    can_open_repair_center: bool = False
+    can_read_repair_history: bool = False
+    can_read_components: bool = False
+
+
+class MinerDetailOverviewData(BaseModel):
+    miner: InventoryMinerDetail
+    operational_state: OperationalState
+    location: MinerDetailLocationSection
+    repair: MinerDetailRepairSection
+    capabilities: MinerDetailCapabilities
+
+
+class MinerDetailOverviewMeta(BaseModel):
+    generated_at: datetime
+    database_query_count: int = Field(ge=1, le=3)
+
+
+class MinerDetailOverviewResponse(BaseModel):
+    data: MinerDetailOverviewData
+    meta: MinerDetailOverviewMeta
+    error: None = None
+

backend/app/miner_detail/router.py

@@ -0,0 +1,59 @@
+"""HTTP boundary for the Internal Alpha Miner Detail overview."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+
+from app.identity import require_permission, user_has_permission
+from app.inventory.exceptions import MinerNotFound
+from app.miner_detail.dependencies import get_miner_detail_service
+from app.miner_detail.models import (
+    MinerDetailAccess,
+    MinerDetailOverviewResponse,
+)
+from app.miner_detail.service import MinerDetailService
+
+
+router = APIRouter(prefix="/api/miners", tags=["miners"])
+MinerDetailUser = Annotated[dict, Depends(require_permission("miners.view"))]
+MinerDetailServiceDependency = Annotated[
+    MinerDetailService,
+    Depends(get_miner_detail_service),
+]
+
+
+@router.get(
+    "/{miner_id}/overview",
+    response_model=MinerDetailOverviewResponse,
+)
+def get_miner_detail_overview(
+    miner_id: UUID,
+    current_user: MinerDetailUser,
+    service: MinerDetailServiceDependency,
+    response: Response,
+) -> MinerDetailOverviewResponse:
+    response.headers["Cache-Control"] = "no-store"
+    try:
+        return service.get_overview(
+            miner_id,
+            MinerDetailAccess(
+                can_view_locations=user_has_permission(
+                    current_user, "locations.view"
+                ),
+                can_read_repairs=user_has_permission(
+                    current_user, "repairs.read"
+                ),
+                can_view_repairs=user_has_permission(
+                    current_user, "repairs.view"
+                ),
+                can_read_components=user_has_permission(
+                    current_user, "components.read"
+                ),
+            ),
+        )
+    except MinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Miner not found",
+        ) from exc

backend/app/miner_detail/service.py

@@ -0,0 +1,152 @@
+"""Composition service for the Internal Alpha Miner Detail overview."""
+
+from datetime import datetime, timezone
+from math import isfinite
+from uuid import UUID
+
+from app.inventory.models import InventoryMinerDetail
+from app.inventory.service import InventoryService
+from app.locations.service import LocationMapService
+from app.miner_detail.models import (
+    MinerDetailAccess,
+    MinerDetailCapabilities,
+    MinerDetailLocationSection,
+    MinerDetailOverviewData,
+    MinerDetailOverviewMeta,
+    MinerDetailOverviewResponse,
+    MinerDetailRepairEpisode,
+    MinerDetailRepairSection,
+    OperationalState,
+)
+from app.repairs.center_service import RepairCenterService
+from app.repairs.models import RepairCenterAccess, RepairCenterItem
+
+
+class MinerDetailService:
+    """Coordinate domain-owned current projections without transport logic."""
+
+    def __init__(
+        self,
+        inventory_service: InventoryService,
+        location_service: LocationMapService,
+        repair_service: RepairCenterService,
+    ):
+        self.inventory_service = inventory_service
+        self.location_service = location_service
+        self.repair_service = repair_service
+
+    @staticmethod
+    def _episode(item: RepairCenterItem) -> MinerDetailRepairEpisode:
+        return MinerDetailRepairEpisode(
+            repair_id=item.repair_id,
+            source=item.source,
+            active=item.active,
+            status=item.repair_status,
+            reason=item.reason,
+            opened_at=item.opened_at,
+            closed_at=item.closed_at,
+            latest_context=item.latest_context,
+            latest_context_at=item.latest_context_at,
+            parts_count=item.parts_count,
+            parts_summary=item.parts_summary,
+        )
+
+    @staticmethod
+    def _operational_state(
+        miner: InventoryMinerDetail,
+        active_repair: MinerDetailRepairEpisode | None,
+    ) -> OperationalState:
+        if active_repair is not None or miner.lifecycle_status == "in_repair":
+            return "repair"
+        if miner.lifecycle_status == "retired":
+            return "retired"
+        if miner.lifecycle_status == "spare":
+            return "spare"
+        runtime = (miner.runtime_status or "").strip().lower()
+        if runtime == "offline":
+            return "offline"
+        if miner.hash_stable is False:
+            return "unstable"
+        if runtime == "online":
+            return "online"
+        return "unknown"
+
+    def get_overview(
+        self,
+        miner_id: UUID,
+        access: MinerDetailAccess,
+    ) -> MinerDetailOverviewResponse:
+        miner = self.inventory_service.get_current_miner(miner_id)
+        # Location is owned by the permission-aware section below. Keep the
+        # shared projection from leaking location identifiers. Non-finite
+        # telemetry is not a factual display value and remains unavailable.
+        redacted = {
+            field: None
+            for field in (
+                "site_id", "site_name", "room_id", "room_name",
+                "location_position_id", "rack_label", "shelf_label",
+                "position_label", "position_index",
+            )
+        }
+        for field in ("hashrate_ths", "power_w", "chip_temp_max_c"):
+            value = getattr(miner, field)
+            if value is not None and not isfinite(value):
+                redacted[field] = None
+        miner = miner.model_copy(
+            update=redacted
+        )
+        location = (
+            self.location_service.get_miner_location(miner_id)
+            if access.can_view_locations
+            else None
+        )
+        repair_items = (
+            self.repair_service.list_miner_repairs(
+                miner_id,
+                RepairCenterAccess(
+                    can_read_repairs=True,
+                    can_view_miners=True,
+                ),
+            )
+            if access.can_read_repairs
+            else []
+        )
+        episodes = [self._episode(item) for item in repair_items]
+        active_repair = next(
+            (
+                episode for episode in episodes
+                if episode.active and episode.source == "modular"
+            ),
+            None,
+        )
+        query_count = 1 + int(access.can_view_locations) + int(access.can_read_repairs)
+        return MinerDetailOverviewResponse(
+            data=MinerDetailOverviewData(
+                miner=miner,
+                operational_state=self._operational_state(miner, active_repair),
+                location=MinerDetailLocationSection(
+                    available=access.can_view_locations,
+                    restricted=not access.can_view_locations,
+                    location=location,
+                ),
+                repair=MinerDetailRepairSection(
+                    available=access.can_read_repairs,
+                    restricted=not access.can_read_repairs,
+                    active_repair=active_repair,
+                    episodes=episodes,
+                ),
+                capabilities=MinerDetailCapabilities(
+                    can_view_map=bool(
+                        access.can_view_locations and location is not None
+                        and location.site_id and location.room_id
+                    ),
+                    can_open_repair_center=access.can_view_repairs,
+                    can_read_repair_history=access.can_read_repairs,
+                    can_read_components=access.can_read_components,
+                ),
+            ),
+            meta=MinerDetailOverviewMeta(
+                generated_at=datetime.now(timezone.utc),
+                database_query_count=query_count,
+            ),
+        )

backend/app/monitoring/__init__.py

@@ -0,0 +1 @@
+"""Historical monitoring read models."""

backend/app/monitoring/dependencies.py

@@ -0,0 +1,8 @@
+"""Dependency construction for the Monitoring domain."""
+
+from app.monitoring.repository import MonitoringRepository
+from app.monitoring.service import MonitoringService
+
+
+def get_monitoring_service() -> MonitoringService:
+    return MonitoringService(MonitoringRepository())

backend/app/monitoring/exceptions.py

@@ -0,0 +1,13 @@
+"""Monitoring domain exceptions."""
+
+
+class MonitoringError(Exception):
+    """Base monitoring-domain error."""
+
+
+class MonitoringValidationError(MonitoringError):
+    """The requested trend scope or range is invalid."""
+
+
+class MonitoringScopeNotFound(MonitoringError):
+    """The requested durable scope does not exist."""

backend/app/monitoring/frontend.py

@@ -0,0 +1,70 @@
+"""Authenticated frontend routes for Monitoring Trends."""
+
+from pathlib import Path
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import HTMLResponse, Response
+
+from app.frontend.views import render_app_page
+from app.identity import require_permission, user_has_permission
+from app.monitoring.models import (
+    MonitoringTrendQuery,
+    TrendRange,
+    TrendScopeType,
+)
+
+
+router = APIRouter(tags=["frontend"])
+STATIC_ROOT = Path(__file__).parents[1] / "frontend" / "static"
+MonitoringUser = Annotated[dict, Depends(require_permission("miners.view"))]
+
+
+@router.get("/assets/minerops-monitoring-trends.css", include_in_schema=False)
+def monitoring_trends_styles() -> Response:
+    return Response(
+        (STATIC_ROOT / "monitoring-trends.css").read_text(encoding="utf-8"),
+        media_type="text/css",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get("/assets/minerops-monitoring-trends.js", include_in_schema=False)
+def monitoring_trends_script() -> Response:
+    return Response(
+        (STATIC_ROOT / "monitoring-trends.js").read_text(encoding="utf-8"),
+        media_type="text/javascript",
+        headers={"Cache-Control": "no-store"},
+    )
+
+
+@router.get(
+    "/monitoring/analytics",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+def monitoring_analytics_page(
+    current_user: MonitoringUser,
+    scope: Annotated[TrendScopeType, Query()] = "fleet",
+    scope_id: Annotated[UUID | None, Query()] = None,
+    time_range: Annotated[TrendRange, Query(alias="range")] = "24h",
+) -> str:
+    try:
+        query = MonitoringTrendQuery(
+            scope=scope, scope_id=scope_id, range=time_range
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    if query.scope in {"site", "room"} and not user_has_permission(
+        current_user, "locations.view"
+    ):
+        raise HTTPException(
+            status_code=403,
+            detail="Location viewing permission is required for this scope",
+        )
+    return render_app_page(
+        "analytics",
+        current_user,
+        lambda permission: user_has_permission(current_user, permission),
+    )

backend/app/monitoring/models.py

@@ -0,0 +1,98 @@
+"""Typed contracts for bounded historical telemetry trends."""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+TrendScopeType = Literal["fleet", "site", "room", "miner"]
+TrendRange = Literal["6h", "24h", "7d"]
+TrendMetric = Literal["hashrate", "power"]
+TrendAttribution = Literal["current_placement_cohort", "miner_identity", "fleet"]
+
+
+class MonitoringTrendQuery(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    scope: TrendScopeType = "fleet"
+    scope_id: UUID | None = None
+    time_range: TrendRange = Field(default="24h", alias="range")
+
+    @model_validator(mode="after")
+    def validate_scope_identity(self) -> "MonitoringTrendQuery":
+        if self.scope == "fleet" and self.scope_id is not None:
+            raise ValueError("scope_id is not allowed for fleet scope")
+        if self.scope != "fleet" and self.scope_id is None:
+            raise ValueError("scope_id is required for this scope")
+        return self
+
+
+class MonitoringScope(BaseModel):
+    type: TrendScopeType
+    id: UUID | None = None
+    label: str
+
+
+class MonitoringSiteOption(BaseModel):
+    id: UUID
+    name: str
+
+
+class MonitoringRoomOption(BaseModel):
+    id: UUID
+    site_id: UUID
+    name: str
+
+
+class MonitoringAvailableScopes(BaseModel):
+    fleet: bool = True
+    sites: list[MonitoringSiteOption] = Field(default_factory=list)
+    rooms: list[MonitoringRoomOption] = Field(default_factory=list)
+
+
+class MonitoringTrendPoint(BaseModel):
+    bucket_start: datetime
+    bucket_end: datetime
+    value: float | None = None
+    observation_count: int
+    metric_sample_count: int
+    observed_miner_count: int
+    contributing_miner_count: int
+    scoped_miner_count: int
+    incomplete: bool = False
+
+
+class MonitoringTrendSeries(BaseModel):
+    metric: TrendMetric
+    unit: Literal["TH/s", "W"]
+    label: str
+    points: list[MonitoringTrendPoint]
+
+
+class MonitoringTrendData(BaseModel):
+    scope: MonitoringScope
+    series: list[MonitoringTrendSeries]
+    available_scopes: MonitoringAvailableScopes
+
+
+class MonitoringTrendMeta(BaseModel):
+    generated_at: datetime
+    latest_observed_at: datetime | None = None
+    source: Literal["raw_snapshots"] = "raw_snapshots"
+    attribution: TrendAttribution
+    time_range: TrendRange = Field(alias="range")
+    bucket_seconds: int
+    maximum_points: int = 200
+    completeness: Literal["not_guaranteed"] = "not_guaranteed"
+    current_bucket_incomplete: bool
+    database_query_count: int = Field(ge=1, le=2)
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class MonitoringTrendResponse(BaseModel):
+    data: MonitoringTrendData
+    meta: MonitoringTrendMeta
+    error: None = None

backend/app/monitoring/repository.py

@@ -0,0 +1,237 @@
+"""PostgreSQL persistence for bounded monitoring trends."""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+from typing import Any
+from uuid import UUID
+
+import psycopg
+from psycopg.rows import dict_row
+
+from app.config import settings
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+TREND_SQL = """
+WITH requested AS (
+    SELECT %s::text AS scope_type, %s::uuid AS scope_id,
+        %s::timestamptz AS window_start, %s::timestamptz AS window_end,
+        %s::interval AS bucket_width
+),
+current_locations AS (
+    SELECT miners.id AS miner_id,
+        COALESCE(position.site_id, miners.site_id) AS site_id,
+        COALESCE(position.room_id, miners.room_id) AS room_id
+    FROM miners
+    LEFT JOIN LATERAL (
+        SELECT rooms.site_id, location_positions.room_id
+        FROM location_positions
+        LEFT JOIN rooms ON rooms.id = location_positions.room_id
+        WHERE location_positions.miner_id = miners.id
+        ORDER BY location_positions.id
+        LIMIT 1
+    ) AS position ON true
+),
+scope_meta AS (
+    SELECT requested.scope_type, requested.scope_id,
+        CASE requested.scope_type
+            WHEN 'fleet' THEN true
+            WHEN 'miner' THEN EXISTS (
+                SELECT 1 FROM miners WHERE miners.id = requested.scope_id
+            )
+            WHEN 'site' THEN EXISTS (
+                SELECT 1 FROM sites WHERE sites.id = requested.scope_id
+            )
+            WHEN 'room' THEN EXISTS (
+                SELECT 1 FROM rooms WHERE rooms.id = requested.scope_id
+            )
+            ELSE false
+        END AS scope_exists,
+        CASE requested.scope_type
+            WHEN 'fleet' THEN 'Fleet'
+            WHEN 'miner' THEN (
+                SELECT COALESCE(NULLIF(trim(miners.asset_tag), ''), miners.id::text)
+                FROM miners WHERE miners.id = requested.scope_id
+            )
+            WHEN 'site' THEN (
+                SELECT sites.name FROM sites WHERE sites.id = requested.scope_id
+            )
+            WHEN 'room' THEN (
+                SELECT rooms.name FROM rooms WHERE rooms.id = requested.scope_id
+            )
+        END AS scope_label
+    FROM requested
+),
+scoped_miners AS (
+    SELECT miners.id
+    FROM miners
+    JOIN current_locations ON current_locations.miner_id = miners.id
+    CROSS JOIN requested
+    WHERE requested.scope_type = 'fleet'
+       OR (requested.scope_type = 'miner' AND miners.id = requested.scope_id)
+       OR (requested.scope_type = 'site'
+           AND current_locations.site_id = requested.scope_id)
+       OR (requested.scope_type = 'room'
+           AND current_locations.room_id = requested.scope_id)
+),
+scope_count AS (
+    SELECT count(*)::integer AS scoped_miner_count FROM scoped_miners
+),
+buckets AS (
+    SELECT bucket_start,
+        bucket_start + requested.bucket_width AS bucket_end
+    FROM requested
+    CROSS JOIN LATERAL generate_series(
+        requested.window_start,
+        requested.window_end - requested.bucket_width,
+        requested.bucket_width
+    ) AS bucket_start
+),
+per_miner_bucket AS (
+    SELECT date_bin(
+            requested.bucket_width,
+            snapshots.observed_at,
+            '1970-01-01 00:00:00+00'::timestamptz
+        ) AS bucket_start,
+        snapshots.miner_id,
+        count(*)::integer AS observation_count,
+        count(snapshots.mhs_av)::integer AS hashrate_sample_count,
+        count(snapshots.power_w)::integer AS power_sample_count,
+        avg(snapshots.mhs_av) AS average_mhs_av,
+        avg(snapshots.power_w) AS average_power_w
+    FROM miner_status_snapshots AS snapshots
+    JOIN scoped_miners ON scoped_miners.id = snapshots.miner_id
+    CROSS JOIN requested
+    WHERE snapshots.observed_at >= requested.window_start
+      AND snapshots.observed_at < requested.window_end
+    GROUP BY bucket_start, snapshots.miner_id
+),
+bucket_totals AS (
+    SELECT per_miner_bucket.bucket_start,
+        sum(per_miner_bucket.observation_count)::integer AS observation_count,
+        sum(per_miner_bucket.hashrate_sample_count)::integer
+            AS hashrate_sample_count,
+        sum(per_miner_bucket.power_sample_count)::integer AS power_sample_count,
+        count(*)::integer AS observed_miner_count,
+        count(*) FILTER (
+            WHERE per_miner_bucket.hashrate_sample_count > 0
+        )::integer AS hashrate_contributing_miner_count,
+        count(*) FILTER (
+            WHERE per_miner_bucket.power_sample_count > 0
+        )::integer AS power_contributing_miner_count,
+        CASE WHEN sum(per_miner_bucket.hashrate_sample_count) > 0
+            THEN sum(per_miner_bucket.average_mhs_av) FILTER (
+                WHERE per_miner_bucket.hashrate_sample_count > 0
+            ) / 1000000.0
+        END AS hashrate_ths,
+        CASE WHEN sum(per_miner_bucket.power_sample_count) > 0
+            THEN sum(per_miner_bucket.average_power_w) FILTER (
+                WHERE per_miner_bucket.power_sample_count > 0
+            )
+        END AS power_w
+    FROM per_miner_bucket
+    GROUP BY per_miner_bucket.bucket_start
+),
+latest AS (
+    SELECT max(snapshots.observed_at) AS latest_observed_at
+    FROM miner_status_snapshots AS snapshots
+    JOIN scoped_miners ON scoped_miners.id = snapshots.miner_id
+    CROSS JOIN requested
+    WHERE snapshots.observed_at >= requested.window_start
+      AND snapshots.observed_at < requested.window_end
+)
+SELECT scope_meta.scope_exists, scope_meta.scope_label,
+    buckets.bucket_start, buckets.bucket_end,
+    bucket_totals.hashrate_ths, bucket_totals.power_w,
+    COALESCE(bucket_totals.observation_count, 0) AS observation_count,
+    COALESCE(bucket_totals.hashrate_sample_count, 0) AS hashrate_sample_count,
+    COALESCE(bucket_totals.power_sample_count, 0) AS power_sample_count,
+    COALESCE(bucket_totals.observed_miner_count, 0) AS observed_miner_count,
+    COALESCE(bucket_totals.hashrate_contributing_miner_count, 0)
+        AS hashrate_contributing_miner_count,
+    COALESCE(bucket_totals.power_contributing_miner_count, 0)
+        AS power_contributing_miner_count,
+    scope_count.scoped_miner_count, latest.latest_observed_at
+FROM buckets
+CROSS JOIN scope_meta
+CROSS JOIN scope_count
+CROSS JOIN latest
+LEFT JOIN bucket_totals ON bucket_totals.bucket_start = buckets.bucket_start
+ORDER BY buckets.bucket_start
+"""
+
+
+SCOPE_OPTIONS_SQL = """
+SELECT option_type, id, site_id, name
+FROM (
+    SELECT 'site'::text AS option_type, sites.id,
+           NULL::uuid AS site_id, sites.name
+    FROM sites
+    UNION ALL
+    SELECT 'room'::text AS option_type, rooms.id,
+           rooms.site_id, rooms.name
+    FROM rooms
+) AS options
+ORDER BY option_type DESC, lower(name), id
+"""
+
+
+class MonitoringRepository:
+    """Own the set-based raw-snapshot monitoring read path."""
+
+    def __init__(
+        self,
+        connection_factory: ConnectionFactory | None = None,
+        *,
+        connection: psycopg.Connection | None = None,
+    ):
+        self._connection_factory = connection_factory or default_connection_factory
+        self._connection = connection
+
+    @contextmanager
+    def _connection_scope(self) -> Iterator[psycopg.Connection]:
+        if self._connection is not None:
+            yield self._connection
+            return
+        connection = self._connection_factory()
+        try:
+            yield connection
+        finally:
+            connection.close()
+
+    def read_trends(
+        self,
+        *,
+        scope: str,
+        scope_id: UUID | None,
+        window_start: datetime,
+        window_end: datetime,
+        bucket_width: timedelta,
+    ) -> list[dict[str, Any]]:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    TREND_SQL,
+                    (scope, scope_id, window_start, window_end, bucket_width),
+                )
+                return [dict(row) for row in cur.fetchall()]
+
+    def list_location_scope_options(self) -> list[dict[str, Any]]:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(SCOPE_OPTIONS_SQL)
+                return [dict(row) for row in cur.fetchall()]

backend/app/monitoring/router.py

@@ -0,0 +1,61 @@
+"""HTTP boundary for bounded historical monitoring trends."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+
+from app.identity import require_permission, user_has_permission
+from app.monitoring.dependencies import get_monitoring_service
+from app.monitoring.exceptions import MonitoringScopeNotFound
+from app.monitoring.models import (
+    MonitoringTrendQuery,
+    MonitoringTrendResponse,
+    TrendRange,
+    TrendScopeType,
+)
+from app.monitoring.service import MonitoringService
+
+
+router = APIRouter(prefix="/api/monitoring", tags=["monitoring"])
+MonitoringUser = Annotated[dict, Depends(require_permission("miners.view"))]
+MonitoringServiceDependency = Annotated[
+    MonitoringService,
+    Depends(get_monitoring_service),
+]
+
+
+@router.get("/trends", response_model=MonitoringTrendResponse)
+def get_monitoring_trends(
+    current_user: MonitoringUser,
+    service: MonitoringServiceDependency,
+    response: Response,
+    scope: Annotated[TrendScopeType, Query()] = "fleet",
+    scope_id: Annotated[UUID | None, Query()] = None,
+    time_range: Annotated[TrendRange, Query(alias="range")] = "24h",
+) -> MonitoringTrendResponse:
+    try:
+        query = MonitoringTrendQuery(
+            scope=scope, scope_id=scope_id, range=time_range
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)
+        ) from exc
+    can_view_locations = user_has_permission(current_user, "locations.view")
+    if query.scope in {"site", "room"} and not can_view_locations:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Location viewing permission is required for this scope",
+        )
+    response.headers["Cache-Control"] = "no-store"
+    try:
+        return service.get_trends(
+            query,
+            include_location_scopes=can_view_locations,
+        )
+    except MonitoringScopeNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        ) from exc

backend/app/monitoring/service.py

@@ -0,0 +1,173 @@
+"""Business semantics for bounded historical monitoring trends."""
+
+from datetime import datetime, timedelta, timezone
+from uuid import UUID
+
+from app.monitoring.exceptions import MonitoringScopeNotFound
+from app.monitoring.models import (
+    MonitoringAvailableScopes,
+    MonitoringRoomOption,
+    MonitoringScope,
+    MonitoringSiteOption,
+    MonitoringTrendData,
+    MonitoringTrendMeta,
+    MonitoringTrendPoint,
+    MonitoringTrendQuery,
+    MonitoringTrendResponse,
+    MonitoringTrendSeries,
+)
+from app.monitoring.repository import MonitoringRepository
+
+
+RANGE_CONFIGURATION = {
+    "6h": (timedelta(hours=6), timedelta(minutes=5)),
+    "24h": (timedelta(hours=24), timedelta(minutes=15)),
+    "7d": (timedelta(days=7), timedelta(hours=1)),
+}
+MAXIMUM_POINTS = 200
+
+
+class MonitoringService:
+    """Coordinate factual telemetry aggregation without HTTP dependencies."""
+
+    def __init__(self, repository: MonitoringRepository):
+        self.repository = repository
+
+    @staticmethod
+    def _window(
+        query: MonitoringTrendQuery,
+        generated_at: datetime,
+    ) -> tuple[datetime, datetime, timedelta]:
+        duration, bucket_width = RANGE_CONFIGURATION[query.time_range]
+        generated_at = generated_at.astimezone(timezone.utc)
+        bucket_seconds = int(bucket_width.total_seconds())
+        current_bucket_epoch = (
+            int(generated_at.timestamp()) // bucket_seconds * bucket_seconds
+        )
+        current_bucket_start = datetime.fromtimestamp(
+            current_bucket_epoch, tz=timezone.utc
+        )
+        window_end = current_bucket_start + bucket_width
+        return window_end - duration, window_end, bucket_width
+
+    def get_trends(
+        self,
+        query: MonitoringTrendQuery,
+        *,
+        include_location_scopes: bool,
+        generated_at: datetime | None = None,
+    ) -> MonitoringTrendResponse:
+        generated_at = generated_at or datetime.now(timezone.utc)
+        window_start, window_end, bucket_width = self._window(query, generated_at)
+        rows = self.repository.read_trends(
+            scope=query.scope,
+            scope_id=query.scope_id,
+            window_start=window_start,
+            window_end=window_end,
+            bucket_width=bucket_width,
+        )
+        if not rows or not rows[0]["scope_exists"]:
+            raise MonitoringScopeNotFound(f"{query.scope.title()} not found")
+
+        options = MonitoringAvailableScopes()
+        query_count = 1
+        if include_location_scopes:
+            option_rows = self.repository.list_location_scope_options()
+            query_count += 1
+            options = MonitoringAvailableScopes(
+                sites=[
+                    MonitoringSiteOption.model_validate(row)
+                    for row in option_rows
+                    if row["option_type"] == "site"
+                ],
+                rooms=[
+                    MonitoringRoomOption.model_validate(row)
+                    for row in option_rows
+                    if row["option_type"] == "room"
+                ],
+            )
+
+        generated_at = generated_at.astimezone(timezone.utc)
+        hashrate_points = []
+        power_points = []
+        for row in rows:
+            shared = {
+                "bucket_start": row["bucket_start"],
+                "bucket_end": row["bucket_end"],
+                "observation_count": row["observation_count"],
+                "observed_miner_count": row["observed_miner_count"],
+                "scoped_miner_count": row["scoped_miner_count"],
+                "incomplete": row["bucket_end"] > generated_at,
+            }
+            hashrate_points.append(
+                MonitoringTrendPoint(
+                    **shared,
+                    value=(
+                        float(row["hashrate_ths"])
+                        if row["hashrate_ths"] is not None
+                        else None
+                    ),
+                    metric_sample_count=row["hashrate_sample_count"],
+                    contributing_miner_count=(
+                        row["hashrate_contributing_miner_count"]
+                    ),
+                )
+            )
+            power_points.append(
+                MonitoringTrendPoint(
+                    **shared,
+                    value=(
+                        float(row["power_w"])
+                        if row["power_w"] is not None
+                        else None
+                    ),
+                    metric_sample_count=row["power_sample_count"],
+                    contributing_miner_count=(
+                        row["power_contributing_miner_count"]
+                    ),
+                )
+            )
+
+        if len(rows) > MAXIMUM_POINTS:
+            raise RuntimeError("Monitoring query exceeded the fixed point bound")
+        attribution = (
+            "current_placement_cohort"
+            if query.scope in {"site", "room"}
+            else "miner_identity"
+            if query.scope == "miner"
+            else "fleet"
+        )
+        latest_observed_at = rows[0]["latest_observed_at"]
+        return MonitoringTrendResponse(
+            data=MonitoringTrendData(
+                scope=MonitoringScope(
+                    type=query.scope,
+                    id=query.scope_id,
+                    label=rows[0]["scope_label"],
+                ),
+                series=[
+                    MonitoringTrendSeries(
+                        metric="hashrate",
+                        unit="TH/s",
+                        label="Average recorded hashrate",
+                        points=hashrate_points,
+                    ),
+                    MonitoringTrendSeries(
+                        metric="power",
+                        unit="W",
+                        label="Average observed power",
+                        points=power_points,
+                    ),
+                ],
+                available_scopes=options,
+            ),
+            meta=MonitoringTrendMeta(
+                generated_at=generated_at,
+                latest_observed_at=latest_observed_at,
+                attribution=attribution,
+                range=query.time_range,
+                bucket_seconds=int(bucket_width.total_seconds()),
+                current_bucket_incomplete=window_end > generated_at,
+                database_query_count=query_count,
+            ),
+        )

backend/app/repairs/__init__.py

@@ -0,0 +1,61 @@
+"""Repair workflow models, persistence, and business services."""
+
+from app.repairs.exceptions import (
+    ActiveRepairConflict,
+    IncompatibleMinerLifecycle,
+    InconsistentRepairState,
+    RepairActiveMismatch,
+    RepairActorRequired,
+    RepairCompletionActorRequired,
+    RepairConflict,
+    RepairError,
+    RepairMinerNotFound,
+    RepairMinerNotInRepair,
+    RepairNotActive,
+    RepairNotFound,
+    RepairPersistenceError,
+)
+from app.repairs.models import (
+    BeginRepairRequest,
+    BeginRepairResult,
+    RepairActor,
+    RepairCompleteRequest,
+    RepairCompletedPayload,
+    RepairDetail,
+    RepairPostLifecycle,
+    RepairReason,
+    RepairStatus,
+    RepairTimeline,
+    RepairTimelineEvent,
+)
+from app.repairs.repository import RepairRepository
+from app.repairs.service import RepairService
+
+__all__ = [
+    "ActiveRepairConflict",
+    "BeginRepairRequest",
+    "BeginRepairResult",
+    "IncompatibleMinerLifecycle",
+    "InconsistentRepairState",
+    "RepairActiveMismatch",
+    "RepairActor",
+    "RepairActorRequired",
+    "RepairCompleteRequest",
+    "RepairCompletedPayload",
+    "RepairCompletionActorRequired",
+    "RepairConflict",
+    "RepairDetail",
+    "RepairError",
+    "RepairMinerNotFound",
+    "RepairMinerNotInRepair",
+    "RepairNotActive",
+    "RepairNotFound",
+    "RepairPersistenceError",
+    "RepairPostLifecycle",
+    "RepairReason",
+    "RepairRepository",
+    "RepairService",
+    "RepairStatus",
+    "RepairTimeline",
+    "RepairTimelineEvent",
+]

backend/app/repairs/center_repository.py

@@ -0,0 +1,366 @@
+"""Set-based PostgreSQL read model for the Repair Center."""
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import psycopg
+from psycopg.rows import dict_row
+
+from app.repairs.repository import default_connection_factory
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+
+
+class RepairCenterRepository:
+    """Read-only persistence boundary for consolidated repair operations."""
+
+    def __init__(self, connection_factory: ConnectionFactory | None = None):
+        self._connection_factory = connection_factory or default_connection_factory
+
+    @staticmethod
+    def _ctes(*, show_miners: bool, show_locations: bool) -> str:
+        miner_fields = (
+            "miner.asset_tag AS asset_id, COALESCE(miner.model, miner.miner_type) AS model, miner.miner_sn, miner.power_sn, "
+            "miner.current_mac, host(miner.current_ip) AS current_ip, "
+            "miner.status AS runtime_status"
+            if show_miners else
+            "NULL::text AS asset_id, NULL::text AS model, NULL::text AS miner_sn, NULL::text AS power_sn, "
+            "NULL::text AS current_mac, NULL::text AS current_ip, "
+            "NULL::text AS runtime_status"
+        )
+        location_fields = (
+            "placement.site_id, placement.site_name, placement.room_id, "
+            "placement.room_name, placement.rack_label, placement.shelf_label, "
+            "placement.position_id, placement.position_label, placement.position_index"
+            if show_locations else
+            "NULL::uuid AS site_id, NULL::text AS site_name, NULL::uuid AS room_id, "
+            "NULL::text AS room_name, NULL::text AS rack_label, "
+            "NULL::text AS shelf_label, NULL::uuid AS position_id, "
+            "NULL::text AS position_label, NULL::integer AS position_index"
+        )
+        return f"""
+            WITH latest_legacy AS (
+                SELECT DISTINCT ON (event.miner_id)
+                    event.miner_id, event.event_status, event.event_title,
+                    event.description, event.event_at, event.created_at
+                FROM miner_maintenance_events AS event
+                WHERE event.event_type = 'repair'
+                ORDER BY event.miner_id, event.event_at DESC,
+                    event.created_at DESC, event.id DESC
+            ),
+            legacy_first AS (
+                SELECT event.miner_id,
+                    min(COALESCE(event.event_at, event.created_at)) AS opened_at
+                FROM miner_maintenance_events AS event
+                WHERE event.event_type = 'repair'
+                GROUP BY event.miner_id
+            ),
+            legacy_counts AS (
+                SELECT event.miner_id,
+                    count(*)::integer AS repair_event_count,
+                    count(*) FILTER (WHERE event.event_status IN (
+                        'open', 'diagnosing', 'waiting_parts', 'in_progress',
+                        'testing', 'ready_to_shelf', 'needs_followup'
+                    ))::integer AS open_repair_event_count
+                FROM miner_maintenance_events AS event
+                WHERE event.event_type = 'repair'
+                GROUP BY event.miner_id
+            ),
+            latest_modular AS (
+                SELECT DISTINCT ON (event.repair_id)
+                    event.repair_id, event.payload, event.created_at
+                FROM repair_events AS event
+                ORDER BY event.repair_id, event.sequence DESC, event.id DESC
+            ),
+            initial_note AS (
+                SELECT DISTINCT ON (event.repair_id)
+                    event.repair_id, event.payload ->> 'note' AS note
+                FROM repair_events AS event
+                WHERE event.event_type = 'INITIAL_NOTE'
+                ORDER BY event.repair_id, event.sequence, event.id
+            ),
+            part_rollup AS (
+                SELECT part.repair_id,
+                    count(*) FILTER (WHERE part.voided_at IS NULL)::integer AS parts_count,
+                    COALESCE((array_agg(
+                        CASE WHEN part.consumable_description IS NOT NULL
+                            THEN part.consumable_description
+                            ELSE concat_ws(' ', part.component_type_snapshot,
+                                part.component_asset_id_snapshot,
+                                part.component_manufacturer_serial_snapshot)
+                        END ORDER BY part.recorded_at, part.id
+                    ) FILTER (WHERE part.voided_at IS NULL))[1:3],
+                        ARRAY[]::text[]) AS parts_summary
+                FROM repair_parts AS part GROUP BY part.repair_id
+            ),
+            placement AS (
+                SELECT DISTINCT ON (position.miner_id)
+                    position.miner_id, site.id AS site_id, site.name AS site_name,
+                    room.id AS room_id, COALESCE(room.name, position.room_name) AS room_name,
+                    position.rack_name AS rack_label, position.shelf_name AS shelf_label,
+                    position.id AS position_id, position.position_label,
+                    position.position_index
+                FROM location_positions AS position
+                LEFT JOIN rooms AS room ON room.id = position.room_id
+                LEFT JOIN sites AS site ON site.id = room.site_id
+                WHERE position.miner_id IS NOT NULL
+                ORDER BY position.miner_id, position.id
+            ),
+            modular_rows AS (
+                SELECT repair.id AS repair_id, 'modular'::text AS source,
+                    repair.status = ANY(ARRAY['OPEN', 'IN_PROGRESS',
+                        'WAITING_FOR_PARTS', 'READY_FOR_TEST']) AS active,
+                    repair.opened_at, repair.completed_at AS closed_at,
+                    repair.status AS repair_status, repair.reason,
+                    COALESCE(NULLIF(trim(miner.manual_details ->
+                        'office_repair_import' ->> 'reported_error'), ''),
+                        NULLIF(trim(initial_note.note), ''),
+                        replace(repair.reason, '_', ' ')) AS reported_problem,
+                    COALESCE(NULLIF(trim(latest_modular.payload ->> 'note'), ''),
+                        NULLIF(trim(latest_modular.payload ->> 'notes'), ''),
+                        NULLIF(trim(latest_modular.payload ->> 'completion_summary'), ''),
+                        NULLIF(trim(initial_note.note), ''),
+                        NULLIF(trim(latest_legacy.description), ''),
+                        NULLIF(trim(location_state.state_notes), '')) AS latest_context,
+                    COALESCE(latest_modular.created_at, latest_legacy.event_at,
+                        latest_legacy.created_at, repair.opened_at) AS latest_context_at,
+                    opened_actor.display_name AS opened_by_display_name,
+                    miner.id AS miner_id, {miner_fields}, miner.lifecycle_status,
+                    {location_fields},
+                    COALESCE(part_rollup.parts_count, 0) AS parts_count,
+                    COALESCE(part_rollup.parts_summary, ARRAY[]::text[]) AS parts_summary,
+                    latest_legacy.event_status AS legacy_event_status,
+                    location_state.asset_state AS legacy_asset_state,
+                    latest_legacy.event_title AS latest_event_title,
+                    COALESCE(legacy_counts.repair_event_count, 0) AS repair_event_count,
+                    COALESCE(legacy_counts.open_repair_event_count, 0) AS open_repair_event_count,
+                    miner.manual_details -> 'office_repair_import' ->> 'reported_hashrate_ths' AS reported_hashrate_ths,
+                    miner.manual_details -> 'office_repair_import' ->> 'reported_voltage' AS reported_voltage,
+                    miner.manual_details -> 'office_repair_import' ->> 'location_note' AS location_note,
+                    miner.manual_details -> 'office_repair_import' ->> 'source' AS import_source,
+                    location_state.updated_at AS state_updated_at
+                FROM repairs AS repair
+                JOIN miners AS miner ON miner.id = repair.miner_id
+                JOIN users AS opened_actor ON opened_actor.id = repair.opened_by
+                LEFT JOIN latest_modular ON latest_modular.repair_id = repair.id
+                LEFT JOIN initial_note ON initial_note.repair_id = repair.id
+                LEFT JOIN part_rollup ON part_rollup.repair_id = repair.id
+                LEFT JOIN latest_legacy ON latest_legacy.miner_id = miner.id
+                LEFT JOIN legacy_counts ON legacy_counts.miner_id = miner.id
+                LEFT JOIN miner_location_states AS location_state
+                    ON location_state.miner_id = miner.id
+                LEFT JOIN placement ON placement.miner_id = miner.id
+            ),
+            legacy_rows AS (
+                SELECT NULL::uuid AS repair_id, 'legacy'::text AS source,
+                    true AS active, legacy_first.opened_at, NULL::timestamptz AS closed_at,
+                    COALESCE(latest_legacy.event_status,
+                        location_state.asset_state, 'unknown') AS repair_status,
+                    NULL::text AS reason,
+                    COALESCE(NULLIF(trim(miner.manual_details ->
+                        'office_repair_import' ->> 'reported_error'), ''),
+                        NULLIF(trim(latest_legacy.event_title), '')) AS reported_problem,
+                    COALESCE(NULLIF(trim(latest_legacy.description), ''),
+                        NULLIF(trim(location_state.state_notes), '')) AS latest_context,
+                    COALESCE(latest_legacy.event_at, latest_legacy.created_at,
+                        location_state.updated_at) AS latest_context_at,
+                    NULL::text AS opened_by_display_name,
+                    miner.id AS miner_id, {miner_fields}, miner.lifecycle_status,
+                    {location_fields}, NULL::integer AS parts_count,
+                    ARRAY[]::text[] AS parts_summary,
+                    latest_legacy.event_status AS legacy_event_status,
+                    location_state.asset_state AS legacy_asset_state,
+                    latest_legacy.event_title AS latest_event_title,
+                    COALESCE(legacy_counts.repair_event_count, 0) AS repair_event_count,
+                    COALESCE(legacy_counts.open_repair_event_count, 0) AS open_repair_event_count,
+                    miner.manual_details -> 'office_repair_import' ->> 'reported_hashrate_ths' AS reported_hashrate_ths,
+                    miner.manual_details -> 'office_repair_import' ->> 'reported_voltage' AS reported_voltage,
+                    miner.manual_details -> 'office_repair_import' ->> 'location_note' AS location_note,
+                    miner.manual_details -> 'office_repair_import' ->> 'source' AS import_source,
+                    location_state.updated_at AS state_updated_at
+                FROM miner_location_states AS location_state
+                JOIN miners AS miner ON miner.id = location_state.miner_id
+                LEFT JOIN latest_legacy ON latest_legacy.miner_id = miner.id
+                LEFT JOIN legacy_counts ON legacy_counts.miner_id = miner.id
+                LEFT JOIN legacy_first ON legacy_first.miner_id = miner.id
+                LEFT JOIN placement ON placement.miner_id = miner.id
+                WHERE location_state.asset_state = 'repair'
+                  AND NOT EXISTS (
+                    SELECT 1 FROM repairs AS active_repair
+                    WHERE active_repair.miner_id = miner.id
+                      AND active_repair.status = ANY(ARRAY['OPEN', 'IN_PROGRESS',
+                          'WAITING_FOR_PARTS', 'READY_FOR_TEST'])
+                  )
+            ),
+            candidates AS (
+                SELECT * FROM modular_rows
+                UNION ALL
+                SELECT * FROM legacy_rows
+            )
+        """
+
+    @staticmethod
+    def _where(filters: Mapping[str, Any]) -> tuple[str, list[Any]]:
+        conditions: list[str] = []
+        params: list[Any] = []
+        scope = filters.get("scope", "active")
+        if scope == "active":
+            conditions.append("candidate.active")
+        elif scope == "historical":
+            conditions.append("NOT candidate.active")
+        for key, column in (
+            ("status", "repair_status"),
+            ("lifecycle_status", "lifecycle_status"),
+            ("site_id", "site_id"),
+            ("room_id", "room_id"),
+        ):
+            if filters.get(key):
+                conditions.append(f"candidate.{column} = %s")
+                params.append(filters[key])
+        if filters.get("model"):
+            conditions.append("lower(trim(candidate.model)) = lower(trim(%s))")
+            params.append(filters["model"])
+        if filters.get("query"):
+            conditions.append(
+                "concat_ws(' ', candidate.repair_id, candidate.miner_id, "
+                "candidate.asset_id, candidate.model, candidate.miner_sn, "
+                "candidate.current_mac, candidate.current_ip, "
+                "candidate.repair_status, candidate.reason, "
+                "candidate.reported_problem, candidate.latest_context) ILIKE %s"
+            )
+            params.append(f"%{filters['query']}%")
+        return " AND ".join(conditions) if conditions else "true", params
+
+    def list_repair_center(
+        self,
+        filters: Mapping[str, Any],
+        *,
+        include_miner_details: bool,
+        include_location_details: bool,
+    ) -> dict[str, Any]:
+        ctes = self._ctes(
+            show_miners=include_miner_details,
+            show_locations=include_location_details,
+        )
+        where_sql, params = self._where(filters)
+        item_sql = f"""
+            {ctes}
+            SELECT candidate.* FROM candidates AS candidate
+            WHERE {where_sql}
+            ORDER BY candidate.active DESC,
+                CASE WHEN candidate.active THEN candidate.opened_at END ASC NULLS LAST,
+                candidate.opened_at DESC NULLS LAST,
+                candidate.repair_id NULLS LAST, candidate.miner_id
+            LIMIT %s OFFSET %s
+        """
+        summary_sql = f"""
+            {ctes}, filtered AS (
+                SELECT * FROM candidates AS candidate WHERE {where_sql}
+            )
+            SELECT count(*)::integer AS total,
+                count(*) FILTER (WHERE active)::integer AS active,
+                count(*) FILTER (WHERE NOT active)::integer AS historical,
+                COALESCE((SELECT jsonb_object_agg(status_rows.repair_status,
+                    status_rows.status_count) FROM (
+                        SELECT repair_status, count(*)::integer AS status_count
+                        FROM filtered GROUP BY repair_status
+                    ) AS status_rows), '{{}}'::jsonb) AS status_counts,
+                COALESCE((SELECT jsonb_object_agg(model_rows.model,
+                    model_rows.model_count) FROM (
+                        SELECT model, count(*)::integer AS model_count
+                        FROM filtered WHERE model IS NOT NULL GROUP BY model
+                    ) AS model_rows), '{{}}'::jsonb) AS model_counts,
+                COALESCE((SELECT jsonb_object_agg(error_rows.error,
+                    error_rows.error_count) FROM (
+                        SELECT COALESCE(reported_problem, 'No reported error') AS error,
+                            count(*)::integer AS error_count
+                        FROM filtered
+                        GROUP BY COALESCE(reported_problem, 'No reported error')
+                    ) AS error_rows), '{{}}'::jsonb) AS error_counts
+            FROM filtered
+        """
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    item_sql,
+                    [*params, int(filters.get("limit", 50)),
+                        int(filters.get("offset", 0))],
+                )
+                items = [dict(row) for row in cur.fetchall()]
+                cur.execute(summary_sql, params)
+                summary = dict(cur.fetchone())
+                options = {"sites": [], "rooms": []}
+                if include_location_details:
+                    cur.execute(
+                        f"""
+                        {ctes}
+                        SELECT jsonb_build_object(
+                            'sites', COALESCE((SELECT jsonb_agg(site_rows
+                                ORDER BY lower(site_rows.name), site_rows.id)
+                                FROM (SELECT DISTINCT site_id AS id, site_name AS name
+                                    FROM candidates WHERE site_id IS NOT NULL) site_rows),
+                                '[]'::jsonb),
+                            'rooms', COALESCE((SELECT jsonb_agg(room_rows
+                                ORDER BY lower(room_rows.name), room_rows.id)
+                                FROM (SELECT DISTINCT room_id AS id, site_id,
+                                    room_name AS name FROM candidates
+                                    WHERE room_id IS NOT NULL) room_rows), '[]'::jsonb)
+                        ) AS options
+                        """
+                    )
+                    options = cur.fetchone()["options"]
+        finally:
+            connection.close()
+        return {"items": items, "summary": summary, "location_options": options}
+
+    def list_miner_repairs(self, miner_id) -> list[dict[str, Any]]:
+        """Return a bounded, exact repair history for one durable miner."""
+        ctes = self._ctes(show_miners=False, show_locations=False)
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    {ctes}
+                    SELECT candidate.* FROM candidates AS candidate
+                    WHERE candidate.miner_id = %s
+                    ORDER BY candidate.active DESC,
+                        candidate.opened_at DESC NULLS LAST,
+                        candidate.repair_id NULLS LAST
+                    LIMIT 50
+                    """,
+                    (miner_id,),
+                )
+                return [dict(row) for row in cur.fetchall()]
+        finally:
+            connection.close()
+
+    def summarize_active_repairs(self) -> dict[str, Any]:
+        """Return exact active counts without loading Repair Center rows."""
+        ctes = self._ctes(show_miners=False, show_locations=False)
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    f"""
+                    {ctes}, active_rows AS (
+                        SELECT repair_status FROM candidates WHERE active
+                    )
+                    SELECT count(*)::integer AS active,
+                        COALESCE((SELECT jsonb_object_agg(
+                            status_rows.repair_status,
+                            status_rows.status_count
+                        ) FROM (
+                            SELECT repair_status,
+                                count(*)::integer AS status_count
+                            FROM active_rows
+                            GROUP BY repair_status
+                        ) AS status_rows), '{{}}'::jsonb) AS status_counts
+                    FROM active_rows
+                    """
+                )
+                return dict(cur.fetchone())
+        finally:
+            connection.close()

backend/app/repairs/center_service.py

@@ -0,0 +1,124 @@
+"""Application service for the consolidated Repair Center read model."""
+
+from app.repairs.center_repository import RepairCenterRepository
+from app.repairs.models import (
+    ActiveRepairSummary,
+    RepairCenterAccess,
+    RepairCenterCapabilities,
+    RepairCenterFilters,
+    RepairCenterItem,
+    RepairCenterList,
+    RepairCenterLocationOptions,
+    RepairCenterMeta,
+    RepairCenterResponse,
+    RepairCenterSummary,
+)
+
+
+class RepairCenterService:
+    """Build typed, permission-aware Repair Center projections."""
+
+    def __init__(self, repository: RepairCenterRepository):
+        self.repository = repository
+
+    @staticmethod
+    def _capabilities(
+        item: RepairCenterItem,
+        access: RepairCenterAccess,
+    ) -> RepairCenterCapabilities:
+        modular = item.source == "modular" and item.repair_id is not None
+        legacy = item.source == "legacy"
+        placed = bool(item.site_id and item.room_id and item.position_id)
+        return RepairCenterCapabilities(
+            can_open_miner=access.can_view_miners,
+            can_open_map=access.can_view_locations and placed,
+            can_read_modular_timeline=modular and access.can_read_repairs,
+            can_read_modular_parts=modular and access.can_read_repairs,
+            can_manage_modular_parts=(
+                modular and item.active and access.can_read_repairs
+                and access.can_manage_parts
+            ),
+            can_complete_modular_repair=(
+                modular and item.active and access.can_complete_repairs
+            ),
+            can_read_legacy_history=legacy and access.can_read_repairs,
+            can_manage_legacy=legacy and access.can_manage_legacy,
+            can_mark_legacy_repaired=legacy and access.can_manage_legacy,
+            can_decommission_legacy=legacy and access.can_manage_legacy,
+        )
+
+    def list_repair_center(
+        self,
+        filters: RepairCenterFilters,
+        access: RepairCenterAccess,
+    ) -> RepairCenterResponse:
+        query = filters.query.strip() if filters.query else None
+        model = filters.model.strip() if filters.model else None
+        status = filters.status.strip() if filters.status else None
+        repository_filters = filters.model_dump()
+        repository_filters.update(query=query or None, model=model or None,
+                                  status=status or None)
+        projection = self.repository.list_repair_center(
+            repository_filters,
+            include_miner_details=access.can_view_miners,
+            include_location_details=access.can_view_locations,
+        )
+        items: list[RepairCenterItem] = []
+        for row in projection["items"]:
+            row = {
+                **row,
+                "miner_status": row.get("runtime_status"),
+                "latest_event_status": row.get("legacy_event_status"),
+                "latest_event_description": row.get("latest_context"),
+                "latest_event_at": row.get("latest_context_at"),
+                "asset_state": row.get("legacy_asset_state"),
+                "state_notes": row.get("latest_context"),
+                "reported_error": row.get("reported_problem"),
+            }
+            item = RepairCenterItem.model_validate(
+                {**row, "capabilities": RepairCenterCapabilities()}
+            )
+            item.capabilities = self._capabilities(item, access)
+            items.append(item)
+
+        summary = RepairCenterSummary.model_validate(projection["summary"])
+        location_options = RepairCenterLocationOptions.model_validate(
+            projection.get("location_options") or {}
+        )
+        return RepairCenterResponse(
+            data=RepairCenterList(items=items, summary=summary),
+            meta=RepairCenterMeta(
+                limit=filters.limit,
+                offset=filters.offset,
+                returned=len(items),
+                total=summary.total,
+                location_options=location_options,
+            ),
+        )
+
+    def list_miner_repairs(
+        self, miner_id, access: RepairCenterAccess
+    ) -> list[RepairCenterItem]:
+        items = []
+        for row in self.repository.list_miner_repairs(miner_id):
+            mapped = {
+                **row,
+                "miner_status": row.get("runtime_status"),
+                "latest_event_status": row.get("legacy_event_status"),
+                "latest_event_description": row.get("latest_context"),
+                "latest_event_at": row.get("latest_context_at"),
+                "asset_state": row.get("legacy_asset_state"),
+                "state_notes": row.get("latest_context"),
+                "reported_error": row.get("reported_problem"),
+            }
+            item = RepairCenterItem.model_validate(
+                {**mapped, "capabilities": RepairCenterCapabilities()}
+            )
+            item.capabilities = self._capabilities(item, access)
+            items.append(item)
+        return items
+
+    def summarize_active_repairs(self) -> ActiveRepairSummary:
+        return ActiveRepairSummary.model_validate(
+            self.repository.summarize_active_repairs()
+        )

backend/app/repairs/dependencies.py

@@ -0,0 +1,14 @@
+"""Dependency construction for the Repairs domain."""
+
+from app.repairs.repository import RepairRepository
+from app.repairs.center_repository import RepairCenterRepository
+from app.repairs.center_service import RepairCenterService
+from app.repairs.service import RepairService
+
+
+def get_repair_service() -> RepairService:
+    return RepairService(RepairRepository())
+
+
+def get_repair_center_service() -> RepairCenterService:
+    return RepairCenterService(RepairCenterRepository())

backend/app/repairs/exceptions.py

@@ -0,0 +1,172 @@
+"""Domain exceptions for repair workflows."""
+
+
+class RepairError(Exception):
+    """Base exception for repair operations."""
+
+
+class RepairMinerNotFound(RepairError):
+    """Raised when the requested miner does not exist."""
+
+    def __init__(self, miner_id: object):
+        self.miner_id = miner_id
+        super().__init__(f"Miner not found: {miner_id}")
+
+
+class RepairNotFound(RepairError):
+    """Raised when the requested repair does not exist."""
+
+    def __init__(self, repair_id: object):
+        self.repair_id = repair_id
+        super().__init__(f"Repair not found: {repair_id}")
+
+
+class RepairConflict(RepairError):
+    """Base exception for a conflicting repair state."""
+
+
+class ActiveRepairConflict(RepairConflict):
+    """Raised when a miner already has an active repair."""
+
+    def __init__(self, miner_id: object):
+        self.miner_id = miner_id
+        super().__init__(f"Miner already has an active repair: {miner_id}")
+
+
+class IncompatibleMinerLifecycle(RepairConflict):
+    """Raised when the miner lifecycle cannot enter repair."""
+
+    def __init__(self, miner_id: object, lifecycle_status: object):
+        self.miner_id = miner_id
+        self.lifecycle_status = lifecycle_status
+        super().__init__(
+            "Miner lifecycle is incompatible with beginning repair: "
+            f"{lifecycle_status}"
+        )
+
+
+class InconsistentRepairState(RepairConflict):
+    """Raised when lifecycle state and repair records disagree."""
+
+    def __init__(self, miner_id: object):
+        self.miner_id = miner_id
+        super().__init__(
+            "Miner is marked in repair but has no active repair record"
+        )
+
+
+class RepairActorRequired(RepairError):
+    """Raised when an operational workflow lacks an authenticated actor."""
+
+    def __init__(self):
+        super().__init__("An authenticated actor is required to begin repair")
+
+
+class RepairCompletionActorRequired(RepairError):
+    """Raised when Return to Service lacks an authenticated actor."""
+
+    def __init__(self):
+        super().__init__(
+            "An authenticated actor is required to return a miner to service"
+        )
+
+
+class RepairNotActive(RepairConflict):
+    """Raised when a repair is no longer active."""
+
+    def __init__(self, repair_id: object, repair_status: object):
+        self.repair_id = repair_id
+        self.repair_status = repair_status
+        super().__init__(
+            f"Repair is not active: {repair_id} ({repair_status})"
+        )
+
+
+class RepairMinerNotInRepair(RepairConflict):
+    """Raised when a repair's miner has already left repair lifecycle."""
+
+    def __init__(self, miner_id: object, lifecycle_status: object):
+        self.miner_id = miner_id
+        self.lifecycle_status = lifecycle_status
+        super().__init__(
+            "Miner is not in repair lifecycle: "
+            f"{miner_id} ({lifecycle_status})"
+        )
+
+
+class RepairActiveMismatch(RepairConflict):
+    """Raised when the requested repair is not the miner's active repair."""
+
+    def __init__(self, repair_id: object, miner_id: object):
+        self.repair_id = repair_id
+        self.miner_id = miner_id
+        super().__init__(
+            f"Repair is not the active repair for miner: {repair_id}"
+        )
+
+
+class RepairPersistenceError(RepairError):
+    """Raised when a required repair persistence operation fails."""
+
+
+class ControlBoardReplacementActorRequired(RepairError):
+    """Raised when a board replacement lacks an authenticated actor."""
+
+    def __init__(self):
+        super().__init__("An authenticated actor is required to replace a control board")
+
+
+class ControlBoardReplacementConflict(RepairConflict):
+    """Raised when current repair, component, or MAC state blocks replacement."""
+
+
+class InvalidMacAddress(RepairError):
+    """Raised when a replacement MAC is malformed or prohibited."""
+
+    def __init__(self, message: str = "New MAC address is invalid"):
+        super().__init__(message)
+
+
+class MacOwnershipConflict(ControlBoardReplacementConflict):
+    """Raised when a MAC belongs to another durable miner."""
+
+    def __init__(self, normalized_mac: str):
+        self.normalized_mac = normalized_mac
+        super().__init__(
+            "MAC address has current or historical ownership on another miner"
+        )
+
+
+class RepairPartNotFound(RepairError):
+    """Raised when a nested repair-part UUID does not exist for a repair."""
+
+    def __init__(self, repair_part_id: object):
+        self.repair_part_id = repair_part_id
+        super().__init__(f"Repair part not found: {repair_part_id}")
+
+
+class RepairPartComponentNotFound(RepairError):
+    """Raised when a tracked component UUID does not exist."""
+
+    def __init__(self, component_id: object):
+        self.component_id = component_id
+        super().__init__(f"Component not found: {component_id}")
+
+
+class RepairPartValidationError(RepairError):
+    """Raised when repair-part input violates a domain rule."""
+
+
+class RepairPartActorRequired(RepairError):
+    """Raised when a repair-part action lacks an authenticated actor."""
+
+    def __init__(self):
+        super().__init__("An authenticated actor is required for repair-part actions")
+
+
+class RepairPartAlreadyVoided(RepairConflict):
+    """Raised when an immutable repair-part entry was already voided."""
+
+    def __init__(self, repair_part_id: object):
+        self.repair_part_id = repair_part_id
+        super().__init__(f"Repair part is already voided: {repair_part_id}")

backend/app/repairs/models.py

@@ -0,0 +1,429 @@
+"""Typed contracts for the Repairs domain."""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, model_validator
+from app.components.models import ComponentType
+
+
+RepairReason = Literal[
+    "HARDWARE_FAILURE",
+    "LOW_HASHRATE",
+    "CONTROL_BOARD",
+    "HASHBOARD",
+    "PSU",
+    "FAN",
+    "OVERHEATING",
+    "NETWORKING",
+    "PREVENTIVE_MAINTENANCE",
+    "INSPECTION",
+    "OTHER",
+]
+RepairStatus = Literal[
+    "OPEN",
+    "IN_PROGRESS",
+    "WAITING_FOR_PARTS",
+    "READY_FOR_TEST",
+    "COMPLETED",
+    "CANCELLED",
+]
+RepairEventType = Literal[
+    "REPAIR_STARTED",
+    "INITIAL_NOTE",
+    "REPAIR_COMPLETED",
+    "CONTROL_BOARD_REPLACED",
+    "REPAIR_PART_RECORDED",
+    "REPAIR_PART_VOIDED",
+]
+RepairEligibleLifecycle = Literal["active", "spare"]
+RepairPostLifecycle = Literal["active", "spare"]
+RepairMinerLifecycle = Literal["active", "spare", "retired", "in_repair"]
+
+
+class BeginRepairRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    miner_id: UUID
+    reason: RepairReason
+    notes: str | None = Field(default=None, max_length=4000)
+
+
+class RepairCompleteRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    target_lifecycle: RepairPostLifecycle
+    completion_summary: str | None = Field(default=None, max_length=4000)
+
+
+ControlBoardReplacementReason = Literal[
+    "failed",
+    "upgrade",
+    "diagnostic_swap",
+    "preventive_maintenance",
+    "temporary_donor",
+    "unknown",
+]
+RemovedBoardDisposition = Literal[
+    "repair_inventory",
+    "sent_for_repair",
+    "scrapped",
+    "retained_for_diagnosis",
+    "returned_to_vendor",
+    "unknown",
+]
+
+
+class ControlBoardReplacementRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    new_mac_address: str = Field(min_length=1, max_length=64)
+    new_control_board_serial: str | None = Field(..., max_length=255)
+    board_model: str | None = Field(default=None, max_length=255)
+    board_revision: str | None = Field(default=None, max_length=255)
+    firmware_version: str | None = Field(default=None, max_length=255)
+    removed_board_disposition: RemovedBoardDisposition
+    replacement_reason: ControlBoardReplacementReason
+    notes: str | None = Field(default=None, max_length=4000)
+
+
+class RepairStartedPayload(BaseModel):
+    reason: RepairReason
+    from_lifecycle: RepairEligibleLifecycle
+    to_lifecycle: Literal["in_repair"] = "in_repair"
+
+
+class InitialRepairNotePayload(BaseModel):
+    note: str = Field(min_length=1, max_length=4000)
+
+
+class RepairCompletedPayload(BaseModel):
+    previous_miner_lifecycle: Literal["in_repair"] = "in_repair"
+    resulting_miner_lifecycle: RepairPostLifecycle
+    pre_repair_lifecycle: RepairEligibleLifecycle | None = None
+    completion_summary: str | None = Field(default=None, max_length=4000)
+
+
+class ControlBoardReplacedPayload(BaseModel):
+    old_mac_address: str | None
+    new_mac_address: str
+    old_control_board_serial: str | None
+    new_control_board_serial: str | None
+    old_board_model: str | None = None
+    new_board_model: str | None = None
+    old_board_revision: str | None = None
+    new_board_revision: str | None = None
+    new_firmware_version: str | None = None
+    removed_board_disposition: RemovedBoardDisposition
+    replacement_reason: ControlBoardReplacementReason
+    notes: str | None = Field(default=None, max_length=4000)
+
+
+class ControlBoardReplacementResult(BaseModel):
+    miner_id: UUID
+    asset_id: str | None = None
+    repair_id: UUID
+    installation_id: UUID
+    event_id: UUID
+    event_sequence: int = Field(ge=1)
+    current_mac: str
+    control_board_serial: str | None
+    replaced_at: AwareDatetime
+    replaced_by: UUID
+
+
+class ControlBoardReplacementResponse(BaseModel):
+    data: ControlBoardReplacementResult
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class BeginRepairResult(BaseModel):
+    repair_id: UUID
+    miner_id: UUID
+    status: Literal["OPEN"]
+    reason: RepairReason
+    opened_at: datetime
+    opened_by: UUID
+
+
+class BeginRepairResponse(BaseModel):
+    data: BeginRepairResult
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class RepairActor(BaseModel):
+    user_id: UUID
+    display_name: str
+
+
+class RepairDetail(BaseModel):
+    repair_id: UUID
+    miner_id: UUID
+    miner_asset_id: str | None = None
+    status: RepairStatus
+    reason: RepairReason
+    opened_at: AwareDatetime
+    opened_by: RepairActor
+    closed_at: AwareDatetime | None = None
+    closed_by: RepairActor | None = None
+    miner_lifecycle: RepairMinerLifecycle
+    latest_event_sequence: int | None = Field(default=None, ge=1)
+
+
+class RepairTimelineEvent(BaseModel):
+    event_id: UUID
+    sequence: int = Field(ge=1)
+    event_type: RepairEventType
+    actor: RepairActor
+    occurred_at: AwareDatetime
+    payload: dict[str, Any]
+
+
+class RepairTimeline(BaseModel):
+    repair_id: UUID
+    events: list[RepairTimelineEvent] = Field(default_factory=list)
+
+
+class RepairDetailResponse(BaseModel):
+    data: RepairDetail
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class RepairTimelineResponse(BaseModel):
+    data: RepairTimeline
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+ConsumableUnit = Literal["each", "gram", "millilitre", "metre", "centimetre"]
+RepairPartEntryKind = Literal["consumable", "tracked_component"]
+
+
+class ConsumableInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    description: str = Field(min_length=1, max_length=255)
+    quantity: Decimal = Field(gt=0, max_digits=12, decimal_places=3)
+    unit: ConsumableUnit
+
+    @model_validator(mode="after")
+    def validate_each_quantity(self) -> "ConsumableInput":
+        if self.unit == "each" and self.quantity != self.quantity.to_integral_value():
+            raise ValueError("quantity for unit 'each' must be a whole number")
+        return self
+
+
+class RepairPartRecordRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    consumable: ConsumableInput | None = None
+    tracked_component_uuid: UUID | None = None
+    notes: str | None = Field(default=None, max_length=4000)
+
+    @model_validator(mode="after")
+    def validate_entry_shape(self) -> "RepairPartRecordRequest":
+        if (self.consumable is None) == (self.tracked_component_uuid is None):
+            raise ValueError(
+                "exactly one of consumable and tracked_component_uuid is required"
+            )
+        return self
+
+
+class RepairPartVoidRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    reason: str = Field(min_length=1, max_length=1000)
+
+
+class RepairPartConsumable(BaseModel):
+    description: str
+    quantity: Decimal
+    unit: ConsumableUnit
+
+
+class RepairPartComponentSnapshot(BaseModel):
+    component_type: ComponentType
+    asset_id: str | None = None
+    manufacturer: str | None = None
+    model: str | None = None
+    manufacturer_serial: str | None = None
+
+
+class RepairPartDetail(BaseModel):
+    repair_part_id: UUID
+    repair_id: UUID
+    entry_kind: RepairPartEntryKind
+    consumable: RepairPartConsumable | None = None
+    component_id: UUID | None = None
+    component_snapshot: RepairPartComponentSnapshot | None = None
+    notes: str | None = None
+    recorded_by: UUID
+    recorded_at: AwareDatetime
+    recorded_event_id: UUID
+    voided_by: UUID | None = None
+    voided_at: AwareDatetime | None = None
+    void_reason: str | None = None
+    void_event_id: UUID | None = None
+
+
+class RepairPartList(BaseModel):
+    repair_id: UUID
+    entries: list[RepairPartDetail] = Field(default_factory=list)
+
+
+class RepairPartResponse(BaseModel):
+    data: RepairPartDetail
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class RepairPartListResponse(BaseModel):
+    data: RepairPartList
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+RepairCenterSource = Literal["modular", "legacy"]
+RepairCenterScope = Literal["active", "historical", "all"]
+
+
+class RepairCenterAccess(BaseModel):
+    can_read_repairs: bool = False
+    can_view_miners: bool = False
+    can_view_locations: bool = False
+    can_complete_repairs: bool = False
+    can_manage_parts: bool = False
+    can_manage_legacy: bool = False
+
+
+class RepairCenterFilters(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    query: str | None = Field(default=None, max_length=255)
+    scope: RepairCenterScope = "active"
+    status: str | None = Field(default=None, max_length=64)
+    model: str | None = Field(default=None, max_length=255)
+    lifecycle_status: RepairMinerLifecycle | None = None
+    site_id: UUID | None = None
+    room_id: UUID | None = None
+    limit: int = Field(default=50, ge=1, le=250)
+    offset: int = Field(default=0, ge=0)
+
+
+class RepairCenterCapabilities(BaseModel):
+    can_open_miner: bool = False
+    can_open_map: bool = False
+    can_read_modular_timeline: bool = False
+    can_read_modular_parts: bool = False
+    can_manage_modular_parts: bool = False
+    can_complete_modular_repair: bool = False
+    can_read_legacy_history: bool = False
+    can_manage_legacy: bool = False
+    can_mark_legacy_repaired: bool = False
+    can_decommission_legacy: bool = False
+
+
+class RepairCenterItem(BaseModel):
+    repair_id: UUID | None = None
+    source: RepairCenterSource
+    active: bool
+    opened_at: AwareDatetime | None = None
+    closed_at: AwareDatetime | None = None
+    repair_status: str
+    reason: str | None = None
+    reported_problem: str | None = None
+    latest_context: str | None = None
+    latest_context_at: AwareDatetime | None = None
+    opened_by_display_name: str | None = None
+    miner_id: UUID
+    asset_id: str | None = None
+    model: str | None = None
+    miner_sn: str | None = None
+    power_sn: str | None = None
+    current_mac: str | None = None
+    current_ip: str | None = None
+    lifecycle_status: RepairMinerLifecycle
+    runtime_status: str | None = None
+    miner_status: str | None = None
+    site_id: UUID | None = None
+    site_name: str | None = None
+    room_id: UUID | None = None
+    room_name: str | None = None
+    rack_label: str | None = None
+    shelf_label: str | None = None
+    position_id: UUID | None = None
+    position_label: str | None = None
+    position_index: int | None = None
+    parts_count: int | None = None
+    parts_summary: list[str] = Field(default_factory=list)
+    legacy_event_status: str | None = None
+    legacy_asset_state: str | None = None
+    latest_event_status: str | None = None
+    latest_event_title: str | None = None
+    latest_event_description: str | None = None
+    latest_event_at: AwareDatetime | None = None
+    asset_state: str | None = None
+    state_notes: str | None = None
+    repair_event_count: int = 0
+    open_repair_event_count: int = 0
+    state_updated_at: AwareDatetime | None = None
+    reported_error: str | None = None
+    reported_hashrate_ths: str | None = None
+    reported_voltage: str | None = None
+    location_note: str | None = None
+    import_source: str | None = None
+    capabilities: RepairCenterCapabilities
+
+
+class RepairCenterSummary(BaseModel):
+    total: int
+    active: int
+    historical: int
+    status_counts: dict[str, int] = Field(default_factory=dict)
+    model_counts: dict[str, int] = Field(default_factory=dict)
+    error_counts: dict[str, int] = Field(default_factory=dict)
+
+
+class ActiveRepairSummary(BaseModel):
+    active: int
+    status_counts: dict[str, int] = Field(default_factory=dict)
+
+
+class RepairCenterLocationOption(BaseModel):
+    id: UUID
+    name: str
+
+
+class RepairCenterRoomOption(RepairCenterLocationOption):
+    site_id: UUID
+
+
+class RepairCenterLocationOptions(BaseModel):
+    sites: list[RepairCenterLocationOption] = Field(default_factory=list)
+    rooms: list[RepairCenterRoomOption] = Field(default_factory=list)
+
+
+class RepairCenterList(BaseModel):
+    items: list[RepairCenterItem]
+    summary: RepairCenterSummary
+
+
+class RepairCenterMeta(BaseModel):
+    limit: int
+    offset: int
+    returned: int
+    total: int
+    location_options: RepairCenterLocationOptions = Field(
+        default_factory=RepairCenterLocationOptions
+    )
+
+
+class RepairCenterResponse(BaseModel):
+    data: RepairCenterList
+    meta: RepairCenterMeta
+    error: None = None

backend/app/repairs/repository.py

@@ -0,0 +1,846 @@
+"""PostgreSQL persistence for repair workflows."""
+
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+from uuid import UUID
+
+import psycopg
+from psycopg.errors import CheckViolation, LockNotAvailable, UniqueViolation
+from psycopg.rows import dict_row
+from psycopg.types.json import Jsonb
+
+from app.config import settings
+from app.repairs.exceptions import (
+    ActiveRepairConflict,
+    ControlBoardReplacementConflict,
+    MacOwnershipConflict,
+    RepairPersistenceError,
+)
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+ACTIVE_REPAIR_STATUSES = (
+    "OPEN",
+    "IN_PROGRESS",
+    "WAITING_FOR_PARTS",
+    "READY_FOR_TEST",
+)
+ACTIVE_REPAIR_CONSTRAINT = "uq_repairs_one_active_per_miner"
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+class RepairRepository:
+    """Persistence boundary for explicit atomic repair workflows."""
+
+    def __init__(
+        self,
+        connection_factory: ConnectionFactory | None = None,
+        *,
+        connection: psycopg.Connection | None = None,
+    ):
+        self._connection_factory = connection_factory or default_connection_factory
+        self._connection = connection
+
+    @contextmanager
+    def transaction(self) -> Iterator["RepairRepository"]:
+        if self._connection is not None:
+            yield self
+            return
+
+        connection = self._connection_factory()
+        transaction_repository = RepairRepository(
+            self._connection_factory,
+            connection=connection,
+        )
+        try:
+            yield transaction_repository
+            connection.commit()
+        except UniqueViolation as exc:
+            connection.rollback()
+            if exc.diag.constraint_name in {
+                "uq_miner_mac_ownerships_owner",
+                "uq_miner_network_identities_normalized_mac",
+                "uq_miners_current_normalized_mac",
+                "uq_control_board_installations_current_miner",
+                "uq_control_board_installations_current_mac",
+            }:
+                raise ControlBoardReplacementConflict(
+                    "Concurrent control-board replacement or MAC ownership conflict"
+                ) from exc
+            raise
+        except CheckViolation as exc:
+            connection.rollback()
+            if exc.diag.constraint_name == "ck_current_control_board_projection":
+                raise ControlBoardReplacementConflict(
+                    "Control-board projection would contradict authoritative history"
+                ) from exc
+            raise
+        except Exception:
+            connection.rollback()
+            raise
+        finally:
+            connection.close()
+
+    @contextmanager
+    def _connection_scope(
+        self,
+        *,
+        write: bool = False,
+    ) -> Iterator[psycopg.Connection]:
+        if self._connection is not None:
+            yield self._connection
+            return
+
+        connection = self._connection_factory()
+        try:
+            yield connection
+            if write:
+                connection.commit()
+        except Exception:
+            if write:
+                connection.rollback()
+            raise
+        finally:
+            connection.close()
+
+    def lock_miner_for_update(self, miner_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT id, asset_tag, lifecycle_status, current_mac, control_board_sn,
+                           firmware_version
+                    FROM miners
+                    WHERE id = %s
+                    FOR UPDATE
+                    """,
+                    (miner_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def lock_miner_for_control_board_replacement(
+        self, miner_id: UUID
+    ) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                try:
+                    cur.execute(
+                        """
+                        SELECT id, asset_tag, lifecycle_status, current_mac,
+                               control_board_sn, firmware_version
+                        FROM miners WHERE id = %s FOR UPDATE NOWAIT
+                        """,
+                        (miner_id,),
+                    )
+                except LockNotAvailable as exc:
+                    raise ControlBoardReplacementConflict(
+                        "A control-board replacement is already in progress"
+                    ) from exc
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def get_active_repair(self, miner_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        id,
+                        miner_id,
+                        status,
+                        reason,
+                        opened_at,
+                        opened_by,
+                        completed_at,
+                        completed_by
+                    FROM repairs
+                    WHERE miner_id = %s
+                      AND status = ANY(%s)
+                    ORDER BY opened_at, id
+                    LIMIT 1
+                    """,
+                    (miner_id, list(ACTIVE_REPAIR_STATUSES)),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def create_repair(
+        self,
+        miner_id: UUID,
+        reason: str,
+        opened_by: UUID,
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                try:
+                    cur.execute(
+                        """
+                        INSERT INTO repairs (miner_id, reason, opened_by)
+                        VALUES (%s, %s, %s)
+                        RETURNING
+                            id,
+                            miner_id,
+                            status,
+                            reason,
+                            opened_at,
+                            opened_by,
+                            completed_at,
+                            completed_by
+                        """,
+                        (miner_id, reason, opened_by),
+                    )
+                except UniqueViolation as exc:
+                    if exc.diag.constraint_name == ACTIVE_REPAIR_CONSTRAINT:
+                        raise ActiveRepairConflict(miner_id) from exc
+                    raise
+                return dict(cur.fetchone())
+
+    def create_event(
+        self,
+        repair_id: UUID,
+        *,
+        sequence: int,
+        event_type: str,
+        created_by: UUID,
+        payload: Mapping[str, Any],
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO repair_events (
+                        repair_id,
+                        sequence,
+                        event_type,
+                        created_by,
+                        payload
+                    )
+                    VALUES (%s, %s, %s, %s, %s)
+                    RETURNING
+                        id,
+                        repair_id,
+                        sequence,
+                        event_type,
+                        created_at,
+                        created_by,
+                        payload
+                    """,
+                    (
+                        repair_id,
+                        sequence,
+                        event_type,
+                        created_by,
+                        Jsonb(dict(payload)),
+                    ),
+                )
+                return dict(cur.fetchone())
+
+    def set_miner_lifecycle(
+        self,
+        miner_id: UUID,
+        lifecycle_status: str,
+    ) -> None:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    UPDATE miners
+                    SET lifecycle_status = %s,
+                        updated_at = now()
+                    WHERE id = %s
+                    """,
+                    (lifecycle_status, miner_id),
+                )
+                if cur.rowcount != 1:
+                    raise RepairPersistenceError(
+                        "Miner lifecycle transition did not update one record"
+                    )
+
+    def get_repair_identity(self, repair_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT id, miner_id
+                    FROM repairs
+                    WHERE id = %s
+                    """,
+                    (repair_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def lock_repair_for_update(self, repair_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        id,
+                        miner_id,
+                        status,
+                        reason,
+                        opened_at,
+                        opened_by,
+                        completed_at,
+                        completed_by,
+                        completion_summary,
+                        resulting_lifecycle
+                    FROM repairs
+                    WHERE id = %s
+                    FOR UPDATE
+                    """,
+                    (repair_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def get_next_event_sequence(self, repair_id: UUID) -> int:
+        with self._connection_scope() as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT COALESCE(max(sequence), 0) + 1
+                    FROM repair_events
+                    WHERE repair_id = %s
+                    """,
+                    (repair_id,),
+                )
+                return int(cur.fetchone()[0])
+
+    def get_pre_repair_lifecycle(self, repair_id: UUID) -> str | None:
+        with self._connection_scope() as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT event.payload ->> 'from_lifecycle'
+                    FROM repair_events AS event
+                    WHERE event.repair_id = %s
+                      AND event.event_type = 'REPAIR_STARTED'
+                    ORDER BY event.sequence
+                    LIMIT 2
+                    """,
+                    (repair_id,),
+                )
+                rows = cur.fetchall()
+
+        if len(rows) != 1:
+            return None
+        lifecycle_status = rows[0][0]
+        if lifecycle_status not in {"active", "spare"}:
+            return None
+        return str(lifecycle_status)
+
+    def complete_repair(
+        self,
+        repair_id: UUID,
+        *,
+        completed_by: UUID,
+        completion_summary: str | None,
+        resulting_lifecycle: str,
+    ) -> dict | None:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    UPDATE repairs
+                    SET status = 'COMPLETED',
+                        completed_at = now(),
+                        completed_by = %s,
+                        completion_summary = %s,
+                        resulting_lifecycle = %s
+                    WHERE id = %s
+                      AND status = ANY(%s)
+                    RETURNING
+                        id,
+                        miner_id,
+                        status,
+                        reason,
+                        opened_at,
+                        opened_by,
+                        completed_at,
+                        completed_by,
+                        completion_summary,
+                        resulting_lifecycle
+                    """,
+                    (
+                        completed_by,
+                        completion_summary,
+                        resulting_lifecycle,
+                        repair_id,
+                        list(ACTIVE_REPAIR_STATUSES),
+                    ),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def lock_active_repair_for_miner(self, miner_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT id, miner_id, status, reason, opened_at, opened_by
+                    FROM repairs
+                    WHERE miner_id = %s AND status = ANY(%s)
+                    ORDER BY opened_at, id
+                    LIMIT 1
+                    FOR UPDATE
+                    """,
+                    (miner_id, list(ACTIVE_REPAIR_STATUSES)),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def lock_current_control_board(self, miner_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT * FROM miner_control_board_installations
+                    WHERE miner_id = %s AND removed_at IS NULL
+                    FOR UPDATE
+                    """,
+                    (miner_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def create_legacy_control_board(self, miner: Mapping[str, Any]) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                mac_address = miner.get("current_mac")
+                normalized_mac = (
+                    "".join(ch for ch in str(mac_address).lower() if ch in "0123456789abcdef")
+                    if mac_address else None
+                )
+                if normalized_mac and len(normalized_mac) == 12:
+                    mac_address = ":".join(
+                        normalized_mac[index:index + 2].upper()
+                        for index in range(0, 12, 2)
+                    )
+                elif normalized_mac:
+                    normalized_mac = None
+                    mac_address = None
+                cur.execute(
+                    """
+                    INSERT INTO miner_control_board_installations (
+                        miner_id, record_origin, mac_address, normalized_mac,
+                        board_serial, firmware_version
+                    )
+                    VALUES (%s, 'legacy_projection', %s, %s, %s, %s)
+                    RETURNING *
+                    """,
+                    (miner["id"], mac_address, normalized_mac,
+                     miner.get("control_board_sn"), miner.get("firmware_version")),
+                )
+                return dict(cur.fetchone())
+
+    def claim_mac_ownership(
+        self, normalized_mac: str, miner_id: UUID, actor_user_id: UUID
+    ) -> None:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    "SELECT pg_advisory_xact_lock(hashtextextended(%s, 0))",
+                    (normalized_mac,),
+                )
+                cur.execute(
+                    "SELECT miner_id FROM miner_mac_ownerships "
+                    "WHERE normalized_mac = %s FOR UPDATE",
+                    (normalized_mac,),
+                )
+                row = cur.fetchone()
+                if row and row["miner_id"] != miner_id:
+                    raise MacOwnershipConflict(normalized_mac)
+                if row is None:
+                    cur.execute(
+                        """
+                        INSERT INTO miner_mac_ownerships (
+                            normalized_mac, miner_id, claimed_at, claimed_by
+                        ) VALUES (%s, %s, now(), %s)
+                        """,
+                        (normalized_mac, miner_id, actor_user_id),
+                    )
+
+    def close_control_board(
+        self, installation_id: UUID, *, repair_id: UUID, actor_user_id: UUID,
+        disposition: str
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    UPDATE miner_control_board_installations
+                    SET removed_at = now(), removed_by = %s,
+                        removed_repair_id = %s, removed_disposition = %s
+                    WHERE id = %s AND removed_at IS NULL
+                    RETURNING *
+                    """,
+                    (actor_user_id, repair_id, disposition, installation_id),
+                )
+                row = cur.fetchone()
+                if row is None:
+                    raise RepairPersistenceError(
+                        "Current control-board installation was not closed"
+                    )
+                return dict(row)
+
+    def create_control_board_installation(
+        self, *, miner_id: UUID, repair_id: UUID, mac_address: str,
+        normalized_mac: str, board_serial: str | None, board_model: str | None,
+        board_revision: str | None, firmware_version: str | None,
+        replacement_reason: str, notes: str | None, actor_user_id: UUID
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO miner_control_board_installations (
+                        miner_id, record_origin, installed_repair_id, mac_address,
+                        normalized_mac, board_serial, board_model, board_revision,
+                        firmware_version, replacement_reason, installed_at,
+                        installed_by, notes
+                    ) VALUES (
+                        %s, 'replacement', %s, %s, %s, %s, %s, %s, %s, %s,
+                        now(), %s, %s
+                    ) RETURNING *
+                    """,
+                    (miner_id, repair_id, mac_address, normalized_mac, board_serial,
+                     board_model, board_revision, firmware_version,
+                     replacement_reason, actor_user_id, notes),
+                )
+                return dict(cur.fetchone())
+
+    def set_current_control_board(
+        self, miner_id: UUID, *, mac_address: str, board_serial: str | None
+    ) -> None:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    UPDATE miners SET current_mac = %s, control_board_sn = %s,
+                        updated_at = now() WHERE id = %s
+                    """,
+                    (mac_address, board_serial, miner_id),
+                )
+                if cur.rowcount != 1:
+                    raise RepairPersistenceError(
+                        "Current miner control-board projection was not updated"
+                    )
+
+    def ensure_network_identity_history(
+        self, miner_id: UUID, *, mac_address: str, normalized_mac: str
+    ) -> None:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    INSERT INTO miner_network_identities (
+                        miner_id, mac_address, source, is_current,
+                        first_seen_at, last_seen_at, associated_at
+                    )
+                    SELECT %s, %s, 'legacy_projection', false, NULL, NULL, now()
+                    WHERE NOT EXISTS (
+                        SELECT 1 FROM miner_network_identities
+                        WHERE miner_id = %s
+                          AND regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') = %s
+                    )
+                    """,
+                    (miner_id, mac_address, miner_id, normalized_mac),
+                )
+
+    def set_current_network_identity(
+        self, miner_id: UUID, *, mac_address: str, normalized_mac: str
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    "UPDATE miner_network_identities SET is_current = false, "
+                    "updated_at = now() WHERE miner_id = %s AND is_current",
+                    (miner_id,),
+                )
+                cur.execute(
+                    """
+                    UPDATE miner_network_identities
+                    SET is_current = true, associated_at = now(), updated_at = now()
+                    WHERE miner_id = %s
+                      AND regexp_replace(lower(mac_address), '[^0-9a-f]', '', 'g') = %s
+                    RETURNING *
+                    """,
+                    (miner_id, normalized_mac),
+                )
+                row = cur.fetchone()
+                if row is None:
+                    cur.execute(
+                        """
+                        INSERT INTO miner_network_identities (
+                            miner_id, mac_address, source, is_current,
+                            first_seen_at, last_seen_at, associated_at
+                        ) VALUES (%s, %s, 'control_board_replacement', true,
+                                  NULL, NULL, now())
+                        RETURNING *
+                        """,
+                        (miner_id, mac_address),
+                    )
+                    row = cur.fetchone()
+                return dict(row)
+
+    def lock_component_for_update(self, component_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        id,
+                        component_type,
+                        asset_id,
+                        manufacturer,
+                        model,
+                        manufacturer_serial
+                    FROM components
+                    WHERE id = %s
+                    FOR UPDATE
+                    """,
+                    (component_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def create_repair_part(
+        self,
+        *,
+        repair_part_id: UUID,
+        repair_id: UUID,
+        consumable_description: str | None,
+        quantity: object | None,
+        unit: str | None,
+        component: Mapping[str, Any] | None,
+        notes: str | None,
+        recorded_event: Mapping[str, Any],
+    ) -> dict:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO repair_parts (
+                        id,
+                        repair_id,
+                        consumable_description,
+                        quantity,
+                        unit,
+                        component_id,
+                        component_type_snapshot,
+                        component_asset_id_snapshot,
+                        component_manufacturer_snapshot,
+                        component_model_snapshot,
+                        component_manufacturer_serial_snapshot,
+                        notes,
+                        recorded_by,
+                        recorded_at,
+                        recorded_event_id
+                    )
+                    VALUES (
+                        %s, %s, %s, %s, %s, %s, %s, %s,
+                        %s, %s, %s, %s, %s, %s, %s
+                    )
+                    RETURNING *
+                    """,
+                    (
+                        repair_part_id,
+                        repair_id,
+                        consumable_description,
+                        quantity,
+                        unit,
+                        component.get("id") if component else None,
+                        component.get("component_type") if component else None,
+                        component.get("asset_id") if component else None,
+                        component.get("manufacturer") if component else None,
+                        component.get("model") if component else None,
+                        component.get("manufacturer_serial") if component else None,
+                        notes,
+                        recorded_event["created_by"],
+                        recorded_event["created_at"],
+                        recorded_event["id"],
+                    ),
+                )
+                return dict(cur.fetchone())
+
+    def get_repair_part(
+        self,
+        repair_id: UUID,
+        repair_part_id: UUID,
+    ) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT part.*, event.sequence AS recorded_event_sequence
+                    FROM repair_parts AS part
+                    JOIN repair_events AS event
+                      ON event.id = part.recorded_event_id
+                    WHERE part.repair_id = %s AND part.id = %s
+                    """,
+                    (repair_id, repair_part_id),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def get_repair_parts(self, repair_id: UUID) -> list[dict] | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        repair.id AS existing_repair_id,
+                        part.*,
+                        event.sequence AS recorded_event_sequence
+                    FROM repairs AS repair
+                    LEFT JOIN repair_parts AS part
+                      ON part.repair_id = repair.id
+                    LEFT JOIN repair_events AS event
+                      ON event.id = part.recorded_event_id
+                    WHERE repair.id = %s
+                    ORDER BY event.sequence ASC, part.id ASC
+                    """,
+                    (repair_id,),
+                )
+                rows = [dict(row) for row in cur.fetchall()]
+
+        if not rows:
+            return None
+        return [row for row in rows if row.get("id") is not None]
+
+    def lock_repair_part_for_update(
+        self,
+        repair_id: UUID,
+        repair_part_id: UUID,
+    ) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT *
+                    FROM repair_parts
+                    WHERE repair_id = %s AND id = %s
+                    FOR UPDATE
+                    """,
+                    (repair_id, repair_part_id),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def void_repair_part(
+        self,
+        repair_id: UUID,
+        repair_part_id: UUID,
+        *,
+        reason: str,
+        void_event: Mapping[str, Any],
+    ) -> dict | None:
+        with self._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    UPDATE repair_parts
+                    SET voided_by = %s,
+                        voided_at = %s,
+                        void_reason = %s,
+                        void_event_id = %s
+                    WHERE repair_id = %s
+                      AND id = %s
+                      AND voided_at IS NULL
+                    RETURNING *
+                    """,
+                    (
+                        void_event["created_by"],
+                        void_event["created_at"],
+                        reason,
+                        void_event["id"],
+                        repair_id,
+                        repair_part_id,
+                    ),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def get_repair_detail(self, repair_id: UUID) -> dict | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        repair.id AS repair_id,
+                        repair.miner_id,
+                        miner.asset_tag AS miner_asset_id,
+                        repair.status,
+                        repair.reason,
+                        repair.opened_at,
+                        opened_actor.id AS opened_by_user_id,
+                        opened_actor.display_name AS opened_by_display_name,
+                        repair.completed_at AS closed_at,
+                        closed_actor.id AS closed_by_user_id,
+                        closed_actor.display_name AS closed_by_display_name,
+                        miner.lifecycle_status AS miner_lifecycle,
+                        (
+                            SELECT max(event.sequence)
+                            FROM repair_events AS event
+                            WHERE event.repair_id = repair.id
+                        ) AS latest_event_sequence
+                    FROM repairs AS repair
+                    JOIN miners AS miner ON miner.id = repair.miner_id
+                    JOIN users AS opened_actor
+                      ON opened_actor.id = repair.opened_by
+                    LEFT JOIN users AS closed_actor
+                      ON closed_actor.id = repair.completed_by
+                    WHERE repair.id = %s
+                    """,
+                    (repair_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+
+    def get_repair_events(
+        self,
+        repair_id: UUID,
+    ) -> list[dict] | None:
+        with self._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        repair.id AS repair_id,
+                        event.id AS event_id,
+                        event.sequence,
+                        event.event_type,
+                        actor.id AS actor_user_id,
+                        actor.display_name AS actor_display_name,
+                        event.created_at AS occurred_at,
+                        event.payload
+                    FROM repairs AS repair
+                    LEFT JOIN (
+                        repair_events AS event
+                        JOIN users AS actor
+                          ON actor.id = event.created_by
+                    ) ON event.repair_id = repair.id
+                    WHERE repair.id = %s
+                    ORDER BY event.sequence ASC
+                    """,
+                    (repair_id,),
+                )
+                rows = [dict(row) for row in cur.fetchall()]
+
+        if not rows:
+            return None
+        return [row for row in rows if row["event_id"] is not None]

backend/app/repairs/router.py

@@ -0,0 +1,300 @@
+"""HTTP mapping for explicit repair workflows."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.identity import require_permission
+from app.repairs.dependencies import get_repair_service
+from app.repairs.exceptions import (
+    ControlBoardReplacementActorRequired,
+    InvalidMacAddress,
+    RepairActorRequired,
+    RepairCompletionActorRequired,
+    RepairConflict,
+    RepairMinerNotFound,
+    RepairNotFound,
+    RepairPartActorRequired,
+    RepairPartComponentNotFound,
+    RepairPartNotFound,
+    RepairPartValidationError,
+)
+from app.repairs.models import (
+    BeginRepairRequest,
+    ControlBoardReplacementRequest,
+    ControlBoardReplacementResponse,
+    BeginRepairResponse,
+    RepairCompleteRequest,
+    RepairDetailResponse,
+    RepairTimelineResponse,
+    RepairPartListResponse,
+    RepairPartRecordRequest,
+    RepairPartResponse,
+    RepairPartVoidRequest,
+)
+from app.repairs.service import RepairService
+
+
+router = APIRouter(prefix="/api/repairs", tags=["repairs"])
+control_board_router = APIRouter(prefix="/api/miners", tags=["miners"])
+require_repair_create = require_permission("repairs.create")
+require_repair_read = require_permission("repairs.read")
+require_repair_complete = require_permission("repairs.complete")
+require_repair_parts_manage = require_permission("repairs.parts.manage")
+require_control_board_replace = require_permission("miners.replace_control_board")
+
+RepairServiceDependency = Annotated[
+    RepairService,
+    Depends(get_repair_service),
+]
+RepairCreateUser = Annotated[dict, Depends(require_repair_create)]
+RepairReadUser = Annotated[dict, Depends(require_repair_read)]
+RepairCompleteUser = Annotated[dict, Depends(require_repair_complete)]
+RepairPartsManageUser = Annotated[dict, Depends(require_repair_parts_manage)]
+ControlBoardReplaceUser = Annotated[dict, Depends(require_control_board_replace)]
+
+
+@control_board_router.post(
+    "/{miner_id}/replace-control-board",
+    response_model=ControlBoardReplacementResponse,
+)
+def replace_control_board(
+    miner_id: UUID,
+    request: ControlBoardReplacementRequest,
+    service: RepairServiceDependency,
+    current_user: ControlBoardReplaceUser,
+) -> ControlBoardReplacementResponse:
+    try:
+        result = service.replace_control_board(
+            miner_id, request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except RepairMinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Miner not found"
+        ) from exc
+    except RepairConflict as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail=str(exc)
+        ) from exc
+    except (InvalidMacAddress, ControlBoardReplacementActorRequired) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)
+        ) from exc
+    return ControlBoardReplacementResponse(data=result)
+
+
+@router.post(
+    "",
+    response_model=BeginRepairResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def begin_repair(
+    request: BeginRepairRequest,
+    service: RepairServiceDependency,
+    current_user: RepairCreateUser,
+) -> BeginRepairResponse:
+    try:
+        repair = service.begin_repair(
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except RepairMinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Miner not found",
+        ) from exc
+    except RepairConflict as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except RepairActorRequired as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+
+    return BeginRepairResponse(data=repair)
+
+
+@router.post(
+    "/{repair_id}/complete",
+    response_model=RepairDetailResponse,
+)
+def complete_repair(
+    repair_id: UUID,
+    request: RepairCompleteRequest,
+    service: RepairServiceDependency,
+    current_user: RepairCompleteUser,
+) -> RepairDetailResponse:
+    try:
+        repair = service.complete_repair(
+            repair_id,
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except RepairNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Repair not found",
+        ) from exc
+    except RepairMinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Repair miner no longer exists",
+        ) from exc
+    except RepairConflict as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except RepairCompletionActorRequired as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+
+    return RepairDetailResponse(data=repair)
+
+
+@router.get(
+    "/{repair_id}/parts",
+    response_model=RepairPartListResponse,
+)
+def list_repair_parts(
+    repair_id: UUID,
+    service: RepairServiceDependency,
+    current_user: RepairReadUser,
+) -> RepairPartListResponse:
+    del current_user
+    try:
+        parts = service.list_repair_parts(repair_id)
+    except RepairNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Repair not found",
+        ) from exc
+    return RepairPartListResponse(data=parts)
+
+
+@router.post(
+    "/{repair_id}/parts",
+    response_model=RepairPartResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def record_repair_part(
+    repair_id: UUID,
+    request: RepairPartRecordRequest,
+    service: RepairServiceDependency,
+    current_user: RepairPartsManageUser,
+) -> RepairPartResponse:
+    try:
+        part = service.record_repair_part(
+            repair_id,
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except (RepairNotFound, RepairPartComponentNotFound) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        ) from exc
+    except RepairMinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Repair miner no longer exists",
+        ) from exc
+    except RepairConflict as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except (RepairPartActorRequired, RepairPartValidationError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+    return RepairPartResponse(data=part)
+
+
+@router.post(
+    "/{repair_id}/parts/{repair_part_id}/void",
+    response_model=RepairPartResponse,
+)
+def void_repair_part(
+    repair_id: UUID,
+    repair_part_id: UUID,
+    request: RepairPartVoidRequest,
+    service: RepairServiceDependency,
+    current_user: RepairPartsManageUser,
+) -> RepairPartResponse:
+    try:
+        part = service.void_repair_part(
+            repair_id,
+            repair_part_id,
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+    except (RepairNotFound, RepairPartNotFound) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        ) from exc
+    except RepairMinerNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Repair miner no longer exists",
+        ) from exc
+    except RepairConflict as exc:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=str(exc),
+        ) from exc
+    except (RepairPartActorRequired, RepairPartValidationError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=str(exc),
+        ) from exc
+    return RepairPartResponse(data=part)
+
+
+@router.get(
+    "/{repair_id}",
+    response_model=RepairDetailResponse,
+)
+def get_repair(
+    repair_id: UUID,
+    service: RepairServiceDependency,
+    current_user: RepairReadUser,
+) -> RepairDetailResponse:
+    del current_user
+    try:
+        repair = service.get_repair(repair_id)
+    except RepairNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Repair not found",
+        ) from exc
+    return RepairDetailResponse(data=repair)
+
+
+@router.get(
+    "/{repair_id}/events",
+    response_model=RepairTimelineResponse,
+)
+def get_repair_events(
+    repair_id: UUID,
+    service: RepairServiceDependency,
+    current_user: RepairReadUser,
+) -> RepairTimelineResponse:
+    del current_user
+    try:
+        timeline = service.get_repair_timeline(repair_id)
+    except RepairNotFound as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Repair not found",
+        ) from exc
+    return RepairTimelineResponse(data=timeline)

backend/app/repairs/service.py

@@ -0,0 +1,684 @@
+"""Business rules and orchestration for repair workflows."""
+
+from decimal import Decimal
+from uuid import UUID, uuid4
+
+import re
+
+from app.repairs.exceptions import (
+    ActiveRepairConflict,
+    ControlBoardReplacementActorRequired,
+    ControlBoardReplacementConflict,
+    InvalidMacAddress,
+    IncompatibleMinerLifecycle,
+    InconsistentRepairState,
+    RepairActiveMismatch,
+    RepairActorRequired,
+    RepairCompletionActorRequired,
+    RepairMinerNotFound,
+    RepairMinerNotInRepair,
+    RepairNotActive,
+    RepairNotFound,
+    RepairPersistenceError,
+    RepairPartActorRequired,
+    RepairPartAlreadyVoided,
+    RepairPartComponentNotFound,
+    RepairPartNotFound,
+    RepairPartValidationError,
+)
+from app.repairs.models import (
+    BeginRepairRequest,
+    ControlBoardReplacedPayload,
+    ControlBoardReplacementRequest,
+    ControlBoardReplacementResult,
+    BeginRepairResult,
+    InitialRepairNotePayload,
+    RepairActor,
+    RepairCompleteRequest,
+    RepairCompletedPayload,
+    RepairPartComponentSnapshot,
+    RepairPartConsumable,
+    RepairPartDetail,
+    RepairPartList,
+    RepairPartRecordRequest,
+    RepairPartVoidRequest,
+    RepairDetail,
+    RepairTimeline,
+    RepairTimelineEvent,
+    RepairStartedPayload,
+)
+from app.repairs.repository import RepairRepository
+
+
+ELIGIBLE_LIFECYCLE_STATUSES = frozenset({"active", "spare"})
+ACTIVE_REPAIR_STATUSES = frozenset(
+    {"OPEN", "IN_PROGRESS", "WAITING_FOR_PARTS", "READY_FOR_TEST"}
+)
+REPAIR_LIFECYCLE_STATUS = "in_repair"
+
+
+class RepairService:
+    """Explicit operational repair workflows independent of FastAPI."""
+
+    def __init__(self, repository: RepairRepository):
+        self.repository = repository
+
+    @staticmethod
+    def normalize_note(note: str | None) -> str | None:
+        if note is None:
+            return None
+        normalized = str(note).strip()
+        return normalized or None
+
+    @staticmethod
+    def _map_repair_detail(repair: dict) -> RepairDetail:
+        closed_by = None
+        if repair["closed_by_user_id"] is not None:
+            closed_by = RepairActor(
+                user_id=repair["closed_by_user_id"],
+                display_name=repair["closed_by_display_name"],
+            )
+
+        return RepairDetail(
+            repair_id=repair["repair_id"],
+            miner_id=repair["miner_id"],
+            miner_asset_id=repair["miner_asset_id"],
+            status=repair["status"],
+            reason=repair["reason"],
+            opened_at=repair["opened_at"],
+            opened_by=RepairActor(
+                user_id=repair["opened_by_user_id"],
+                display_name=repair["opened_by_display_name"],
+            ),
+            closed_at=repair["closed_at"],
+            closed_by=closed_by,
+            miner_lifecycle=repair["miner_lifecycle"],
+            latest_event_sequence=repair["latest_event_sequence"],
+        )
+
+    def begin_repair(
+        self,
+        request: BeginRepairRequest,
+        *,
+        actor_user_id: UUID | None,
+    ) -> BeginRepairResult:
+        if actor_user_id is None:
+            raise RepairActorRequired()
+
+        note = self.normalize_note(request.notes)
+
+        with self.repository.transaction() as repository:
+            miner = repository.lock_miner_for_update(request.miner_id)
+            if not miner:
+                raise RepairMinerNotFound(request.miner_id)
+
+            lifecycle_status = str(miner["lifecycle_status"])
+            active_repair = repository.get_active_repair(request.miner_id)
+            if active_repair:
+                raise ActiveRepairConflict(request.miner_id)
+            if lifecycle_status == REPAIR_LIFECYCLE_STATUS:
+                raise InconsistentRepairState(request.miner_id)
+            if lifecycle_status not in ELIGIBLE_LIFECYCLE_STATUSES:
+                raise IncompatibleMinerLifecycle(
+                    request.miner_id,
+                    lifecycle_status,
+                )
+
+            repair = repository.create_repair(
+                request.miner_id,
+                request.reason,
+                actor_user_id,
+            )
+            started_payload = RepairStartedPayload(
+                reason=request.reason,
+                from_lifecycle=lifecycle_status,
+            )
+            repository.create_event(
+                repair["id"],
+                sequence=1,
+                event_type="REPAIR_STARTED",
+                created_by=actor_user_id,
+                payload=started_payload.model_dump(mode="json"),
+            )
+            if note is not None:
+                note_payload = InitialRepairNotePayload(note=note)
+                repository.create_event(
+                    repair["id"],
+                    sequence=2,
+                    event_type="INITIAL_NOTE",
+                    created_by=actor_user_id,
+                    payload=note_payload.model_dump(mode="json"),
+                )
+            repository.set_miner_lifecycle(
+                request.miner_id,
+                REPAIR_LIFECYCLE_STATUS,
+            )
+
+        return BeginRepairResult(
+            repair_id=repair["id"],
+            miner_id=repair["miner_id"],
+            status=repair["status"],
+            reason=repair["reason"],
+            opened_at=repair["opened_at"],
+            opened_by=repair["opened_by"],
+        )
+
+    @staticmethod
+    def normalize_optional_text(value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None
+
+    @staticmethod
+    def normalize_mac_address(value: str) -> tuple[str, str]:
+        raw = str(value).strip()
+        if not raw or re.fullmatch(r"[0-9A-Fa-f:\-.\s]+", raw) is None:
+            raise InvalidMacAddress()
+        normalized = re.sub(r"[^0-9A-Fa-f]", "", raw).lower()
+        if len(normalized) != 12:
+            raise InvalidMacAddress()
+        first_octet = int(normalized[:2], 16)
+        if normalized == "000000000000":
+            raise InvalidMacAddress("All-zero MAC addresses are not allowed")
+        if normalized == "ffffffffffff":
+            raise InvalidMacAddress("Broadcast MAC addresses are not allowed")
+        if first_octet & 1:
+            raise InvalidMacAddress("Multicast MAC addresses are not allowed")
+        canonical = ":".join(
+            normalized[index:index + 2].upper()
+            for index in range(0, 12, 2)
+        )
+        return canonical, normalized
+
+    def replace_control_board(
+        self, miner_id: UUID, request: ControlBoardReplacementRequest, *,
+        actor_user_id: UUID | None
+    ) -> ControlBoardReplacementResult:
+        if actor_user_id is None:
+            raise ControlBoardReplacementActorRequired()
+
+        new_mac, new_mac_normalized = self.normalize_mac_address(
+            request.new_mac_address
+        )
+        new_serial = self.normalize_optional_text(
+            request.new_control_board_serial
+        )
+        board_model = self.normalize_optional_text(request.board_model)
+        board_revision = self.normalize_optional_text(request.board_revision)
+        firmware_version = self.normalize_optional_text(request.firmware_version)
+        notes = self.normalize_note(request.notes)
+
+        with self.repository.transaction() as repository:
+            miner = repository.lock_miner_for_control_board_replacement(miner_id)
+            if miner is None:
+                raise RepairMinerNotFound(miner_id)
+            if str(miner["lifecycle_status"]) != REPAIR_LIFECYCLE_STATUS:
+                raise RepairMinerNotInRepair(
+                    miner_id, miner["lifecycle_status"]
+                )
+
+            repair = repository.lock_active_repair_for_miner(miner_id)
+            if repair is None:
+                raise ControlBoardReplacementConflict(
+                    "Miner has no active repair"
+                )
+
+            current_board = repository.lock_current_control_board(miner_id)
+            if current_board is None:
+                if not miner.get("current_mac") and not miner.get("control_board_sn"):
+                    raise ControlBoardReplacementConflict(
+                        "Miner has no current control-board identity to replace"
+                    )
+                current_board = repository.create_legacy_control_board(miner)
+
+            old_mac = current_board.get("mac_address") or miner.get("current_mac")
+            old_mac_canonical = None
+            old_mac_normalized = None
+            if old_mac:
+                try:
+                    old_mac_canonical, old_mac_normalized = (
+                        self.normalize_mac_address(str(old_mac))
+                    )
+                except InvalidMacAddress:
+                    old_mac_canonical = str(old_mac)
+            if old_mac_normalized == new_mac_normalized:
+                raise ControlBoardReplacementConflict(
+                    "New MAC address is the same as the current MAC address"
+                )
+
+            if old_mac_normalized is not None:
+                repository.ensure_network_identity_history(
+                    miner_id, mac_address=old_mac_canonical,
+                    normalized_mac=old_mac_normalized
+                )
+            repository.claim_mac_ownership(
+                new_mac_normalized, miner_id, actor_user_id
+            )
+            previous_board = repository.close_control_board(
+                current_board["id"],
+                repair_id=repair["id"],
+                actor_user_id=actor_user_id,
+                disposition=request.removed_board_disposition,
+            )
+            installation = repository.create_control_board_installation(
+                miner_id=miner_id,
+                repair_id=repair["id"],
+                mac_address=new_mac,
+                normalized_mac=new_mac_normalized,
+                board_serial=new_serial,
+                board_model=board_model,
+                board_revision=board_revision,
+                firmware_version=firmware_version,
+                replacement_reason=request.replacement_reason,
+                notes=notes,
+                actor_user_id=actor_user_id,
+            )
+            repository.set_current_network_identity(
+                miner_id, mac_address=new_mac,
+                normalized_mac=new_mac_normalized
+            )
+            repository.set_current_control_board(
+                miner_id, mac_address=new_mac, board_serial=new_serial
+            )
+
+            next_sequence = repository.get_next_event_sequence(repair["id"])
+            payload = ControlBoardReplacedPayload(
+                old_mac_address=old_mac_canonical,
+                new_mac_address=new_mac,
+                old_control_board_serial=previous_board.get("board_serial"),
+                new_control_board_serial=new_serial,
+                old_board_model=previous_board.get("board_model"),
+                new_board_model=board_model,
+                old_board_revision=previous_board.get("board_revision"),
+                new_board_revision=board_revision,
+                new_firmware_version=firmware_version,
+                removed_board_disposition=request.removed_board_disposition,
+                replacement_reason=request.replacement_reason,
+                notes=notes,
+            )
+            event = repository.create_event(
+                repair["id"], sequence=next_sequence,
+                event_type="CONTROL_BOARD_REPLACED",
+                created_by=actor_user_id,
+                payload=payload.model_dump(mode="json", exclude_none=False),
+            )
+
+        return ControlBoardReplacementResult(
+            miner_id=miner_id, asset_id=miner.get("asset_tag"),
+            repair_id=repair["id"], installation_id=installation["id"],
+            event_id=event["id"], event_sequence=event["sequence"],
+            current_mac=new_mac, control_board_serial=new_serial,
+            replaced_at=event["created_at"], replaced_by=actor_user_id,
+        )
+
+    def complete_repair(
+        self,
+        repair_id: UUID,
+        request: RepairCompleteRequest,
+        *,
+        actor_user_id: UUID | None,
+    ) -> RepairDetail:
+        if actor_user_id is None:
+            raise RepairCompletionActorRequired()
+
+        completion_summary = self.normalize_note(request.completion_summary)
+
+        with self.repository.transaction() as repository:
+            repair_identity = repository.get_repair_identity(repair_id)
+            if repair_identity is None:
+                raise RepairNotFound(repair_id)
+
+            miner_id = repair_identity["miner_id"]
+            # Begin Repair also locks the miner first. Keeping this order makes
+            # competing lifecycle workflows serialize on the durable asset.
+            miner = repository.lock_miner_for_update(miner_id)
+            if miner is None:
+                raise RepairMinerNotFound(miner_id)
+
+            repair = repository.lock_repair_for_update(repair_id)
+            if repair is None:
+                raise RepairNotFound(repair_id)
+            if repair["miner_id"] != miner_id:
+                raise RepairActiveMismatch(repair_id, miner_id)
+            if repair["status"] not in ACTIVE_REPAIR_STATUSES:
+                raise RepairNotActive(repair_id, repair["status"])
+
+            active_repair = repository.get_active_repair(miner_id)
+            if active_repair is None or active_repair["id"] != repair_id:
+                raise RepairActiveMismatch(repair_id, miner_id)
+
+            lifecycle_status = str(miner["lifecycle_status"])
+            if lifecycle_status != REPAIR_LIFECYCLE_STATUS:
+                raise RepairMinerNotInRepair(miner_id, lifecycle_status)
+
+            next_sequence = repository.get_next_event_sequence(repair_id)
+            pre_repair_lifecycle = repository.get_pre_repair_lifecycle(
+                repair_id
+            )
+            completed = repository.complete_repair(
+                repair_id,
+                completed_by=actor_user_id,
+                completion_summary=completion_summary,
+                resulting_lifecycle=request.target_lifecycle,
+            )
+            if completed is None:
+                raise RepairNotActive(repair_id, repair["status"])
+
+            repository.set_miner_lifecycle(
+                miner_id,
+                request.target_lifecycle,
+            )
+            payload = RepairCompletedPayload(
+                resulting_miner_lifecycle=request.target_lifecycle,
+                pre_repair_lifecycle=pre_repair_lifecycle,
+                completion_summary=completion_summary,
+            )
+            repository.create_event(
+                repair_id,
+                sequence=next_sequence,
+                event_type="REPAIR_COMPLETED",
+                created_by=actor_user_id,
+                payload=payload.model_dump(mode="json", exclude_none=True),
+            )
+
+            detail = repository.get_repair_detail(repair_id)
+            if detail is None:
+                raise RepairPersistenceError(
+                    "Completed repair could not be read in its transaction"
+                )
+
+        return self._map_repair_detail(detail)
+
+    @staticmethod
+    def _normalize_repair_part_text(
+        value: str | None,
+        *,
+        field_name: str,
+        max_length: int,
+    ) -> str | None:
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        if not normalized:
+            raise RepairPartValidationError(
+                f"{field_name} must not be blank when supplied"
+            )
+        if len(normalized) > max_length:
+            raise RepairPartValidationError(
+                f"{field_name} must not exceed {max_length} characters"
+            )
+        return normalized
+
+    @staticmethod
+    def _validate_consumable_quantity(quantity: Decimal, unit: str) -> Decimal:
+        normalized = Decimal(quantity)
+        if normalized <= 0:
+            raise RepairPartValidationError("quantity must be greater than zero")
+        significant = normalized.normalize()
+        fractional_places = max(-significant.as_tuple().exponent, 0)
+        if fractional_places > 3 or normalized >= Decimal("1000000000"):
+            raise RepairPartValidationError(
+                "quantity must fit NUMERIC(12,3)"
+            )
+        if unit == "each" and normalized != normalized.to_integral_value():
+            raise RepairPartValidationError(
+                "quantity for unit 'each' must be a whole number"
+            )
+        return normalized
+
+    @staticmethod
+    def _map_repair_part(part: dict) -> RepairPartDetail:
+        if part["consumable_description"] is not None:
+            consumable = RepairPartConsumable(
+                description=part["consumable_description"],
+                quantity=part["quantity"],
+                unit=part["unit"],
+            )
+            component_snapshot = None
+            entry_kind = "consumable"
+        else:
+            consumable = None
+            component_snapshot = RepairPartComponentSnapshot(
+                component_type=part["component_type_snapshot"],
+                asset_id=part["component_asset_id_snapshot"],
+                manufacturer=part["component_manufacturer_snapshot"],
+                model=part["component_model_snapshot"],
+                manufacturer_serial=(
+                    part["component_manufacturer_serial_snapshot"]
+                ),
+            )
+            entry_kind = "tracked_component"
+
+        return RepairPartDetail(
+            repair_part_id=part["id"],
+            repair_id=part["repair_id"],
+            entry_kind=entry_kind,
+            consumable=consumable,
+            component_id=part["component_id"],
+            component_snapshot=component_snapshot,
+            notes=part["notes"],
+            recorded_by=part["recorded_by"],
+            recorded_at=part["recorded_at"],
+            recorded_event_id=part["recorded_event_id"],
+            voided_by=part["voided_by"],
+            voided_at=part["voided_at"],
+            void_reason=part["void_reason"],
+            void_event_id=part["void_event_id"],
+        )
+
+    @staticmethod
+    def _lock_active_repair(
+        repository: RepairRepository,
+        repair_id: UUID,
+    ) -> tuple[dict, dict]:
+        identity = repository.get_repair_identity(repair_id)
+        if identity is None:
+            raise RepairNotFound(repair_id)
+
+        miner_id = identity["miner_id"]
+        miner = repository.lock_miner_for_update(miner_id)
+        if miner is None:
+            raise RepairMinerNotFound(miner_id)
+
+        repair = repository.lock_repair_for_update(repair_id)
+        if repair is None:
+            raise RepairNotFound(repair_id)
+        if repair["miner_id"] != miner_id:
+            raise RepairActiveMismatch(repair_id, miner_id)
+        if repair["status"] not in ACTIVE_REPAIR_STATUSES:
+            raise RepairNotActive(repair_id, repair["status"])
+
+        active_repair = repository.get_active_repair(miner_id)
+        if active_repair is None or active_repair["id"] != repair_id:
+            raise RepairActiveMismatch(repair_id, miner_id)
+        lifecycle_status = str(miner["lifecycle_status"])
+        if lifecycle_status != REPAIR_LIFECYCLE_STATUS:
+            raise RepairMinerNotInRepair(miner_id, lifecycle_status)
+        return miner, repair
+
+    def record_repair_part(
+        self,
+        repair_id: UUID,
+        request: RepairPartRecordRequest,
+        *,
+        actor_user_id: UUID | None,
+    ) -> RepairPartDetail:
+        if actor_user_id is None:
+            raise RepairPartActorRequired()
+
+        notes = self._normalize_repair_part_text(
+            request.notes,
+            field_name="notes",
+            max_length=4000,
+        )
+        description = None
+        quantity = None
+        unit = None
+        if request.consumable is not None:
+            description = self._normalize_repair_part_text(
+                request.consumable.description,
+                field_name="consumable.description",
+                max_length=255,
+            )
+            quantity = self._validate_consumable_quantity(
+                request.consumable.quantity,
+                request.consumable.unit,
+            )
+            unit = request.consumable.unit
+
+        with self.repository.transaction() as repository:
+            self._lock_active_repair(repository, repair_id)
+
+            component = None
+            if request.tracked_component_uuid is not None:
+                component = repository.lock_component_for_update(
+                    request.tracked_component_uuid
+                )
+                if component is None:
+                    raise RepairPartComponentNotFound(
+                        request.tracked_component_uuid
+                    )
+
+            repair_part_id = uuid4()
+            next_sequence = repository.get_next_event_sequence(repair_id)
+            if component is None:
+                payload = {
+                    "repair_part_id": str(repair_part_id),
+                    "entry_kind": "consumable",
+                    "description": description,
+                    "quantity": format(quantity, "f"),
+                    "unit": unit,
+                    "notes": notes,
+                }
+            else:
+                payload = {
+                    "repair_part_id": str(repair_part_id),
+                    "entry_kind": "tracked_component",
+                    "component_id": str(component["id"]),
+                    "component_type": component["component_type"],
+                    "component_asset_id": component["asset_id"],
+                    "component_manufacturer": component["manufacturer"],
+                    "component_model": component["model"],
+                    "component_manufacturer_serial": (
+                        component["manufacturer_serial"]
+                    ),
+                    "notes": notes,
+                }
+            event = repository.create_event(
+                repair_id,
+                sequence=next_sequence,
+                event_type="REPAIR_PART_RECORDED",
+                created_by=actor_user_id,
+                payload=payload,
+            )
+            repository.create_repair_part(
+                repair_part_id=repair_part_id,
+                repair_id=repair_id,
+                consumable_description=description,
+                quantity=quantity,
+                unit=unit,
+                component=component,
+                notes=notes,
+                recorded_event=event,
+            )
+            part = repository.get_repair_part(repair_id, repair_part_id)
+            if part is None:
+                raise RepairPersistenceError(
+                    "Recorded repair part could not be read in its transaction"
+                )
+
+        return self._map_repair_part(part)
+
+    def list_repair_parts(self, repair_id: UUID) -> RepairPartList:
+        parts = self.repository.get_repair_parts(repair_id)
+        if parts is None:
+            raise RepairNotFound(repair_id)
+        return RepairPartList(
+            repair_id=repair_id,
+            entries=[self._map_repair_part(part) for part in parts],
+        )
+
+    def void_repair_part(
+        self,
+        repair_id: UUID,
+        repair_part_id: UUID,
+        request: RepairPartVoidRequest,
+        *,
+        actor_user_id: UUID | None,
+    ) -> RepairPartDetail:
+        if actor_user_id is None:
+            raise RepairPartActorRequired()
+        reason = self._normalize_repair_part_text(
+            request.reason,
+            field_name="reason",
+            max_length=1000,
+        )
+        assert reason is not None
+
+        with self.repository.transaction() as repository:
+            self._lock_active_repair(repository, repair_id)
+            part = repository.lock_repair_part_for_update(
+                repair_id,
+                repair_part_id,
+            )
+            if part is None:
+                raise RepairPartNotFound(repair_part_id)
+            if part["voided_at"] is not None:
+                raise RepairPartAlreadyVoided(repair_part_id)
+
+            next_sequence = repository.get_next_event_sequence(repair_id)
+            event = repository.create_event(
+                repair_id,
+                sequence=next_sequence,
+                event_type="REPAIR_PART_VOIDED",
+                created_by=actor_user_id,
+                payload={
+                    "repair_part_id": str(repair_part_id),
+                    "reason": reason,
+                },
+            )
+            voided = repository.void_repair_part(
+                repair_id,
+                repair_part_id,
+                reason=reason,
+                void_event=event,
+            )
+            if voided is None:
+                raise RepairPartAlreadyVoided(repair_part_id)
+            part = repository.get_repair_part(repair_id, repair_part_id)
+            if part is None:
+                raise RepairPersistenceError(
+                    "Voided repair part could not be read in its transaction"
+                )
+
+        return self._map_repair_part(part)
+
+    def get_repair(self, repair_id: UUID) -> RepairDetail:
+        repair = self.repository.get_repair_detail(repair_id)
+        if repair is None:
+            raise RepairNotFound(repair_id)
+        return self._map_repair_detail(repair)
+
+    def get_repair_timeline(self, repair_id: UUID) -> RepairTimeline:
+        events = self.repository.get_repair_events(repair_id)
+        if events is None:
+            raise RepairNotFound(repair_id)
+
+        return RepairTimeline(
+            repair_id=repair_id,
+            events=[
+                RepairTimelineEvent(
+                    event_id=event["event_id"],
+                    sequence=event["sequence"],
+                    event_type=event["event_type"],
+                    actor=RepairActor(
+                        user_id=event["actor_user_id"],
+                        display_name=event["actor_display_name"],
+                    ),
+                    occurred_at=event["occurred_at"],
+                    payload=event["payload"],
+                )
+                for event in events
+            ],
+        )

backend/requirements.txt

@@ -11,3 +11,4 @@ email-validator==2.3.0
 python-multipart==0.0.20
 asyncpg
 pycryptodome==3.23.0
+httpx==0.28.1

backend/tests/__init__.py

@@ -0,0 +1 @@
+"""MinerOps backend tests."""

backend/tests/test_control_board_replacement.py

@@ -0,0 +1,808 @@
+import ast
+from concurrent.futures import ThreadPoolExecutor
+from threading import Barrier
+from unittest.mock import patch
+import unittest
+from contextlib import contextmanager
+from copy import deepcopy
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from psycopg.errors import CheckViolation, RaiseException, UniqueViolation
+from psycopg.rows import dict_row
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+
+from app.identity import get_current_user, required_api_permission
+from app.repairs.dependencies import get_repair_service
+from app.repairs.exceptions import (
+    ControlBoardReplacementConflict,
+    InvalidMacAddress,
+    MacOwnershipConflict,
+    RepairMinerNotFound,
+    RepairMinerNotInRepair,
+)
+from app.repairs.models import (
+    BeginRepairRequest,
+    ControlBoardReplacementRequest,
+    ControlBoardReplacementResult,
+)
+from app.repairs.repository import RepairRepository
+from app.repairs.router import control_board_router
+from app.repairs.service import RepairService
+
+
+NOW = datetime(2026, 8, 2, 12, 0, tzinfo=timezone.utc)
+
+
+def request(**overrides):
+    values = {
+        "new_mac_address": "02:AA:BB:CC:DD:02",
+        "new_control_board_serial": " CB-NEW ",
+        "board_model": " Model X ",
+        "board_revision": " Rev B ",
+        "firmware_version": " 1.2.3 ",
+        "removed_board_disposition": "sent_for_repair",
+        "replacement_reason": "failed",
+        "notes": " Board would not boot. ",
+    }
+    values.update(overrides)
+    return ControlBoardReplacementRequest(**values)
+
+
+class FakeReplacementRepository:
+    def __init__(self):
+        self.miner_id = uuid4()
+        self.repair_id = uuid4()
+        self.actor_id = uuid4()
+        self.miner = {
+            "id": self.miner_id,
+            "asset_tag": "MINER-004",
+            "lifecycle_status": "in_repair",
+            "current_mac": "02:AA:BB:CC:DD:01",
+            "control_board_sn": "CB-OLD",
+            "firmware_version": "1.0.0",
+        }
+        self.repair = {"id": self.repair_id, "miner_id": self.miner_id}
+        self.installations = []
+        self.events = [{"sequence": 1}]
+        self.identities = []
+        self.calls = []
+        self.fail_at = None
+        self.owner = None
+
+    @contextmanager
+    def transaction(self):
+        self.calls.append("transaction")
+        snapshot = deepcopy(
+            (self.miner, self.installations, self.events, self.identities)
+        )
+        try:
+            yield self
+        except Exception:
+            self.miner, self.installations, self.events, self.identities = snapshot
+            raise
+
+    def _fail(self, name):
+        self.calls.append(name)
+        if self.fail_at == name:
+            raise RuntimeError(name)
+
+    def lock_miner_for_control_board_replacement(self, miner_id):
+        self._fail("lock_miner")
+        return self.miner if miner_id == self.miner_id else None
+
+    def lock_active_repair_for_miner(self, miner_id):
+        self._fail("lock_repair")
+        return self.repair if miner_id == self.miner_id else None
+
+    def lock_current_control_board(self, miner_id):
+        self._fail("lock_board")
+        current = [row for row in self.installations if row["removed_at"] is None]
+        return current[0] if current else None
+
+    def create_legacy_control_board(self, miner):
+        self._fail("create_legacy_board")
+        row = {
+            "id": uuid4(), "miner_id": miner["id"],
+            "mac_address": miner["current_mac"],
+            "board_serial": miner["control_board_sn"],
+            "board_model": None, "board_revision": None,
+            "removed_at": None,
+        }
+        self.installations.append(row)
+        return row
+
+    def ensure_network_identity_history(self, miner_id, **values):
+        self._fail("ensure_old_identity")
+        self.identities.append({"miner_id": miner_id, "is_current": False, **values})
+
+    def claim_mac_ownership(self, normalized_mac, miner_id, actor_user_id):
+        self._fail("claim_mac")
+        if self.owner is not None and self.owner != miner_id:
+            raise MacOwnershipConflict(normalized_mac)
+        self.owner = miner_id
+
+    def close_control_board(self, installation_id, **values):
+        self._fail("close_board")
+        row = next(row for row in self.installations if row["id"] == installation_id)
+        row.update(removed_at=NOW, **values)
+        return row
+
+    def create_control_board_installation(self, **values):
+        self._fail("create_board")
+        row = {"id": uuid4(), "removed_at": None, **values, "installed_at": NOW}
+        self.installations.append(row)
+        return row
+
+    def set_current_network_identity(self, miner_id, **values):
+        self._fail("set_identity")
+        self.identities.append({"miner_id": miner_id, **values})
+        return self.identities[-1]
+
+    def set_current_control_board(self, miner_id, *, mac_address, board_serial):
+        self._fail("set_projection")
+        self.miner.update(current_mac=mac_address, control_board_sn=board_serial)
+
+    def get_next_event_sequence(self, repair_id):
+        self._fail("next_sequence")
+        return max(event["sequence"] for event in self.events) + 1
+
+    def create_event(self, repair_id, **values):
+        self._fail("create_event")
+        row = {"id": uuid4(), "repair_id": repair_id, "created_at": NOW, **values}
+        self.events.append(row)
+        return row
+
+
+class ControlBoardReplacementServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeReplacementRepository()
+        self.service = RepairService(self.repository)
+
+    def replace(self, replacement=None):
+        return self.service.replace_control_board(
+            self.repository.miner_id,
+            replacement or request(),
+            actor_user_id=self.repository.actor_id,
+        )
+
+    def test_replacement_is_atomic_and_preserves_durable_identity(self):
+        miner_id = self.repository.miner["id"]
+        asset_id = self.repository.miner["asset_tag"]
+        result = self.replace()
+
+        self.assertEqual(result.miner_id, miner_id)
+        self.assertEqual(result.asset_id, asset_id)
+        self.assertEqual(result.current_mac, "02:AA:BB:CC:DD:02")
+        self.assertEqual(result.control_board_serial, "CB-NEW")
+        self.assertEqual(self.repository.miner["id"], miner_id)
+        self.assertEqual(self.repository.miner["asset_tag"], asset_id)
+        self.assertEqual(len([x for x in self.repository.installations if x["removed_at"] is None]), 1)
+        event = self.repository.events[-1]
+        self.assertEqual(event["event_type"], "CONTROL_BOARD_REPLACED")
+        self.assertEqual(event["sequence"], 2)
+        self.assertEqual(event["created_by"], self.repository.actor_id)
+        self.assertEqual(event["payload"]["old_mac_address"], "02:AA:BB:CC:DD:01")
+        self.assertEqual(event["payload"]["old_control_board_serial"], "CB-OLD")
+        self.assertEqual(event["payload"]["notes"], "Board would not boot.")
+
+    def test_mac_normalization_and_prohibited_values(self):
+        self.assertEqual(
+            self.service.normalize_mac_address("02-aA-bb-cc-dd-02"),
+            ("02:AA:BB:CC:DD:02", "02aabbccdd02"),
+        )
+        for value in (
+            "bad", "00:00:00:00:00:00", "FF:FF:FF:FF:FF:FF",
+            "01:00:5E:00:00:01",
+        ):
+            with self.subTest(value=value), self.assertRaises(InvalidMacAddress):
+                self.service.normalize_mac_address(value)
+
+    def test_conflicting_states_do_not_write(self):
+        cases = ("active", "spare", "retired")
+        for lifecycle in cases:
+            with self.subTest(lifecycle=lifecycle):
+                repository = FakeReplacementRepository()
+                repository.miner["lifecycle_status"] = lifecycle
+                with self.assertRaises(RepairMinerNotInRepair):
+                    RepairService(repository).replace_control_board(
+                        repository.miner_id, request(),
+                        actor_user_id=repository.actor_id,
+                    )
+                self.assertEqual(repository.events, [{"sequence": 1}])
+
+    def test_same_and_historically_owned_mac_conflict(self):
+        with self.assertRaises(ControlBoardReplacementConflict):
+            self.replace(request(new_mac_address="02:AA:BB:CC:DD:01"))
+        repository = FakeReplacementRepository()
+        repository.owner = uuid4()
+        with self.assertRaises(MacOwnershipConflict):
+            RepairService(repository).replace_control_board(
+                repository.miner_id, request(), actor_user_id=repository.actor_id
+            )
+
+    def test_missing_miner_and_active_repair_conflict(self):
+        with self.assertRaises(RepairMinerNotFound):
+            self.service.replace_control_board(
+                uuid4(), request(), actor_user_id=self.repository.actor_id
+            )
+        self.repository.repair = None
+        with self.assertRaises(ControlBoardReplacementConflict):
+            self.replace()
+
+    def test_each_meaningful_write_failure_rolls_back(self):
+        for step in (
+            "claim_mac", "close_board", "create_board", "set_identity",
+            "set_projection", "create_event",
+        ):
+            with self.subTest(step=step):
+                repository = FakeReplacementRepository()
+                repository.fail_at = step
+                original = deepcopy(repository.miner)
+                with self.assertRaises(RuntimeError):
+                    RepairService(repository).replace_control_board(
+                        repository.miner_id, request(),
+                        actor_user_id=repository.actor_id,
+                    )
+                self.assertEqual(repository.miner, original)
+                self.assertEqual(repository.installations, [])
+                self.assertEqual(repository.events, [{"sequence": 1}])
+
+
+class StubReplacementService:
+    def __init__(self):
+        self.error = None
+        self.result = None
+        self.request = None
+        self.actor = None
+
+    def replace_control_board(self, miner_id, request, *, actor_user_id):
+        self.request = request
+        self.actor = actor_user_id
+        if self.error:
+            raise self.error
+        return self.result
+
+
+class ControlBoardReplacementRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubReplacementService()
+        self.app = FastAPI()
+        self.app.include_router(control_board_router)
+        self.app.dependency_overrides[get_repair_service] = lambda: self.service
+        self.client = TestClient(self.app)
+        self.actor = uuid4()
+        self.miner = uuid4()
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions=("miners.replace_control_board",), role="Technician"):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(self.actor), "role": role,
+            "permissions": list(permissions),
+        }
+
+    def post(self, body=None):
+        return self.client.post(
+            f"/api/miners/{self.miner}/replace-control-board",
+            json=(request().model_dump(mode="json") if body is None else body),
+        )
+
+    def test_authentication_and_permission_are_required(self):
+        self.assertEqual(self.post().status_code, 401)
+        self.authenticate(permissions=("miners.update",))
+        self.assertEqual(self.post().status_code, 403)
+
+    def test_success_uses_typed_envelope_and_authenticated_actor(self):
+        self.authenticate()
+        self.service.result = ControlBoardReplacementResult(
+            miner_id=self.miner, asset_id="MINER-004", repair_id=uuid4(),
+            installation_id=uuid4(), event_id=uuid4(), event_sequence=4,
+            current_mac="02:AA:BB:CC:DD:02", control_board_serial="CB-NEW",
+            replaced_at=NOW, replaced_by=self.actor,
+        )
+        response = self.post()
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["data"]["miner_id"], str(self.miner))
+        self.assertEqual(response.json()["meta"], {})
+        self.assertIsNone(response.json()["error"])
+        self.assertEqual(self.service.actor, self.actor)
+
+    def test_validation_and_domain_error_mapping(self):
+        self.authenticate()
+        self.assertEqual(self.post({"new_mac_address": "bad"}).status_code, 422)
+        self.service.error = RepairMinerNotFound(self.miner)
+        self.assertEqual(self.post().status_code, 404)
+        self.service.error = ControlBoardReplacementConflict("conflict")
+        self.assertEqual(self.post().status_code, 409)
+        self.service.error = InvalidMacAddress()
+        self.assertEqual(self.post().status_code, 422)
+
+    def test_route_and_permission_mapping_are_exact(self):
+        routes = [
+            (route.path, route.methods) for route in control_board_router.routes
+            if hasattr(route, "methods")
+        ]
+        self.assertEqual(routes, [
+            ("/api/miners/{miner_id}/replace-control-board", {"POST"})
+        ])
+        path = f"/api/miners/{self.miner}/replace-control-board"
+        self.assertEqual(
+            required_api_permission("POST", path),
+            "miners.replace_control_board",
+        )
+
+    def test_allowed_roles_and_read_only_matrix(self):
+        self.service.result = ControlBoardReplacementResult(
+            miner_id=self.miner, asset_id="MINER-004", repair_id=uuid4(),
+            installation_id=uuid4(), event_id=uuid4(), event_sequence=2,
+            current_mac="02:AA:BB:CC:DD:02", control_board_serial=None,
+            replaced_at=NOW, replaced_by=self.actor,
+        )
+        for role in ("Admin", "Manager", "Technician"):
+            with self.subTest(role=role):
+                self.authenticate(role=role)
+                self.assertEqual(self.post().status_code, 200)
+        self.authenticate(permissions=(), role="Read Only")
+        self.assertEqual(self.post().status_code, 403)
+
+    def test_request_contract_rejects_invalid_shapes(self):
+        self.authenticate()
+        valid = request().model_dump(mode="json")
+        invalid_bodies = []
+        missing_serial = dict(valid)
+        missing_serial.pop("new_control_board_serial")
+        invalid_bodies.append(missing_serial)
+        for field, value in (
+            ("new_mac_address", ""),
+            ("notes", "x" * 4001),
+            ("replacement_reason", "invented"),
+            ("removed_board_disposition", "invented"),
+        ):
+            body = dict(valid)
+            body[field] = value
+            invalid_bodies.append(body)
+        unknown = dict(valid)
+        unknown["created_by"] = str(self.actor)
+        invalid_bodies.append(unknown)
+        for body in invalid_bodies:
+            with self.subTest(body=body):
+                self.assertEqual(self.post(body).status_code, 422)
+
+
+    def test_router_has_no_sql_driver_or_transaction_management(self):
+        path = Path(__file__).parents[1] / "app" / "repairs" / "router.py"
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        modules = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                modules.extend(alias.name for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                modules.append(node.module)
+        self.assertFalse(any(name.startswith(("psycopg", "sqlalchemy", "asyncpg")) for name in modules))
+        for keyword in ("SELECT ", "INSERT ", "UPDATE ", "DELETE ", ".COMMIT(", ".ROLLBACK("):
+            self.assertNotIn(keyword, source.upper())
+
+
+class LegacyChangeMacCompatibilityTests(unittest.TestCase):
+    def setUp(self):
+        from app import main as main_module
+
+        self.main = main_module
+        self.service = StubReplacementService()
+        self.actor = uuid4()
+        self.miner = uuid4()
+        self.service.result = ControlBoardReplacementResult(
+            miner_id=self.miner, asset_id="MINER-004", repair_id=uuid4(),
+            installation_id=uuid4(), event_id=uuid4(), event_sequence=3,
+            current_mac="02:AA:BB:CC:DD:02", control_board_serial="CB-NEW",
+            replaced_at=NOW, replaced_by=self.actor,
+        )
+
+    def legacy_request(self, **overrides):
+        values = {
+            "new_mac": "02:AA:BB:CC:DD:02",
+            "component_serial": "CB-NEW",
+            "description": "Replaced during repair.",
+            "replacement_reason": "failed",
+            "removed_board_disposition": "sent_for_repair",
+        }
+        values.update(overrides)
+        return self.main.MinerMacChangeRequest(**values)
+
+    def call(self, legacy_request):
+        with patch.object(self.main, "RepairRepository"), patch.object(
+            self.main, "RepairService", return_value=self.service
+        ):
+            return self.main.change_miner_mac_address(
+                str(self.miner), legacy_request, {"id": str(self.actor)}
+            )
+
+    def test_alias_uses_same_permission_and_domain_workflow(self):
+        path = f"/api/miners/{self.miner}/change-mac"
+        self.assertEqual(
+            required_api_permission("POST", path),
+            "miners.replace_control_board",
+        )
+        response = self.call(self.legacy_request())
+        self.assertEqual(self.service.actor, self.actor)
+        self.assertEqual(self.service.request.replacement_reason, "failed")
+        self.assertEqual(
+            self.service.request.removed_board_disposition, "sent_for_repair"
+        )
+        self.assertEqual(
+            response["data"]["miner"]["current_mac"],
+            "02:AA:BB:CC:DD:02",
+        )
+        self.assertIn("control_board_replacement", response["data"])
+        self.assertNotIn("maintenance_event", response["data"])
+
+    def test_alias_does_not_fabricate_required_workflow_fields(self):
+        for changes in (
+            {"replacement_reason": None},
+            {"removed_board_disposition": None},
+            {"new_ip": "192.0.2.4"},
+            {"downtime_minutes": 10},
+        ):
+            with self.subTest(changes=changes), self.assertRaises(HTTPException) as caught:
+                self.call(self.legacy_request(**changes))
+            self.assertEqual(caught.exception.status_code, 422)
+
+    def test_alias_maps_domain_conflicts_without_internal_error(self):
+        self.service.error = ControlBoardReplacementConflict("Miner has no active repair")
+        with self.assertRaises(HTTPException) as caught:
+            self.call(self.legacy_request())
+        self.assertEqual(caught.exception.status_code, 409)
+
+
+class ControlBoardReplacementDatabaseTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.repository = RepairRepository()
+
+    def setUp(self):
+        self.actor = uuid4()
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute("DROP TRIGGER IF EXISTS test_board_event_failure ON repair_events")
+                cur.execute("DROP FUNCTION IF EXISTS test_fail_board_event()")
+                cur.execute(
+                    "TRUNCATE miner_control_board_installations, "
+                    "miner_network_identities, miner_mac_ownerships"
+                )
+                cur.execute("ALTER TABLE repair_events DISABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repair_events")
+                cur.execute("ALTER TABLE repair_events ENABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repairs")
+                cur.execute("DELETE FROM miner_tags")
+                cur.execute("DELETE FROM miner_asset_id_history")
+                cur.execute("DELETE FROM miners")
+                cur.execute("DELETE FROM users WHERE username LIKE 'board-test-%'")
+                cur.execute(
+                    """
+                    INSERT INTO users (
+                        id, username, display_name, password_hash, role_id
+                    )
+                    SELECT %s, %s, 'Board Test Actor', 'unused', id
+                    FROM roles WHERE name = 'Admin'
+                    """,
+                    (self.actor, f"board-test-{self.actor}"),
+                )
+
+    def tearDown(self):
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute("DROP TRIGGER IF EXISTS test_board_event_failure ON repair_events")
+                cur.execute("DROP FUNCTION IF EXISTS test_fail_board_event()")
+                cur.execute(
+                    "TRUNCATE miner_control_board_installations, "
+                    "miner_network_identities, miner_mac_ownerships"
+                )
+                cur.execute("ALTER TABLE repair_events DISABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repair_events")
+                cur.execute("ALTER TABLE repair_events ENABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repairs")
+                cur.execute("DELETE FROM miner_tags")
+                cur.execute("DELETE FROM miner_asset_id_history")
+                cur.execute("DELETE FROM miners")
+                cur.execute("DELETE FROM users WHERE username LIKE 'board-test-%'")
+
+
+    def create_repairing_miner(self, mac_address, serial):
+        asset_id = f"BOARD-{uuid4()}"
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO miners (
+                        asset_tag, current_mac, control_board_sn, status,
+                        lifecycle_status, first_seen_at, last_seen_at
+                    ) VALUES (%s, %s, %s, 'unknown', 'active', NULL, NULL)
+                    RETURNING id
+                    """,
+                    (asset_id, mac_address, serial),
+                )
+                miner_id = cur.fetchone()["id"]
+        repair = RepairService(self.repository).begin_repair(
+            BeginRepairRequest(miner_id=miner_id, reason="CONTROL_BOARD"),
+            actor_user_id=self.actor,
+        )
+        return miner_id, asset_id, repair.repair_id
+
+    def replace(self, miner_id, mac_address="02:AA:BB:CC:EE:02"):
+        return RepairService(self.repository).replace_control_board(
+            miner_id, request(new_mac_address=mac_address),
+            actor_user_id=self.actor,
+        )
+
+    def fetchall(self, sql, values=()):
+        with self.repository._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(sql, values)
+                return [dict(row) for row in cur.fetchall()]
+
+    def test_database_success_preserves_identity_and_authoritative_history(self):
+        miner_id, asset_id, repair_id = self.create_repairing_miner(
+            "02:AA:BB:CC:EE:01", "CB-OLD"
+        )
+        result = self.replace(miner_id)
+        miner = self.fetchall(
+            "SELECT * FROM miners WHERE id = %s", (miner_id,)
+        )[0]
+        boards = self.fetchall(
+            "SELECT * FROM miner_control_board_installations "
+            "WHERE miner_id = %s ORDER BY created_at, id", (miner_id,)
+        )
+        identities = self.fetchall(
+            "SELECT * FROM miner_network_identities "
+            "WHERE miner_id = %s ORDER BY is_current, mac_address", (miner_id,)
+        )
+        events = self.fetchall(
+            "SELECT * FROM repair_events WHERE repair_id = %s "
+            "AND event_type = 'CONTROL_BOARD_REPLACED'", (repair_id,)
+        )
+        self.assertEqual(result.miner_id, miner_id)
+        self.assertEqual(miner["asset_tag"], asset_id)
+        self.assertEqual(miner["current_mac"], "02:AA:BB:CC:EE:02")
+        self.assertEqual(len(boards), 2)
+        self.assertEqual(sum(row["removed_at"] is None for row in boards), 1)
+        legacy = next(row for row in boards if row["record_origin"] == "legacy_projection")
+        current = next(row for row in boards if row["removed_at"] is None)
+        self.assertIsNone(legacy["installed_at"])
+        self.assertIsNone(legacy["installed_by"])
+        self.assertEqual(current["record_origin"], "replacement")
+        self.assertEqual(current["installed_by"], self.actor)
+        self.assertEqual(current["normalized_mac"], "02aabbccee02")
+        self.assertEqual(len(identities), 2)
+        self.assertEqual(sum(row["is_current"] for row in identities), 1)
+        self.assertEqual(
+            next(row for row in identities if row["is_current"])["mac_address"],
+            "02:AA:BB:CC:EE:02",
+        )
+        self.assertTrue(any(row["mac_address"] == "02:AA:BB:CC:EE:01" for row in identities))
+        self.assertEqual(len(events), 1)
+        self.assertEqual(events[0]["created_by"], self.actor)
+        self.assertEqual(events[0]["sequence"], result.event_sequence)
+
+    def test_database_allows_omitted_optional_notes(self):
+        miner_id, _, repair_id = self.create_repairing_miner(
+            "02:AA:BB:CC:EA:01", "CB-OLD"
+        )
+        RepairService(self.repository).replace_control_board(
+            miner_id,
+            request(new_mac_address="02:AA:BB:CC:EA:02", notes=None),
+            actor_user_id=self.actor,
+        )
+        event = self.fetchall(
+            "SELECT payload FROM repair_events WHERE repair_id = %s "
+            "AND event_type = 'CONTROL_BOARD_REPLACED'",
+            (repair_id,),
+        )[0]
+        self.assertIn("notes", event["payload"])
+        self.assertIsNone(event["payload"]["notes"])
+
+    def test_database_constraints_prevent_drift_and_history_mutation(self):
+        miner_id, _, repair_id = self.create_repairing_miner(
+            "02:AA:BB:CC:ED:01", "CB-OLD"
+        )
+        self.replace(miner_id, "02:AA:BB:CC:ED:02")
+
+        with self.assertRaises(UniqueViolation):
+            with self.repository._connection_scope(write=True) as connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        """
+                        INSERT INTO miner_control_board_installations (
+                            miner_id, record_origin, board_serial
+                        ) VALUES (%s, 'legacy_projection', 'SECOND')
+                        """,
+                        (miner_id,),
+                    )
+        with self.assertRaises(CheckViolation):
+            with self.repository._connection_scope(write=True) as connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        "UPDATE miners SET control_board_sn = 'DRIFT' "
+                        "WHERE id = %s",
+                        (miner_id,),
+                    )
+        with self.assertRaises(CheckViolation):
+            with self.repository._connection_scope(write=True) as connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        "UPDATE miner_network_identities SET is_current = false "
+                        "WHERE miner_id = %s AND is_current",
+                        (miner_id,),
+                    )
+        with self.assertRaises(RaiseException):
+            with self.repository._connection_scope(write=True) as connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        "DELETE FROM miner_network_identities "
+                        "WHERE miner_id = %s",
+                        (miner_id,),
+                    )
+        with self.assertRaises(RaiseException):
+            with self.repository._connection_scope(write=True) as connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        "DELETE FROM miner_control_board_installations "
+                        "WHERE miner_id = %s",
+                        (miner_id,),
+                    )
+        for statement in (
+            "UPDATE miner_mac_ownerships SET miner_id = gen_random_uuid() "
+            "WHERE normalized_mac = '02aabbcced02'",
+            "DELETE FROM miner_mac_ownerships "
+            "WHERE normalized_mac = '02aabbcced02'",
+        ):
+            with self.assertRaises(RaiseException):
+                with self.repository._connection_scope(write=True) as connection:
+                    with connection.cursor() as cur:
+                        cur.execute(statement)
+        with self.assertRaises(UniqueViolation):
+            with self.repository._connection_scope(write=True) as connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        """
+                        INSERT INTO repair_events (
+                            repair_id, sequence, event_type, created_by, payload
+                        )
+                        SELECT repair_id, sequence, event_type, created_by, payload
+                        FROM repair_events
+                        WHERE repair_id = %s ORDER BY sequence LIMIT 1
+                        """,
+                        (repair_id,),
+                    )
+
+    def test_database_rejects_prohibited_component_mac(self):
+        miner_id, _, _ = self.create_repairing_miner(
+            "02:AA:BB:CC:EC:01", "CB-OLD"
+        )
+        for mac_address, normalized_mac in (
+            ("01:00:5E:00:00:01", "01005e000001"),
+            ("00:00:00:00:00:00", "000000000000"),
+            ("FF:FF:FF:FF:FF:FF", "ffffffffffff"),
+            ("02-AA-BB-CC-EC-02", "02aabbccec02"),
+        ):
+            with self.subTest(mac_address=mac_address), self.assertRaises(CheckViolation):
+                with self.repository._connection_scope(write=True) as connection:
+                    with connection.cursor() as cur:
+                        cur.execute(
+                            """
+                            INSERT INTO miner_control_board_installations (
+                                miner_id, record_origin, mac_address, normalized_mac
+                            ) VALUES (%s, 'legacy_projection', %s, %s)
+                            """,
+                            (miner_id, mac_address, normalized_mac),
+                        )
+
+
+    def test_event_failure_rolls_back_every_replacement_write(self):
+        miner_id, _, repair_id = self.create_repairing_miner(
+            "02:AA:BB:CC:EF:01", "CB-OLD"
+        )
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    CREATE FUNCTION test_fail_board_event() RETURNS trigger AS $$
+                    BEGIN
+                      IF NEW.event_type = 'CONTROL_BOARD_REPLACED' THEN
+                        RAISE EXCEPTION 'forced replacement event failure';
+                      END IF;
+                      RETURN NEW;
+                    END $$ LANGUAGE plpgsql
+                    """
+                )
+                cur.execute(
+                    "CREATE TRIGGER test_board_event_failure BEFORE INSERT ON "
+                    "repair_events FOR EACH ROW EXECUTE FUNCTION test_fail_board_event()"
+                )
+        with self.assertRaises(RaiseException):
+            self.replace(miner_id, "02:AA:BB:CC:EF:02")
+        miner = self.fetchall("SELECT * FROM miners WHERE id = %s", (miner_id,))[0]
+        self.assertEqual(miner["current_mac"], "02:AA:BB:CC:EF:01")
+        self.assertEqual(self.fetchall(
+            "SELECT * FROM miner_control_board_installations WHERE miner_id = %s",
+            (miner_id,),
+        ), [])
+        self.assertEqual(self.fetchall(
+            "SELECT * FROM miner_network_identities WHERE miner_id = %s",
+            (miner_id,),
+        ), [])
+        self.assertEqual(len(self.fetchall(
+            "SELECT * FROM repair_events WHERE repair_id = %s", (repair_id,)
+        )), 1)
+        owners = self.fetchall(
+            "SELECT normalized_mac FROM miner_mac_ownerships WHERE miner_id = %s",
+            (miner_id,),
+        )
+        self.assertEqual(owners, [{"normalized_mac": "02aabbccef01"}])
+
+    def test_concurrent_replacements_on_one_miner_succeed_once(self):
+        miner_id, _, repair_id = self.create_repairing_miner(
+            "02:AA:BB:CC:F0:01", "CB-OLD"
+        )
+        barrier = Barrier(2)
+
+        def replace(mac_address):
+            barrier.wait()
+            return self.replace(miner_id, mac_address)
+
+        outcomes = []
+        with ThreadPoolExecutor(max_workers=2) as executor:
+            futures = [
+                executor.submit(replace, "02:AA:BB:CC:F0:02"),
+                executor.submit(replace, "02:AA:BB:CC:F0:04"),
+            ]
+            for future in futures:
+                try:
+                    outcomes.append(future.result(timeout=15))
+                except ControlBoardReplacementConflict as exc:
+                    outcomes.append(exc)
+        self.assertEqual(sum(not isinstance(item, Exception) for item in outcomes), 1)
+        self.assertEqual(sum(isinstance(item, Exception) for item in outcomes), 1)
+        self.assertEqual(len(self.fetchall(
+            "SELECT * FROM miner_control_board_installations "
+            "WHERE miner_id = %s AND removed_at IS NULL", (miner_id,)
+        )), 1)
+        self.assertEqual(len(self.fetchall(
+            "SELECT * FROM repair_events WHERE repair_id = %s "
+            "AND event_type = 'CONTROL_BOARD_REPLACED'", (repair_id,)
+        )), 1)
+
+    def test_two_miners_cannot_concurrently_claim_one_mac(self):
+        first, _, _ = self.create_repairing_miner("02:AA:BB:CC:F1:01", "CB-1")
+        second, _, _ = self.create_repairing_miner("02:AA:BB:CC:F1:02", "CB-2")
+        barrier = Barrier(2)
+
+        def replace(miner_id):
+            barrier.wait()
+            return self.replace(miner_id, "02:AA:BB:CC:F1:04")
+
+        outcomes = []
+        with ThreadPoolExecutor(max_workers=2) as executor:
+            futures = [executor.submit(replace, first), executor.submit(replace, second)]
+            for future in futures:
+                try:
+                    outcomes.append(future.result(timeout=15))
+                except ControlBoardReplacementConflict as exc:
+                    outcomes.append(exc)
+        self.assertEqual(sum(not isinstance(item, Exception) for item in outcomes), 1)
+        self.assertEqual(sum(isinstance(item, Exception) for item in outcomes), 1)
+        owner = self.fetchall(
+            "SELECT miner_id FROM miner_mac_ownerships "
+            "WHERE normalized_mac = '02aabbccf104'"
+        )
+        self.assertEqual(len(owner), 1)
+
+
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_dashboard.py

@@ -0,0 +1,347 @@
+import ast
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+import psycopg
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.config import settings
+from app.dashboard.dependencies import get_dashboard_service
+from app.dashboard.models import (
+    DashboardAccess,
+    DashboardOverviewData,
+    DashboardOverviewResponse,
+)
+from app.dashboard.router import router
+from app.dashboard.service import DashboardService
+from app.identity import get_current_user
+from app.inventory.models import (
+    InventoryFleetAttentionSummary,
+    InventoryFleetSummary,
+)
+from app.inventory.repository import InventoryRepository
+from app.locations.models import LocationSummary
+from app.locations.repository import LocationMapRepository
+from app.repairs.center_repository import RepairCenterRepository
+from app.repairs.models import ActiveRepairSummary
+
+
+NOW = datetime(2026, 8, 11, 12, 0, tzinfo=timezone.utc)
+APP_ROOT = Path(__file__).parents[1] / "app"
+
+
+def fleet_summary() -> InventoryFleetSummary:
+    return InventoryFleetSummary(
+        total=12,
+        runtime_online=7,
+        runtime_offline=3,
+        runtime_unknown=2,
+        lifecycle_in_repair=2,
+        lifecycle_spare=1,
+        lifecycle_retired=1,
+        attention=InventoryFleetAttentionSummary(
+            offline=2,
+            unknown=1,
+            unstable=1,
+            repair=2,
+        ),
+    )
+
+
+class FakeInventoryService:
+    def __init__(self):
+        self.calls = 0
+
+    def summarize_fleet(self):
+        self.calls += 1
+        return fleet_summary()
+
+
+class FakeRepairService:
+    def __init__(self):
+        self.calls = 0
+
+    def summarize_active_repairs(self):
+        self.calls += 1
+        return ActiveRepairSummary(
+            active=3,
+            status_counts={"OPEN": 2, "waiting_parts": 1},
+        )
+
+
+class FakeLocationService:
+    def __init__(self):
+        self.calls = []
+
+    def summarize_locations(self, *, include_miner_counts):
+        self.calls.append(include_miner_counts)
+        return LocationSummary(
+            sites=2,
+            rooms=4,
+            positions=20,
+            occupied_positions=12,
+            empty_positions=8,
+            mapped_miners=12 if include_miner_counts else None,
+            unmapped_miners=0 if include_miner_counts else None,
+        )
+
+
+class DashboardServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.inventory = FakeInventoryService()
+        self.repairs = FakeRepairService()
+        self.locations = FakeLocationService()
+        self.service = DashboardService(
+            self.inventory,
+            self.repairs,
+            self.locations,
+        )
+
+    def test_composes_each_authorized_domain_once(self):
+        result = self.service.get_overview(
+            DashboardAccess(
+                can_view_miners=True,
+                can_view_repairs=True,
+                can_view_locations=True,
+            )
+        )
+        self.assertEqual(result.data.fleet.total, 12)
+        self.assertEqual(result.data.repairs.active, 3)
+        self.assertEqual(result.data.locations.mapped_miners, 12)
+        self.assertEqual(self.inventory.calls, 1)
+        self.assertEqual(self.repairs.calls, 1)
+        self.assertEqual(self.locations.calls, [True])
+        self.assertEqual(
+            result.meta.available_sections,
+            ["fleet", "repairs", "locations"],
+        )
+
+    def test_unauthorized_domains_are_not_called_or_returned(self):
+        result = self.service.get_overview(DashboardAccess())
+        self.assertIsNone(result.data.fleet)
+        self.assertIsNone(result.data.repairs)
+        self.assertIsNone(result.data.locations)
+        self.assertEqual(result.meta.available_sections, [])
+        self.assertEqual(self.inventory.calls, 0)
+        self.assertEqual(self.repairs.calls, 0)
+        self.assertEqual(self.locations.calls, [])
+
+    def test_location_only_summary_omits_miner_placement_counts(self):
+        result = self.service.get_overview(
+            DashboardAccess(can_view_locations=True)
+        )
+        self.assertEqual(self.locations.calls, [False])
+        self.assertIsNone(result.data.locations.mapped_miners)
+        self.assertIsNone(result.data.locations.unmapped_miners)
+        self.assertIsNone(result.data.fleet)
+
+
+class StubDashboardService:
+    def __init__(self):
+        self.access = None
+
+    def get_overview(self, access):
+        self.access = access
+        return DashboardOverviewResponse(
+            data=DashboardOverviewData(
+                fleet=fleet_summary() if access.can_view_miners else None,
+                repairs=(
+                    ActiveRepairSummary(active=1, status_counts={"OPEN": 1})
+                    if access.can_view_repairs else None
+                ),
+                locations=(
+                    LocationSummary(
+                        sites=1,
+                        rooms=1,
+                        positions=2,
+                        occupied_positions=1,
+                        empty_positions=1,
+                        mapped_miners=1 if access.can_view_miners else None,
+                        unmapped_miners=11 if access.can_view_miners else None,
+                    )
+                    if access.can_view_locations else None
+                ),
+                generated_at=NOW,
+            ),
+            meta={
+                "available_sections": [
+                    name
+                    for name, allowed in (
+                        ("fleet", access.can_view_miners),
+                        ("repairs", access.can_view_repairs),
+                        ("locations", access.can_view_locations),
+                    )
+                    if allowed
+                ]
+            },
+        )
+
+
+class DashboardRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubDashboardService()
+        self.app = FastAPI()
+        self.app.include_router(router)
+        self.app.dependency_overrides[get_dashboard_service] = lambda: self.service
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()),
+            "role": "Custom",
+            "permissions": list(permissions),
+        }
+
+    def test_requires_authentication_and_dashboard_permission(self):
+        self.assertEqual(self.client.get("/api/dashboard/overview").status_code, 401)
+        self.authenticate(("miners.view",))
+        self.assertEqual(self.client.get("/api/dashboard/overview").status_code, 403)
+
+    def test_returns_one_typed_permission_aware_envelope(self):
+        self.authenticate(("dashboard.view", "miners.view", "locations.view"))
+        response = self.client.get("/api/dashboard/overview")
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["data"]["fleet"]["total"], 12)
+        self.assertIsNone(payload["data"]["repairs"])
+        self.assertEqual(payload["data"]["locations"]["mapped_miners"], 1)
+        self.assertEqual(
+            payload["meta"]["available_sections"],
+            ["fleet", "locations"],
+        )
+        self.assertEqual(response.headers["cache-control"], "no-store")
+        self.assertFalse(self.service.access.can_view_repairs)
+
+    def test_location_only_response_contains_no_miner_counts(self):
+        self.authenticate(("dashboard.view", "locations.view"))
+        payload = self.client.get("/api/dashboard/overview").json()
+        self.assertIsNone(payload["data"]["fleet"])
+        self.assertIsNone(payload["data"]["locations"]["mapped_miners"])
+        self.assertIsNone(payload["data"]["locations"]["unmapped_miners"])
+
+
+class DashboardRepositoryIntegrationTests(unittest.TestCase):
+    def setUp(self):
+        self.connection = psycopg.connect(
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            dbname=settings.postgres_db,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+        )
+
+    def tearDown(self):
+        self.connection.rollback()
+        self.connection.close()
+
+    def test_fleet_counts_are_exact_unbounded_and_preserve_overlap(self):
+        repository = InventoryRepository(connection=self.connection)
+        before = repository.summarize_fleet()
+        rows = []
+        states = (
+            ("offline", "in_repair"),
+            ("online", "spare"),
+            ("maintenance", "retired"),
+            ("online", "active"),
+            ("offline", "active"),
+            ("unknown", "active"),
+        )
+        for runtime, lifecycle in states:
+            rows.append((uuid4(), runtime, lifecycle))
+        bulk = [(uuid4(), "online", "active") for _ in range(501)]
+        with self.connection.cursor() as cur:
+            cur.executemany(
+                "INSERT INTO miners (id, status, lifecycle_status, first_seen_at, last_seen_at) "
+                "VALUES (%s, %s, %s, NULL, NULL)",
+                [*rows, *bulk],
+            )
+            cur.execute(
+                "INSERT INTO miner_status_snapshots (miner_id, hash_stable) VALUES (%s, false)",
+                (rows[3][0],),
+            )
+        after = repository.summarize_fleet()
+        self.assertEqual(after["total"] - before["total"], 507)
+        self.assertEqual(after["runtime_online"] - before["runtime_online"], 503)
+        self.assertEqual(after["runtime_offline"] - before["runtime_offline"], 2)
+        self.assertEqual(after["runtime_unknown"] - before["runtime_unknown"], 2)
+        self.assertEqual(after["lifecycle_in_repair"] - before["lifecycle_in_repair"], 1)
+        self.assertEqual(after["lifecycle_spare"] - before["lifecycle_spare"], 1)
+        self.assertEqual(after["lifecycle_retired"] - before["lifecycle_retired"], 1)
+        self.assertEqual(after["attention_repair"] - before["attention_repair"], 1)
+        self.assertEqual(after["attention_offline"] - before["attention_offline"], 1)
+        self.assertEqual(after["attention_unknown"] - before["attention_unknown"], 1)
+        self.assertEqual(after["attention_unstable"] - before["attention_unstable"], 1)
+
+    def test_location_summary_uses_current_positions_not_virtual_map_subset(self):
+        repository = LocationMapRepository(connection=self.connection)
+        before = repository.summarize_locations(include_miner_counts=True)
+        site_id, room_id = uuid4(), uuid4()
+        mapped_id, unmapped_id = uuid4(), uuid4()
+        with self.connection.cursor() as cur:
+            cur.execute("INSERT INTO sites (id, name) VALUES (%s, %s)", (site_id, str(site_id)))
+            cur.execute(
+                "INSERT INTO rooms (id, site_id, name) VALUES (%s, %s, %s)",
+                (room_id, site_id, str(room_id)),
+            )
+            cur.executemany(
+                "INSERT INTO miners (id, lifecycle_status, first_seen_at, last_seen_at) "
+                "VALUES (%s, 'active', NULL, NULL)",
+                [(mapped_id,), (unmapped_id,)],
+            )
+            cur.execute(
+                "INSERT INTO location_positions (room_id, room_name, rack_name, shelf_name, "
+                "position_index, miner_id) VALUES (%s, 'Room', 'A', '1', 1, %s), "
+                "(%s, 'Room', 'A', '1', 2, NULL)",
+                (room_id, mapped_id, room_id),
+            )
+        after = repository.summarize_locations(include_miner_counts=True)
+        self.assertEqual(after["sites"] - before["sites"], 1)
+        self.assertEqual(after["rooms"] - before["rooms"], 1)
+        self.assertEqual(after["positions"] - before["positions"], 2)
+        self.assertEqual(after["occupied_positions"] - before["occupied_positions"], 1)
+        self.assertEqual(after["empty_positions"] - before["empty_positions"], 1)
+        self.assertEqual(after["mapped_miners"] - before["mapped_miners"], 1)
+        self.assertEqual(after["unmapped_miners"] - before["unmapped_miners"], 1)
+
+    def test_repair_summary_executes_without_loading_queue_items(self):
+        summary = RepairCenterRepository().summarize_active_repairs()
+        self.assertIn("active", summary)
+        self.assertIn("status_counts", summary)
+
+
+class DashboardArchitectureTests(unittest.TestCase):
+    def test_router_and_service_have_no_sql_or_database_driver_imports(self):
+        for relative in ("dashboard/router.py", "dashboard/service.py"):
+            source = (APP_ROOT / relative).read_text(encoding="utf-8")
+            modules = []
+            for node in ast.walk(ast.parse(source)):
+                if isinstance(node, ast.Import):
+                    modules.extend(alias.name for alias in node.names)
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    modules.append(node.module)
+            self.assertFalse(
+                any(name.startswith(("psycopg", "sqlalchemy", "asyncpg")) for name in modules)
+            )
+            for keyword in ("SELECT ", "INSERT ", "UPDATE ", "DELETE "):
+                self.assertNotIn(keyword, source.upper())
+
+    def test_dashboard_frontend_has_one_read_only_request_and_safe_dom_writes(self):
+        source = (APP_ROOT / "frontend" / "static" / "dashboard.js").read_text(
+            encoding="utf-8"
+        )
+        self.assertEqual(source.count('fetch("/api/dashboard/overview"'), 1)
+        self.assertNotIn("innerHTML", source)
+        self.assertNotIn("setInterval", source)
+        self.assertNotIn('method: "POST"', source)
+        self.assertNotIn('method: "PATCH"', source)
+        self.assertNotIn('method: "DELETE"', source)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_frontend_shell.py

@@ -0,0 +1,572 @@
+import re
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+from urllib.parse import parse_qs, urlsplit
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.frontend.router import router
+from app.identity import (
+    get_current_user,
+    router as identity_router,
+    safe_next_path,
+    install_identity_middleware,
+    protected_page,
+    required_page_permission,
+)
+
+
+ROUTES = (
+    "/dashboard",
+    "/monitoring/map",
+    "/operations/repairs",
+    "/assets/miners",
+)
+STATIC_ROOT = Path(__file__).parents[1] / "app" / "frontend" / "static"
+
+
+class FrontendShellTests(unittest.TestCase):
+    def setUp(self):
+        self.app = FastAPI()
+        self.app.include_router(router)
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions=None, role="Read Only"):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": "00000000-0000-0000-0000-000000000321",
+            "username": "operator",
+            "display_name": "Floor Operator",
+            "role": role,
+            "permissions": list(
+                permissions
+                or (
+                    "dashboard.view",
+                    "locations.view",
+                    "repairs.view",
+                    "miners.view",
+                )
+            ),
+        }
+
+    def test_routes_require_authentication(self):
+        for path in ROUTES:
+            with self.subTest(path=path):
+                self.assertEqual(self.client.get(path).status_code, 401)
+
+    def test_all_direct_routes_render_authenticated_shell(self):
+        self.authenticate()
+        for path in ROUTES:
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 200)
+                self.assertIn("MinerOps", response.text)
+                self.assertIn(
+                    "Operational Intelligence for Mining",
+                    response.text,
+                )
+                self.assertIn("Floor Operator", response.text)
+                self.assertIn(
+                    'aria-label="Primary navigation"',
+                    response.text,
+                )
+
+    def test_navigation_connects_all_internal_alpha_views(self):
+        self.authenticate()
+        response = self.client.get("/dashboard")
+        for path in ROUTES:
+            self.assertIn(f'href="{path}"', response.text)
+        self.assertIn('aria-current="page"', response.text)
+
+    def test_each_route_requires_its_specific_permission(self):
+        cases = (
+            ("/dashboard", "dashboard.view"),
+            ("/monitoring/map", "locations.view"),
+            ("/operations/repairs", "repairs.view"),
+            ("/assets/miners", "miners.view"),
+        )
+        for path, permission in cases:
+            with self.subTest(path=path):
+                self.authenticate(permissions=("unrelated.permission",))
+                self.assertEqual(self.client.get(path).status_code, 403)
+                self.authenticate(permissions=(permission,))
+                self.assertEqual(self.client.get(path).status_code, 200)
+
+    def test_main_authentication_gate_redirects_to_existing_login(self):
+        app = FastAPI()
+        app.include_router(router)
+        install_identity_middleware(app)
+        with TestClient(app) as client, patch(
+            "app.identity.request_user_or_none",
+            return_value=None,
+        ):
+            for path in ROUTES:
+                with self.subTest(path=path):
+                    response = client.get(path, follow_redirects=False)
+                    self.assertEqual(response.status_code, 303)
+                    self.assertTrue(
+                        response.headers["location"].startswith(
+                            "/login?next="
+                        )
+                    )
+
+    def test_page_permission_mapping_covers_new_routes(self):
+        expected = {
+            "/dashboard": "dashboard.view",
+            "/monitoring/map": "locations.view",
+            "/operations/repairs": "repairs.view",
+            "/assets/miners": "miners.view",
+        }
+        for path, permission in expected.items():
+            with self.subTest(path=path):
+                self.assertTrue(protected_page(path))
+                self.assertEqual(
+                    required_page_permission(path),
+                    permission,
+                )
+
+    def test_dashboard_does_not_fabricate_operational_values(self):
+        self.authenticate()
+        response = self.client.get("/dashboard")
+        for value in (
+            'id="dashboardFleetTotal"',
+            'id="dashboardActiveRepairs"',
+            'id="dashboardSites"',
+            "/assets/minerops-dashboard.js",
+            "Runtime and lifecycle are separate dimensions",
+        ):
+            self.assertIn(value, response.text)
+        self.assertIn("Loading operational overview", response.text)
+        self.assertNotIn("Live health summary not yet connected", response.text)
+        self.assertNotIn("100 TH/s", response.text)
+
+    def test_dashboard_html_omits_unauthorized_sections_and_links(self):
+        self.authenticate(permissions=("dashboard.view", "locations.view"))
+        response = self.client.get("/dashboard")
+        self.assertIn("Locations", response.text)
+        self.assertIn("Open Mine Map", response.text)
+        self.assertNotIn("Fleet overview", response.text)
+        self.assertNotIn("Needs attention", response.text)
+        self.assertNotIn("Open Fleet", response.text)
+        self.assertNotIn("Active repair records", response.text)
+        self.assertNotIn("Open Repair Center", response.text)
+        self.assertNotIn("Mapped miners", response.text)
+        self.assertNotIn("Unmapped miners", response.text)
+
+    def test_dashboard_script_dom_contract_matches_authorized_page(self):
+        self.authenticate()
+        response = self.client.get("/dashboard")
+        javascript = (STATIC_ROOT / "dashboard.js").read_text(encoding="utf-8")
+        declared_ids = re.search(r"const ids = \[(.*?)\];", javascript, re.DOTALL)
+        self.assertIsNotNone(declared_ids)
+        required = set(re.findall(r'"([A-Za-z][A-Za-z0-9]+)"', declared_ids.group(1)))
+        rendered = set(re.findall(r'id="([A-Za-z][A-Za-z0-9]+)"', response.text))
+        self.assertEqual(required - rendered, set())
+
+    def test_map_is_a_structured_operational_view(self):
+        self.authenticate()
+        response = self.client.get("/monitoring/map")
+        for label in (
+            "Site",
+            "Room",
+            "Operational Status",
+            "Miner details",
+            "Find miner",
+        ):
+            self.assertIn(label, response.text)
+        for value in (
+            'id="mapSite"', 'id="mapRoom"', 'id="mapLayer"',
+            'id="mapProblemsOnly"',
+            'id="mapViewport"', 'id="mapInspector"',
+            '/assets/minerops-mine-map.js',
+        ):
+            self.assertIn(value, response.text)
+        self.assertNotIn("Live layout and telemetry data are not", response.text)
+
+    def test_map_script_dom_contract_matches_rendered_page(self):
+        self.authenticate()
+        response = self.client.get("/monitoring/map")
+        javascript = (STATIC_ROOT / "mine-map.js").read_text(encoding="utf-8")
+        declared_ids = re.search(
+            r"const ids = \[(.*?)\];",
+            javascript,
+            re.DOTALL,
+        )
+        self.assertIsNotNone(declared_ids)
+        required = set(
+            re.findall(
+                r'"([A-Za-z][A-Za-z0-9]+)"',
+                declared_ids.group(1),
+            )
+        )
+        required.update(
+            re.findall(
+                r'document\.getElementById\("([^"]+)"\)',
+                javascript,
+            )
+        )
+        rendered = set(re.findall(r'\bid="([^"]+)"', response.text))
+        self.assertEqual(required - rendered, set())
+
+    def test_data_views_include_all_request_states(self):
+        self.authenticate()
+        for path in ("/operations/repairs", "/assets/miners"):
+            with self.subTest(path=path):
+                response_text = self.client.get(path).text
+                for state in (
+                    "loading",
+                    "empty",
+                    "error",
+                    "denied",
+                    "ready",
+                ):
+                    self.assertIn(
+                        f'data-view-state="{state}"',
+                        response_text,
+                    )
+
+    def test_frontend_assets_are_responsive_and_accessible(self):
+        css = (STATIC_ROOT / "app.css").read_text(encoding="utf-8")
+        javascript = (STATIC_ROOT / "app.js").read_text(
+            encoding="utf-8"
+        )
+        self.assertIn("@media (max-width: 560px)", css)
+        self.assertIn(":focus-visible", css)
+        self.assertIn(".skip-link", css)
+        repair_center = (STATIC_ROOT / "repair-center.js").read_text(
+            encoding="utf-8"
+        )
+        self.assertIn('response.status === 401', repair_center)
+        self.assertIn('response.status === 403', repair_center)
+        self.assertIn('credentials: "same-origin"', javascript)
+
+    def test_static_assets_are_served_without_an_api_route(self):
+        css_response = self.client.get("/assets/minerops-app.css")
+        script_response = self.client.get("/assets/minerops-app.js")
+        self.assertEqual(css_response.status_code, 200)
+        self.assertEqual(
+            css_response.headers["content-type"],
+            "text/css; charset=utf-8",
+        )
+        self.assertEqual(script_response.status_code, 200)
+        paths = {route.path for route in router.routes}
+        self.assertFalse(any(path.startswith("/api/") for path in paths))
+
+    def test_live_app_prefers_new_shell_and_preserves_legacy_pages(self):
+        from app.main import app
+        from app.frontend.router import dashboard_page
+
+        first_handlers = {}
+        for route in app.routes:
+            if route.path not in first_handlers:
+                first_handlers[route.path] = route.endpoint
+
+        for path in ROUTES:
+            with self.subTest(path=path):
+                self.assertEqual(
+                    first_handlers[path].__module__,
+                    "app.frontend.router",
+                )
+        for path in (
+            "/repairs",
+            "/locations",
+            "/miners/{miner_id}/detail",
+        ):
+            with self.subTest(legacy_path=path):
+                self.assertIn(path, first_handlers)
+
+        dashboard_handlers = [
+            route.endpoint
+            for route in app.routes
+            if route.path == "/dashboard" and "GET" in (route.methods or set())
+        ]
+        self.assertIs(dashboard_handlers[0], dashboard_page)
+        self.assertEqual(dashboard_handlers.count(dashboard_page), 1)
+
+    def test_live_dashboard_excludes_legacy_dashboard_injections(self):
+        from app.main import app
+
+        current_user = {
+            "id": "00000000-0000-0000-0000-000000000654",
+            "username": "dashboard-reader",
+            "display_name": "Dashboard Reader",
+            "role": "Read Only",
+            "permissions": [
+                "dashboard.view",
+                "miners.view",
+                "locations.view",
+                "repairs.view",
+            ],
+        }
+        app.dependency_overrides[get_current_user] = lambda: current_user
+        try:
+            with patch(
+                "app.identity.request_user_or_none",
+                return_value=current_user,
+            ):
+                client = TestClient(app)
+                try:
+                    response = client.get("/dashboard")
+                finally:
+                    client.close()
+        finally:
+            app.dependency_overrides.pop(get_current_user, None)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("<title>Dashboard | MinerOps</title>", response.text)
+        self.assertIn('id="dashboardFleetTotal"', response.text)
+        self.assertEqual(response.text.count('id="dashboardFleetTotal"'), 1)
+        self.assertNotIn("/assets/minerops-repair-quick-nav.js", response.text)
+        self.assertNotIn(
+            "/assets/minerops-dashboard-repair-summary.js",
+            response.text,
+        )
+        self.assertNotIn("mineropsDashboardRepairSummary", response.text)
+        self.assertNotIn("Repair Summary", response.text)
+
+
+    def test_safe_next_path_accepts_only_protected_local_pages(self):
+        valid = (
+            "/dashboard",
+            "/assets/miners?query=S19%20Pro",
+            "/miners/00000000-0000-0000-0000-000000000123/detail",
+        )
+        for value in valid:
+            with self.subTest(valid=value):
+                self.assertEqual(safe_next_path(value), value)
+
+        invalid = (
+            None,
+            "",
+            "https://example.invalid/dashboard",
+            "//example.invalid/dashboard",
+            r"\\example.invalid\dashboard",
+            "/../login",
+            "/assets/%2f%2fexample.invalid",
+            "/dashboard#fragment",
+            "/login",
+            "/api/inventory/miners",
+            " /dashboard",
+            "/dashboard\n",
+        )
+        for value in invalid:
+            with self.subTest(invalid=value):
+                self.assertEqual(safe_next_path(value), "/dashboard")
+
+    def test_login_redirect_preserves_direct_link_query(self):
+        app = FastAPI()
+        app.include_router(identity_router)
+        app.include_router(router)
+        install_identity_middleware(app)
+        with TestClient(app) as client, patch(
+            "app.identity.request_user_or_none",
+            return_value=None,
+        ):
+            response = client.get(
+                "/assets/miners?query=S19%20Pro",
+                follow_redirects=False,
+            )
+        self.assertEqual(response.status_code, 303)
+        location = urlsplit(response.headers["location"])
+        self.assertEqual(location.path, "/login")
+        self.assertEqual(
+            parse_qs(location.query)["next"],
+            ["/assets/miners?query=S19%20Pro"],
+        )
+
+    def test_authenticated_login_redirect_rejects_unsafe_next(self):
+        app = FastAPI()
+        app.include_router(identity_router)
+        install_identity_middleware(app)
+        with TestClient(app) as client, patch(
+            "app.identity.request_user_or_none",
+            return_value={"id": "user"},
+        ):
+            for value in (
+                "https://example.invalid",
+                "//example.invalid",
+                r"\\example.invalid\dashboard",
+                "/../login",
+            ):
+                with self.subTest(value=value):
+                    response = client.get(
+                        "/login",
+                        params={"next": value},
+                        follow_redirects=False,
+                    )
+                    self.assertEqual(response.status_code, 303)
+                    self.assertEqual(
+                        response.headers["location"],
+                        "/dashboard",
+                    )
+
+    def test_login_template_escapes_safe_query_destination(self):
+        app = FastAPI()
+        app.include_router(identity_router)
+        hostile = '/assets/miners?query="><script>alert(1)</script>'
+        with TestClient(app) as client:
+            response = client.get("/login", params={"next": hostile})
+        self.assertEqual(response.status_code, 200)
+        self.assertNotIn(hostile, response.text)
+        self.assertIn("&quot;&gt;&lt;script&gt;", response.text)
+        self.assertNotIn("new URLSearchParams(location.search)", response.text)
+
+    def test_user_values_are_html_escaped(self):
+        hostile = '<img src=x onerror=alert(1)>'
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": "00000000-0000-0000-0000-000000000321",
+            "username": "operator",
+            "display_name": hostile,
+            "role": "Read Only",
+            "permissions": ["dashboard.view", "miners.view"],
+        }
+        response = self.client.get("/dashboard")
+        self.assertEqual(response.status_code, 200)
+        self.assertNotIn(hostile, response.text)
+        self.assertIn("&lt;img src=x onerror=alert(1)&gt;", response.text)
+
+    def test_navigation_and_search_are_permission_aware(self):
+        self.authenticate(permissions=("dashboard.view",))
+        response = self.client.get("/dashboard")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn('href="/dashboard"', response.text)
+        for path in ROUTES[1:]:
+            self.assertNotIn(f'href="{path}"', response.text)
+        self.assertNotIn('id="globalSearchForm"', response.text)
+        self.assertIn('data-can-view-miners="false"', response.text)
+
+    def test_assets_disable_caching_and_missing_assets_are_404(self):
+        for path in (
+            "/assets/minerops-app.css",
+            "/assets/minerops-app.js",
+            "/assets/minerops-dashboard.js",
+            "/assets/minerops-mine-map.js",
+            "/assets/minerops-fleet.js",
+        ):
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 200)
+                self.assertEqual(response.headers["cache-control"], "no-store")
+        self.assertEqual(
+            self.client.get("/assets/missing-minerops-file.js").status_code,
+            404,
+        )
+
+    def test_trailing_slash_redirects_are_consistent(self):
+        self.authenticate()
+        for path in ROUTES:
+            with self.subTest(path=path):
+                response = self.client.get(
+                    path + "/",
+                    follow_redirects=False,
+                )
+                self.assertEqual(response.status_code, 307)
+                self.assertEqual(
+                    urlsplit(response.headers["location"]).path,
+                    path,
+                )
+
+    def test_shell_markup_has_accessibility_landmarks(self):
+        self.authenticate()
+        for path in ROUTES:
+            with self.subTest(path=path):
+                text = self.client.get(path).text
+                self.assertEqual(text.count("<h1>"), 1)
+                self.assertIn('class="skip-link"', text)
+                self.assertIn('<main class="main-content"', text)
+                self.assertIn('aria-label="Primary navigation"', text)
+                self.assertIn('aria-controls="primaryNav"', text)
+
+    def test_javascript_uses_safe_dom_and_strict_failure_states(self):
+        javascript = (STATIC_ROOT / "app.js").read_text(encoding="utf-8")
+        repair_center = (STATIC_ROOT / "repair-center.js").read_text(
+            encoding="utf-8"
+        )
+        for source in (javascript, repair_center):
+            for unsafe in ("innerHTML", "insertAdjacentHTML", "document.write"):
+                self.assertNotIn(unsafe, source)
+            self.assertIn("window.location.replace", source)
+        self.assertNotIn("/api/repairs/queue", javascript)
+        self.assertIn("new AbortController()", repair_center)
+        self.assertIn("cell.textContent = text(content)", repair_center)
+        self.assertIn("encodeURIComponent(item.miner_id)", repair_center)
+        self.assertIn("invalid Repair Center response", repair_center)
+
+    def test_fleet_page_is_semantic_responsive_and_permission_aware(self):
+        self.authenticate()
+        response = self.client.get("/assets/miners")
+        self.assertEqual(response.status_code, 200)
+        for value in (
+            'id="fleetFilters"', 'id="fleetRows"', 'id="fleetResultSummary"',
+            '<table class="fleet-table">', '<th>Operational</th>',
+            'id="fleetPrevious"', 'id="fleetNext"',
+            '/assets/minerops-fleet.js', 'data-can-view-locations="true"',
+            'id="fleetSite"', 'id="fleetRoom"',
+        ):
+            self.assertIn(value, response.text)
+
+        self.authenticate(permissions=("miners.view",))
+        restricted = self.client.get("/assets/miners").text
+        self.assertIn('data-can-view-locations="false"', restricted)
+        self.assertNotIn('id="fleetSite"', restricted)
+        self.assertNotIn('id="fleetRoom"', restricted)
+
+    def test_fleet_reset_action_has_a_visible_label(self):
+        self.authenticate()
+        response = self.client.get("/assets/miners")
+        self.assertIn(
+            '<button class="quiet-button" id="fleetReset" '
+            'type="button">Reset</button>',
+            response.text,
+        )
+        css = (STATIC_ROOT / "app.css").read_text(encoding="utf-8")
+        self.assertIn(
+            ".fleet-filter-actions .quiet-button { color: var(--ink); }",
+            css,
+        )
+
+    def test_fleet_script_dom_contract_matches_authorized_page(self):
+        self.authenticate()
+        response = self.client.get("/assets/miners")
+        source = (STATIC_ROOT / "fleet.js").read_text(encoding="utf-8")
+        declared = re.search(r"const ids = \[(.*?)\];", source, re.DOTALL)
+        self.assertIsNotNone(declared)
+        required = set(re.findall(r'"([A-Za-z][A-Za-z0-9]+)"', declared.group(1)))
+        required.update(("fleetSite", "fleetRoom"))
+        rendered = set(re.findall(r'\bid="([^"]+)"', response.text))
+        self.assertEqual(required - rendered, set())
+
+    def test_fleet_script_is_bounded_read_only_and_xss_safe(self):
+        source = (STATIC_ROOT / "fleet.js").read_text(encoding="utf-8")
+        self.assertEqual(source.count('fetch("/api/inventory/miners?"'), 1)
+        self.assertNotIn("/api/location/map", source)
+        self.assertNotIn("setInterval", source)
+        for method in ('method: "POST"', 'method: "PATCH"', 'method: "PUT"', 'method: "DELETE"'):
+            self.assertNotIn(method, source)
+        for unsafe in ("innerHTML", "insertAdjacentHTML", "document.write"):
+            self.assertNotIn(unsafe, source)
+        self.assertIn("textContent", source)
+        self.assertIn('"/miners/" + encodeURIComponent(miner.id) + "/detail"', source)
+        self.assertIn('"/monitoring/map?" + params.toString()', source)
+        self.assertNotRegex(source.lower(), r"stale.{0,20}(threshold|minutes|hours)")
+        self.assertNotIn("lowHashrate", source)
+
+    def test_fleet_css_has_status_text_mobile_cards_and_visible_focus(self):
+        css = (STATIC_ROOT / "app.css").read_text(encoding="utf-8")
+        self.assertIn('.fleet-row[data-status="offline"]', css)
+        self.assertIn("content: attr(data-label)", css)
+        self.assertIn(".fleet-pagination", css)
+        self.assertIn(":focus-visible", css)
+
+    def test_styles_have_no_motion_to_reduce(self):
+        css = (STATIC_ROOT / "app.css").read_text(encoding="utf-8")
+        self.assertNotIn("animation:", css)
+        self.assertNotIn("transition:", css)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_inventory_domain.py

@@ -0,0 +1,718 @@
+import ast
+import unittest
+from copy import deepcopy
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from psycopg.errors import ForeignKeyViolation, UniqueViolation
+
+from app.inventory import (
+    DuplicateAssetID,
+    InventoryCreateRequest,
+    InventoryMetadataUpdateRequest,
+    InventoryRepository,
+    InventorySearchFilters,
+    InventoryService,
+    InventoryUpdateRequest,
+    InventoryValidationError,
+    MinerNotFound,
+)
+from app.inventory.models import InventoryAssetIDHistoryEntry
+
+
+def inventory_row(**overrides):
+    now = datetime.now(timezone.utc)
+    row = {
+        "id": uuid4(),
+        "site_id": None,
+        "room_id": None,
+        "asset_tag": "ASSET-001",
+        "current_mac": None,
+        "current_ip": None,
+        "hostname": None,
+        "miner_sn": None,
+        "control_board_sn": None,
+        "power_sn": None,
+        "model": None,
+        "firmware_version": None,
+        "lifecycle_status": "active",
+        "status": "unknown",
+        "notes": None,
+        "first_seen_at": None,
+        "last_seen_at": None,
+        "created_at": now,
+        "updated_at": now,
+        "tags": [],
+        "site_name": None,
+        "room_name": None,
+        "location_position_id": None,
+        "rack_label": None,
+        "shelf_label": None,
+        "position_label": None,
+        "position_index": None,
+        "observed_at": None,
+        "hashrate_ths": None,
+        "power_w": None,
+        "chip_temp_max_c": None,
+        "hash_stable": None,
+        "active_repair_id": None,
+        "active_repair_status": None,
+        "active_repair_reason": None,
+    }
+    row.update(overrides)
+    return row
+
+
+class FakeInventoryRepository:
+    def __init__(self):
+        self.rows = {}
+        self.created_values = None
+        self.asset_id_history = []
+        self.update_error = None
+        self.search_kwargs = None
+
+    @contextmanager
+    def transaction(self):
+        rows_snapshot = deepcopy(self.rows)
+        history_snapshot = deepcopy(self.asset_id_history)
+        try:
+            yield self
+        except Exception:
+            self.rows = rows_snapshot
+            self.asset_id_history = history_snapshot
+            raise
+
+    def get_miner_by_id(self, miner_id):
+        return self.rows.get(miner_id)
+
+    def get_miner_by_id_for_update(self, miner_id):
+        return self.get_miner_by_id(miner_id)
+
+    def get_miner_by_asset_id(self, asset_id):
+        key = asset_id.strip().casefold()
+        return next(
+            (
+                row
+                for row in self.rows.values()
+                if str(row.get("asset_tag") or "").strip().casefold() == key
+            ),
+            None,
+        )
+
+    def list_miners(self, *, limit=100, offset=0):
+        return list(self.rows.values())[offset : offset + limit]
+
+    def search_miners(self, **kwargs):
+        self.search_kwargs = kwargs
+        rows = list(self.rows.values())
+        lifecycle = kwargs.get("lifecycle_status")
+        if lifecycle:
+            rows = [
+                row for row in rows if row["lifecycle_status"] == lifecycle
+            ]
+        return rows[kwargs.get("offset", 0) : kwargs.get("limit", 100)]
+
+    def create_miner(self, values):
+        self.created_values = dict(values)
+        row = inventory_row(**values)
+        self.rows[row["id"]] = row
+        return row
+
+    def update_miner(self, miner_id, values):
+        if self.update_error is not None:
+            raise self.update_error
+        row = self.rows.get(miner_id)
+        if not row:
+            return None
+        row.update(values)
+        row["updated_at"] = datetime.now(timezone.utc)
+        return row
+
+    def add_asset_id_history(
+        self, miner_id, old_asset_id, new_asset_id, changed_by
+    ):
+        history = {
+            "id": uuid4(),
+            "miner_id": miner_id,
+            "old_asset_id": old_asset_id,
+            "new_asset_id": new_asset_id,
+            "changed_at": datetime.now(timezone.utc),
+            "changed_by": changed_by,
+            "changed_by_display_name": "Test Actor",
+        }
+        self.asset_id_history.append(history)
+        return history
+
+    def list_asset_id_history(self, miner_id):
+        return [
+            row
+            for row in self.asset_id_history
+            if row["miner_id"] == miner_id
+        ]
+
+    def add_tag(self, miner_id, tag_name):
+        now = datetime.now(timezone.utc)
+        tag = {
+            "id": uuid4(),
+            "name": tag_name,
+            "created_at": now,
+            "updated_at": now,
+        }
+        existing = {
+            item["name"].strip().casefold()
+            for item in self.rows[miner_id]["tags"]
+        }
+        if tag_name.casefold() not in existing:
+            self.rows[miner_id]["tags"].append(tag)
+        return tag
+
+    def remove_tag(self, miner_id, tag_id):
+        before = len(self.rows[miner_id]["tags"])
+        self.rows[miner_id]["tags"] = [
+            tag for tag in self.rows[miner_id]["tags"] if tag["id"] != tag_id
+        ]
+        return len(self.rows[miner_id]["tags"]) != before
+
+
+class InventoryServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeInventoryRepository()
+        self.service = InventoryService(self.repository)
+        self.actor_user_id = uuid4()
+
+    def test_create_normalizes_asset_id_tags_and_never_seen(self):
+        created = self.service.create_miner(
+            InventoryCreateRequest(
+                asset_id="  Mine-001  ",
+                psu_serial="  PSU-9  ",
+                tags=[" Priority ", "priority", "\tRepair\n"],
+            )
+        )
+
+        self.assertEqual(created.asset_id, "Mine-001")
+        self.assertEqual(created.psu_serial, "PSU-9")
+        self.assertEqual([tag.name for tag in created.tags], ["Priority", "Repair"])
+        self.assertIsNone(created.first_seen_at)
+        self.assertIsNone(created.last_seen_at)
+        self.assertIsNone(self.repository.created_values["first_seen_at"])
+        self.assertIsNone(self.repository.created_values["last_seen_at"])
+
+    def test_duplicate_asset_id_is_case_and_whitespace_insensitive(self):
+        row = inventory_row(asset_tag="Mine-001")
+        self.repository.rows[row["id"]] = row
+
+        with self.assertRaises(DuplicateAssetID):
+            self.service.create_miner(
+                InventoryCreateRequest(asset_id="  mine-001 ")
+            )
+
+    def test_lifecycle_validation_is_owned_by_service(self):
+        self.assertEqual(
+            self.service.validate_lifecycle_status(" SPARE "),
+            "spare",
+        )
+        with self.assertRaises(InventoryValidationError):
+            self.service.create_miner(
+                InventoryCreateRequest(
+                    asset_id="ASSET-BAD",
+                    lifecycle_status="warehouse",
+                )
+            )
+
+    def test_blank_asset_and_tags_are_rejected(self):
+        with self.assertRaises(InventoryValidationError):
+            self.service.normalize_asset_id("   ")
+        with self.assertRaises(InventoryValidationError):
+            self.service.normalize_tags(["valid", "\t\n"])
+
+    def test_asset_id_history_empty_for_known_miner(self):
+        row = inventory_row()
+        self.repository.rows[row["id"]] = row
+
+        self.assertEqual(
+            self.service.get_asset_id_history(row["id"]),
+            [],
+        )
+
+    def test_asset_id_history_maps_populated_repository_results(self):
+        row = inventory_row()
+        self.repository.rows[row["id"]] = row
+        first_changed_at = datetime(2026, 7, 27, tzinfo=timezone.utc)
+        second_changed_at = datetime(2026, 7, 28, tzinfo=timezone.utc)
+        self.repository.asset_id_history = [
+            {
+                "id": uuid4(),
+                "miner_id": row["id"],
+                "old_asset_id": "ASSET-FIRST",
+                "new_asset_id": "ASSET-SECOND",
+                "changed_at": first_changed_at,
+                "changed_by": self.actor_user_id,
+                "changed_by_display_name": "Test Actor",
+            },
+            {
+                "id": uuid4(),
+                "miner_id": row["id"],
+                "old_asset_id": "ASSET-SECOND",
+                "new_asset_id": "ASSET-THIRD",
+                "changed_at": second_changed_at,
+                "changed_by": self.actor_user_id,
+                "changed_by_display_name": "Test Actor",
+            },
+        ]
+
+        history = self.service.get_asset_id_history(row["id"])
+
+        self.assertEqual(len(history), 2)
+        self.assertTrue(
+            all(
+                isinstance(entry, InventoryAssetIDHistoryEntry)
+                for entry in history
+            )
+        )
+        self.assertEqual(
+            [entry.new_asset_id for entry in history],
+            ["ASSET-SECOND", "ASSET-THIRD"],
+        )
+        self.assertEqual(history[0].changed_by_display_name, "Test Actor")
+
+    def test_asset_id_history_unknown_miner_raises_not_found(self):
+        with self.assertRaises(MinerNotFound):
+            self.service.get_asset_id_history(uuid4())
+
+    def test_metadata_update_preserves_unspecified_fields(self):
+        row = inventory_row(
+            asset_tag="ASSET-001",
+            miner_sn="MINER-OLD",
+            power_sn="PSU-OLD",
+            model="M50",
+            notes="Old notes",
+        )
+        self.repository.rows[row["id"]] = row
+
+        updated = self.service.update_metadata(
+            row["id"],
+            InventoryMetadataUpdateRequest(
+                model="M60",
+                notes=None,
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertEqual(updated.id, row["id"])
+        self.assertEqual(updated.asset_id, "ASSET-001")
+        self.assertEqual(updated.miner_sn, "MINER-OLD")
+        self.assertEqual(updated.psu_serial, "PSU-OLD")
+        self.assertEqual(updated.model, "M60")
+        self.assertIsNone(updated.notes)
+        self.assertEqual(self.repository.asset_id_history, [])
+
+    def test_asset_id_change_preserves_uuid_and_creates_history(self):
+        row = inventory_row(asset_tag="ASSET-OLD")
+        self.repository.rows[row["id"]] = row
+
+        updated = self.service.update_metadata(
+            row["id"],
+            InventoryMetadataUpdateRequest(asset_id="  ASSET-NEW  "),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertEqual(updated.id, row["id"])
+        self.assertEqual(updated.asset_id, "ASSET-NEW")
+        self.assertEqual(len(self.repository.asset_id_history), 1)
+        history = self.repository.asset_id_history[0]
+        self.assertEqual(history["miner_id"], row["id"])
+        self.assertEqual(history["old_asset_id"], "ASSET-OLD")
+        self.assertEqual(history["new_asset_id"], "ASSET-NEW")
+        self.assertEqual(history["changed_by"], self.actor_user_id)
+
+    def test_unchanged_normalized_asset_id_creates_no_history(self):
+        row = inventory_row(asset_tag="ASSET-001")
+        original_updated_at = row["updated_at"]
+        self.repository.rows[row["id"]] = row
+
+        updated = self.service.update_metadata(
+            row["id"],
+            InventoryMetadataUpdateRequest(asset_id="  ASSET-001  "),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertEqual(updated.asset_id, "ASSET-001")
+        self.assertEqual(updated.updated_at, original_updated_at)
+        self.assertEqual(self.repository.asset_id_history, [])
+
+    def test_duplicate_asset_id_leaves_miner_and_history_unchanged(self):
+        row = inventory_row(asset_tag="ASSET-OLD")
+        duplicate = inventory_row(asset_tag="ASSET-TAKEN")
+        self.repository.rows[row["id"]] = row
+        self.repository.rows[duplicate["id"]] = duplicate
+
+        with self.assertRaises(DuplicateAssetID):
+            self.service.update_metadata(
+                row["id"],
+                InventoryMetadataUpdateRequest(asset_id=" asset-taken "),
+                actor_user_id=self.actor_user_id,
+            )
+
+        self.assertEqual(
+            self.repository.rows[row["id"]]["asset_tag"],
+            "ASSET-OLD",
+        )
+        self.assertEqual(self.repository.asset_id_history, [])
+
+    def test_empty_or_invalid_metadata_update_does_not_write(self):
+        row = inventory_row(asset_tag="ASSET-OLD", model="M50")
+        self.repository.rows[row["id"]] = row
+
+        for request in (
+            InventoryMetadataUpdateRequest(),
+            InventoryMetadataUpdateRequest(asset_id="   ", model="M60"),
+        ):
+            with self.subTest(request=request):
+                with self.assertRaises(InventoryValidationError):
+                    self.service.update_metadata(
+                        row["id"],
+                        request,
+                        actor_user_id=self.actor_user_id,
+                    )
+
+        self.assertEqual(self.repository.rows[row["id"]]["model"], "M50")
+        self.assertEqual(self.repository.asset_id_history, [])
+
+    def test_uniqueness_race_becomes_duplicate_asset_id(self):
+        row = inventory_row(asset_tag="ASSET-OLD")
+        self.repository.rows[row["id"]] = row
+        self.repository.update_error = UniqueViolation("duplicate Asset ID")
+
+        with self.assertRaises(DuplicateAssetID):
+            self.service.update_metadata(
+                row["id"],
+                InventoryMetadataUpdateRequest(asset_id="ASSET-NEW"),
+                actor_user_id=self.actor_user_id,
+            )
+
+        self.assertEqual(
+            self.repository.rows[row["id"]]["asset_tag"],
+            "ASSET-OLD",
+        )
+        self.assertEqual(self.repository.asset_id_history, [])
+
+    def test_update_maps_product_names_without_repository_rules(self):
+        row = inventory_row(asset_tag="ASSET-OLD", power_sn="PSU-OLD")
+        self.repository.rows[row["id"]] = row
+
+        updated = self.service.update_miner(
+            row["id"],
+            InventoryUpdateRequest(
+                psu_serial=" PSU-NEW ",
+                lifecycle_status="retired",
+            ),
+        )
+
+        self.assertEqual(updated.asset_id, "ASSET-OLD")
+        self.assertEqual(updated.psu_serial, "PSU-NEW")
+        self.assertEqual(updated.lifecycle_status, "retired")
+
+    def test_legacy_update_rejects_asset_id_change_without_actor(self):
+        row = inventory_row(asset_tag="ASSET-OLD")
+        self.repository.rows[row["id"]] = row
+
+        with self.assertRaisesRegex(
+            InventoryValidationError,
+            "actor-attributed metadata update",
+        ):
+            self.service.update_miner(
+                row["id"],
+                InventoryUpdateRequest(asset_id="ASSET-NEW"),
+            )
+
+        self.assertEqual(
+            self.repository.rows[row["id"]]["asset_tag"],
+            "ASSET-OLD",
+        )
+        self.assertEqual(self.repository.asset_id_history, [])
+
+    def test_fleet_projection_mapping_and_filter_forwarding(self):
+        miner_id = uuid4()
+        repair_id = uuid4()
+        site_id = uuid4()
+        row = inventory_row(
+            id=miner_id,
+            miner_sn="MINER-SN",
+            site_id=site_id,
+            site_name="North Site",
+            observed_at=datetime.now(timezone.utc),
+            hashrate_ths=0.0,
+            power_w=0.0,
+            chip_temp_max_c=0.0,
+            hash_stable=False,
+            active_repair_id=repair_id,
+            active_repair_status="IN_PROGRESS",
+            active_repair_reason="Hashboard diagnostics",
+        )
+        self.repository.rows[miner_id] = row
+        filters = InventorySearchFilters(
+            model=" M50 ", runtime_status="offline", repair="active",
+            operational_state="repair", problems=True, site_id=site_id,
+            limit=25, offset=0,
+        )
+
+        result = self.service.search_miners(
+            filters, include_location_details=True
+        )[0]
+
+        self.assertEqual(result.miner_sn, "MINER-SN")
+        self.assertEqual(result.hashrate_ths, 0.0)
+        self.assertEqual(result.power_w, 0.0)
+        self.assertEqual(result.chip_temp_max_c, 0.0)
+        self.assertFalse(result.hash_stable)
+        self.assertEqual(result.active_repair.id, repair_id)
+        self.assertEqual(self.repository.search_kwargs["model"], "M50")
+        self.assertEqual(self.repository.search_kwargs["site_id"], site_id)
+        self.assertTrue(self.repository.search_kwargs["include_location_details"])
+
+    def test_location_filter_without_projection_is_rejected(self):
+        with self.assertRaisesRegex(
+            InventoryValidationError, "Location filters require"
+        ):
+            self.service.search_miners(
+                InventorySearchFilters(site_id=uuid4())
+            )
+        self.assertIsNone(self.repository.search_kwargs)
+
+    def test_search_validation_precedes_repository(self):
+        with self.assertRaises(InventoryValidationError):
+            self.service.search_miners(
+                InventorySearchFilters(lifecycle_status="broken")
+            )
+
+
+class InventoryRepositoryIntegrationTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.repository = InventoryRepository()
+
+    def setUp(self):
+        self.actor_user_id = UUID("00000000-0000-0000-0000-000000000951")
+        with self.repository.transaction() as repository:
+            with repository._connection.cursor() as cur:
+                cur.execute("DELETE FROM miner_asset_id_history")
+                cur.execute("DELETE FROM miner_tags")
+                cur.execute("DELETE FROM tags")
+                cur.execute("DELETE FROM miners")
+                cur.execute(
+                    """
+                    INSERT INTO users (
+                        id, username, display_name, password_hash, role_id
+                    )
+                    SELECT %s, %s, %s, %s, id
+                    FROM roles
+                    WHERE name = 'Admin'
+                    ON CONFLICT (id) DO NOTHING
+                    """,
+                    (
+                        self.actor_user_id,
+                        "inventory-history-test",
+                        "Inventory History Test",
+                        "not-used",
+                    ),
+                )
+
+    def test_repository_crud_search_and_tags(self):
+        created = self.repository.create_miner(
+            {
+                "asset_tag": "REPO-001",
+                "current_ip": "192.0.2.10",
+                "model": "M50",
+                "miner_sn": "MINER-001",
+                "control_board_sn": "CB-001",
+                "power_sn": "PSU-001",
+                "lifecycle_status": "active",
+                "status": "unknown",
+                "first_seen_at": None,
+                "last_seen_at": None,
+            }
+        )
+        miner_id = created["id"]
+
+        self.assertIsInstance(miner_id, UUID)
+        self.assertIsNone(created["first_seen_at"])
+        self.assertIsNone(created["last_seen_at"])
+        self.assertEqual(
+            self.repository.get_miner_by_asset_id(" repo-001 ")["id"],
+            miner_id,
+        )
+        self.assertEqual(self.repository.get_miner_by_id(miner_id)["model"], "M50")
+        self.assertEqual(len(self.repository.list_miners()), 1)
+        self.assertEqual(
+            self.repository.search_miners(query="CB-001")[0]["id"],
+            miner_id,
+        )
+
+        fleet = self.repository.search_miners(
+            model="M50",
+            runtime_status="unknown",
+            operational_state="unknown",
+            problems=True,
+            include_location_details=True,
+        )
+        self.assertEqual(fleet[0]["id"], miner_id)
+        self.assertEqual(fleet[0]["miner_sn"], "MINER-001")
+        self.assertIsNone(fleet[0]["observed_at"])
+        self.assertIsNone(fleet[0]["location_position_id"])
+        self.assertEqual(
+            self.repository.list_location_filter_options(),
+            {"sites": [], "rooms": []},
+        )
+
+        updated = self.repository.update_miner(
+            miner_id,
+            {"lifecycle_status": "spare", "notes": "Bench stock"},
+        )
+        self.assertEqual(updated["lifecycle_status"], "spare")
+        self.assertEqual(
+            self.repository.search_miners(lifecycle_status="spare")[0]["id"],
+            miner_id,
+        )
+
+        tag = self.repository.add_tag(miner_id, "Priority")
+        repeated = self.repository.add_tag(miner_id, " priority ")
+        self.assertEqual(tag["id"], repeated["id"])
+        self.assertEqual(len(self.repository.list_tags()), 1)
+        self.assertEqual(
+            self.repository.search_miners(tag_names=["priority"])[0]["id"],
+            miner_id,
+        )
+        self.assertEqual(
+            len(self.repository.get_miner_by_id(miner_id)["tags"]),
+            1,
+        )
+        self.assertTrue(self.repository.remove_tag(miner_id, tag["id"]))
+        self.assertEqual(
+            self.repository.get_miner_by_id(miner_id)["tags"],
+            [],
+        )
+
+    def test_repeated_asset_id_changes_preserve_chronological_history(self):
+        service = InventoryService(self.repository)
+        created = service.create_miner(
+            InventoryCreateRequest(asset_id="ASSET-FIRST")
+        )
+
+        second = service.update_metadata(
+            created.id,
+            InventoryMetadataUpdateRequest(asset_id="ASSET-SECOND"),
+            actor_user_id=self.actor_user_id,
+        )
+        third = service.update_metadata(
+            created.id,
+            InventoryMetadataUpdateRequest(asset_id="ASSET-THIRD"),
+            actor_user_id=self.actor_user_id,
+        )
+        other = service.create_miner(
+            InventoryCreateRequest(asset_id="OTHER-FIRST")
+        )
+        service.update_metadata(
+            other.id,
+            InventoryMetadataUpdateRequest(asset_id="OTHER-SECOND"),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertEqual(created.id, second.id)
+        self.assertEqual(second.id, third.id)
+        history = self.repository.list_asset_id_history(created.id)
+        self.assertEqual(len(history), 2)
+        self.assertEqual(
+            [
+                (row["old_asset_id"], row["new_asset_id"])
+                for row in history
+            ],
+            [
+                ("ASSET-FIRST", "ASSET-SECOND"),
+                ("ASSET-SECOND", "ASSET-THIRD"),
+            ],
+        )
+        self.assertLessEqual(
+            history[0]["changed_at"],
+            history[1]["changed_at"],
+        )
+        self.assertTrue(
+            all(
+                row["miner_id"] == created.id
+                and row["changed_by_display_name"]
+                == "Inventory History Test"
+                for row in history
+            )
+        )
+        other_history = self.repository.list_asset_id_history(other.id)
+        self.assertEqual(len(other_history), 1)
+        self.assertEqual(other_history[0]["new_asset_id"], "OTHER-SECOND")
+
+    def test_history_failure_rolls_back_asset_id_update(self):
+        service = InventoryService(self.repository)
+        created = service.create_miner(
+            InventoryCreateRequest(asset_id="ASSET-ROLLBACK-OLD")
+        )
+
+        with self.assertRaises(ForeignKeyViolation):
+            service.update_metadata(
+                created.id,
+                InventoryMetadataUpdateRequest(
+                    asset_id="ASSET-ROLLBACK-NEW"
+                ),
+                actor_user_id=uuid4(),
+            )
+
+        persisted = self.repository.get_miner_by_id(created.id)
+        self.assertEqual(persisted["asset_tag"], "ASSET-ROLLBACK-OLD")
+        self.assertEqual(
+            self.repository.list_asset_id_history(created.id),
+            [],
+        )
+
+    def test_transaction_rolls_back_repository_writes(self):
+        with self.assertRaises(RuntimeError):
+            with self.repository.transaction() as repository:
+                repository.create_miner(
+                    {
+                        "asset_tag": "ROLLBACK-001",
+                        "status": "unknown",
+                        "first_seen_at": None,
+                        "last_seen_at": None,
+                    }
+                )
+                raise RuntimeError("rollback")
+
+        self.assertIsNone(
+            self.repository.get_miner_by_asset_id("ROLLBACK-001")
+        )
+
+
+class InventoryArchitectureTests(unittest.TestCase):
+    def test_inventory_domain_layers_have_no_http_dependency(self):
+        inventory_path = Path(__file__).parents[1] / "app" / "inventory"
+        domain_files = (
+            "dependencies.py",
+            "exceptions.py",
+            "models.py",
+            "repository.py",
+            "service.py",
+        )
+        for filename in domain_files:
+            source_path = inventory_path / filename
+            tree = ast.parse(source_path.read_text(encoding="utf-8"))
+            imported_modules = []
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    imported_modules.extend(alias.name for alias in node.names)
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    imported_modules.append(node.module)
+            self.assertFalse(
+                any(module.startswith("fastapi") for module in imported_modules),
+                source_path,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_inventory_router.py

@@ -0,0 +1,689 @@
+import ast
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.identity import get_current_user
+from app.inventory.dependencies import get_inventory_service
+from app.inventory.exceptions import (
+    DuplicateAssetID,
+    InventoryValidationError,
+    MinerNotFound,
+)
+from app.inventory.models import (
+    InventoryAssetIDHistoryEntry,
+    InventoryCreateRequest,
+    InventoryMetadataUpdateRequest,
+    InventoryMinerDetail,
+    InventoryMinerSummary,
+    InventorySearchFilters,
+)
+from app.inventory.router import router
+
+
+class StubInventoryService:
+    def __init__(self):
+        self.search_result: list[InventoryMinerSummary] = []
+        self.detail_result: InventoryMinerDetail | None = None
+        self.search_filters: InventorySearchFilters | None = None
+        self.detail_miner_id: UUID | None = None
+        self.search_error: InventoryValidationError | None = None
+        self.create_result: InventoryMinerDetail | None = None
+        self.create_error: Exception | None = None
+        self.create_request: InventoryCreateRequest | None = None
+        self.update_result: InventoryMinerDetail | None = None
+        self.update_error: Exception | None = None
+        self.update_miner_id: UUID | None = None
+        self.update_request: InventoryMetadataUpdateRequest | None = None
+        self.update_actor_user_id: UUID | None = None
+        self.history_result: list[InventoryAssetIDHistoryEntry] = []
+        self.history_error: Exception | None = None
+        self.history_miner_id: UUID | None = None
+        self.include_location_details = False
+        self.location_options = {"sites": [], "rooms": []}
+
+    def search_miners(
+        self,
+        filters: InventorySearchFilters,
+        *,
+        include_location_details: bool = False,
+    ) -> list[InventoryMinerSummary]:
+        self.search_filters = filters
+        self.include_location_details = include_location_details
+        if self.search_error is not None:
+            raise self.search_error
+        return self.search_result
+
+    def list_location_filter_options(self):
+        return self.location_options
+
+    def create_miner(
+        self,
+        request: InventoryCreateRequest,
+    ) -> InventoryMinerDetail:
+        self.create_request = request
+        if self.create_error is not None:
+            raise self.create_error
+        if self.create_result is None:
+            raise AssertionError("create_result was not configured")
+        return self.create_result
+
+    def update_metadata(
+        self,
+        miner_id: UUID,
+        request: InventoryMetadataUpdateRequest,
+        *,
+        actor_user_id: UUID,
+    ) -> InventoryMinerDetail:
+        self.update_miner_id = miner_id
+        self.update_request = request
+        self.update_actor_user_id = actor_user_id
+        if self.update_error is not None:
+            raise self.update_error
+        if self.update_result is None:
+            raise AssertionError("update_result was not configured")
+        return self.update_result
+
+    def get_miner(self, miner_id: UUID) -> InventoryMinerDetail:
+        self.detail_miner_id = miner_id
+        if self.detail_result is None or self.detail_result.id != miner_id:
+            raise MinerNotFound(miner_id)
+        return self.detail_result
+
+    def get_asset_id_history(
+        self,
+        miner_id: UUID,
+    ) -> list[InventoryAssetIDHistoryEntry]:
+        self.history_miner_id = miner_id
+        if self.history_error is not None:
+            raise self.history_error
+        return self.history_result
+
+
+def miner_summary(miner_id: UUID | None = None) -> InventoryMinerSummary:
+    now = datetime.now(timezone.utc)
+    return InventoryMinerSummary(
+        id=miner_id or uuid4(),
+        asset_id="ASSET-001",
+        model="M50",
+        lifecycle_status="active",
+        runtime_status="unknown",
+        created_at=now,
+        updated_at=now,
+    )
+
+
+def miner_detail(miner_id: UUID | None = None) -> InventoryMinerDetail:
+    values = miner_summary(miner_id).model_dump()
+    values["miner_sn"] = "MINER-001"
+    return InventoryMinerDetail(
+        **values,
+        control_board_sn="CB-001",
+        psu_serial="PSU-001",
+    )
+
+
+def history_entry(
+    *,
+    old_asset_id: str | None,
+    new_asset_id: str,
+    changed_at: datetime,
+) -> InventoryAssetIDHistoryEntry:
+    return InventoryAssetIDHistoryEntry(
+        old_asset_id=old_asset_id,
+        new_asset_id=new_asset_id,
+        changed_at=changed_at,
+        changed_by=UUID("00000000-0000-0000-0000-000000000951"),
+        changed_by_display_name="Inventory Test User",
+    )
+
+
+class InventoryRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubInventoryService()
+        self.app = FastAPI()
+        self.app.include_router(router)
+        self.app.dependency_overrides[get_inventory_service] = (
+            lambda: self.service
+        )
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions=("miners.view",)):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()),
+            "username": "reader",
+            "role": "Read Only",
+            "permissions": list(permissions),
+        }
+
+    def test_create_requires_authentication(self):
+        response = self.client.post(
+            "/api/inventory/miners",
+            json={"asset_id": "ASSET-NEW"},
+        )
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["detail"], "Login required")
+
+    def test_create_requires_miners_update_permission(self):
+        self.authenticate(permissions=("miners.view",))
+        response = self.client.post(
+            "/api/inventory/miners",
+            json={"asset_id": "ASSET-NEW"},
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertIsNone(self.service.create_request)
+
+    def test_create_returns_new_miner_in_typed_envelope(self):
+        self.authenticate(permissions=("miners.update",))
+        created = miner_detail()
+        self.service.create_result = created
+
+        response = self.client.post(
+            "/api/inventory/miners",
+            json={
+                "asset_id": "  ASSET-NEW  ",
+                "lifecycle_status": "spare",
+                "site_id": str(uuid4()),
+                "tags": ["Priority", "Repair"],
+            },
+        )
+
+        self.assertEqual(response.status_code, 201)
+        self.assertEqual(response.json()["data"]["id"], str(created.id))
+        self.assertEqual(response.json()["meta"], {})
+        self.assertIsNone(response.json()["error"])
+        request = self.service.create_request
+        self.assertIsNotNone(request)
+        self.assertEqual(request.asset_id, "  ASSET-NEW  ")
+        self.assertEqual(request.lifecycle_status, "spare")
+        self.assertEqual(request.tags, ["Priority", "Repair"])
+
+    def test_duplicate_asset_id_returns_conflict(self):
+        self.authenticate(permissions=("miners.update",))
+        self.service.create_error = DuplicateAssetID("ASSET-001")
+
+        response = self.client.post(
+            "/api/inventory/miners",
+            json={"asset_id": "ASSET-001"},
+        )
+
+        self.assertEqual(response.status_code, 409)
+        self.assertEqual(
+            response.json()["detail"],
+            "Asset ID already exists: ASSET-001",
+        )
+
+    def test_invalid_create_body_returns_validation_error(self):
+        self.authenticate(permissions=("miners.update",))
+        for body in (
+            {},
+            {"asset_id": "A" * 121},
+            {"asset_id": "ASSET-001", "site_id": "not-a-uuid"},
+        ):
+            with self.subTest(body=body):
+                response = self.client.post(
+                    "/api/inventory/miners",
+                    json=body,
+                )
+                self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.create_request)
+
+    def test_create_maps_domain_validation_error(self):
+        self.authenticate(permissions=("miners.update",))
+        self.service.create_error = InventoryValidationError(
+            "Tag names cannot be blank"
+        )
+
+        response = self.client.post(
+            "/api/inventory/miners",
+            json={"asset_id": "ASSET-001", "tags": ["   "]},
+        )
+
+        self.assertEqual(response.status_code, 422)
+        self.assertEqual(
+            response.json()["detail"],
+            "Tag names cannot be blank",
+        )
+
+    def test_patch_requires_authentication(self):
+        response = self.client.patch(
+            f"/api/inventory/miners/{uuid4()}",
+            json={"model": "M60"},
+        )
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["detail"], "Login required")
+
+    def test_patch_requires_miners_update_permission(self):
+        self.authenticate(permissions=("miners.view",))
+        response = self.client.patch(
+            f"/api/inventory/miners/{uuid4()}",
+            json={"model": "M60"},
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertIsNone(self.service.update_request)
+
+    def test_patch_unknown_miner_returns_not_found(self):
+        self.authenticate(permissions=("miners.update",))
+        miner_id = uuid4()
+        self.service.update_error = MinerNotFound(miner_id)
+
+        response = self.client.patch(
+            f"/api/inventory/miners/{miner_id}",
+            json={"model": "M60"},
+        )
+
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.json()["detail"], "Miner not found")
+
+    def test_patch_malformed_uuid_returns_validation_error(self):
+        self.authenticate(permissions=("miners.update",))
+        response = self.client.patch(
+            "/api/inventory/miners/not-a-uuid",
+            json={"model": "M60"},
+        )
+        self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.update_request)
+
+    def test_empty_patch_maps_domain_validation_error(self):
+        self.authenticate(permissions=("miners.update",))
+        self.service.update_error = InventoryValidationError(
+            "At least one metadata field must be provided"
+        )
+
+        response = self.client.patch(
+            f"/api/inventory/miners/{uuid4()}",
+            json={},
+        )
+
+        self.assertEqual(response.status_code, 422)
+        self.assertEqual(
+            response.json()["detail"],
+            "At least one metadata field must be provided",
+        )
+
+    def test_patch_rejects_unknown_and_operational_fields(self):
+        self.authenticate(permissions=("miners.update",))
+        for body in (
+            {"unknown_field": "value"},
+            {"lifecycle_status": "retired"},
+            {"current_ip": "192.0.2.10"},
+            {"current_mac": "AA:BB:CC:DD:EE:FF"},
+            {"control_board_sn": "CB-NEW"},
+            {"site_id": str(uuid4())},
+            {"room_id": str(uuid4())},
+            {"tags": ["Priority"]},
+            {"firmware_version": "1.2.3"},
+            {"hostname": "miner-host"},
+        ):
+            with self.subTest(body=body):
+                response = self.client.patch(
+                    f"/api/inventory/miners/{uuid4()}",
+                    json=body,
+                )
+                self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.update_request)
+
+    def test_valid_metadata_patch_returns_typed_envelope(self):
+        self.authenticate(permissions=("miners.update",))
+        updated = miner_detail()
+        self.service.update_result = updated
+
+        response = self.client.patch(
+            f"/api/inventory/miners/{updated.id}",
+            json={
+                "asset_id": " ASSET-NEW ",
+                "miner_sn": "MINER-NEW",
+                "psu_serial": None,
+                "model": "M60",
+                "notes": "Bench verified",
+            },
+        )
+
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["data"]["id"], str(updated.id))
+        self.assertEqual(body["meta"], {})
+        self.assertIsNone(body["error"])
+        self.assertEqual(self.service.update_miner_id, updated.id)
+        self.assertIsInstance(self.service.update_actor_user_id, UUID)
+        request = self.service.update_request
+        self.assertIsNotNone(request)
+        self.assertEqual(
+            request.model_fields_set,
+            {"asset_id", "miner_sn", "psu_serial", "model", "notes"},
+        )
+        self.assertIsNone(request.psu_serial)
+
+    def test_patch_duplicate_asset_id_returns_conflict(self):
+        self.authenticate(permissions=("miners.update",))
+        self.service.update_error = DuplicateAssetID("ASSET-TAKEN")
+
+        response = self.client.patch(
+            f"/api/inventory/miners/{uuid4()}",
+            json={"asset_id": "ASSET-TAKEN"},
+        )
+
+        self.assertEqual(response.status_code, 409)
+        self.assertEqual(
+            response.json()["detail"],
+            "Asset ID already exists: ASSET-TAKEN",
+        )
+
+    def test_list_requires_authentication(self):
+        response = self.client.get("/api/inventory/miners")
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["detail"], "Login required")
+
+    def test_detail_requires_authentication(self):
+        response = self.client.get(f"/api/inventory/miners/{uuid4()}")
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["detail"], "Login required")
+
+    def test_asset_id_history_requires_authentication(self):
+        response = self.client.get(
+            f"/api/inventory/miners/{uuid4()}/asset-id-history"
+        )
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["detail"], "Login required")
+
+    def test_list_requires_miners_view_permission(self):
+        self.authenticate(permissions=())
+        response = self.client.get("/api/inventory/miners")
+        self.assertEqual(response.status_code, 403)
+
+    def test_asset_id_history_requires_miners_view_permission(self):
+        self.authenticate(permissions=())
+        response = self.client.get(
+            f"/api/inventory/miners/{uuid4()}/asset-id-history"
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertIsNone(self.service.history_miner_id)
+
+    def test_authenticated_list_returns_typed_envelope(self):
+        self.authenticate()
+        self.service.search_result = [miner_summary()]
+
+        response = self.client.get("/api/inventory/miners")
+
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(len(body["data"]), 1)
+        self.assertEqual(body["data"][0]["asset_id"], "ASSET-001")
+        self.assertEqual(
+            body["meta"],
+            {"limit": 100, "offset": 0, "returned": 1,
+                "location_options": {"sites": [], "rooms": []}},
+        )
+        self.assertIsNone(body["error"])
+
+    def test_list_projection_and_location_permission_are_explicit(self):
+        miner_id = uuid4()
+        site_id = uuid4()
+        room_id = uuid4()
+        position_id = uuid4()
+        self.service.search_result = [
+            InventoryMinerSummary(
+                id=miner_id,
+                asset_id="FLEET-001",
+                model="M50",
+                miner_sn="SN-001",
+                lifecycle_status="active",
+                runtime_status="online",
+                site_id=site_id,
+                site_name="North Site",
+                room_id=room_id,
+                room_name="Room A",
+                location_position_id=position_id,
+                rack_label="Rack 1",
+                shelf_label="Shelf 2",
+                position_index=3,
+                observed_at=datetime.now(timezone.utc),
+                hashrate_ths=120.0,
+                power_w=3400.0,
+                chip_temp_max_c=72.0,
+                hash_stable=True,
+                created_at=datetime.now(timezone.utc),
+                updated_at=datetime.now(timezone.utc),
+            )
+        ]
+        self.service.location_options = {
+            "sites": [{"id": site_id, "name": "North Site"}],
+            "rooms": [{"id": room_id, "site_id": site_id, "name": "Room A"}],
+        }
+
+        self.authenticate(("miners.view", "locations.view"))
+        response = self.client.get("/api/inventory/miners")
+        data = response.json()["data"][0]
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(data["miner_sn"], "SN-001")
+        self.assertEqual(data["location_position_id"], str(position_id))
+        self.assertEqual(data["hashrate_ths"], 120.0)
+        self.assertTrue(self.service.include_location_details)
+        self.assertEqual(
+            response.json()["meta"]["location_options"]["sites"][0]["name"],
+            "North Site",
+        )
+
+        self.authenticate(("miners.view",))
+        self.service.search_result = [miner_summary(miner_id)]
+        response = self.client.get("/api/inventory/miners")
+        data = response.json()["data"][0]
+        self.assertIsNone(data["site_id"])
+        self.assertIsNone(data["room_id"])
+        self.assertIsNone(data["location_position_id"])
+        self.assertEqual(response.json()["meta"]["location_options"], {"sites": [], "rooms": []})
+        self.assertFalse(self.service.include_location_details)
+
+    def test_location_filters_require_locations_view(self):
+        self.authenticate(("miners.view",))
+        response = self.client.get(
+            "/api/inventory/miners", params={"site_id": str(uuid4())}
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertIsNone(self.service.search_filters)
+
+    def test_empty_list_returns_successful_empty_collection(self):
+        self.authenticate()
+
+        response = self.client.get("/api/inventory/miners")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["data"], [])
+        self.assertEqual(response.json()["meta"]["returned"], 0)
+
+    def test_search_filters_are_passed_to_service(self):
+        self.authenticate()
+
+        response = self.client.get(
+            "/api/inventory/miners",
+            params=[
+                ("query", "M50"),
+                ("asset_id", "ASSET-001"),
+                ("lifecycle_status", "spare"),
+                ("model", "M50"),
+                ("runtime_status", "offline"),
+                ("repair", "active"),
+                ("operational_state", "repair"),
+                ("problems", "true"),
+                ("tags", "Priority"),
+                ("tags", "Repair"),
+                ("limit", "25"),
+                ("offset", "50"),
+            ],
+        )
+
+        self.assertEqual(response.status_code, 200)
+        filters = self.service.search_filters
+        self.assertIsNotNone(filters)
+        self.assertEqual(filters.query, "M50")
+        self.assertEqual(filters.asset_id, "ASSET-001")
+        self.assertEqual(filters.lifecycle_status, "spare")
+        self.assertEqual(filters.model, "M50")
+        self.assertEqual(filters.runtime_status, "offline")
+        self.assertEqual(filters.repair, "active")
+        self.assertEqual(filters.operational_state, "repair")
+        self.assertTrue(filters.problems)
+        self.assertEqual(filters.tags, ["Priority", "Repair"])
+        self.assertEqual(filters.limit, 25)
+        self.assertEqual(filters.offset, 50)
+
+    def test_invalid_lifecycle_filter_returns_client_error(self):
+        self.authenticate()
+        self.service.search_error = InventoryValidationError(
+            "Lifecycle status must be active, spare, or retired"
+        )
+        response = self.client.get(
+            "/api/inventory/miners",
+            params={"lifecycle_status": "broken"},
+        )
+        self.assertEqual(response.status_code, 422)
+        self.assertIn("Lifecycle status", response.json()["detail"])
+
+    def test_pagination_is_validated_and_bounded(self):
+        self.authenticate()
+        for params in (
+            {"limit": 0},
+            {"limit": 501},
+            {"offset": -1},
+        ):
+            with self.subTest(params=params):
+                response = self.client.get(
+                    "/api/inventory/miners",
+                    params=params,
+                )
+                self.assertEqual(response.status_code, 422)
+
+    def test_existing_uuid_returns_inventory_detail(self):
+        self.authenticate()
+        expected = miner_detail()
+        self.service.detail_result = expected
+
+        response = self.client.get(
+            f"/api/inventory/miners/{expected.id}"
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["data"]["id"], str(expected.id))
+        self.assertEqual(response.json()["data"]["psu_serial"], "PSU-001")
+        self.assertEqual(self.service.detail_miner_id, expected.id)
+
+    def test_unknown_uuid_returns_not_found(self):
+        self.authenticate()
+        response = self.client.get(f"/api/inventory/miners/{uuid4()}")
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.json()["detail"], "Miner not found")
+
+    def test_malformed_uuid_returns_client_error(self):
+        self.authenticate()
+        response = self.client.get("/api/inventory/miners/not-a-uuid")
+        self.assertEqual(response.status_code, 422)
+
+    def test_asset_id_history_malformed_uuid_returns_validation_error(self):
+        self.authenticate()
+        response = self.client.get(
+            "/api/inventory/miners/not-a-uuid/asset-id-history"
+        )
+        self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.history_miner_id)
+
+    def test_asset_id_history_unknown_miner_returns_not_found(self):
+        self.authenticate()
+        miner_id = uuid4()
+        self.service.history_error = MinerNotFound(miner_id)
+
+        response = self.client.get(
+            f"/api/inventory/miners/{miner_id}/asset-id-history"
+        )
+
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.json()["detail"], "Miner not found")
+
+    def test_asset_id_history_empty_collection_uses_typed_envelope(self):
+        self.authenticate()
+        miner_id = uuid4()
+
+        response = self.client.get(
+            f"/api/inventory/miners/{miner_id}/asset-id-history"
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(
+            response.json(),
+            {"data": [], "meta": {}, "error": None},
+        )
+        self.assertEqual(self.service.history_miner_id, miner_id)
+
+    def test_asset_id_history_preserves_chronological_service_order(self):
+        self.authenticate()
+        miner_id = uuid4()
+        first = datetime(2026, 7, 27, 12, 0, tzinfo=timezone.utc)
+        second = datetime(2026, 7, 28, 12, 0, tzinfo=timezone.utc)
+        self.service.history_result = [
+            history_entry(
+                old_asset_id="ASSET-FIRST",
+                new_asset_id="ASSET-SECOND",
+                changed_at=first,
+            ),
+            history_entry(
+                old_asset_id="ASSET-SECOND",
+                new_asset_id="ASSET-FIRST",
+                changed_at=second,
+            ),
+        ]
+
+        response = self.client.get(
+            f"/api/inventory/miners/{miner_id}/asset-id-history"
+        )
+
+        self.assertEqual(response.status_code, 200)
+        data = response.json()["data"]
+        self.assertEqual(
+            [entry["new_asset_id"] for entry in data],
+            ["ASSET-SECOND", "ASSET-FIRST"],
+        )
+        self.assertEqual(
+            data[0]["changed_by"],
+            "00000000-0000-0000-0000-000000000951",
+        )
+        self.assertEqual(
+            data[0]["changed_by_display_name"],
+            "Inventory Test User",
+        )
+        self.assertEqual(response.json()["meta"], {})
+        self.assertIsNone(response.json()["error"])
+
+    def test_router_has_no_sql_or_database_driver_imports(self):
+        router_path = (
+            Path(__file__).parents[1] / "app" / "inventory" / "router.py"
+        )
+        source = router_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        imported_modules = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imported_modules.extend(alias.name for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                imported_modules.append(node.module)
+
+        database_modules = ("psycopg", "asyncpg", "sqlalchemy")
+        self.assertFalse(
+            any(
+                module == name or module.startswith(f"{name}.")
+                for module in imported_modules
+                for name in database_modules
+            )
+        )
+        upper_source = source.upper()
+        for keyword in ("SELECT ", "INSERT ", "UPDATE ", "DELETE "):
+            self.assertNotIn(keyword, upper_source)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_mine_map.py

@@ -0,0 +1,400 @@
+import ast
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import patch
+from uuid import UUID, uuid4
+
+from fastapi import FastAPI
+import psycopg
+from fastapi.testclient import TestClient
+
+from app.config import settings
+from app.identity import get_current_user
+from app.locations.dependencies import get_location_map_service
+from app.locations.repository import LocationMapRepository
+from app.locations.router import router
+from app.locations.service import LocationMapService
+
+
+NOW = datetime(2026, 8, 10, 12, 0, tzinfo=timezone.utc)
+STATIC_ROOT = Path(__file__).parents[1] / "app" / "frontend" / "static"
+
+
+def map_rows():
+    site_a, site_b, room_a, room_b = uuid4(), uuid4(), uuid4(), uuid4()
+    miner_id, position_id, repair_id = uuid4(), uuid4(), uuid4()
+    return {
+        "sites": [{"id": site_a, "name": "North"}, {"id": site_b, "name": "South"}],
+        "rooms": [
+            {"id": room_a, "site_id": site_a, "site_name": "North", "name": "Room 1", "sort_order": 1},
+            {"id": room_b, "site_id": site_b, "site_name": "South", "name": "Room 1", "sort_order": 1},
+        ],
+        "positions": [{
+            "location_position_id": position_id, "site_id": site_a,
+            "site_name": "North", "room_id": room_a, "room_name": "Room 1",
+            "rack_name": "A", "shelf_name": "Top", "shelf_index": 1,
+            "position_index": 1, "position_label": "A-1", "position_kind": "miner_slot",
+            "position_status": "occupied", "occupied": True,
+            "expected_mac": "de:ad:be:ef:00:01",
+            "equipment_label": None, "notes": None, "source_file": None,
+            "source_cell": None, "conflict_reason": None, "miner_id": miner_id,
+            "asset_id": '<img src=x onerror="alert(1)">', "current_mac": "aa:bb:cc:dd:ee:ff",
+            "current_ip": "192.0.2.10", "miner_status": "online", "hostname": "miner-a",
+            "miner_sn": "SERIAL-1", "power_sn": None, "model": "M50",
+            "miner_type": "WhatsMiner", "firmware_version": "1.0",
+            "lifecycle_status": "in_repair", "last_seen_at": NOW,
+            "asset_state": "shelved", "observed_at": NOW, "hashrate_ths": 120.5,
+            "power_w": 3320.0, "chip_temp_max_c": 71.0, "chip_temp_avg_c": 66.0,
+            "hash_stable": True, "pool_rejected_percent": 0.2,
+            "active_repair_id": repair_id, "active_repair_status": "OPEN",
+            "active_repair_reason": "CONTROL_BOARD",
+        }, {
+            "location_position_id": uuid4(), "site_id": site_a, "site_name": "North",
+            "room_id": room_a, "room_name": "Room 1", "rack_name": "A",
+            "shelf_name": "Top", "shelf_index": 1, "position_index": 2,
+            "position_label": "A-2", "position_kind": "miner_slot",
+            "position_status": "available", "occupied": False,
+            "active_repair_id": None, "active_repair_status": None,
+            "active_repair_reason": None,
+        }],
+        "virtual_miners": [],
+    }
+
+
+class FakeLocationRepository:
+    def __init__(self):
+        self.rows = map_rows()
+        self.calls = []
+
+    def read_map(self, *, site_id=None, room_id=None):
+        self.calls.append((site_id, room_id))
+        return self.rows
+
+
+class MineMapServiceTests(unittest.TestCase):
+    def test_service_builds_typed_bulk_map_with_repair_and_empty_position(self):
+        repository = FakeLocationRepository()
+        response = LocationMapService(repository).get_map(include_miner_details=True)
+        self.assertEqual(len(repository.calls), 1)
+        self.assertEqual(response.data.rooms[0].name, response.data.rooms[1].name)
+        self.assertNotEqual(response.data.rooms[0].site_id, response.data.rooms[1].site_id)
+        self.assertTrue(response.data.positions[0].occupied)
+        self.assertEqual(response.data.positions[0].active_repair.status, "OPEN")
+        self.assertFalse(response.data.positions[1].occupied)
+        self.assertEqual(response.data.positions[0].hashrate_ths, 120.5)
+
+    def test_location_only_user_receives_layout_without_miner_details(self):
+        response = LocationMapService(FakeLocationRepository()).get_map(
+            include_miner_details=False
+        )
+        position = response.data.positions[0]
+        self.assertTrue(position.occupied)
+        self.assertIsNone(position.miner_id)
+        self.assertIsNone(position.asset_id)
+        self.assertIsNone(position.expected_mac)
+        for field in ("current_mac", "current_ip", "miner_status", "hostname",
+                      "miner_sn", "power_sn", "model", "miner_type",
+                      "firmware_version", "lifecycle_status", "last_seen_at",
+                      "asset_state", "observed_at", "hashrate_ths", "power_w",
+                      "chip_temp_max_c", "chip_temp_avg_c", "hash_stable",
+                      "pool_rejected_percent"):
+            self.assertIsNone(getattr(position, field), field)
+        self.assertIsNone(position.active_repair)
+        self.assertEqual(response.data.virtual_miners, [])
+        self.assertFalse(response.meta.miner_details_included)
+
+
+    def test_service_preserves_legacy_position_without_assigning_durable_scope(self):
+        repository = FakeLocationRepository()
+        legacy = dict(repository.rows["positions"][1])
+        legacy.update({
+            "location_position_id": uuid4(), "site_id": None, "site_name": None,
+            "room_id": None, "room_name": "Imported Room", "rack_name": "A",
+            "shelf_name": "Top", "position_index": 3,
+        })
+        repository.rows["positions"].append(legacy)
+        response = LocationMapService(repository).get_map(include_miner_details=True)
+        position = response.data.positions[-1]
+        self.assertIsNone(position.site_id)
+        self.assertIsNone(position.room_id)
+        self.assertEqual(position.room_name, "Imported Room")
+
+
+class StubMapService:
+    def __init__(self):
+        self.repository = FakeLocationRepository()
+        self.service = LocationMapService(self.repository)
+        self.include = None
+
+    def get_map(self, **kwargs):
+        self.include = kwargs["include_miner_details"]
+        return self.service.get_map(**kwargs)
+
+
+class MineMapRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubMapService()
+        self.app = FastAPI()
+        self.app.include_router(router)
+        self.app.dependency_overrides[get_location_map_service] = lambda: self.service
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": list(permissions)
+        }
+
+    def test_map_requires_authentication_and_locations_permission(self):
+        self.assertEqual(self.client.get("/api/location/map").status_code, 401)
+        self.authenticate(("miners.view",))
+        self.assertEqual(self.client.get("/api/location/map").status_code, 403)
+
+    def test_map_returns_typed_envelope_and_permission_aware_miner_shape(self):
+        self.authenticate(("locations.view", "miners.view"))
+        response = self.client.get("/api/location/map")
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["meta"]["miner_details_included"])
+        self.assertEqual(response.json()["data"]["positions"][0]["asset_id"],
+                         '<img src=x onerror="alert(1)">')
+        self.assertIsNone(response.json()["error"])
+        self.authenticate(("locations.view",))
+        response = self.client.get("/api/location/map")
+        redacted = response.json()["data"]["positions"][0]
+        self.assertIsNone(redacted["miner_id"])
+        self.assertIsNone(redacted["expected_mac"])
+        self.assertIsNone(redacted["active_repair"])
+        self.assertEqual(response.json()["data"]["virtual_miners"], [])
+        self.assertFalse(response.json()["meta"]["miner_details_included"])
+
+    def test_uuid_filters_are_validated_and_forwarded(self):
+        self.authenticate(("locations.view", "miners.view"))
+        site_id, room_id = uuid4(), uuid4()
+        response = self.client.get(
+            "/api/location/map", params={"site_id": site_id, "room_id": room_id}
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(self.service.repository.calls[-1], (site_id, room_id))
+        self.assertEqual(self.client.get("/api/location/map?site_id=bad").status_code, 422)
+
+    def test_router_has_no_sql_or_database_driver_imports(self):
+        path = Path(__file__).parents[1] / "app" / "locations" / "router.py"
+        source = path.read_text(encoding="utf-8")
+        modules = []
+        for node in ast.walk(ast.parse(source)):
+            if isinstance(node, ast.Import): modules.extend(alias.name for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module: modules.append(node.module)
+        self.assertFalse(any(name.startswith(("psycopg", "sqlalchemy", "asyncpg")) for name in modules))
+        for keyword in ("SELECT ", "INSERT ", "UPDATE ", "DELETE "):
+            self.assertNotIn(keyword, source.upper())
+
+
+class MineMapRepositoryIntegrationTests(unittest.TestCase):
+    def test_set_based_query_scopes_same_named_rooms_by_uuid_and_site(self):
+        connection = psycopg.connect(
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            dbname=settings.postgres_db,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+        )
+        try:
+            repository = LocationMapRepository(connection=connection)
+            site_a, site_b, room_a, room_b = uuid4(), uuid4(), uuid4(), uuid4()
+            miner_id = uuid4()
+            room_name = "Map Same Name " + uuid4().hex[:8]
+            with connection.cursor() as cur:
+                cur.execute(
+                    "INSERT INTO sites (id, name) VALUES (%s, %s), (%s, %s)",
+                    (site_a, "Map North " + uuid4().hex[:8],
+                     site_b, "Map South " + uuid4().hex[:8]),
+                )
+                cur.execute(
+                    "INSERT INTO rooms (id, site_id, name, sort_order) "
+                    "VALUES (%s, %s, %s, 1), (%s, %s, %s, 1)",
+                    (room_a, site_a, room_name, room_b, site_b, room_name),
+                )
+                cur.execute(
+                    "INSERT INTO miners (id, site_id, room_id, asset_tag, status, "
+                    "lifecycle_status) VALUES (%s, %s, %s, %s, 'online', 'active')",
+                    (miner_id, site_a, room_a, "MAP-" + uuid4().hex[:8]),
+                )
+                cur.execute(
+                    "INSERT INTO location_positions "
+                    "(room_id, room_name, rack_name, shelf_name, shelf_index, "
+                    "position_index, position_kind, position_status, miner_id) "
+                    "VALUES (%s, %s, 'A', '1', 1, 1, 'miner_slot', 'occupied', %s), "
+                    "(%s, %s, 'B', '1', 1, 1, 'miner_slot', 'available', NULL)",
+                    (room_a, room_name, miner_id, room_b, room_name),
+                )
+                cur.execute(
+                    "INSERT INTO miner_status_snapshots "
+                    "(miner_id, mhs_av, power_w, chip_temp_max_c, hash_stable) "
+                    "VALUES (%s, 120000000, 3300, 70, true)",
+                    (miner_id,),
+                )
+            result = repository.read_map(site_id=site_a, room_id=room_a)
+            self.assertEqual(len(result["positions"]), 1)
+            row = result["positions"][0]
+            self.assertEqual(row["site_id"], site_a)
+            self.assertEqual(row["room_id"], room_a)
+            self.assertTrue(row["occupied"])
+            self.assertEqual(row["hashrate_ths"], 120.0)
+            matching_rooms = [room for room in result["rooms"] if room["name"] == room_name]
+            self.assertEqual({room["site_id"] for room in matching_rooms}, {site_a, site_b})
+        finally:
+            connection.rollback()
+            connection.close()
+
+
+class DummyCursor:
+    def __enter__(self): return self
+    def __exit__(self, *args): return False
+    def execute(self, *args): return None
+    def fetchall(self): return []
+
+
+class DummyConnection:
+    def cursor(self, **kwargs): return DummyCursor()
+    def close(self): return None
+
+
+class StatusSnapshotPermissionTests(unittest.TestCase):
+    def setUp(self):
+        from app.main import list_miner_status_snapshots
+        self.app = FastAPI()
+        self.app.get("/api/miners/{miner_id}/status-snapshots")(
+            list_miner_status_snapshots
+        )
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.app.dependency_overrides.pop(get_current_user, None)
+        self.client.close()
+
+    def test_status_snapshots_require_authentication_permission_and_allow_reader(self):
+        miner_id = uuid4()
+        self.assertEqual(self.client.get(f"/api/miners/{miner_id}/status-snapshots").status_code, 401)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": ["locations.view"]
+        }
+        self.assertEqual(self.client.get(f"/api/miners/{miner_id}/status-snapshots").status_code, 403)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": ["miners.view"]
+        }
+        with patch("app.main.get_db_connection", return_value=DummyConnection()):
+            response = self.client.get(f"/api/miners/{miner_id}/status-snapshots")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["data"], [])
+
+    def test_established_roles_and_custom_roles_follow_miners_view_permission(self):
+        miner_id = uuid4()
+        allowed = (("Admin", []), ("Manager", ["miners.view"]),
+                   ("Technician", ["miners.view"]), ("Read Only", ["miners.view"]),
+                   ("Custom", ["miners.view"]))
+        with patch("app.main.get_db_connection", return_value=DummyConnection()):
+            for role, permissions in allowed:
+                with self.subTest(role=role):
+                    self.app.dependency_overrides[get_current_user] = lambda r=role, p=permissions: {
+                        "id": str(uuid4()), "role": r, "permissions": p
+                    }
+                    response = self.client.get(f"/api/miners/{miner_id}/status-snapshots")
+                    self.assertEqual(response.status_code, 200)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": []
+        }
+        self.assertEqual(
+            self.client.get(f"/api/miners/{miner_id}/status-snapshots").status_code, 403
+        )
+
+
+class MineMapFrontendAuditTests(unittest.TestCase):
+    def test_map_module_uses_one_bulk_endpoint_and_safe_dom(self):
+        source = (STATIC_ROOT / "mine-map.js").read_text(encoding="utf-8")
+        self.assertEqual(source.count('fetch("/api/location/map"'), 1)
+        self.assertNotIn("/api/inventory/miners", source)
+        self.assertNotIn("status-snapshots", source)
+        for unsafe in ("innerHTML", "outerHTML", "insertAdjacentHTML",
+                       "document.write", "eval(", "Function("):
+            self.assertNotIn(unsafe, source)
+        self.assertIn("textContent", source)
+        self.assertIn("encodeURIComponent(position.miner_id)", source)
+        self.assertIn('window.addEventListener("popstate"', source)
+        self.assertIn('el.mapWorkspace.addEventListener("click"', source)
+        self.assertIn('el.mapWorkspace.addEventListener("keydown"', source)
+        self.assertIn('tile.setAttribute("aria-pressed"', source)
+        self.assertIn("syncTileTabStops", source)
+        self.assertIn("renderLegacyPositions", source)
+        self.assertIn("minerDetailsIncluded", source)
+        self.assertIn("mapProblemsOnly", source)
+
+    def test_map_has_factual_status_rules_without_thresholds_or_mutation(self):
+        source = (STATIC_ROOT / "mine-map.js").read_text(encoding="utf-8")
+        for invented in ("> 90", ">= 90", "staleMinutes", "degradedThreshold"):
+            self.assertNotIn(invented, source)
+        self.assertIn('runtime === "offline"', source)
+        self.assertIn("position.hash_stable === false", source)
+        self.assertNotIn('method: "POST"', source)
+        self.assertNotIn('method: "PATCH"', source)
+        self.assertNotIn('method: "DELETE"', source)
+        self.assertIn('if (!state.minerDetailsIncluded)', source)
+        self.assertIn('Number.isFinite(value)', source)
+
+    def test_problems_and_measurement_layers_use_factual_relative_values(self):
+        source = (STATIC_ROOT / "mine-map.js").read_text(encoding="utf-8")
+        css = (STATIC_ROOT / "app.css").read_text(encoding="utf-8")
+        self.assertIn("const PROBLEM_KEYS = new Set", source)
+        for state in ("offline", "unknown", "unstable", "repair"):
+            self.assertIn(f'"{state}"', source)
+        self.assertIn("state.problemsOnly", source)
+        self.assertIn('"--relative-percent"', source)
+        self.assertIn("Relative range", source)
+        self.assertIn('data-problems-muted="true"', css)
+        self.assertIn(".relative-scale-track", css)
+
+    def test_map_repository_uses_constant_set_based_queries(self):
+        source = (Path(__file__).parents[1] / "app" / "locations" /
+                  "repository.py").read_text(encoding="utf-8")
+
+        read_map_source = source.split("    def read_map(", 1)[1].split(
+            "    def summarize_locations(", 1
+        )[0]
+
+        latest_telemetry_sql = source.split(
+            'LATEST_TELEMETRY_SQL = """', 1
+        )[1].split('"""', 1)[0]
+
+        active_repair_sql = source.split(
+            'ACTIVE_REPAIR_SQL = """', 1
+        )[1].split('"""', 1)[0]
+
+        self.assertEqual(read_map_source.count("cur.execute("), 4)
+        self.assertEqual(
+            read_map_source.count("{LATEST_TELEMETRY_SQL}"),
+            2,
+        )
+        self.assertEqual(
+            read_map_source.count("{ACTIVE_REPAIR_SQL}"),
+            2,
+        )
+
+        self.assertIn("LEFT JOIN LATERAL", latest_telemetry_sql)
+        self.assertIn("LEFT JOIN LATERAL", active_repair_sql)
+
+        self.assertIn(
+            "ORDER BY snapshots.observed_at DESC, snapshots.id DESC",
+            latest_telemetry_sql,
+        )
+        self.assertIn(
+            "ORDER BY repairs.opened_at, repairs.id",
+            active_repair_sql,
+        )
+
+        self.assertNotIn("for miner", read_map_source)
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_miner_detail.py

@@ -0,0 +1,636 @@
+import ast
+import re
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from unittest.mock import patch
+from uuid import UUID, uuid4
+
+import psycopg
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.config import settings
+from app.frontend.router import miner_detail_page, router as frontend_router
+from app.identity import get_current_user
+from app.inventory.exceptions import MinerNotFound
+from app.inventory.models import InventoryMinerDetail
+from app.inventory.repository import InventoryRepository
+from app.inventory.service import InventoryService
+from app.locations.models import MinerLocationDetail
+from app.locations.repository import LocationMapRepository
+from app.miner_detail.dependencies import get_miner_detail_service
+from app.miner_detail.models import MinerDetailAccess
+from app.miner_detail.router import router as detail_router
+from app.miner_detail.service import MinerDetailService
+from app.repairs.center_repository import RepairCenterRepository
+from app.repairs.models import RepairCenterCapabilities, RepairCenterItem
+
+
+NOW = datetime(2026, 8, 17, 12, 0, tzinfo=timezone.utc)
+APP_ROOT = Path(__file__).parents[1] / "app"
+STATIC_ROOT = APP_ROOT / "frontend" / "static"
+
+
+def current_miner(**updates):
+    values = {
+        "id": uuid4(),
+        "asset_id": "MOP-001",
+        "current_mac": "aa:bb:cc:dd:ee:ff",
+        "current_ip": "192.0.2.10",
+        "model": "M50",
+        "miner_sn": "MINER-SN",
+        "lifecycle_status": "active",
+        "runtime_status": "online",
+        "site_id": uuid4(),
+        "site_name": "Restricted Site",
+        "room_id": uuid4(),
+        "room_name": "Restricted Room",
+        "location_position_id": uuid4(),
+        "rack_label": "Rack A",
+        "shelf_label": "Shelf 1",
+        "position_label": "A-01",
+        "position_index": 1,
+        "observed_at": NOW,
+        "hashrate_ths": 0.0,
+        "power_w": 0.0,
+        "chip_temp_max_c": 0.0,
+        "hash_stable": None,
+        "tags": [],
+        "created_at": NOW - timedelta(days=10),
+        "updated_at": NOW,
+        "last_seen_at": NOW,
+        "hostname": "miner-001",
+        "control_board_sn": "CB-SN",
+        "psu_serial": "PSU-SN",
+        "firmware_version": "1.2.3",
+        "notes": None,
+        "first_seen_at": NOW - timedelta(days=9),
+    }
+    values.update(updates)
+    return InventoryMinerDetail(**values)
+
+
+def location():
+    return MinerLocationDetail(
+        site_id=uuid4(),
+        site_name="North Site",
+        room_id=uuid4(),
+        room_name="Room 1",
+        position_id=uuid4(),
+        rack_label="Rack A",
+        shelf_label="Shelf 1",
+        position_label="A-01",
+        position_index=1,
+    )
+
+
+def repair_item(*, source="modular", active=True):
+    return RepairCenterItem(
+        repair_id=uuid4() if source == "modular" else None,
+        source=source,
+        active=active,
+        opened_at=NOW - timedelta(hours=2),
+        repair_status="OPEN" if active else "COMPLETED",
+        reason="CONTROL_BOARD" if source == "modular" else None,
+        latest_context="Board diagnostics",
+        latest_context_at=NOW,
+        miner_id=uuid4(),
+        lifecycle_status="in_repair" if active else "active",
+        parts_count=1 if source == "modular" else None,
+        parts_summary=["control board"] if source == "modular" else [],
+        capabilities=RepairCenterCapabilities(),
+    )
+
+
+class FakeInventoryService:
+    def __init__(self, miner=None, *, missing=False):
+        self.miner = miner or current_miner()
+        self.missing = missing
+        self.calls = []
+
+    def get_current_miner(self, miner_id):
+        self.calls.append(miner_id)
+        if self.missing:
+            raise MinerNotFound(miner_id)
+        return self.miner
+
+
+class FakeLocationService:
+    def __init__(self, value=None):
+        self.value = value
+        self.calls = []
+
+    def get_miner_location(self, miner_id):
+        self.calls.append(miner_id)
+        return self.value
+
+
+class FakeRepairService:
+    def __init__(self, values=None):
+        self.values = list(values or [])
+        self.calls = []
+
+    def list_miner_repairs(self, miner_id, access):
+        self.calls.append((miner_id, access))
+        return self.values
+
+
+class MinerDetailServiceTests(unittest.TestCase):
+    def build(self, *, miner=None, mapped=None, repairs=None, missing=False):
+        self.inventory = FakeInventoryService(miner, missing=missing)
+        self.locations = FakeLocationService(mapped)
+        self.repairs = FakeRepairService(repairs)
+        return MinerDetailService(self.inventory, self.locations, self.repairs)
+
+    def test_full_access_uses_three_domain_queries_and_preserves_zero(self):
+        miner_id = uuid4()
+        mapped = location()
+        active = repair_item()
+        service = self.build(mapped=mapped, repairs=[active])
+        response = service.get_overview(
+            miner_id,
+            MinerDetailAccess(
+                can_view_locations=True,
+                can_read_repairs=True,
+                can_view_repairs=True,
+                can_read_components=True,
+            ),
+        )
+        self.assertEqual(self.inventory.calls, [miner_id])
+        self.assertEqual(self.locations.calls, [miner_id])
+        self.assertEqual(len(self.repairs.calls), 1)
+        self.assertEqual(response.meta.database_query_count, 3)
+        self.assertEqual(response.data.miner.hashrate_ths, 0)
+        self.assertEqual(response.data.miner.power_w, 0)
+        self.assertEqual(response.data.miner.chip_temp_max_c, 0)
+        self.assertIsNone(response.data.miner.hash_stable)
+        self.assertEqual(response.data.location.location, mapped)
+        self.assertEqual(response.data.repair.active_repair.repair_id, active.repair_id)
+        self.assertEqual(response.data.operational_state, "repair")
+        self.assertTrue(response.data.capabilities.can_view_map)
+        self.assertTrue(response.data.capabilities.can_open_repair_center)
+
+    def test_restricted_domains_are_not_queried_and_location_never_leaks(self):
+        service = self.build(mapped=location(), repairs=[repair_item()])
+        response = service.get_overview(uuid4(), MinerDetailAccess())
+        self.assertEqual(response.meta.database_query_count, 1)
+        self.assertEqual(self.locations.calls, [])
+        self.assertEqual(self.repairs.calls, [])
+        self.assertTrue(response.data.location.restricted)
+        self.assertIsNone(response.data.location.location)
+        self.assertTrue(response.data.repair.restricted)
+        self.assertEqual(response.data.repair.episodes, [])
+        miner = response.data.miner
+        for field in (
+            "site_id", "site_name", "room_id", "room_name",
+            "location_position_id", "rack_label", "shelf_label",
+            "position_label", "position_index",
+        ):
+            self.assertIsNone(getattr(miner, field), field)
+        serialized = response.model_dump_json()
+        self.assertNotIn("Restricted Site", serialized)
+        self.assertNotIn("Restricted Room", serialized)
+
+    def test_no_repair_and_legacy_repair_are_truthfully_distinct(self):
+        no_repair = self.build().get_overview(
+            uuid4(), MinerDetailAccess(can_read_repairs=True)
+        )
+        self.assertTrue(no_repair.data.repair.available)
+        self.assertFalse(no_repair.data.repair.restricted)
+        self.assertIsNone(no_repair.data.repair.active_repair)
+        self.assertEqual(no_repair.data.repair.episodes, [])
+
+        legacy = repair_item(source="legacy")
+        legacy_response = self.build(repairs=[legacy]).get_overview(
+            uuid4(), MinerDetailAccess(can_read_repairs=True)
+        )
+        self.assertIsNone(legacy_response.data.repair.active_repair)
+        self.assertEqual(legacy_response.data.repair.episodes[0].source, "legacy")
+        self.assertIsNone(legacy_response.data.repair.episodes[0].repair_id)
+
+    def test_unscoped_legacy_position_is_truthful_but_not_map_linkable(self):
+        unscoped = location().model_copy(
+            update={"site_id": None, "site_name": None, "room_id": None}
+        )
+        response = self.build(mapped=unscoped).get_overview(
+            uuid4(), MinerDetailAccess(can_view_locations=True)
+        )
+        self.assertTrue(response.data.location.available)
+        self.assertEqual(response.data.location.location.position_label, "A-01")
+        self.assertFalse(response.data.capabilities.can_view_map)
+
+    def test_factual_state_uses_no_temperature_or_age_threshold(self):
+        cases = (
+            ({"runtime_status": "offline", "chip_temp_max_c": 99.0}, "offline"),
+            ({"runtime_status": "online", "hash_stable": False}, "unstable"),
+            ({"runtime_status": "online", "observed_at": NOW - timedelta(days=90)}, "online"),
+            ({"runtime_status": "unknown", "chip_temp_max_c": 1000.0}, "unknown"),
+            ({"runtime_status": "online", "lifecycle_status": "spare"}, "spare"),
+            ({"runtime_status": "online", "lifecycle_status": "retired"}, "retired"),
+        )
+        for updates, expected in cases:
+            with self.subTest(expected=expected):
+                response = self.build(miner=current_miner(**updates)).get_overview(
+                    uuid4(), MinerDetailAccess()
+                )
+                self.assertEqual(response.data.operational_state, expected)
+
+        response = self.build(
+            miner=current_miner(hashrate_ths=float("nan"))
+        ).get_overview(uuid4(), MinerDetailAccess())
+        self.assertIsNone(response.data.miner.hashrate_ths)
+        self.assertEqual(response.data.operational_state, "online")
+
+    def test_unknown_miner_propagates_domain_not_found_without_other_queries(self):
+        service = self.build(missing=True, mapped=location(), repairs=[repair_item()])
+        with self.assertRaises(MinerNotFound):
+            service.get_overview(
+                uuid4(),
+                MinerDetailAccess(can_view_locations=True, can_read_repairs=True),
+            )
+        self.assertEqual(self.locations.calls, [])
+        self.assertEqual(self.repairs.calls, [])
+
+
+class StubMinerDetailService:
+    def __init__(self, *, missing=False):
+        self.missing = missing
+        self.calls = []
+        self.delegate = MinerDetailService(
+            FakeInventoryService(),
+            FakeLocationService(location()),
+            FakeRepairService([repair_item()]),
+        )
+
+    def get_overview(self, miner_id, access):
+        self.calls.append((miner_id, access))
+        if self.missing:
+            raise MinerNotFound(miner_id)
+        return self.delegate.get_overview(miner_id, access)
+
+
+class MinerDetailRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubMinerDetailService()
+        self.app = FastAPI()
+        self.app.include_router(detail_router)
+        self.app.dependency_overrides[get_miner_detail_service] = lambda: self.service
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()),
+            "role": "Custom",
+            "permissions": list(permissions),
+        }
+
+    def test_requires_authentication_and_miners_view(self):
+        path = f"/api/miners/{uuid4()}/overview"
+        self.assertEqual(self.client.get(path).status_code, 401)
+        self.authenticate(("locations.view", "repairs.read"))
+        self.assertEqual(self.client.get(path).status_code, 403)
+
+    def test_returns_typed_permission_aware_no_store_envelope(self):
+        miner_id = uuid4()
+        self.authenticate((
+            "miners.view", "locations.view", "repairs.read",
+            "repairs.view", "components.read",
+        ))
+        response = self.client.get(f"/api/miners/{miner_id}/overview")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.headers["cache-control"], "no-store")
+        payload = response.json()
+        self.assertEqual(payload["data"]["miner"]["id"], str(self.service.delegate.inventory_service.miner.id))
+        self.assertEqual(payload["meta"]["database_query_count"], 3)
+        self.assertIsNone(payload["error"])
+        _, access = self.service.calls[-1]
+        self.assertTrue(access.can_view_locations)
+        self.assertTrue(access.can_read_repairs)
+        self.assertTrue(access.can_view_repairs)
+        self.assertTrue(access.can_read_components)
+
+    def test_malformed_and_unknown_uuid_use_existing_validation_and_404(self):
+        self.authenticate(("miners.view",))
+        self.assertEqual(self.client.get("/api/miners/not-a-uuid/overview").status_code, 422)
+        self.service.missing = True
+        response = self.client.get(f"/api/miners/{uuid4()}/overview")
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.json()["detail"], "Miner not found")
+
+
+class MinerDetailRepositoryIntegrationTests(unittest.TestCase):
+    def setUp(self):
+        self.connection = psycopg.connect(
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            dbname=settings.postgres_db,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+        )
+
+    def tearDown(self):
+        self.connection.rollback()
+        self.connection.close()
+
+    def test_inventory_and_location_projections_use_latest_factual_rows(self):
+        miner_id, site_id, room_id = uuid4(), uuid4(), uuid4()
+        earlier = NOW - timedelta(hours=1)
+        with self.connection.cursor() as cur:
+            cur.execute("INSERT INTO sites (id, name) VALUES (%s, 'Detail Site')", (site_id,))
+            cur.execute(
+                "INSERT INTO rooms (id, site_id, name) VALUES (%s, %s, 'Detail Room')",
+                (room_id, site_id),
+            )
+            cur.execute(
+                "INSERT INTO miners (id, asset_tag, current_mac, current_ip, model, "
+                "status, lifecycle_status, first_seen_at, last_seen_at) "
+                "VALUES (%s, %s, 'aa:bb:cc:00:00:01', '192.0.2.22', 'M50', "
+                "'online', 'active', NULL, NULL)",
+                (miner_id, "DETAIL-" + uuid4().hex[:8]),
+            )
+            cur.execute(
+                "INSERT INTO location_positions (room_id, room_name, rack_name, "
+                "shelf_name, position_index, position_label, miner_id) "
+                "VALUES (%s, 'Detail Room', 'Rack A', 'Shelf 1', 2, 'A-02', %s)",
+                (room_id, miner_id),
+            )
+            cur.execute(
+                "INSERT INTO miner_status_snapshots "
+                "(id, miner_id, observed_at, mhs_av, power_w, chip_temp_max_c, hash_stable) "
+                "VALUES (%s, %s, %s, 120000000, 3300, 70, true), "
+                "(%s, %s, %s, 0, 0, 0, NULL)",
+                (uuid4(), miner_id, earlier, uuid4(), miner_id, NOW),
+            )
+        inventory = InventoryService(
+            InventoryRepository(connection=self.connection)
+        ).get_current_miner(miner_id)
+        self.assertEqual(inventory.hashrate_ths, 0)
+        self.assertEqual(inventory.power_w, 0)
+        self.assertEqual(inventory.chip_temp_max_c, 0)
+        self.assertIsNone(inventory.hash_stable)
+        self.assertEqual(inventory.observed_at, NOW)
+        placement = LocationMapRepository(
+            connection=self.connection
+        ).get_miner_location(miner_id)
+        self.assertEqual(placement["site_id"], site_id)
+        self.assertEqual(placement["room_id"], room_id)
+        self.assertEqual(placement["rack_label"], "Rack A")
+        self.assertIsInstance(placement["position_id"], UUID)
+        self.assertEqual(RepairCenterRepository().list_miner_repairs(miner_id), [])
+
+
+class DummyCursor:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+    def execute(self, *args):
+        return None
+
+    def fetchall(self):
+        return []
+
+
+class DummyConnection:
+    def cursor(self, **kwargs):
+        return DummyCursor()
+
+    def close(self):
+        return None
+
+
+class NetworkIdentityPermissionTests(unittest.TestCase):
+    def setUp(self):
+        from app.main import list_miner_network_identities
+
+        self.app = FastAPI()
+        self.app.get("/api/miners/{miner_id}/network-identities")(
+            list_miner_network_identities
+        )
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def test_network_history_requires_miners_view(self):
+        path = f"/api/miners/{uuid4()}/network-identities"
+        self.assertEqual(self.client.get(path).status_code, 401)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": ["locations.view"]
+        }
+        self.assertEqual(self.client.get(path).status_code, 403)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": ["miners.view"]
+        }
+        with patch("app.main.get_db_connection", return_value=DummyConnection()):
+            response = self.client.get(path)
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["data"], [])
+
+
+class MinerDetailFrontendTests(unittest.TestCase):
+    def setUp(self):
+        self.app = FastAPI()
+        self.app.include_router(frontend_router)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()),
+            "username": "reader",
+            "display_name": "Detail Reader",
+            "role": "Read Only",
+            "permissions": [
+                "miners.view", "locations.view", "repairs.read", "repairs.view"
+            ],
+        }
+        self.client = TestClient(self.app)
+        self.miner_id = uuid4()
+
+    def tearDown(self):
+        self.client.close()
+
+    def test_page_requires_permission_and_renders_only_internal_alpha_shell(self):
+        path = f"/miners/{self.miner_id}/detail"
+        response = self.client.get(path)
+        self.assertEqual(response.status_code, 200)
+        for expected in (
+            "<title>Miner Detail | MinerOps</title>",
+            'data-view="miner_detail"',
+            f'data-miner-id="{self.miner_id}"',
+            "/assets/minerops-miner-detail.js",
+            'id="minerIdentityDetails"',
+            'id="minerRepairEpisodes"',
+            'id="minerObservations"',
+        ):
+            self.assertIn(expected, response.text)
+        for legacy in (
+            "minerops-miner-detail-extra", "minerops-miner-detail-clean-v3",
+            "minerops-location-management", "Manual Edit Missing Details",
+            "Reboot", "Performance Mode",
+        ):
+            self.assertNotIn(legacy, response.text)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": []
+        }
+        self.assertEqual(self.client.get(path).status_code, 403)
+
+    def test_return_to_accepts_protected_local_context_and_rejects_external(self):
+        path = f"/miners/{self.miner_id}/detail"
+        local = "/monitoring/map?site_id=" + str(uuid4()) + "&miner_id=" + str(self.miner_id)
+        response = self.client.get(path, params={"return_to": local})
+        self.assertIn("data-return-to=", response.text)
+        self.assertIn("/monitoring/map?site_id=", response.text)
+        response = self.client.get(
+            path, params={"return_to": "https://example.invalid/steal"}
+        )
+        self.assertNotIn("data-return-to=", response.text)
+        self.assertNotIn("example.invalid", response.text)
+
+    def test_refresh_action_has_visible_name_and_keeps_existing_behavior(self):
+        response = self.client.get(f"/miners/{self.miner_id}/detail")
+        self.assertRegex(
+            response.text,
+            r'<button class="quiet-button" id="minerDetailRefresh" '
+            r'type="button">Refresh</button>',
+        )
+        source = (STATIC_ROOT / "miner-detail.js").read_text(encoding="utf-8")
+        self.assertIn(
+            'el.refresh.addEventListener("click", loadOverview);',
+            source,
+        )
+        css = (STATIC_ROOT / "app.css").read_text(encoding="utf-8")
+        self.assertIn(".miner-detail-actions .quiet-button { color: var(--ink); }", css)
+
+    def test_live_route_precedence_and_middleware_isolation(self):
+        from app.main import app
+
+        detail_handlers = [
+            route.endpoint for route in app.routes
+            if route.path == "/miners/{miner_id}/detail"
+            and "GET" in (route.methods or set())
+        ]
+        self.assertGreaterEqual(len(detail_handlers), 2)
+        self.assertIs(detail_handlers[0], miner_detail_page)
+        current_user = {
+            "id": str(uuid4()), "username": "reader",
+            "display_name": "Detail Reader", "role": "Read Only",
+            "permissions": ["miners.view"],
+        }
+        app.dependency_overrides[get_current_user] = lambda: current_user
+        try:
+            with patch("app.identity.request_user_or_none", return_value=current_user):
+                with TestClient(app) as client:
+                    response = client.get(f"/miners/{self.miner_id}/detail")
+        finally:
+            app.dependency_overrides.pop(get_current_user, None)
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.text.count('data-view="miner_detail"'), 1)
+        self.assertIn("/assets/minerops-miner-detail.js", response.text)
+        for legacy in (
+            "/assets/minerops-miner-detail-extra.js",
+            "/assets/minerops-miner-detail-extra-v2.js",
+            "/assets/minerops-miner-detail-clean-v3.js",
+            "/assets/minerops-location-management.js",
+        ):
+            self.assertNotIn(legacy, response.text)
+        paths = {route.path for route in app.routes}
+        for legacy_api in (
+            "/api/miners/{miner_id}",
+            "/api/miners/{miner_id}/detail-extra",
+            "/api/miners/{miner_id}/detail-clean-v3",
+            "/api/miners/{miner_id}/network-identities",
+            "/api/miners/{miner_id}/status-snapshots",
+        ):
+            self.assertIn(legacy_api, paths)
+
+    def test_frontend_is_lazy_read_only_bounded_and_xss_safe(self):
+        source = (STATIC_ROOT / "miner-detail.js").read_text(encoding="utf-8")
+        self.assertEqual(
+            source.count(
+                'api("/api/miners/" + encodeURIComponent(minerId) + "/overview")'
+            ),
+            1,
+        )
+        self.assertEqual(source.count("Promise.all(["), 2)
+        self.assertIn("/asset-id-history", source)
+        self.assertIn("/network-identities", source)
+        self.assertIn("/status-snapshots", source)
+        self.assertIn("/events", source)
+        self.assertIn("/parts", source)
+        self.assertNotIn("setInterval", source)
+        for mutation in (
+            'method: "POST"', 'method: "PATCH"', 'method: "PUT"',
+            'method: "DELETE"', "reboot", "change-mac", "manual-details",
+        ):
+            self.assertNotIn(mutation, source)
+        for unsafe in ("innerHTML", "outerHTML", "insertAdjacentHTML", "document.write"):
+            self.assertNotIn(unsafe, source)
+        self.assertIn("textContent", source)
+        self.assertIn("new URLSearchParams", source)
+        self.assertIn("encodeURIComponent", source)
+        self.assertNotRegex(
+            source.lower(),
+            r"(temperature|hashrate|stale).{0,40}(threshold|>=\s*90|>\s*90)",
+        )
+        main_source = (APP_ROOT / "main.py").read_text(encoding="utf-8")
+        snapshot = re.search(
+            r'def list_miner_status_snapshots\(.*?LIMIT 100;',
+            main_source,
+            re.DOTALL,
+        )
+        self.assertIsNotNone(snapshot)
+
+    def test_cross_navigation_preserves_context_with_durable_uuid(self):
+        fleet = (STATIC_ROOT / "fleet.js").read_text(encoding="utf-8")
+        repairs = (STATIC_ROOT / "repair-center.js").read_text(encoding="utf-8")
+        for source in (fleet, repairs):
+            self.assertIn('return_to', source)
+            self.assertIn("window.location.pathname + window.location.search", source)
+            self.assertIn("encodeURIComponent", source)
+        detail = (STATIC_ROOT / "miner-detail.js").read_text(encoding="utf-8")
+        self.assertIn('new URLSearchParams({ miner_id: minerIdValue })', detail)
+        self.assertIn('params.set("site_id", location.site_id)', detail)
+        self.assertIn('params.set("room_id", location.room_id)', detail)
+        self.assertIn('new URLSearchParams({ scope: "all", q: data.miner.id })', detail)
+
+
+class MinerDetailArchitectureTests(unittest.TestCase):
+    def test_router_and_service_preserve_dependency_boundaries(self):
+        for relative in ("miner_detail/router.py", "miner_detail/service.py"):
+            source = (APP_ROOT / relative).read_text(encoding="utf-8")
+            modules = []
+            for node in ast.walk(ast.parse(source)):
+                if isinstance(node, ast.Import):
+                    modules.extend(alias.name for alias in node.names)
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    modules.append(node.module)
+            self.assertFalse(
+                any(name.startswith(("psycopg", "sqlalchemy", "asyncpg"))
+                    for name in modules)
+            )
+            for keyword in ("SELECT ", "INSERT ", "UPDATE ", "DELETE "):
+                self.assertNotIn(keyword, source.upper())
+        service_source = (APP_ROOT / "miner_detail" / "service.py").read_text(
+            encoding="utf-8"
+        )
+        self.assertNotIn("fastapi", service_source.lower())
+
+    def test_exactly_one_new_api_route_and_no_state_changing_page_get(self):
+        routes = [
+            (route.path, route.methods)
+            for route in detail_router.routes
+        ]
+        self.assertEqual(routes, [("/api/miners/{miner_id}/overview", {"GET"})])
+        page = next(
+            route for route in frontend_router.routes
+            if route.path == "/miners/{miner_id}/detail"
+        )
+        self.assertEqual(page.methods, {"GET"})
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_monitoring_trends.py

@@ -0,0 +1,448 @@
+import ast
+import time
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import psycopg
+
+from app.config import settings
+from app.identity import get_current_user, protected_page, required_page_permission
+from app.monitoring.dependencies import get_monitoring_service
+from app.monitoring.frontend import router as monitoring_frontend_router
+from app.monitoring.models import MonitoringTrendQuery
+from app.monitoring.repository import MonitoringRepository, TREND_SQL
+from app.monitoring.router import router as monitoring_router
+from app.monitoring.service import MonitoringService
+
+
+NOW = datetime(2026, 8, 17, 12, 2, tzinfo=timezone.utc)
+APP_ROOT = Path(__file__).parents[1] / "app"
+STATIC_ROOT = APP_ROOT / "frontend" / "static"
+
+
+def trend_rows(count=72, *, scope_exists=True, label="Fleet"):
+    start = datetime(2026, 8, 17, 6, 5, tzinfo=timezone.utc)
+    rows = []
+    for index in range(count):
+        bucket_start = start + timedelta(minutes=5 * index)
+        rows.append({
+            "scope_exists": scope_exists,
+            "scope_label": label,
+            "bucket_start": bucket_start,
+            "bucket_end": bucket_start + timedelta(minutes=5),
+            "hashrate_ths": 0 if index == 0 else None,
+            "power_w": 0 if index == 0 else None,
+            "observation_count": 1 if index < 2 else 0,
+            "hashrate_sample_count": 1 if index == 0 else 0,
+            "power_sample_count": 1 if index == 0 else 0,
+            "observed_miner_count": 1 if index < 2 else 0,
+            "hashrate_contributing_miner_count": 1 if index == 0 else 0,
+            "power_contributing_miner_count": 1 if index == 0 else 0,
+            "scoped_miner_count": 2,
+            "latest_observed_at": start + timedelta(minutes=1),
+        })
+    return rows
+
+
+class FakeMonitoringRepository:
+    def __init__(self, rows=None):
+        self.rows = rows or trend_rows()
+        self.trend_calls = []
+        self.option_calls = 0
+
+    def read_trends(self, **kwargs):
+        self.trend_calls.append(kwargs)
+        return self.rows
+
+    def list_location_scope_options(self):
+        self.option_calls += 1
+        site_id, room_id = uuid4(), uuid4()
+        return [
+            {"option_type": "site", "id": site_id, "site_id": None,
+             "name": '<script>alert("site")</script>'},
+            {"option_type": "room", "id": room_id, "site_id": site_id,
+             "name": "Room 1"},
+        ]
+
+
+class MonitoringServiceTests(unittest.TestCase):
+    def test_fixed_ranges_emit_expected_bounded_points(self):
+        expected = {"6h": (72, 300), "24h": (96, 900), "7d": (168, 3600)}
+        for range_name, (count, seconds) in expected.items():
+            with self.subTest(range_name=range_name):
+                rows = trend_rows(count)
+                repository = FakeMonitoringRepository(rows)
+                response = MonitoringService(repository).get_trends(
+                    MonitoringTrendQuery(scope="fleet", range=range_name),
+                    include_location_scopes=False,
+                    generated_at=NOW,
+                )
+                self.assertEqual(len(response.data.series), 2)
+                self.assertEqual(len(response.data.series[0].points), count)
+                self.assertLessEqual(count, response.meta.maximum_points)
+                self.assertEqual(response.meta.bucket_seconds, seconds)
+                self.assertEqual(response.meta.database_query_count, 1)
+
+    def test_zero_null_and_empty_bucket_semantics_remain_distinct(self):
+        response = MonitoringService(FakeMonitoringRepository()).get_trends(
+            MonitoringTrendQuery(scope="fleet", range="6h"),
+            include_location_scopes=False,
+            generated_at=NOW,
+        )
+        points = response.data.series[0].points
+        self.assertEqual(points[0].value, 0)
+        self.assertEqual(points[0].metric_sample_count, 1)
+        self.assertIsNone(points[1].value)
+        self.assertEqual(points[1].observation_count, 1)
+        self.assertEqual(points[1].metric_sample_count, 0)
+        self.assertIsNone(points[2].value)
+        self.assertEqual(points[2].observation_count, 0)
+
+    def test_location_options_and_attribution_are_permission_aware(self):
+        repository = FakeMonitoringRepository(trend_rows(label="North Site"))
+        response = MonitoringService(repository).get_trends(
+            MonitoringTrendQuery(scope="site", scope_id=uuid4(), range="6h"),
+            include_location_scopes=True,
+            generated_at=NOW,
+        )
+        self.assertEqual(response.meta.attribution, "current_placement_cohort")
+        self.assertEqual(response.meta.database_query_count, 2)
+        self.assertEqual(repository.option_calls, 1)
+        self.assertEqual(len(response.data.available_scopes.sites), 1)
+        repository = FakeMonitoringRepository()
+        response = MonitoringService(repository).get_trends(
+            MonitoringTrendQuery(scope="fleet", range="6h"),
+            include_location_scopes=False,
+            generated_at=NOW,
+        )
+        self.assertEqual(response.data.available_scopes.sites, [])
+        self.assertEqual(repository.option_calls, 0)
+
+
+class MonitoringRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeMonitoringRepository()
+        self.service = MonitoringService(self.repository)
+        self.app = FastAPI()
+        self.app.include_router(monitoring_router)
+        self.app.dependency_overrides[get_monitoring_service] = lambda: self.service
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": list(permissions)
+        }
+
+    def test_authentication_permission_and_location_scope_boundaries(self):
+        self.assertEqual(self.client.get("/api/monitoring/trends").status_code, 401)
+        self.authenticate(())
+        self.assertEqual(self.client.get("/api/monitoring/trends").status_code, 403)
+        self.authenticate(("miners.view",))
+        self.assertEqual(self.client.get("/api/monitoring/trends").status_code, 200)
+        response = self.client.get(
+            "/api/monitoring/trends",
+            params={"scope": "site", "scope_id": uuid4(), "range": "6h"},
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertEqual(self.repository.trend_calls[-1]["scope"], "fleet")
+
+    def test_typed_validation_rejects_unbounded_or_ambiguous_queries(self):
+        self.authenticate(("miners.view", "locations.view"))
+        cases = (
+            {"scope": "fleet", "scope_id": uuid4()},
+            {"scope": "miner"},
+            {"scope": "miner", "scope_id": "bad"},
+            {"scope": "fleet", "range": "30d"},
+            {"scope": "anything"},
+            {"scope": "fleet", "resolution": "1 second"},
+        )
+        for query in cases[:-1]:
+            with self.subTest(query=query):
+                self.assertEqual(
+                    self.client.get("/api/monitoring/trends", params=query).status_code,
+                    422,
+                )
+        response = self.client.get("/api/monitoring/trends", params=cases[-1])
+        self.assertEqual(response.status_code, 200)
+        self.assertNotIn("resolution", self.repository.trend_calls[-1])
+
+    def test_typed_envelope_returns_both_series_and_no_store(self):
+        self.authenticate(("miners.view",))
+        response = self.client.get("/api/monitoring/trends?scope=fleet&range=6h")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(
+            self.repository.trend_calls[-1]["window_end"]
+            - self.repository.trend_calls[-1]["window_start"],
+            timedelta(hours=6),
+        )
+        self.assertEqual(response.headers["cache-control"], "no-store")
+        payload = response.json()
+        self.assertEqual([item["metric"] for item in payload["data"]["series"]],
+                         ["hashrate", "power"])
+        self.assertEqual(payload["meta"]["source"], "raw_snapshots")
+        self.assertEqual(payload["meta"]["completeness"], "not_guaranteed")
+        self.assertIsNone(payload["error"])
+
+
+class MonitoringRepositoryIntegrationTests(unittest.TestCase):
+    def setUp(self):
+        self.connection = psycopg.connect(
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            dbname=settings.postgres_db,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+        )
+        self.repository = MonitoringRepository(connection=self.connection)
+
+    def tearDown(self):
+        self.connection.rollback()
+        self.connection.close()
+
+    def test_location_scope_options_execute_and_order_deterministically(self):
+        site_alpha, site_beta = uuid4(), uuid4()
+        room_alpha, room_beta = uuid4(), uuid4()
+        suffix = uuid4().hex[:10]
+        with self.connection.cursor() as cur:
+            cur.execute(
+                "INSERT INTO sites (id, name) VALUES (%s, %s), (%s, %s)",
+                (site_alpha, "Scope Alpha " + suffix,
+                 site_beta, "scope Beta " + suffix),
+            )
+            cur.execute(
+                "INSERT INTO rooms (id, site_id, name) VALUES "
+                "(%s, %s, %s), (%s, %s, %s)",
+                (room_alpha, site_alpha, "Scope Alpha Room " + suffix,
+                 room_beta, site_beta, "scope Beta Room " + suffix),
+            )
+
+        rows = self.repository.list_location_scope_options()
+        site_rows = [row for row in rows if row["option_type"] == "site"]
+        room_rows = [row for row in rows if row["option_type"] == "room"]
+
+        self.assertEqual(
+            [row["option_type"] for row in rows],
+            ["site"] * len(site_rows) + ["room"] * len(room_rows),
+        )
+        ordering = lambda row: (row["name"].lower(), str(row["id"]))
+        self.assertEqual(site_rows, sorted(site_rows, key=ordering))
+        self.assertEqual(room_rows, sorted(room_rows, key=ordering))
+
+        by_id = {row["id"]: row for row in rows}
+        self.assertIsNone(by_id[site_alpha]["site_id"])
+        self.assertIsNone(by_id[site_beta]["site_id"])
+        self.assertEqual(by_id[room_alpha]["site_id"], site_alpha)
+        self.assertEqual(by_id[room_beta]["site_id"], site_beta)
+
+    def test_per_miner_first_math_counts_and_current_location_precedence(self):
+        site_a, site_b, room_a = uuid4(), uuid4(), uuid4()
+        miner_a, miner_b = uuid4(), uuid4()
+        suffix = uuid4().hex[:10]
+        with self.connection.cursor() as cur:
+            cur.execute(
+                "INSERT INTO sites (id, name) VALUES (%s, %s), (%s, %s)",
+                (site_a, "Trend A " + suffix, site_b, "Trend B " + suffix),
+            )
+            cur.execute(
+                "INSERT INTO rooms (id, site_id, name) VALUES (%s, %s, %s)",
+                (room_a, site_a, "Trend Room " + suffix),
+            )
+            cur.execute(
+                "INSERT INTO miners (id, site_id, room_id, asset_tag, lifecycle_status) "
+                "VALUES (%s, %s, NULL, %s, 'active'), "
+                "(%s, %s, %s, %s, 'active')",
+                (miner_a, site_b, "TREND-A-" + suffix,
+                 miner_b, site_a, room_a, "TREND-B-" + suffix),
+            )
+            cur.execute(
+                "INSERT INTO location_positions "
+                "(room_id, room_name, rack_name, shelf_name, position_index, miner_id) "
+                "VALUES (%s, %s, %s, '1', 1, %s)",
+                (room_a, "Trend Room " + suffix, "Rack " + suffix, miner_a),
+            )
+            observed = datetime(2026, 8, 17, 11, 56, tzinfo=timezone.utc)
+            cur.execute(
+                "INSERT INTO miner_status_snapshots "
+                "(miner_id, observed_at, mhs_av, power_w) VALUES "
+                "(%s, %s, 100000000, 1000), (%s, %s, 200000000, NULL), "
+                "(%s, %s, 0, 0), (%s, %s, NULL, 3000)",
+                (miner_a, observed, miner_a, observed + timedelta(minutes=1),
+                 miner_b, observed, miner_b, observed + timedelta(minutes=1)),
+            )
+        rows = self.repository.read_trends(
+            scope="site", scope_id=site_a,
+            window_start=datetime(2026, 8, 17, 6, 5, tzinfo=timezone.utc),
+            window_end=datetime(2026, 8, 17, 12, 5, tzinfo=timezone.utc),
+            bucket_width=timedelta(minutes=5),
+        )
+        point = next(row for row in rows if row["bucket_start"].hour == 11
+                     and row["bucket_start"].minute == 55)
+        self.assertEqual(float(point["hashrate_ths"]), 150.0)
+        self.assertEqual(float(point["power_w"]), 2500.0)
+        self.assertEqual(point["observation_count"], 4)
+        self.assertEqual(point["hashrate_sample_count"], 3)
+        self.assertEqual(point["power_sample_count"], 3)
+        self.assertEqual(point["observed_miner_count"], 2)
+        self.assertEqual(point["hashrate_contributing_miner_count"], 2)
+        self.assertEqual(point["scoped_miner_count"], 2)
+        empty = next(row for row in rows if row["bucket_start"].hour == 11
+                     and row["bucket_start"].minute == 50)
+        self.assertIsNone(empty["hashrate_ths"])
+        self.assertEqual(empty["observation_count"], 0)
+        self.assertEqual(len(rows), 72)
+
+    def test_utc_bucket_is_independent_of_session_timezone(self):
+        miner_id = uuid4()
+        with self.connection.cursor() as cur:
+            cur.execute("SET LOCAL TIME ZONE 'Pacific/Honolulu'")
+            cur.execute(
+                "INSERT INTO miners (id, asset_tag, lifecycle_status) "
+                "VALUES (%s, %s, 'active')",
+                (miner_id, "TZ-" + uuid4().hex[:10]),
+            )
+            cur.execute(
+                "INSERT INTO miner_status_snapshots "
+                "(miner_id, observed_at, mhs_av) VALUES (%s, %s, 1000000)",
+                (miner_id, datetime.fromisoformat("2026-08-17T07:01:00-05:00")),
+            )
+        rows = self.repository.read_trends(
+            scope="miner", scope_id=miner_id,
+            window_start=datetime(2026, 8, 17, 6, 5, tzinfo=timezone.utc),
+            window_end=datetime(2026, 8, 17, 12, 5, tzinfo=timezone.utc),
+            bucket_width=timedelta(minutes=5),
+        )
+        value = next(row for row in rows
+                     if row["bucket_start"].astimezone(timezone.utc).hour == 12)
+        self.assertEqual(float(value["hashrate_ths"]), 1.0)
+
+    def test_representative_raw_query_is_bounded(self):
+        prefix = "BENCH-" + uuid4().hex[:8]
+        with self.connection.cursor() as cur:
+            cur.execute(
+                "INSERT INTO miners (asset_tag, lifecycle_status) "
+                "SELECT %s || '-' || value, 'active' "
+                "FROM generate_series(1, 500) AS value",
+                (prefix,),
+            )
+            cur.execute(
+                "INSERT INTO miner_status_snapshots "
+                "(miner_id, observed_at, mhs_av, power_w) "
+                "SELECT miners.id, %s::timestamptz - value * interval '1 hour', "
+                "100000000, 3200 FROM miners "
+                "CROSS JOIN generate_series(0, 167) AS value "
+                "WHERE miners.asset_tag LIKE %s",
+                (NOW, prefix + "%"),
+            )
+        started = time.monotonic()
+        rows = self.repository.read_trends(
+            scope="fleet", scope_id=None,
+            window_start=datetime(2026, 8, 10, 13, 0, tzinfo=timezone.utc),
+            window_end=datetime(2026, 8, 17, 13, 0, tzinfo=timezone.utc),
+            bucket_width=timedelta(hours=1),
+        )
+        elapsed = time.monotonic() - started
+        self.assertEqual(len(rows), 168)
+        self.assertLess(elapsed, 15.0)
+        print(f"Monitoring synthetic benchmark: 84,000 rows, 168 points, {elapsed:.3f}s")
+
+
+class MonitoringFrontendTests(unittest.TestCase):
+    def setUp(self):
+        self.app = FastAPI()
+        self.app.include_router(monitoring_frontend_router)
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "username": "reader", "display_name": "Reader",
+            "role": "Custom", "permissions": list(permissions),
+        }
+
+    def test_page_requires_scope_aligned_permissions_and_renders_shell(self):
+        self.assertEqual(self.client.get("/monitoring/analytics").status_code, 401)
+        self.authenticate(("miners.view",))
+        response = self.client.get("/monitoring/analytics")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn('data-view="analytics"', response.text)
+        self.assertIn("/assets/minerops-monitoring-trends.js", response.text)
+        self.assertNotIn('<option value="site">', response.text)
+        response = self.client.get(
+            "/monitoring/analytics",
+            params={"scope": "site", "scope_id": uuid4(), "range": "24h"},
+        )
+        self.assertEqual(response.status_code, 403)
+        self.authenticate(("miners.view", "locations.view"))
+        self.assertEqual(self.client.get(
+            "/monitoring/analytics",
+            params={"scope": "site", "scope_id": uuid4(), "range": "24h"},
+        ).status_code, 200)
+
+    def test_script_is_one_request_read_only_safe_dom_and_accessible(self):
+        source = (STATIC_ROOT / "monitoring-trends.js").read_text(encoding="utf-8")
+        self.assertEqual(source.count('fetch(url,'), 1)
+        self.assertIn("return el.site.value || state.scopeId", source)
+        self.assertIn("return el.room.value || state.scopeId", source)
+        self.assertNotIn("setInterval", source)
+        for method in ('method: "POST"', 'method: "PATCH"', 'method: "PUT"',
+                       'method: "DELETE"'):
+            self.assertNotIn(method, source)
+        for unsafe in ("innerHTML", "outerHTML", "insertAdjacentHTML",
+                       "document.write", "eval(", "Function("):
+            self.assertNotIn(unsafe, source)
+        for expected in ("textContent", "tabindex", "aria-label", "View ",
+                         "Gaps indicate", "prefers-reduced-motion"):
+            combined = source + (STATIC_ROOT / "monitoring-trends.css").read_text()
+            self.assertIn(expected, combined)
+        for forbidden in ("threshold", "healthy range", "kWh", "30d"):
+            self.assertNotIn(forbidden, source)
+
+    def test_navigation_identity_and_miner_detail_use_canonical_durable_link(self):
+        self.assertTrue(protected_page("/monitoring/analytics"))
+        self.assertEqual(required_page_permission("/monitoring/analytics"), "miners.view")
+        detail_html = (APP_ROOT / "frontend" / "miner_detail_view.py").read_text()
+        detail_js = (STATIC_ROOT / "miner-detail.js").read_text()
+        self.assertIn("View trends", detail_html)
+        self.assertIn('scope: "miner", scope_id: data.miner.id, range: "24h"', detail_js)
+        self.assertIn('"/monitoring/analytics?"', detail_js)
+
+
+class MonitoringArchitectureTests(unittest.TestCase):
+    def test_layering_routes_and_sql_are_bounded(self):
+        for relative in ("monitoring/router.py", "monitoring/service.py",
+                         "monitoring/frontend.py"):
+            source = (APP_ROOT / relative).read_text(encoding="utf-8")
+            modules = []
+            for node in ast.walk(ast.parse(source)):
+                if isinstance(node, ast.Import):
+                    modules.extend(alias.name for alias in node.names)
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    modules.append(node.module)
+            self.assertFalse(any(name.startswith(("psycopg", "asyncpg", "sqlalchemy"))
+                                 for name in modules))
+            for statement in ("SELECT ", "INSERT ", "UPDATE ", "DELETE "):
+                self.assertNotIn(statement, source.upper())
+        service = (APP_ROOT / "monitoring" / "service.py").read_text()
+        repository = (APP_ROOT / "monitoring" / "repository.py").read_text()
+        self.assertNotIn("fastapi", service.lower())
+        self.assertEqual(repository.count("cur.execute("), 2)
+        self.assertIn("miner_status_snapshots", TREND_SQL)
+        self.assertNotIn("miner_status_hourly_rollups", TREND_SQL)
+        self.assertNotIn("miner_status_daily_rollups", TREND_SQL)
+        self.assertIn("date_bin", TREND_SQL)
+        self.assertIn("%s", TREND_SQL)
+        self.assertEqual([(route.path, route.methods) for route in monitoring_router.routes],
+                         [("/api/monitoring/trends", {"GET"})])
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_repair_center.py

@@ -0,0 +1,430 @@
+import inspect
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+
+from app.frontend.router import router as frontend_router
+from app.identity import get_current_user, required_api_permission
+from app.repairs.center_repository import RepairCenterRepository
+from app.repairs.center_service import RepairCenterService
+from app.repairs.models import RepairCenterAccess, RepairCenterFilters
+
+
+NOW = datetime(2026, 8, 11, 12, 0, tzinfo=timezone.utc)
+STATIC_ROOT = Path(__file__).parents[1] / "app" / "frontend" / "static"
+
+
+class FakeCenterRepository:
+    def __init__(self):
+        self.arguments = None
+        self.rows = []
+
+    def list_repair_center(self, filters, **permissions):
+        self.arguments = (filters, permissions)
+        return {
+            "items": self.rows,
+            "summary": {"total": len(self.rows), "active": len(self.rows),
+                        "historical": 0, "status_counts": {"OPEN": len(self.rows)}},
+            "location_options": {"sites": [], "rooms": []},
+        }
+
+
+def center_row(source="modular", active=True):
+    repair_id = uuid4() if source == "modular" else None
+    return {
+        "repair_id": repair_id,
+        "source": source,
+        "active": active,
+        "opened_at": NOW,
+        "closed_at": None,
+        "repair_status": "OPEN" if source == "modular" else "testing",
+        "reason": "HARDWARE_FAILURE" if source == "modular" else None,
+        "reported_problem": "Hashboard not detected",
+        "latest_context": "Testing replacement board",
+        "latest_context_at": NOW,
+        "opened_by_display_name": "Repair Tech" if source == "modular" else None,
+        "miner_id": uuid4(),
+        "asset_id": "MINER-100",
+        "model": "M60S",
+        "miner_sn": "SN-100",
+        "power_sn": "PSU-100",
+        "current_mac": "00:11:22:33:44:55",
+        "current_ip": "192.0.2.10",
+        "lifecycle_status": "in_repair",
+        "runtime_status": "offline",
+        "site_id": uuid4(),
+        "site_name": "Site A",
+        "room_id": uuid4(),
+        "room_name": "Room 1",
+        "rack_label": "12",
+        "shelf_label": "3",
+        "position_id": uuid4(),
+        "position_label": "P04",
+        "position_index": 4,
+        "parts_count": 1 if source == "modular" else None,
+        "parts_summary": ["Fan"] if source == "modular" else [],
+        "legacy_event_status": "testing" if source == "legacy" else None,
+        "legacy_asset_state": "repair" if source == "legacy" else None,
+    }
+
+
+class RepairCenterServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeCenterRepository()
+        self.service = RepairCenterService(self.repository)
+
+    def test_modular_capabilities_use_repair_uuid_and_permissions(self):
+        self.repository.rows = [center_row()]
+        result = self.service.list_repair_center(
+            RepairCenterFilters(),
+            RepairCenterAccess(can_read_repairs=True, can_view_miners=True,
+                can_view_locations=True, can_complete_repairs=True,
+                can_manage_parts=True, can_manage_legacy=True),
+        )
+        item = result.data.items[0]
+        self.assertTrue(item.capabilities.can_read_modular_timeline)
+        self.assertTrue(item.capabilities.can_manage_modular_parts)
+        self.assertTrue(item.capabilities.can_complete_modular_repair)
+        self.assertFalse(item.capabilities.can_manage_legacy)
+        self.assertTrue(item.capabilities.can_open_map)
+
+    def test_part_management_requires_modular_read_access(self):
+        self.repository.rows = [center_row()]
+        result = self.service.list_repair_center(
+            RepairCenterFilters(),
+            RepairCenterAccess(can_manage_parts=True),
+        )
+        self.assertFalse(
+            result.data.items[0].capabilities.can_manage_modular_parts
+        )
+
+    def test_legacy_capabilities_never_enable_modular_mutations(self):
+        self.repository.rows = [center_row("legacy")]
+        result = self.service.list_repair_center(
+            RepairCenterFilters(),
+            RepairCenterAccess(can_read_repairs=True, can_view_miners=True,
+                can_view_locations=True, can_complete_repairs=True,
+                can_manage_parts=True, can_manage_legacy=True),
+        )
+        item = result.data.items[0]
+        self.assertTrue(item.capabilities.can_manage_legacy)
+        self.assertTrue(item.capabilities.can_mark_legacy_repaired)
+        self.assertFalse(item.capabilities.can_complete_modular_repair)
+        self.assertFalse(item.capabilities.can_manage_modular_parts)
+
+    def test_repository_receives_explicit_redaction_flags(self):
+        self.service.list_repair_center(
+            RepairCenterFilters(query=" fan "), RepairCenterAccess()
+        )
+        filters, permissions = self.repository.arguments
+        self.assertEqual(filters["query"], "fan")
+        self.assertFalse(permissions["include_miner_details"])
+        self.assertFalse(permissions["include_location_details"])
+
+    def test_pagination_and_exact_summary_are_preserved(self):
+        self.repository.rows = [center_row()]
+        result = self.service.list_repair_center(
+            RepairCenterFilters(limit=25, offset=50), RepairCenterAccess()
+        )
+        self.assertEqual(result.meta.limit, 25)
+        self.assertEqual(result.meta.offset, 50)
+        self.assertEqual(result.meta.returned, 1)
+        self.assertEqual(result.meta.total, 1)
+        self.assertEqual(result.data.summary.status_counts, {"OPEN": 1})
+
+
+
+class RepairCenterDatabaseTests(unittest.TestCase):
+    def test_empty_database_projection_executes_as_typed_set_query(self):
+        result = RepairCenterRepository().list_repair_center(
+            {"scope": "active", "limit": 25, "offset": 0},
+            include_miner_details=True,
+            include_location_details=True,
+        )
+        self.assertEqual(result["items"], [])
+        self.assertEqual(result["summary"]["total"], 0)
+        self.assertEqual(result["location_options"], {"sites": [], "rooms": []})
+
+    def test_projection_consolidates_sources_filters_and_pages_exactly(self):
+        repository = RepairCenterRepository()
+        actor_id = uuid4()
+        site_id = uuid4()
+        room_id = uuid4()
+        modular_miner_id = uuid4()
+        legacy_miner_id = uuid4()
+        completed_miner_id = uuid4()
+        connection = repository._connection_factory()
+        try:
+            with connection:
+                with connection.cursor() as cur:
+                    cur.execute(
+                        """
+                        INSERT INTO users (
+                            id, username, display_name, password_hash, role_id
+                        )
+                        SELECT %s, %s, 'Repair Center Actor', 'not-used', id
+                        FROM roles WHERE name = 'Admin'
+                        """,
+                        (actor_id, f"repair-center-{actor_id}"),
+                    )
+                    cur.execute(
+                        "INSERT INTO sites (id, name) VALUES (%s, %s)",
+                        (site_id, f"Repair Center Site {site_id}"),
+                    )
+                    cur.execute(
+                        """
+                        INSERT INTO rooms (id, site_id, name)
+                        VALUES (%s, %s, 'Repair Room')
+                        """,
+                        (room_id, site_id),
+                    )
+                    for miner_id, asset_id, lifecycle in (
+                        (modular_miner_id, "RC-MODULAR", "in_repair"),
+                        (legacy_miner_id, "RC-LEGACY", "in_repair"),
+                        (completed_miner_id, "RC-COMPLETED", "active"),
+                    ):
+                        cur.execute(
+                            """
+                            INSERT INTO miners (
+                                id, asset_tag, model, status, lifecycle_status,
+                                first_seen_at, last_seen_at
+                            )
+                            VALUES (%s, %s, 'M60S', 'offline', %s, NULL, NULL)
+                            """,
+                            (miner_id, asset_id, lifecycle),
+                        )
+                    for index, miner_id in enumerate(
+                        (modular_miner_id, legacy_miner_id), start=1
+                    ):
+                        cur.execute(
+                            """
+                            INSERT INTO location_positions (
+                                room_id, room_name, rack_name, shelf_name,
+                                position_index, position_label, miner_id
+                            )
+                            VALUES (%s, 'Repair Room', 'Rack 1', 'Shelf A',
+                                %s, %s, %s)
+                            """,
+                            (room_id, index, f"P{index:02d}", miner_id),
+                        )
+                        cur.execute(
+                            """
+                            INSERT INTO miner_location_states (
+                                miner_id, asset_state, state_notes,
+                                updated_by_user_id
+                            )
+                            VALUES (%s, 'repair', 'Legacy repair context', %s)
+                            """,
+                            (miner_id, actor_id),
+                        )
+                        cur.execute(
+                            """
+                            INSERT INTO miner_maintenance_events (
+                                miner_id, event_type, event_status, event_title,
+                                description, created_by_user_id
+                            )
+                            VALUES (%s, 'repair', 'waiting_parts',
+                                'Legacy board issue', 'Waiting for board', %s)
+                            """,
+                            (miner_id, actor_id),
+                        )
+                    cur.execute(
+                        """
+                        INSERT INTO repairs (miner_id, reason, opened_by)
+                        VALUES (%s, 'CONTROL_BOARD', %s)
+                        """,
+                        (modular_miner_id, actor_id),
+                    )
+                    cur.execute(
+                        """
+                        INSERT INTO repairs (
+                            miner_id, status, reason, opened_by, completed_at,
+                            completed_by, resulting_lifecycle
+                        )
+                        VALUES (%s, 'COMPLETED', 'INSPECTION', %s, now(),
+                            %s, 'active')
+                        """,
+                        (completed_miner_id, actor_id, actor_id),
+                    )
+        finally:
+            connection.close()
+
+        from app.main import minerops_repair_reject_modular_mutation
+
+        boundary_connection = repository._connection_factory()
+        try:
+            with boundary_connection.cursor() as cur:
+                with self.assertRaises(HTTPException) as raised:
+                    minerops_repair_reject_modular_mutation(
+                        cur, str(modular_miner_id)
+                    )
+                self.assertEqual(raised.exception.status_code, 409)
+                minerops_repair_reject_modular_mutation(
+                    cur, str(legacy_miner_id)
+                )
+        finally:
+            boundary_connection.close()
+
+        active = repository.list_repair_center(
+            {"scope": "active", "limit": 1, "offset": 0},
+            include_miner_details=True,
+            include_location_details=True,
+        )
+        self.assertEqual(active["summary"]["total"], 2)
+        self.assertEqual(len(active["items"]), 1)
+        self.assertEqual(active["summary"]["active"], 2)
+        self.assertEqual(active["location_options"]["sites"][0]["id"], str(site_id))
+
+        all_active = repository.list_repair_center(
+            {"scope": "active", "limit": 25, "offset": 0},
+            include_miner_details=True,
+            include_location_details=True,
+        )
+        by_miner = {row["miner_id"]: row for row in all_active["items"]}
+        self.assertEqual(set(by_miner), {modular_miner_id, legacy_miner_id})
+        self.assertEqual(by_miner[modular_miner_id]["source"], "modular")
+        self.assertEqual(by_miner[legacy_miner_id]["source"], "legacy")
+        self.assertEqual(by_miner[legacy_miner_id]["repair_event_count"], 1)
+        self.assertEqual(
+            by_miner[legacy_miner_id]["latest_event_title"],
+            "Legacy board issue",
+        )
+        self.assertEqual(all_active["summary"]["model_counts"], {"M60S": 2})
+        self.assertEqual(
+            all_active["summary"]["error_counts"],
+            {"CONTROL BOARD": 1, "Legacy board issue": 1},
+        )
+
+        filtered = repository.list_repair_center(
+            {"scope": "all", "query": "RC-COMPLETED", "model": "m60s",
+                "limit": 25, "offset": 0},
+            include_miner_details=True,
+            include_location_details=True,
+        )
+        self.assertEqual(filtered["summary"]["total"], 1)
+        self.assertFalse(filtered["items"][0]["active"])
+
+        redacted = repository.list_repair_center(
+            {"scope": "active", "limit": 25, "offset": 0},
+            include_miner_details=False,
+            include_location_details=False,
+        )
+        self.assertEqual(redacted["summary"]["total"], 2)
+        self.assertTrue(all(row["asset_id"] is None for row in redacted["items"]))
+        self.assertTrue(all(row["site_id"] is None for row in redacted["items"]))
+        self.assertEqual(redacted["location_options"], {"sites": [], "rooms": []})
+
+class RepairCenterRepositoryAuditTests(unittest.TestCase):
+    def test_projection_prevents_duplicate_active_legacy_rows(self):
+        source = inspect.getsource(RepairCenterRepository._ctes)
+        self.assertIn("NOT EXISTS", source)
+        self.assertIn("active_repair.miner_id = miner.id", source)
+        self.assertIn("UNION ALL", source)
+        self.assertIn("part_rollup", source)
+        self.assertIn("placement", source)
+
+    def test_projection_uses_constant_set_based_queries(self):
+        source = inspect.getsource(RepairCenterRepository.list_repair_center)
+        self.assertEqual(source.count("cur.execute("), 3)
+        self.assertNotIn("for item in", source)
+        self.assertIn("count(*) FILTER", source)
+        self.assertIn("LIMIT %s OFFSET %s", source)
+
+    def test_filter_sql_is_parameterized_and_complete_result_scoped(self):
+        where, params = RepairCenterRepository._where({
+            "scope": "historical", "status": "COMPLETED", "query": "fan",
+            "site_id": uuid4(), "room_id": uuid4(),
+        })
+        self.assertIn("NOT candidate.active", where)
+        self.assertIn("candidate.repair_status = %s", where)
+        self.assertIn("candidate.site_id = %s", where)
+        self.assertTrue(params[-1].startswith("%fan"))
+
+
+class RepairCenterFrontendTests(unittest.TestCase):
+    def setUp(self):
+        self.app = FastAPI()
+        self.app.include_router(frontend_router)
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "username": "tech", "display_name": "Repair Tech",
+            "role": "Technician", "permissions": ["repairs.view", "repairs.read",
+                "repairs.manage", "repairs.complete", "repairs.parts.manage",
+                "miners.view", "locations.view"],
+        }
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def test_page_has_semantic_queue_filters_paging_and_inspector(self):
+        response = self.client.get("/operations/repairs")
+        self.assertEqual(response.status_code, 200)
+        for value in ('id="repairFilters"', 'id="repairRows"',
+            'id="repairInspector"', 'id="repairPrevious"', 'id="repairNext"',
+            '<th>Reported problem</th>', '/assets/minerops-repair-center.js'):
+            self.assertIn(value, response.text)
+
+    def test_location_filters_are_not_rendered_without_permission(self):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()), "role": "Custom", "permissions": ["repairs.view"]
+        }
+        text = self.client.get("/operations/repairs").text
+        self.assertNotIn('id="repairSite"', text)
+        self.assertNotIn('id="repairModel"', text)
+        self.assertNotIn('id="repairRoom"', text)
+
+    def test_restricted_filter_parameters_are_rejected(self):
+        from app.main import minerops_repair_queue_api
+
+        arguments = {
+            "query": None, "scope": "active", "status_filter": None,
+            "model": None, "lifecycle_status": None, "site_id": None,
+            "room_id": None, "limit": 50, "offset": 0,
+            "current_user": {"permissions": ["repairs.view"]},
+        }
+        for field, value in (("model", "M60S"), ("site_id", uuid4())):
+            with self.subTest(field=field):
+                with self.assertRaises(HTTPException) as raised:
+                    minerops_repair_queue_api(**{**arguments, field: value})
+                self.assertEqual(raised.exception.status_code, 403)
+
+    def test_frontend_is_one_initial_read_without_polling_or_unsafe_html(self):
+        source = (STATIC_ROOT / "repair-center.js").read_text(encoding="utf-8")
+        self.assertEqual(source.count('api("/api/repairs/queue?"'), 1)
+        self.assertNotIn("setInterval", source)
+        for unsafe in ("innerHTML", "insertAdjacentHTML", "document.write"):
+            self.assertNotIn(unsafe, source)
+        self.assertIn("Promise.all", source)
+        self.assertIn("encodeURIComponent", source)
+        self.assertIn("URLSearchParams", source)
+
+    def test_mutations_are_source_specific_and_gets_are_read_only(self):
+        source = (STATIC_ROOT / "repair-center.js").read_text(encoding="utf-8")
+        self.assertIn('/complete"', source)
+        self.assertIn('/parts"', source)
+        self.assertIn('"/note" : "/status"', source)
+        self.assertIn('/state"', source)
+        self.assertNotIn('method: "GET"', source)
+        self.assertIn("Type DECOMMISSION", source)
+
+    def test_miner_and_map_links_use_durable_safe_identifiers(self):
+        source = (STATIC_ROOT / "repair-center.js").read_text(encoding="utf-8")
+        self.assertIn('encodeURIComponent(item.miner_id) + "/detail"', source)
+        self.assertIn("site_id: item.site_id", source)
+        self.assertIn("room_id: item.room_id", source)
+        self.assertIn("miner_id: item.miner_id", source)
+
+    def test_history_get_requires_repairs_read(self):
+        self.assertEqual(required_api_permission(
+            "GET", f"/api/miners/{uuid4()}/maintenance-events"), "repairs.read")
+        self.assertEqual(required_api_permission(
+            "PATCH", f"/api/miners/{uuid4()}/maintenance-events/{uuid4()}"),
+            "repairs.manage")
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_repair_parts_tracking.py

@@ -0,0 +1,455 @@
+import ast
+from contextlib import contextmanager
+from copy import deepcopy
+from datetime import datetime, timezone
+from decimal import Decimal
+from pathlib import Path
+import unittest
+from uuid import uuid4
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+
+from app.components.dependencies import get_component_service
+from app.components.exceptions import ComponentValidationError
+from app.components.models import ComponentCreateRequest, ComponentDetail
+from app.components.router import router as component_router
+from app.components.service import ComponentService
+from app.identity import get_current_user, required_api_permission
+from app.repairs.dependencies import get_repair_service
+from app.repairs.exceptions import RepairPartAlreadyVoided
+from app.repairs.models import (
+    ConsumableInput,
+    RepairPartComponentSnapshot,
+    RepairPartConsumable,
+    RepairPartDetail,
+    RepairPartList,
+    RepairPartRecordRequest,
+    RepairPartVoidRequest,
+)
+from app.repairs.router import router as repair_router
+from app.repairs.service import RepairService
+
+
+NOW = datetime(2026, 8, 2, 12, 0, tzinfo=timezone.utc)
+
+
+class FakeComponentRepository:
+    def __init__(self):
+        self.rows = {}
+        self.calls = []
+
+    @contextmanager
+    def transaction(self):
+        self.calls.append("transaction")
+        yield self
+
+    def create_component(self, **values):
+        component_id = uuid4()
+        row = {
+            "component_id": component_id,
+            "created_at": NOW,
+            **values,
+        }
+        self.rows[component_id] = row
+        return row
+
+    def get_component(self, component_id):
+        return self.rows.get(component_id)
+
+
+class ComponentServiceTests(unittest.TestCase):
+    def test_create_normalizes_metadata_and_uses_authoritative_fields(self):
+        repository = FakeComponentRepository()
+        actor = uuid4()
+        component = ComponentService(repository).create_component(
+            ComponentCreateRequest(
+                component_type="hashboard",
+                asset_id="  HB-0042  ",
+                manufacturer="  MicroBT  ",
+            ),
+            actor_user_id=actor,
+        )
+        self.assertEqual(component.asset_id, "HB-0042")
+        self.assertEqual(component.manufacturer, "MicroBT")
+        self.assertEqual(component.created_by, actor)
+        self.assertIsNotNone(component.component_id)
+        self.assertEqual(repository.calls, ["transaction"])
+
+    def test_component_request_rejects_blank_unknown_and_server_fields(self):
+        for body, exception in (
+            ({"component_type": "other"}, ValidationError),
+            ({"component_type": "fan", "asset_id": "   "}, ComponentValidationError),
+            ({"component_type": "fan", "created_by": str(uuid4())}, ValidationError),
+        ):
+            with self.subTest(body=body), self.assertRaises(exception):
+                request = ComponentCreateRequest(**body)
+                ComponentService(FakeComponentRepository()).create_component(
+                    request, actor_user_id=uuid4()
+                )
+
+
+class FakeRepairPartRepository:
+    def __init__(self):
+        self.repair_id = uuid4()
+        self.miner_id = uuid4()
+        self.actor_id = uuid4()
+        self.component_id = uuid4()
+        self.miner = {"id": self.miner_id, "lifecycle_status": "in_repair"}
+        self.repair = {
+            "id": self.repair_id,
+            "miner_id": self.miner_id,
+            "status": "OPEN",
+        }
+        self.component = {
+            "id": self.component_id,
+            "component_type": "control_board",
+            "asset_id": "CB-42",
+            "manufacturer": "MicroBT",
+            "model": None,
+            "manufacturer_serial": "SER-42",
+        }
+        self.events = [{"sequence": 1}]
+        self.parts = {}
+        self.calls = []
+        self.fail_at = None
+
+    @contextmanager
+    def transaction(self):
+        self.calls.append("transaction")
+        snapshot = deepcopy((self.events, self.parts))
+        try:
+            yield self
+        except Exception:
+            self.events, self.parts = snapshot
+            raise
+
+    def _call(self, name):
+        self.calls.append(name)
+        if self.fail_at == name:
+            raise RuntimeError(name)
+
+    def get_repair_identity(self, repair_id):
+        self._call("repair_identity")
+        return {"miner_id": self.miner_id} if repair_id == self.repair_id else None
+
+    def lock_miner_for_update(self, miner_id):
+        self._call("lock_miner")
+        return self.miner if miner_id == self.miner_id else None
+
+    def lock_repair_for_update(self, repair_id):
+        self._call("lock_repair")
+        return self.repair if repair_id == self.repair_id else None
+
+    def get_active_repair(self, miner_id):
+        self._call("active_repair")
+        return self.repair if miner_id == self.miner_id else None
+
+    def lock_component_for_update(self, component_id):
+        self._call("lock_component")
+        return self.component if component_id == self.component_id else None
+
+    def get_next_event_sequence(self, repair_id):
+        self._call("next_sequence")
+        return max(event["sequence"] for event in self.events) + 1
+
+    def create_event(self, repair_id, **values):
+        self._call("create_event")
+        row = {"id": uuid4(), "repair_id": repair_id, "created_at": NOW, **values}
+        self.events.append(row)
+        return row
+
+    def create_repair_part(self, **values):
+        self._call("create_part")
+        component = values["component"]
+        row = {
+            "id": values["repair_part_id"],
+            "repair_id": values["repair_id"],
+            "consumable_description": values["consumable_description"],
+            "quantity": values["quantity"],
+            "unit": values["unit"],
+            "component_id": component["id"] if component else None,
+            "component_type_snapshot": component["component_type"] if component else None,
+            "component_asset_id_snapshot": component["asset_id"] if component else None,
+            "component_manufacturer_snapshot": component["manufacturer"] if component else None,
+            "component_model_snapshot": component["model"] if component else None,
+            "component_manufacturer_serial_snapshot": component["manufacturer_serial"] if component else None,
+            "notes": values["notes"],
+            "recorded_by": values["recorded_event"]["created_by"],
+            "recorded_at": values["recorded_event"]["created_at"],
+            "recorded_event_id": values["recorded_event"]["id"],
+            "voided_by": None,
+            "voided_at": None,
+            "void_reason": None,
+            "void_event_id": None,
+        }
+        self.parts[row["id"]] = row
+        return row
+
+    def get_repair_part(self, repair_id, repair_part_id):
+        self._call("get_part")
+        row = self.parts.get(repair_part_id)
+        return row if row and row["repair_id"] == repair_id else None
+
+    def get_repair_parts(self, repair_id):
+        rows = [row for row in self.parts.values() if row["repair_id"] == repair_id]
+        return rows if repair_id == self.repair_id else None
+
+    def lock_repair_part_for_update(self, repair_id, repair_part_id):
+        self._call("lock_part")
+        return self.get_repair_part(repair_id, repair_part_id)
+
+    def void_repair_part(self, repair_id, repair_part_id, *, reason, void_event):
+        self._call("void_part")
+        row = self.get_repair_part(repair_id, repair_part_id)
+        if row is None or row["voided_at"] is not None:
+            return None
+        row.update(
+            voided_by=void_event["created_by"],
+            voided_at=void_event["created_at"],
+            void_reason=reason,
+            void_event_id=void_event["id"],
+        )
+        return row
+
+
+class RepairPartServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeRepairPartRepository()
+        self.service = RepairService(self.repository)
+
+    def test_request_xor_precision_units_and_trim(self):
+        valid = ConsumableInput(description=" Paste ", quantity="1.250", unit="gram")
+        self.assertEqual(valid.description, "Paste")
+        self.assertEqual(valid.quantity, Decimal("1.250"))
+        invalid = (
+            {"consumable": None, "tracked_component_uuid": None},
+            {"consumable": valid, "tracked_component_uuid": uuid4()},
+            {"consumable": {"description": "x", "quantity": "1.0001", "unit": "gram"}},
+            {"consumable": {"description": "x", "quantity": "1.5", "unit": "each"}},
+            {"consumable": {"description": "x", "quantity": "1", "unit": "kg"}},
+        )
+        for body in invalid:
+            with self.subTest(body=body), self.assertRaises(ValidationError):
+                RepairPartRecordRequest(**body)
+
+    def test_consumable_record_is_atomic_and_sequenced(self):
+        result = self.service.record_repair_part(
+            self.repository.repair_id,
+            RepairPartRecordRequest(
+                consumable={"description": " Paste ", "quantity": "2", "unit": "gram"},
+                notes=" Used on board ",
+            ),
+            actor_user_id=self.repository.actor_id,
+        )
+        self.assertEqual(result.entry_kind, "consumable")
+        self.assertEqual(result.consumable.description, "Paste")
+        event = self.repository.events[-1]
+        self.assertEqual(event["event_type"], "REPAIR_PART_RECORDED")
+        self.assertEqual(event["sequence"], 2)
+        self.assertEqual(event["created_by"], self.repository.actor_id)
+        self.assertEqual(event["payload"]["quantity"], "2")
+        self.assertEqual(self.repository.calls[:5], [
+            "transaction", "repair_identity", "lock_miner", "lock_repair", "active_repair"
+        ])
+
+    def test_tracked_component_uses_locked_snapshot_without_mutation(self):
+        before = deepcopy(self.repository.component)
+        result = self.service.record_repair_part(
+            self.repository.repair_id,
+            RepairPartRecordRequest(tracked_component_uuid=self.repository.component_id),
+            actor_user_id=self.repository.actor_id,
+        )
+        self.assertEqual(result.component_id, self.repository.component_id)
+        self.assertEqual(result.component_snapshot.asset_id, "CB-42")
+        self.assertEqual(self.repository.component, before)
+        self.assertLess(
+            self.repository.calls.index("lock_repair"),
+            self.repository.calls.index("lock_component"),
+        )
+
+    def test_void_is_one_way_and_rollbacks_leave_no_partial_event(self):
+        part = self.service.record_repair_part(
+            self.repository.repair_id,
+            RepairPartRecordRequest(
+                consumable={"description": "Fuse", "quantity": 1, "unit": "each"}
+            ),
+            actor_user_id=self.repository.actor_id,
+        )
+        voided = self.service.void_repair_part(
+            self.repository.repair_id,
+            part.repair_part_id,
+            RepairPartVoidRequest(reason=" Wrong repair "),
+            actor_user_id=self.repository.actor_id,
+        )
+        self.assertEqual(voided.void_reason, "Wrong repair")
+        with self.assertRaises(RepairPartAlreadyVoided):
+            self.service.void_repair_part(
+                self.repository.repair_id,
+                part.repair_part_id,
+                RepairPartVoidRequest(reason="Again"),
+                actor_user_id=self.repository.actor_id,
+            )
+        self.assertEqual(
+            [event.get("event_type") for event in self.repository.events].count("REPAIR_PART_VOIDED"),
+            1,
+        )
+
+    def test_insert_failure_rolls_back_event_and_part(self):
+        self.repository.fail_at = "create_part"
+        with self.assertRaises(RuntimeError):
+            self.service.record_repair_part(
+                self.repository.repair_id,
+                RepairPartRecordRequest(
+                    consumable={"description": "Fuse", "quantity": 1, "unit": "each"}
+                ),
+                actor_user_id=self.repository.actor_id,
+            )
+        self.assertEqual(self.repository.events, [{"sequence": 1}])
+        self.assertEqual(self.repository.parts, {})
+
+
+def part_detail(repair_id, actor_id):
+    return RepairPartDetail(
+        repair_part_id=uuid4(), repair_id=repair_id, entry_kind="consumable",
+        consumable=RepairPartConsumable(description="Fuse", quantity=1, unit="each"),
+        component_id=None, component_snapshot=None, notes=None,
+        recorded_by=actor_id, recorded_at=NOW, recorded_event_id=uuid4(),
+    )
+
+
+class StubComponentService:
+    def __init__(self, actor):
+        self.actor = actor
+
+    def create_component(self, request, *, actor_user_id):
+        self.actor_seen = actor_user_id
+        return ComponentDetail(
+            component_id=uuid4(), component_type=request.component_type,
+            created_at=NOW, created_by=actor_user_id,
+        )
+
+    def get_component(self, component_id):
+        return ComponentDetail(
+            component_id=component_id, component_type="fan",
+            created_at=NOW, created_by=self.actor,
+        )
+
+
+class StubRepairService:
+    def __init__(self, repair_id, actor):
+        self.repair_id = repair_id
+        self.actor = actor
+        self.detail = part_detail(repair_id, actor)
+
+    def record_repair_part(self, repair_id, request, *, actor_user_id):
+        self.actor_seen = actor_user_id
+        return self.detail
+
+    def list_repair_parts(self, repair_id):
+        return RepairPartList(repair_id=repair_id, entries=[self.detail])
+
+    def void_repair_part(self, repair_id, repair_part_id, request, *, actor_user_id):
+        self.actor_seen = actor_user_id
+        return self.detail.model_copy(update={
+            "voided_by": actor_user_id, "voided_at": NOW,
+            "void_reason": request.reason, "void_event_id": uuid4(),
+        })
+
+
+class Task005RouterTests(unittest.TestCase):
+    def setUp(self):
+        self.actor = uuid4()
+        self.repair_id = uuid4()
+        self.component_service = StubComponentService(self.actor)
+        self.repair_service = StubRepairService(self.repair_id, self.actor)
+        self.app = FastAPI()
+        self.app.include_router(component_router)
+        self.app.include_router(repair_router)
+        self.app.dependency_overrides[get_component_service] = lambda: self.component_service
+        self.app.dependency_overrides[get_repair_service] = lambda: self.repair_service
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions, role="Technician"):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(self.actor), "role": role, "permissions": list(permissions)
+        }
+
+    def test_authentication_permissions_and_actor_authority(self):
+        path = f"/api/repairs/{self.repair_id}/parts"
+        body = {"consumable": {"description": "Fuse", "quantity": 1, "unit": "each"}}
+        self.assertEqual(self.client.post(path, json=body).status_code, 401)
+        self.authenticate(("repairs.read",), role="Read Only")
+        self.assertEqual(self.client.post(path, json=body).status_code, 403)
+        self.assertEqual(self.client.get(path).status_code, 200)
+        self.authenticate(("repairs.parts.manage",))
+        self.assertEqual(self.client.post(path, json=body).status_code, 201)
+        self.assertEqual(self.repair_service.actor_seen, self.actor)
+
+    def test_component_routes_permissions_and_envelopes(self):
+        self.authenticate(("components.read",), role="Read Only")
+        self.assertEqual(self.client.post("/api/components", json={"component_type": "fan"}).status_code, 403)
+        self.assertEqual(self.client.get(f"/api/components/{uuid4()}").status_code, 200)
+        self.authenticate(("components.create",))
+        response = self.client.post("/api/components", json={"component_type": "fan"})
+        self.assertEqual(response.status_code, 201)
+        self.assertEqual(response.json()["meta"], {})
+        self.assertIsNone(response.json()["error"])
+
+    def test_exact_routes_and_permission_mapping(self):
+        component_routes = {(route.path, tuple(sorted(route.methods))) for route in component_router.routes}
+        self.assertEqual(component_routes, {
+            ("/api/components", ("POST",)),
+            ("/api/components/{component_id}", ("GET",)),
+        })
+        part_routes = {
+            (route.path, tuple(sorted(route.methods)))
+            for route in repair_router.routes if "/parts" in route.path
+        }
+        self.assertEqual(part_routes, {
+            ("/api/repairs/{repair_id}/parts", ("GET",)),
+            ("/api/repairs/{repair_id}/parts", ("POST",)),
+            ("/api/repairs/{repair_id}/parts/{repair_part_id}/void", ("POST",)),
+        })
+        repair_id = uuid4()
+        part_id = uuid4()
+        self.assertEqual(required_api_permission("GET", "/api/components"), "components.read")
+        self.assertEqual(required_api_permission("POST", "/api/components"), "components.create")
+        self.assertEqual(required_api_permission("GET", f"/api/repairs/{repair_id}/parts"), "repairs.read")
+        self.assertEqual(required_api_permission("POST", f"/api/repairs/{repair_id}/parts"), "repairs.parts.manage")
+        self.assertEqual(required_api_permission("POST", f"/api/repairs/{repair_id}/parts/{part_id}/void"), "repairs.parts.manage")
+
+    def test_architecture_boundaries(self):
+        root = Path(__file__).parents[1] / "app"
+        for relative in ("components/router.py", "repairs/router.py"):
+            source = (root / relative).read_text(encoding="utf-8")
+            tree = ast.parse(source)
+            imports = [
+                node.module for node in ast.walk(tree)
+                if isinstance(node, ast.ImportFrom) and node.module
+            ]
+            self.assertFalse(any(name.startswith(("psycopg", "sqlalchemy")) for name in imports))
+            self.assertNotIn("SELECT ", source.upper())
+            self.assertNotIn(".COMMIT(", source.upper())
+        for relative in (
+            "components/service.py", "components/repository.py",
+            "repairs/service.py", "repairs/repository.py",
+        ):
+            tree = ast.parse((root / relative).read_text(encoding="utf-8"))
+            imports = []
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    imports.extend(alias.name for alias in node.names)
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    imports.append(node.module)
+            self.assertFalse(
+                any(name == "fastapi" or name.startswith("fastapi.") for name in imports)
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_repair_timeline.py

@@ -0,0 +1,827 @@
+import ast
+import inspect
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from psycopg.rows import dict_row
+from starlette.routing import Match
+
+from app.identity import get_current_user, required_api_permission
+from app.repairs.dependencies import get_repair_service
+from app.repairs.exceptions import RepairNotFound
+from app.repairs.models import (
+    BeginRepairRequest,
+    BeginRepairResult,
+    RepairActor,
+    RepairDetail,
+    RepairTimeline,
+    RepairTimelineEvent,
+)
+from app.repairs.repository import RepairRepository
+from app.repairs.router import router
+from app.repairs.service import RepairService
+
+
+OPENED_AT = datetime(2026, 7, 29, 12, 0, tzinfo=timezone.utc)
+
+
+def detail_result(
+    repair_id: UUID | None = None,
+    miner_id: UUID | None = None,
+) -> RepairDetail:
+    return RepairDetail(
+        repair_id=repair_id or uuid4(),
+        miner_id=miner_id or uuid4(),
+        miner_asset_id="ASSET-TIMELINE-001",
+        status="OPEN",
+        reason="INSPECTION",
+        opened_at=OPENED_AT,
+        opened_by=RepairActor(
+            user_id=uuid4(),
+            display_name="Timeline Technician",
+        ),
+        closed_at=None,
+        closed_by=None,
+        miner_lifecycle="in_repair",
+        latest_event_sequence=2,
+    )
+
+
+def timeline_result(repair_id: UUID | None = None) -> RepairTimeline:
+    return RepairTimeline(
+        repair_id=repair_id or uuid4(),
+        events=[
+            RepairTimelineEvent(
+                event_id=uuid4(),
+                sequence=1,
+                event_type="REPAIR_STARTED",
+                actor=RepairActor(
+                    user_id=uuid4(),
+                    display_name="Timeline Technician",
+                ),
+                occurred_at=OPENED_AT,
+                payload={
+                    "reason": "INSPECTION",
+                    "from_lifecycle": "active",
+                    "to_lifecycle": "in_repair",
+                },
+            ),
+            RepairTimelineEvent(
+                event_id=uuid4(),
+                sequence=2,
+                event_type="INITIAL_NOTE",
+                actor=RepairActor(
+                    user_id=uuid4(),
+                    display_name="Timeline Manager",
+                ),
+                occurred_at=OPENED_AT,
+                payload={"note": "Inspect control board."},
+            ),
+        ],
+    )
+
+
+class FakeTimelineRepository:
+    def __init__(self):
+        self.detail = None
+        self.events = None
+        self.detail_repair_id = None
+        self.events_repair_id = None
+
+    def get_repair_detail(self, repair_id):
+        self.detail_repair_id = repair_id
+        return self.detail
+
+    def get_repair_events(self, repair_id):
+        self.events_repair_id = repair_id
+        return self.events
+
+
+class RepairTimelineServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeTimelineRepository()
+        self.service = RepairService(self.repository)
+        self.repair_id = uuid4()
+        self.miner_id = uuid4()
+        self.opened_by = uuid4()
+        self.closed_by = uuid4()
+
+    def detail_row(self):
+        return {
+            "repair_id": self.repair_id,
+            "miner_id": self.miner_id,
+            "miner_asset_id": "ASSET-SERVICE-001",
+            "status": "COMPLETED",
+            "reason": "PSU",
+            "opened_at": OPENED_AT,
+            "opened_by_user_id": self.opened_by,
+            "opened_by_display_name": "Opening Technician",
+            "closed_at": OPENED_AT + timedelta(hours=2),
+            "closed_by_user_id": self.closed_by,
+            "closed_by_display_name": "Closing Manager",
+            "miner_lifecycle": "active",
+            "latest_event_sequence": 3,
+        }
+
+    def test_detail_maps_public_fields_and_actors(self):
+        self.repository.detail = self.detail_row()
+
+        detail = self.service.get_repair(self.repair_id)
+
+        self.assertEqual(detail.repair_id, self.repair_id)
+        self.assertEqual(detail.miner_id, self.miner_id)
+        self.assertEqual(detail.miner_asset_id, "ASSET-SERVICE-001")
+        self.assertEqual(detail.status, "COMPLETED")
+        self.assertEqual(detail.reason, "PSU")
+        self.assertEqual(detail.opened_by.user_id, self.opened_by)
+        self.assertEqual(detail.closed_by.user_id, self.closed_by)
+        self.assertEqual(detail.closed_by.display_name, "Closing Manager")
+        self.assertEqual(detail.latest_event_sequence, 3)
+        self.assertEqual(self.repository.detail_repair_id, self.repair_id)
+
+    def test_detail_preserves_nullable_asset_and_empty_sequence(self):
+        row = self.detail_row()
+        row.update(
+            {
+                "miner_asset_id": None,
+                "status": "OPEN",
+                "closed_at": None,
+                "closed_by_user_id": None,
+                "closed_by_display_name": None,
+                "miner_lifecycle": "in_repair",
+                "latest_event_sequence": None,
+            }
+        )
+        self.repository.detail = row
+
+        detail = self.service.get_repair(self.repair_id)
+
+        self.assertIsNone(detail.miner_asset_id)
+        self.assertIsNone(detail.closed_at)
+        self.assertIsNone(detail.closed_by)
+        self.assertIsNone(detail.latest_event_sequence)
+
+    def test_missing_detail_raises_domain_not_found(self):
+        with self.assertRaises(RepairNotFound):
+            self.service.get_repair(self.repair_id)
+
+    def test_timeline_maps_structured_events_without_reordering(self):
+        actor_id = uuid4()
+        self.repository.events = [
+            {
+                "event_id": uuid4(),
+                "sequence": 1,
+                "event_type": "REPAIR_STARTED",
+                "actor_user_id": actor_id,
+                "actor_display_name": "Timeline Actor",
+                "occurred_at": OPENED_AT,
+                "payload": {
+                    "reason": "OTHER",
+                    "from_lifecycle": "spare",
+                    "to_lifecycle": "in_repair",
+                },
+            }
+        ]
+
+        timeline = self.service.get_repair_timeline(self.repair_id)
+
+        self.assertEqual(timeline.repair_id, self.repair_id)
+        self.assertEqual(len(timeline.events), 1)
+        self.assertEqual(timeline.events[0].sequence, 1)
+        self.assertEqual(timeline.events[0].actor.user_id, actor_id)
+        self.assertIsInstance(timeline.events[0].payload, dict)
+        self.assertEqual(
+            timeline.events[0].payload["from_lifecycle"],
+            "spare",
+        )
+
+    def test_empty_timeline_is_successful(self):
+        self.repository.events = []
+        timeline = self.service.get_repair_timeline(self.repair_id)
+        self.assertEqual(timeline.events, [])
+
+    def test_missing_timeline_raises_domain_not_found(self):
+        with self.assertRaises(RepairNotFound):
+            self.service.get_repair_timeline(self.repair_id)
+
+
+class RepairTimelineRepositoryTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.repository = RepairRepository()
+
+    def setUp(self):
+        self.opened_actor = uuid4()
+        self.note_actor = uuid4()
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute("ALTER TABLE repair_events DISABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repair_events")
+                cur.execute("ALTER TABLE repair_events ENABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repairs")
+                cur.execute("DELETE FROM miner_tags")
+                cur.execute("DELETE FROM miner_asset_id_history")
+                cur.execute("DELETE FROM miners")
+                cur.execute(
+                    "DELETE FROM users WHERE username LIKE "
+                    "'repair-timeline-test-%'"
+                )
+                for actor_id, suffix, display_name in (
+                    (
+                        self.opened_actor,
+                        "opened",
+                        "Timeline Opening Technician",
+                    ),
+                    (
+                        self.note_actor,
+                        "note",
+                        "Timeline Note Manager",
+                    ),
+                ):
+                    cur.execute(
+                        """
+                        INSERT INTO users (
+                            id,
+                            username,
+                            display_name,
+                            password_hash,
+                            role_id
+                        )
+                        SELECT %s, %s, %s, 'not-used', id
+                        FROM roles
+                        WHERE name = 'Admin'
+                        """,
+                        (
+                            actor_id,
+                            f"repair-timeline-test-{suffix}",
+                            display_name,
+                        ),
+                    )
+
+    def create_miner(self, asset_id="ASSET-TIMELINE-DB"):
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO miners (
+                        asset_tag,
+                        status,
+                        lifecycle_status,
+                        first_seen_at,
+                        last_seen_at
+                    )
+                    VALUES (%s, 'unknown', 'in_repair', NULL, NULL)
+                    RETURNING id
+                    """,
+                    (asset_id,),
+                )
+                return cur.fetchone()["id"]
+
+    def create_repair(self, miner_id):
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO repairs (miner_id, reason, opened_by)
+                    VALUES (%s, 'INSPECTION', %s)
+                    RETURNING id
+                    """,
+                    (miner_id, self.opened_actor),
+                )
+                return cur.fetchone()["id"]
+
+    def insert_non_monotonic_events(self, repair_id):
+        later = OPENED_AT + timedelta(hours=1)
+        earlier = OPENED_AT
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    INSERT INTO repair_events (
+                        repair_id,
+                        sequence,
+                        event_type,
+                        created_at,
+                        created_by,
+                        payload
+                    )
+                    VALUES
+                        (
+                            %s,
+                            1,
+                            'REPAIR_STARTED',
+                            %s,
+                            %s,
+                            %s::jsonb
+                        ),
+                        (
+                            %s,
+                            2,
+                            'INITIAL_NOTE',
+                            %s,
+                            %s,
+                            %s::jsonb
+                        )
+                    """,
+                    (
+                        repair_id,
+                        later,
+                        self.opened_actor,
+                        '{"reason":"INSPECTION","from_lifecycle":'
+                        '"active","to_lifecycle":"in_repair"}',
+                        repair_id,
+                        earlier,
+                        self.note_actor,
+                        '{"note":"Timestamp is earlier than sequence one."}',
+                    ),
+                )
+
+    def counts(self):
+        with self.repository._connection_scope() as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        (SELECT count(*) FROM repairs),
+                        (SELECT count(*) FROM repair_events)
+                    """
+                )
+                return cur.fetchone()
+
+    def test_detail_joins_asset_lifecycle_actor_and_latest_sequence(self):
+        miner_id = self.create_miner()
+        repair_id = self.create_repair(miner_id)
+        self.insert_non_monotonic_events(repair_id)
+
+        detail = self.repository.get_repair_detail(repair_id)
+
+        self.assertEqual(detail["repair_id"], repair_id)
+        self.assertEqual(detail["miner_id"], miner_id)
+        self.assertEqual(detail["miner_asset_id"], "ASSET-TIMELINE-DB")
+        self.assertEqual(detail["miner_lifecycle"], "in_repair")
+        self.assertEqual(detail["opened_by_user_id"], self.opened_actor)
+        self.assertEqual(
+            detail["opened_by_display_name"],
+            "Timeline Opening Technician",
+        )
+        self.assertIsNone(detail["closed_at"])
+        self.assertIsNone(detail["closed_by_user_id"])
+        self.assertEqual(detail["latest_event_sequence"], 2)
+
+    def test_events_order_by_sequence_not_timestamp_and_join_actors(self):
+        miner_id = self.create_miner()
+        repair_id = self.create_repair(miner_id)
+        self.insert_non_monotonic_events(repair_id)
+
+        events = self.repository.get_repair_events(repair_id)
+
+        self.assertEqual([event["sequence"] for event in events], [1, 2])
+        self.assertGreater(
+            events[0]["occurred_at"],
+            events[1]["occurred_at"],
+        )
+        self.assertEqual(
+            [event["actor_display_name"] for event in events],
+            [
+                "Timeline Opening Technician",
+                "Timeline Note Manager",
+            ],
+        )
+        self.assertIsInstance(events[0]["payload"], dict)
+        self.assertEqual(
+            events[1]["payload"],
+            {"note": "Timestamp is earlier than sequence one."},
+        )
+
+    def test_known_repair_with_no_events_returns_empty_timeline(self):
+        repair_id = self.create_repair(self.create_miner())
+
+        self.assertEqual(self.repository.get_repair_events(repair_id), [])
+        detail = self.repository.get_repair_detail(repair_id)
+        self.assertIsNone(detail["latest_event_sequence"])
+
+    def test_missing_repair_is_distinct_from_empty_timeline(self):
+        repair_id = uuid4()
+        self.assertIsNone(self.repository.get_repair_detail(repair_id))
+        self.assertIsNone(self.repository.get_repair_events(repair_id))
+
+    def test_reads_do_not_modify_repairs_or_events(self):
+        repair_id = self.create_repair(self.create_miner())
+        self.insert_non_monotonic_events(repair_id)
+        before = self.counts()
+
+        self.repository.get_repair_detail(repair_id)
+        self.repository.get_repair_events(repair_id)
+
+        self.assertEqual(self.counts(), before)
+
+
+class StubTimelineService:
+    def __init__(self):
+        self.detail = None
+        self.timeline = None
+        self.error = None
+        self.detail_repair_id = None
+        self.timeline_repair_id = None
+        self.begin_called = False
+
+    def get_repair(self, repair_id):
+        self.detail_repair_id = repair_id
+        if self.error is not None:
+            raise self.error
+        return self.detail
+
+    def get_repair_timeline(self, repair_id):
+        self.timeline_repair_id = repair_id
+        if self.error is not None:
+            raise self.error
+        return self.timeline
+
+    def begin_repair(self, request: BeginRepairRequest, *, actor_user_id):
+        self.begin_called = True
+        return BeginRepairResult(
+            repair_id=uuid4(),
+            miner_id=request.miner_id,
+            status="OPEN",
+            reason=request.reason,
+            opened_at=OPENED_AT,
+            opened_by=actor_user_id,
+        )
+
+
+class RepairTimelineRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubTimelineService()
+        self.app = FastAPI()
+        self.app.include_router(router)
+        self.app.dependency_overrides[get_repair_service] = (
+            lambda: self.service
+        )
+        self.client = TestClient(self.app)
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(
+        self,
+        role="Read Only",
+        permissions=("repairs.read",),
+    ):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(uuid4()),
+            "username": role.lower().replace(" ", "-"),
+            "role": role,
+            "permissions": list(permissions),
+        }
+
+    def test_timeline_routes_require_authentication(self):
+        for path in (
+            f"/api/repairs/{uuid4()}",
+            f"/api/repairs/{uuid4()}/events",
+        ):
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 401)
+
+    def test_timeline_routes_require_repairs_read(self):
+        self.authenticate(permissions=("repairs.view",))
+        for path in (
+            f"/api/repairs/{uuid4()}",
+            f"/api/repairs/{uuid4()}/events",
+        ):
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 403)
+
+    def test_all_default_roles_can_read_detail_and_events(self):
+        repair_id = uuid4()
+        self.service.detail = detail_result(repair_id)
+        self.service.timeline = timeline_result(repair_id)
+        for role in ("Admin", "Manager", "Technician", "Read Only"):
+            with self.subTest(role=role):
+                self.authenticate(role=role)
+                self.assertEqual(
+                    self.client.get(
+                        f"/api/repairs/{repair_id}"
+                    ).status_code,
+                    200,
+                )
+                self.assertEqual(
+                    self.client.get(
+                        f"/api/repairs/{repair_id}/events"
+                    ).status_code,
+                    200,
+                )
+
+    def test_malformed_repair_uuid_returns_validation_error(self):
+        self.authenticate()
+        for path in (
+            "/api/repairs/not-a-uuid",
+            "/api/repairs/not-a-uuid/events",
+        ):
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 422)
+
+    def test_missing_repair_returns_not_found(self):
+        self.authenticate()
+        repair_id = uuid4()
+        self.service.error = RepairNotFound(repair_id)
+        for path in (
+            f"/api/repairs/{repair_id}",
+            f"/api/repairs/{repair_id}/events",
+        ):
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 404)
+                self.assertEqual(
+                    response.json()["detail"],
+                    "Repair not found",
+                )
+
+    def test_detail_returns_typed_public_envelope(self):
+        self.authenticate()
+        repair_id = uuid4()
+        expected = detail_result(repair_id)
+        self.service.detail = expected
+
+        response = self.client.get(f"/api/repairs/{repair_id}")
+
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["data"]["repair_id"], str(repair_id))
+        self.assertEqual(body["data"]["miner_asset_id"], "ASSET-TIMELINE-001")
+        self.assertEqual(body["data"]["miner_lifecycle"], "in_repair")
+        self.assertEqual(body["data"]["latest_event_sequence"], 2)
+        self.assertEqual(
+            body["data"]["opened_by"]["display_name"],
+            "Timeline Technician",
+        )
+        self.assertIsNone(body["data"]["closed_at"])
+        self.assertIsNone(body["data"]["closed_by"])
+        self.assertEqual(body["meta"], {})
+        self.assertIsNone(body["error"])
+
+    def test_events_return_structured_payload_in_service_order(self):
+        self.authenticate()
+        repair_id = uuid4()
+        expected = timeline_result(repair_id)
+        self.service.timeline = expected
+
+        response = self.client.get(
+            f"/api/repairs/{repair_id}/events"
+        )
+
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["data"]["repair_id"], str(repair_id))
+        self.assertEqual(
+            [event["sequence"] for event in body["data"]["events"]],
+            [1, 2],
+        )
+        self.assertIsInstance(body["data"]["events"][0]["payload"], dict)
+        self.assertEqual(
+            body["data"]["events"][1]["actor"]["display_name"],
+            "Timeline Manager",
+        )
+
+    def test_known_empty_timeline_returns_success(self):
+        self.authenticate()
+        repair_id = uuid4()
+        self.service.timeline = RepairTimeline(
+            repair_id=repair_id,
+            events=[],
+        )
+
+        response = self.client.get(
+            f"/api/repairs/{repair_id}/events"
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["data"]["events"], [])
+
+    def test_read_only_cannot_begin_repair(self):
+        self.authenticate(role="Read Only", permissions=("repairs.read",))
+        response = self.client.post(
+            "/api/repairs",
+            json={"miner_id": str(uuid4()), "reason": "OTHER"},
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertFalse(self.service.begin_called)
+
+    def test_timeline_and_parts_get_routes_are_registered(self):
+        get_routes = {
+            route.path
+            for route in router.routes
+            if hasattr(route, "methods") and "GET" in route.methods
+        }
+        self.assertEqual(
+            get_routes,
+            {
+                "/api/repairs/{repair_id}",
+                "/api/repairs/{repair_id}/events",
+                "/api/repairs/{repair_id}/parts",
+            },
+        )
+
+
+class RepairTimelineArchitectureTests(unittest.TestCase):
+    @staticmethod
+    def full_route_matches(app, method, path):
+        scope = {
+            "type": "http",
+            "method": method,
+            "path": path,
+            "root_path": "",
+        }
+        return [
+            route
+            for route in app.routes
+            if route.matches(scope)[0] is Match.FULL
+        ]
+
+    def test_permission_mapper_scopes_new_and_legacy_routes(self):
+        repair_id = uuid4()
+        self.assertEqual(
+            required_api_permission(
+                "GET",
+                f"/api/repairs/{repair_id}",
+            ),
+            "repairs.read",
+        )
+        self.assertEqual(
+            required_api_permission(
+                "GET",
+                f"/api/repairs/{repair_id}/events",
+            ),
+            "repairs.read",
+        )
+        self.assertEqual(
+            required_api_permission("GET", "/api/repairs/queue"),
+            "repairs.view",
+        )
+        self.assertEqual(
+            required_api_permission(
+                "GET",
+                "/api/repairs/parts-summary",
+            ),
+            "repairs.view",
+        )
+        self.assertEqual(
+            required_api_permission("POST", "/api/repairs"),
+            "repairs.create",
+        )
+
+    def test_repair_router_is_registered_after_legacy_static_routes(self):
+        main_path = Path(__file__).parents[1] / "app" / "main.py"
+        source = main_path.read_text(encoding="utf-8")
+        self.assertGreater(
+            source.rfind("app.include_router(repairs_router)"),
+            source.find('@app.get("/api/repairs/parts-summary")'),
+        )
+
+    def test_live_application_repair_route_inventory(self):
+        from app.main import app
+
+        routes = {
+            (method, route.path, route.endpoint.__name__)
+            for route in app.routes
+            if route.path.startswith("/api/repairs")
+            for method in route.methods
+        }
+        self.assertEqual(
+            routes,
+            {
+                ("GET", "/api/repairs/queue", "minerops_repair_queue_api"),
+                (
+                    "POST",
+                    "/api/repairs/{miner_id}/note",
+                    "minerops_repair_add_note_api",
+                ),
+                (
+                    "POST",
+                    "/api/repairs/{miner_id}/status",
+                    "minerops_repair_update_status_api",
+                ),
+                (
+                    "POST",
+                    "/api/repairs/{miner_id}/state",
+                    "minerops_repair_update_state_api",
+                ),
+                (
+                    "GET",
+                    "/api/repairs/parts-summary",
+                    "minerops_repair_parts_summary_api",
+                ),
+                ("POST", "/api/repairs", "begin_repair"),
+                (
+                    "GET",
+                    "/api/repairs/{repair_id}/parts",
+                    "list_repair_parts",
+                ),
+                (
+                    "POST",
+                    "/api/repairs/{repair_id}/parts",
+                    "record_repair_part",
+                ),
+                (
+                    "POST",
+                    "/api/repairs/{repair_id}/parts/{repair_part_id}/void",
+                    "void_repair_part",
+                ),
+                (
+                    "POST",
+                    "/api/repairs/{repair_id}/complete",
+                    "complete_repair",
+                ),
+                ("GET", "/api/repairs/{repair_id}", "get_repair"),
+                (
+                    "GET",
+                    "/api/repairs/{repair_id}/events",
+                    "get_repair_events",
+                ),
+            },
+        )
+
+    def test_static_repair_routes_resolve_before_uuid_detail_route(self):
+        from app.main import app
+
+        for path, endpoint_name in (
+            ("/api/repairs/queue", "minerops_repair_queue_api"),
+            (
+                "/api/repairs/parts-summary",
+                "minerops_repair_parts_summary_api",
+            ),
+        ):
+            with self.subTest(path=path):
+                matches = self.full_route_matches(app, "GET", path)
+                self.assertGreaterEqual(len(matches), 2)
+                self.assertEqual(matches[0].path, path)
+                self.assertEqual(matches[0].endpoint.__name__, endpoint_name)
+                self.assertEqual(matches[1].endpoint.__name__, "get_repair")
+
+    def test_uuid_repair_routes_resolve_to_timeline_handlers(self):
+        from app.main import app
+
+        repair_id = uuid4()
+        for path, endpoint_name in (
+            (f"/api/repairs/{repair_id}", "get_repair"),
+            (
+                f"/api/repairs/{repair_id}/events",
+                "get_repair_events",
+            ),
+        ):
+            with self.subTest(path=path):
+                matches = self.full_route_matches(app, "GET", path)
+                self.assertEqual(len(matches), 1)
+                self.assertEqual(matches[0].endpoint.__name__, endpoint_name)
+
+    def test_repository_event_read_is_one_joined_ordered_query(self):
+        source = inspect.getsource(RepairRepository.get_repair_events)
+        self.assertEqual(source.count("cur.execute("), 1)
+        self.assertIn("JOIN users AS actor", source)
+        self.assertIn("ORDER BY event.sequence ASC", source)
+        for keyword in ("INSERT ", "UPDATE ", "DELETE "):
+            self.assertNotIn(keyword, source.upper())
+
+    def test_service_and_repository_have_no_fastapi_dependency(self):
+        repairs_path = Path(__file__).parents[1] / "app" / "repairs"
+        for filename in ("service.py", "repository.py"):
+            tree = ast.parse(
+                (repairs_path / filename).read_text(encoding="utf-8")
+            )
+            modules = []
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    modules.extend(alias.name for alias in node.names)
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    modules.append(node.module)
+            self.assertFalse(
+                any(
+                    module == "fastapi"
+                    or module.startswith("fastapi.")
+                    for module in modules
+                ),
+                filename,
+            )
+
+    def test_timeline_has_no_mutation_route_or_repository_method(self):
+        methods = {
+            method
+            for route in router.routes
+            if hasattr(route, "methods")
+            for method in route.methods
+        }
+        self.assertNotIn("PATCH", methods)
+        self.assertNotIn("PUT", methods)
+        self.assertNotIn("DELETE", methods)
+        self.assertFalse(hasattr(RepairRepository, "update_repair_event"))
+        self.assertFalse(hasattr(RepairRepository, "delete_repair_event"))
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_repairs_domain.py

@@ -0,0 +1,739 @@
+import ast
+import unittest
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from copy import deepcopy
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import Barrier
+from uuid import UUID, uuid4
+
+from psycopg.errors import RaiseException
+from psycopg.rows import dict_row
+
+from app.repairs import (
+    ActiveRepairConflict,
+    BeginRepairRequest,
+    IncompatibleMinerLifecycle,
+    InconsistentRepairState,
+    RepairActorRequired,
+    RepairMinerNotFound,
+    RepairRepository,
+    RepairService,
+)
+
+
+def repair_row(miner_id, actor_user_id, reason="CONTROL_BOARD"):
+    return {
+        "id": uuid4(),
+        "miner_id": miner_id,
+        "status": "OPEN",
+        "reason": reason,
+        "opened_at": datetime.now(timezone.utc),
+        "opened_by": actor_user_id,
+        "completed_at": None,
+        "completed_by": None,
+    }
+
+
+class FakeRepairRepository:
+    def __init__(self):
+        self.miners = {}
+        self.repairs = []
+        self.events = []
+        self.calls = []
+        self.create_error = None
+        self.event_error = None
+        self.lifecycle_error = None
+
+    @contextmanager
+    def transaction(self):
+        self.calls.append("transaction")
+        snapshot = deepcopy((self.miners, self.repairs, self.events))
+        try:
+            yield self
+        except Exception:
+            self.miners, self.repairs, self.events = snapshot
+            raise
+
+    def lock_miner_for_update(self, miner_id):
+        self.calls.append("lock_miner")
+        return self.miners.get(miner_id)
+
+    def get_active_repair(self, miner_id):
+        self.calls.append("get_active_repair")
+        return next(
+            (
+                repair
+                for repair in self.repairs
+                if repair["miner_id"] == miner_id
+                and repair["status"]
+                in {
+                    "OPEN",
+                    "IN_PROGRESS",
+                    "WAITING_FOR_PARTS",
+                    "READY_FOR_TEST",
+                }
+            ),
+            None,
+        )
+
+    def create_repair(self, miner_id, reason, opened_by):
+        self.calls.append("create_repair")
+        if self.create_error is not None:
+            raise self.create_error
+        row = repair_row(miner_id, opened_by, reason)
+        self.repairs.append(row)
+        return row
+
+    def create_event(
+        self,
+        repair_id,
+        *,
+        sequence,
+        event_type,
+        created_by,
+        payload,
+    ):
+        self.calls.append(f"create_event:{event_type}")
+        if self.event_error is not None:
+            raise self.event_error
+        event = {
+            "id": uuid4(),
+            "repair_id": repair_id,
+            "sequence": sequence,
+            "event_type": event_type,
+            "created_at": datetime.now(timezone.utc),
+            "created_by": created_by,
+            "payload": dict(payload),
+        }
+        self.events.append(event)
+        return event
+
+    def set_miner_lifecycle(self, miner_id, lifecycle_status):
+        self.calls.append("set_miner_lifecycle")
+        if self.lifecycle_error is not None:
+            raise self.lifecycle_error
+        self.miners[miner_id]["lifecycle_status"] = lifecycle_status
+
+
+class RepairServiceTests(unittest.TestCase):
+    def setUp(self):
+        self.repository = FakeRepairRepository()
+        self.service = RepairService(self.repository)
+        self.actor_user_id = uuid4()
+
+    def add_miner(self, lifecycle_status="active"):
+        miner_id = uuid4()
+        self.repository.miners[miner_id] = {
+            "id": miner_id,
+            "lifecycle_status": lifecycle_status,
+        }
+        return miner_id
+
+    def test_begin_repair_creates_record_event_and_lifecycle_atomically(self):
+        miner_id = self.add_miner()
+
+        result = self.service.begin_repair(
+            BeginRepairRequest(
+                miner_id=miner_id,
+                reason="CONTROL_BOARD",
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertEqual(result.miner_id, miner_id)
+        self.assertEqual(result.status, "OPEN")
+        self.assertEqual(result.reason, "CONTROL_BOARD")
+        self.assertEqual(result.opened_by, self.actor_user_id)
+        self.assertEqual(len(self.repository.repairs), 1)
+        self.assertEqual(len(self.repository.events), 1)
+        self.assertEqual(
+            self.repository.events[0]["event_type"],
+            "REPAIR_STARTED",
+        )
+        self.assertEqual(
+            self.repository.events[0]["payload"],
+            {
+                "reason": "CONTROL_BOARD",
+                "from_lifecycle": "active",
+                "to_lifecycle": "in_repair",
+            },
+        )
+        self.assertEqual(
+            self.repository.miners[miner_id]["lifecycle_status"],
+            "in_repair",
+        )
+        self.assertEqual(
+            self.repository.calls,
+            [
+                "transaction",
+                "lock_miner",
+                "get_active_repair",
+                "create_repair",
+                "create_event:REPAIR_STARTED",
+                "set_miner_lifecycle",
+            ],
+        )
+
+    def test_begin_repair_normalizes_and_records_initial_note(self):
+        miner_id = self.add_miner("spare")
+
+        self.service.begin_repair(
+            BeginRepairRequest(
+                miner_id=miner_id,
+                reason="INSPECTION",
+                notes="  Check fan harness.  ",
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertEqual(
+            [event["event_type"] for event in self.repository.events],
+            ["REPAIR_STARTED", "INITIAL_NOTE"],
+        )
+        self.assertEqual(
+            [event["sequence"] for event in self.repository.events],
+            [1, 2],
+        )
+        self.assertEqual(
+            self.repository.events[0]["payload"],
+            {
+                "reason": "INSPECTION",
+                "from_lifecycle": "spare",
+                "to_lifecycle": "in_repair",
+            },
+        )
+        self.assertEqual(
+            self.repository.events[1]["payload"],
+            {"note": "Check fan harness."},
+        )
+
+    def test_absent_and_blank_notes_create_no_note_event(self):
+        for note in (None, " \t\n "):
+            with self.subTest(note=note):
+                repository = FakeRepairRepository()
+                miner_id = uuid4()
+                repository.miners[miner_id] = {
+                    "id": miner_id,
+                    "lifecycle_status": "active",
+                }
+                RepairService(repository).begin_repair(
+                    BeginRepairRequest(
+                        miner_id=miner_id,
+                        reason="OTHER",
+                        notes=note,
+                    ),
+                    actor_user_id=self.actor_user_id,
+                )
+                self.assertEqual(len(repository.events), 1)
+
+    def test_unknown_miner_raises_not_found_without_writes(self):
+        with self.assertRaises(RepairMinerNotFound):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=uuid4(),
+                    reason="OTHER",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+        self.assertEqual(self.repository.repairs, [])
+        self.assertEqual(self.repository.events, [])
+
+    def test_active_repair_conflict_prevents_partial_changes(self):
+        miner_id = self.add_miner()
+        self.repository.repairs.append(
+            repair_row(miner_id, self.actor_user_id)
+        )
+        snapshot = deepcopy(self.repository.repairs)
+
+        with self.assertRaises(ActiveRepairConflict):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="PSU",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+
+        self.assertEqual(self.repository.repairs, snapshot)
+        self.assertEqual(self.repository.events, [])
+        self.assertEqual(
+            self.repository.miners[miner_id]["lifecycle_status"],
+            "active",
+        )
+
+    def test_in_repair_without_active_record_is_inconsistent(self):
+        miner_id = self.add_miner("in_repair")
+        with self.assertRaises(InconsistentRepairState):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+
+    def test_incompatible_lifecycle_is_rejected(self):
+        miner_id = self.add_miner("retired")
+        with self.assertRaises(IncompatibleMinerLifecycle):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+
+    def test_actor_is_required_before_transaction_starts(self):
+        miner_id = self.add_miner()
+        with self.assertRaises(RepairActorRequired):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                ),
+                actor_user_id=None,
+            )
+        self.assertEqual(self.repository.calls, [])
+
+    def test_repository_domain_conflict_propagates(self):
+        miner_id = self.add_miner()
+        self.repository.create_error = ActiveRepairConflict(miner_id)
+        with self.assertRaises(ActiveRepairConflict):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+
+    def test_event_failure_rolls_back_every_change(self):
+        miner_id = self.add_miner()
+        self.repository.event_error = RuntimeError("event failed")
+        with self.assertRaisesRegex(RuntimeError, "event failed"):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+        self.assertEqual(self.repository.repairs, [])
+        self.assertEqual(self.repository.events, [])
+        self.assertEqual(
+            self.repository.miners[miner_id]["lifecycle_status"],
+            "active",
+        )
+
+    def test_lifecycle_failure_rolls_back_repair_and_events(self):
+        miner_id = self.add_miner()
+        self.repository.lifecycle_error = RuntimeError("lifecycle failed")
+        with self.assertRaisesRegex(RuntimeError, "lifecycle failed"):
+            self.service.begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                    notes="Initial note",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+        self.assertEqual(self.repository.repairs, [])
+        self.assertEqual(self.repository.events, [])
+        self.assertEqual(
+            self.repository.miners[miner_id]["lifecycle_status"],
+            "active",
+        )
+
+
+class RepairRepositoryIntegrationTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.repository = RepairRepository()
+        cls.actor_user_id = UUID(
+            "00000000-0000-0000-0000-000000001101"
+        )
+
+    def setUp(self):
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    "DROP TRIGGER IF EXISTS test_repair_event_failure "
+                    "ON repair_events"
+                )
+                cur.execute(
+                    "DROP TRIGGER IF EXISTS test_repair_lifecycle_failure "
+                    "ON miners"
+                )
+                cur.execute(
+                    "DROP FUNCTION IF EXISTS test_fail_repair_event()"
+                )
+                cur.execute(
+                    "DROP FUNCTION IF EXISTS test_fail_repair_lifecycle()"
+                )
+                cur.execute("ALTER TABLE repair_events DISABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repair_events")
+                cur.execute("ALTER TABLE repair_events ENABLE TRIGGER trg_protect_repair_event_history")
+                cur.execute("DELETE FROM repairs")
+                cur.execute("DELETE FROM miner_tags")
+                cur.execute("DELETE FROM miner_asset_id_history")
+                cur.execute("DELETE FROM miners")
+                cur.execute(
+                    "DELETE FROM users "
+                    "WHERE username = 'repair-domain-test'"
+                )
+                cur.execute(
+                    """
+                    INSERT INTO users (
+                        id, username, display_name, password_hash, role_id
+                    )
+                    SELECT %s, %s, %s, %s, id
+                    FROM roles
+                    WHERE name = 'Admin'
+                    """,
+                    (
+                        self.actor_user_id,
+                        "repair-domain-test",
+                        "Repair Domain Test",
+                        "not-used",
+                    ),
+                )
+
+    def create_miner(self, lifecycle_status="active"):
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    INSERT INTO miners (
+                        asset_tag,
+                        status,
+                        lifecycle_status,
+                        first_seen_at,
+                        last_seen_at
+                    )
+                    VALUES (%s, 'unknown', %s, NULL, NULL)
+                    RETURNING id
+                    """,
+                    (f"REPAIR-{uuid4()}", lifecycle_status),
+                )
+                return cur.fetchone()["id"]
+
+    def fetch_events(self, repair_id):
+        with self.repository._connection_scope() as connection:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT *
+                    FROM repair_events
+                    WHERE repair_id = %s
+                    ORDER BY sequence
+                    """,
+                    (repair_id,),
+                )
+                return [dict(row) for row in cur.fetchall()]
+
+    def count_repairs(self, miner_id):
+        with self.repository._connection_scope() as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    "SELECT COUNT(*) FROM repairs WHERE miner_id = %s",
+                    (miner_id,),
+                )
+                return cur.fetchone()[0]
+
+    def lifecycle(self, miner_id):
+        with self.repository._connection_scope() as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    "SELECT lifecycle_status FROM miners WHERE id = %s",
+                    (miner_id,),
+                )
+                return cur.fetchone()[0]
+
+    def test_begin_repair_persists_actor_reason_timestamp_and_started_event(self):
+        miner_id = self.create_miner()
+        before = datetime.now(timezone.utc)
+
+        result = RepairService(self.repository).begin_repair(
+            BeginRepairRequest(
+                miner_id=miner_id,
+                reason="HASHBOARD",
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertGreaterEqual(result.opened_at, before)
+        self.assertEqual(result.opened_by, self.actor_user_id)
+        self.assertEqual(result.reason, "HASHBOARD")
+        self.assertEqual(result.status, "OPEN")
+        self.assertEqual(self.lifecycle(miner_id), "in_repair")
+        active = self.repository.get_active_repair(miner_id)
+        self.assertEqual(active["id"], result.repair_id)
+        events = self.fetch_events(result.repair_id)
+        self.assertEqual(len(events), 1)
+        self.assertEqual(events[0]["event_type"], "REPAIR_STARTED")
+        self.assertEqual(events[0]["sequence"], 1)
+        self.assertEqual(events[0]["created_by"], self.actor_user_id)
+        self.assertIsNotNone(events[0]["created_at"])
+        self.assertEqual(
+            events[0]["payload"],
+            {
+                "reason": "HASHBOARD",
+                "from_lifecycle": "active",
+                "to_lifecycle": "in_repair",
+            },
+        )
+
+    def test_initial_note_is_normalized_and_ordered_after_started_event(self):
+        miner_id = self.create_miner("spare")
+        result = RepairService(self.repository).begin_repair(
+            BeginRepairRequest(
+                miner_id=miner_id,
+                reason="INSPECTION",
+                notes="  Inspect harness.  ",
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+
+        events = self.fetch_events(result.repair_id)
+        self.assertEqual(
+            [(event["sequence"], event["event_type"]) for event in events],
+            [(1, "REPAIR_STARTED"), (2, "INITIAL_NOTE")],
+        )
+        self.assertEqual(
+            events[0]["payload"],
+            {
+                "reason": "INSPECTION",
+                "from_lifecycle": "spare",
+                "to_lifecycle": "in_repair",
+            },
+        )
+        self.assertEqual(events[1]["payload"], {"note": "Inspect harness."})
+
+    def test_database_rejects_duplicate_active_repair(self):
+        miner_id = self.create_miner()
+        service = RepairService(self.repository)
+        service.begin_repair(
+            BeginRepairRequest(miner_id=miner_id, reason="FAN"),
+            actor_user_id=self.actor_user_id,
+        )
+
+        with self.assertRaises(ActiveRepairConflict):
+            self.repository.create_repair(
+                miner_id,
+                "PSU",
+                self.actor_user_id,
+            )
+        self.assertEqual(self.count_repairs(miner_id), 1)
+
+    def test_repairs_are_isolated_by_miner(self):
+        first_miner = self.create_miner()
+        second_miner = self.create_miner()
+        service = RepairService(self.repository)
+
+        first = service.begin_repair(
+            BeginRepairRequest(
+                miner_id=first_miner,
+                reason="LOW_HASHRATE",
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+        second = service.begin_repair(
+            BeginRepairRequest(
+                miner_id=second_miner,
+                reason="NETWORKING",
+            ),
+            actor_user_id=self.actor_user_id,
+        )
+
+        self.assertNotEqual(first.repair_id, second.repair_id)
+        self.assertEqual(
+            self.repository.get_active_repair(first_miner)["id"],
+            first.repair_id,
+        )
+        self.assertEqual(
+            self.repository.get_active_repair(second_miner)["id"],
+            second.repair_id,
+        )
+
+    def test_event_insertion_failure_rolls_back_repair_and_lifecycle(self):
+        miner_id = self.create_miner()
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    CREATE FUNCTION test_fail_repair_event()
+                    RETURNS trigger AS $$
+                    BEGIN
+                        RAISE EXCEPTION 'forced repair event failure';
+                    END;
+                    $$ LANGUAGE plpgsql
+                    """
+                )
+                cur.execute(
+                    """
+                    CREATE TRIGGER test_repair_event_failure
+                    BEFORE INSERT ON repair_events
+                    FOR EACH ROW EXECUTE FUNCTION test_fail_repair_event()
+                    """
+                )
+
+        with self.assertRaises(RaiseException):
+            RepairService(self.repository).begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+
+        self.assertEqual(self.count_repairs(miner_id), 0)
+        self.assertEqual(self.lifecycle(miner_id), "active")
+
+    def test_lifecycle_failure_rolls_back_repair_and_events(self):
+        miner_id = self.create_miner()
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    CREATE FUNCTION test_fail_repair_lifecycle()
+                    RETURNS trigger AS $$
+                    BEGIN
+                        IF NEW.lifecycle_status = 'in_repair' THEN
+                            RAISE EXCEPTION 'forced lifecycle failure';
+                        END IF;
+                        RETURN NEW;
+                    END;
+                    $$ LANGUAGE plpgsql
+                    """
+                )
+                cur.execute(
+                    """
+                    CREATE TRIGGER test_repair_lifecycle_failure
+                    BEFORE UPDATE ON miners
+                    FOR EACH ROW
+                    EXECUTE FUNCTION test_fail_repair_lifecycle()
+                    """
+                )
+
+        with self.assertRaises(RaiseException):
+            RepairService(self.repository).begin_repair(
+                BeginRepairRequest(
+                    miner_id=miner_id,
+                    reason="OTHER",
+                    notes="Must roll back.",
+                ),
+                actor_user_id=self.actor_user_id,
+            )
+
+        self.assertEqual(self.count_repairs(miner_id), 0)
+        self.assertEqual(self.lifecycle(miner_id), "active")
+
+    def test_simultaneous_requests_create_only_one_active_repair(self):
+        miner_id = self.create_miner()
+        barrier = Barrier(2)
+
+        def begin(reason):
+            barrier.wait()
+            return RepairService(RepairRepository()).begin_repair(
+                BeginRepairRequest(miner_id=miner_id, reason=reason),
+                actor_user_id=self.actor_user_id,
+            )
+
+        outcomes = []
+        with ThreadPoolExecutor(max_workers=2) as executor:
+            futures = [
+                executor.submit(begin, "PSU"),
+                executor.submit(begin, "FAN"),
+            ]
+            for future in futures:
+                try:
+                    outcomes.append(future.result(timeout=10))
+                except ActiveRepairConflict as exc:
+                    outcomes.append(exc)
+
+        self.assertEqual(
+            sum(not isinstance(item, Exception) for item in outcomes),
+            1,
+        )
+        self.assertEqual(
+            sum(isinstance(item, ActiveRepairConflict) for item in outcomes),
+            1,
+        )
+        self.assertEqual(self.count_repairs(miner_id), 1)
+        self.assertEqual(self.lifecycle(miner_id), "in_repair")
+
+    def test_repairs_create_permission_matrix_and_idempotent_seed(self):
+        with self.repository._connection_scope(write=True) as connection:
+            with connection.cursor() as cur:
+                cur.execute(
+                    """
+                    INSERT INTO permissions (key, description)
+                    VALUES (
+                        'repairs.create',
+                        'Begin repairs for miner assets'
+                    )
+                    ON CONFLICT (key) DO UPDATE
+                    SET description = EXCLUDED.description
+                    """
+                )
+                cur.execute(
+                    """
+                    INSERT INTO role_permissions (role_id, permission_id)
+                    SELECT roles.id, permissions.id
+                    FROM roles
+                    JOIN permissions
+                      ON permissions.key = 'repairs.create'
+                    WHERE roles.name IN (
+                        'Admin', 'Manager', 'Technician'
+                    )
+                    ON CONFLICT DO NOTHING
+                    """
+                )
+                cur.execute(
+                    """
+                    SELECT roles.name
+                    FROM role_permissions
+                    JOIN roles ON roles.id = role_permissions.role_id
+                    JOIN permissions
+                      ON permissions.id = role_permissions.permission_id
+                    WHERE permissions.key = 'repairs.create'
+                    ORDER BY roles.name
+                    """
+                )
+                role_names = [row[0] for row in cur.fetchall()]
+
+        self.assertEqual(
+            role_names,
+            ["Admin", "Manager", "Technician"],
+        )
+
+
+class RepairArchitectureTests(unittest.TestCase):
+    def test_service_and_repository_have_no_fastapi_dependency(self):
+        repairs_path = Path(__file__).parents[1] / "app" / "repairs"
+        for filename in ("service.py", "repository.py"):
+            tree = ast.parse(
+                (repairs_path / filename).read_text(encoding="utf-8")
+            )
+            imported_modules = []
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    imported_modules.extend(
+                        alias.name for alias in node.names
+                    )
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    imported_modules.append(node.module)
+            self.assertFalse(
+                any(
+                    module == "fastapi"
+                    or module.startswith("fastapi.")
+                    for module in imported_modules
+                ),
+                filename,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

backend/tests/test_repairs_router.py

@@ -0,0 +1,279 @@
+import ast
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.identity import get_current_user
+from app.repairs.dependencies import get_repair_service
+from app.repairs.exceptions import (
+    ActiveRepairConflict,
+    IncompatibleMinerLifecycle,
+    InconsistentRepairState,
+    RepairMinerNotFound,
+)
+from app.repairs.models import (
+    BeginRepairRequest,
+    BeginRepairResult,
+)
+from app.repairs.router import router
+
+
+class StubRepairService:
+    def __init__(self):
+        self.result = None
+        self.error = None
+        self.request = None
+        self.actor_user_id = None
+
+    def begin_repair(
+        self,
+        request: BeginRepairRequest,
+        *,
+        actor_user_id: UUID,
+    ) -> BeginRepairResult:
+        self.request = request
+        self.actor_user_id = actor_user_id
+        if self.error is not None:
+            raise self.error
+        if self.result is None:
+            raise AssertionError("result was not configured")
+        return self.result
+
+
+def repair_result(
+    miner_id=None,
+    actor_user_id=None,
+) -> BeginRepairResult:
+    return BeginRepairResult(
+        repair_id=uuid4(),
+        miner_id=miner_id or uuid4(),
+        status="OPEN",
+        reason="CONTROL_BOARD",
+        opened_at=datetime(2026, 7, 29, 12, 0, tzinfo=timezone.utc),
+        opened_by=actor_user_id or uuid4(),
+    )
+
+
+class RepairRouterTests(unittest.TestCase):
+    def setUp(self):
+        self.service = StubRepairService()
+        self.app = FastAPI()
+        self.app.include_router(router)
+        self.app.dependency_overrides[get_repair_service] = (
+            lambda: self.service
+        )
+        self.client = TestClient(self.app)
+        self.actor_user_id = uuid4()
+
+    def tearDown(self):
+        self.client.close()
+
+    def authenticate(self, permissions=("repairs.create",)):
+        self.app.dependency_overrides[get_current_user] = lambda: {
+            "id": str(self.actor_user_id),
+            "username": "technician",
+            "role": "Technician",
+            "permissions": list(permissions),
+        }
+
+    def test_begin_repair_requires_authentication(self):
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": str(uuid4()),
+                "reason": "CONTROL_BOARD",
+            },
+        )
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["detail"], "Login required")
+
+    def test_begin_repair_requires_repairs_create(self):
+        self.authenticate(permissions=("repairs.view", "repairs.manage"))
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": str(uuid4()),
+                "reason": "CONTROL_BOARD",
+            },
+        )
+        self.assertEqual(response.status_code, 403)
+        self.assertIsNone(self.service.request)
+
+    def test_malformed_miner_uuid_returns_validation_error(self):
+        self.authenticate()
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": "not-a-uuid",
+                "reason": "CONTROL_BOARD",
+            },
+        )
+        self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.request)
+
+    def test_invalid_reason_returns_validation_error(self):
+        self.authenticate()
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": str(uuid4()),
+                "reason": "FREE_FORM_REASON",
+            },
+        )
+        self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.request)
+
+    def test_unknown_miner_returns_not_found(self):
+        self.authenticate()
+        miner_id = uuid4()
+        self.service.error = RepairMinerNotFound(miner_id)
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": str(miner_id),
+                "reason": "OTHER",
+            },
+        )
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.json()["detail"], "Miner not found")
+
+    def test_active_repair_returns_conflict(self):
+        self.authenticate()
+        miner_id = uuid4()
+        self.service.error = ActiveRepairConflict(miner_id)
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": str(miner_id),
+                "reason": "PSU",
+            },
+        )
+        self.assertEqual(response.status_code, 409)
+        self.assertIn("active repair", response.json()["detail"])
+
+    def test_lifecycle_conflicts_return_conflict(self):
+        self.authenticate()
+        miner_id = uuid4()
+        for error in (
+            IncompatibleMinerLifecycle(miner_id, "retired"),
+            InconsistentRepairState(miner_id),
+        ):
+            with self.subTest(error=error):
+                self.service.error = error
+                response = self.client.post(
+                    "/api/repairs",
+                    json={
+                        "miner_id": str(miner_id),
+                        "reason": "OTHER",
+                    },
+                )
+                self.assertEqual(response.status_code, 409)
+
+    def test_success_returns_typed_envelope_and_authenticated_actor(self):
+        self.authenticate()
+        miner_id = uuid4()
+        expected = repair_result(miner_id, self.actor_user_id)
+        self.service.result = expected
+
+        response = self.client.post(
+            "/api/repairs",
+            json={
+                "miner_id": str(miner_id),
+                "reason": "CONTROL_BOARD",
+                "notes": "Miner will not boot.",
+            },
+        )
+
+        self.assertEqual(response.status_code, 201)
+        body = response.json()
+        self.assertEqual(body["data"]["repair_id"], str(expected.repair_id))
+        self.assertEqual(body["data"]["miner_id"], str(miner_id))
+        self.assertEqual(body["data"]["status"], "OPEN")
+        self.assertEqual(body["data"]["reason"], "CONTROL_BOARD")
+        self.assertEqual(body["data"]["opened_by"], str(self.actor_user_id))
+        self.assertEqual(
+            body["data"]["opened_at"],
+            "2026-07-29T12:00:00Z",
+        )
+        self.assertEqual(body["meta"], {})
+        self.assertIsNone(body["error"])
+        self.assertEqual(self.service.actor_user_id, self.actor_user_id)
+        self.assertEqual(
+            self.service.request.notes,
+            "Miner will not boot.",
+        )
+
+    def test_client_cannot_override_server_fields_or_actor(self):
+        self.authenticate()
+        base = {
+            "miner_id": str(uuid4()),
+            "reason": "OTHER",
+        }
+        forbidden = {
+            "repair_id": str(uuid4()),
+            "status": "COMPLETED",
+            "opened_at": "2026-01-01T00:00:00Z",
+            "opened_by": str(uuid4()),
+            "event_id": str(uuid4()),
+            "event_timestamp": "2026-01-01T00:00:00Z",
+            "event_actor": str(uuid4()),
+            "lifecycle_status": "retired",
+        }
+        for field, value in forbidden.items():
+            with self.subTest(field=field):
+                response = self.client.post(
+                    "/api/repairs",
+                    json={**base, field: value},
+                )
+                self.assertEqual(response.status_code, 422)
+        self.assertIsNone(self.service.request)
+
+    def test_router_registers_exact_begin_repair_route(self):
+        routes = [
+            (route.path, route.methods)
+            for route in router.routes
+            if hasattr(route, "methods")
+            and "POST" in route.methods
+            and route.path == "/api/repairs"
+        ]
+        self.assertEqual(routes, [("/api/repairs", {"POST"})])
+
+    def test_router_has_no_sql_driver_or_transaction_management(self):
+        router_path = (
+            Path(__file__).parents[1] / "app" / "repairs" / "router.py"
+        )
+        source = router_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        imported_modules = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imported_modules.extend(alias.name for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                imported_modules.append(node.module)
+
+        database_modules = ("psycopg", "asyncpg", "sqlalchemy")
+        self.assertFalse(
+            any(
+                module == name or module.startswith(f"{name}.")
+                for module in imported_modules
+                for name in database_modules
+            )
+        )
+        upper_source = source.upper()
+        for keyword in (
+            "SELECT ",
+            "INSERT ",
+            "UPDATE ",
+            "DELETE ",
+            ".COMMIT(",
+            ".ROLLBACK(",
+        ):
+            self.assertNotIn(keyword, upper_source)
+
+
+if __name__ == "__main__":
+    unittest.main()

branding/BRANDING.md

@@ -0,0 +1,111 @@
+# MinerOps Brand Guidelines
+
+## Brand Position
+
+MinerOps is practical infrastructure for operators who need a clear, reliable
+view of mining assets, repairs, locations, and controls. The identity should
+feel precise, capable, and built for daily engineering work.
+
+Primary tagline:
+
+> The self-hosted operating system for cryptocurrency mining operations.
+
+Secondary tagline:
+
+> Know every miner. Track every repair. Control every rack.
+
+## Branding Philosophy
+
+- **Operational clarity:** Prefer direct language, strong hierarchy, and
+  purposeful visual elements.
+- **Engineering confidence:** Use measured geometry, consistent spacing, and
+  restrained color.
+- **Self-hosted independence:** Present MinerOps as dependable infrastructure
+  owned and controlled by its operator.
+- **Human utility:** Keep the identity approachable and readable without
+  becoming playful or ornamental.
+
+## Logo System
+
+The MinerOps mark combines a geometric hexagon with an angular letter M. The
+hexagon suggests infrastructure, modular systems, and engineered hardware. The
+M creates immediate product recognition.
+
+Available placeholders:
+
+- `logo.svg`: Primary mark for general use.
+- `logo-light.svg`: Navy and orange mark for light backgrounds.
+- `logo-dark.svg`: White and orange mark for dark backgrounds.
+- `favicon.svg`: Compact filled mark optimized for small sizes.
+- `wordmark.svg`: Symbol paired with the MinerOps name.
+
+Use the supplied artwork without changing its proportions, stroke weights, or
+relative colors. Do not rotate, skew, outline, add effects, or place the mark
+inside another shape. Do not use gradients.
+
+## Clear Space
+
+Maintain clear space around the logo equal to at least one quarter of the
+mark's width. For the wordmark, use the hexagon's internal margin as the
+minimum clear space on every side.
+
+Recommended minimum sizes:
+
+- Standalone logo: 24 px digital, 8 mm print.
+- Wordmark: 120 px digital, 32 mm print.
+- Favicon: 16 px digital.
+
+## Wordmark Usage
+
+Use the wordmark when the audience needs explicit product identification, such
+as documentation covers, sign-in screens, repository graphics, and event
+materials. Use the standalone mark where MinerOps is already named nearby or
+space is limited.
+
+Keep `Miner` in Miner Navy or White and `Ops` in Ops Orange. Do not alter the
+capitalization or insert a space between the words.
+
+## Typography
+
+Recommended interface and brand typefaces:
+
+1. **Inter:** Primary choice for user interfaces, documentation, and marketing
+   copy.
+2. **IBM Plex Sans:** Alternative for a more technical editorial voice.
+3. **IBM Plex Mono:** Recommended for asset IDs, IP addresses, serial numbers,
+   logs, and other machine-oriented data.
+
+Use system sans-serif fallbacks when these fonts are unavailable. Favor medium
+or semibold weights for headings and regular weight for body copy. Avoid
+condensed, decorative, or rounded display type.
+
+## Spacing
+
+Use a 4 px base spacing unit for digital products. Preferred increments are
+4, 8, 12, 16, 24, 32, 48, and 64 px. Align logo placement, typography, and
+supporting elements to a consistent grid.
+
+Brand compositions should have enough open space to feel calm and technical.
+Avoid crowding the mark with borders, controls, or dense copy.
+
+## Icon Usage
+
+Use simple outline icons with consistent stroke weight and square optical
+bounds. Icons should describe actions or system states, not serve as
+decoration. Use filled icons sparingly for selected or critical states.
+
+Prefer Miner Navy or Steel Gray for neutral icons, Ops Orange for active
+emphasis, and semantic colors defined by the product design system for status
+and alerts.
+
+Do not force unrelated interface icons into the hexagonal logo enclosure. The
+hexagon-and-M combination is reserved for the MinerOps brand.
+
+## Tagline Usage
+
+Use the primary tagline for formal product positioning and first introductions.
+Use the secondary tagline for compact campaign copy, presentation endings, or
+operator-focused material.
+
+Taglines should appear as supporting copy and should not be locked permanently
+to the logo artwork. Preserve the exact wording and punctuation shown above.

branding/colors.md

@@ -0,0 +1,40 @@
+# MinerOps Color Palette
+
+## Core Colors
+
+| Color | Hex | Intended usage |
+| --- | --- | --- |
+| Miner Navy | `#0F172A` | Primary brand color, headings, navigation, dark surfaces, and the main logo structure |
+| Ops Orange | `#F97316` | Active emphasis, calls to action, selected states, and the M or Ops accent |
+| Steel Gray | `#475569` | Secondary text, neutral icons, borders, metadata, and supporting UI elements |
+| Light Gray | `#E2E8F0` | Dividers, subtle borders, disabled surfaces, and light neutral backgrounds |
+| White | `#FFFFFF` | Content surfaces, reversed text, and logo details on dark backgrounds |
+
+## Usage Principles
+
+- Use Miner Navy as the primary visual anchor.
+- Reserve Ops Orange for meaningful emphasis rather than large background
+  fields.
+- Use Steel Gray for supporting information that should remain readable without
+  competing with primary content.
+- Use Light Gray to organize interfaces with subtle separation.
+- Use White to preserve clarity and contrast on dark or dense surfaces.
+- Do not introduce gradients into core brand artwork.
+- Check text and control combinations for accessible contrast before production
+  use.
+
+## Common Combinations
+
+| Context | Background | Foreground or accent |
+| --- | --- | --- |
+| Standard light surface | White | Miner Navy with Ops Orange emphasis |
+| Subtle light surface | Light Gray | Miner Navy or Steel Gray |
+| Primary dark surface | Miner Navy | White with Ops Orange emphasis |
+| Neutral metadata | White or Light Gray | Steel Gray |
+| Active control | Ops Orange | Miner Navy or White after contrast review |
+
+## Color Proportions
+
+For general brand compositions, use neutral surfaces and Miner Navy for most of
+the visual area. Ops Orange should typically occupy the smallest share and
+signal action, focus, or product identity.

branding/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">MinerOps favicon</title>
+  <path fill="#0F172A" d="M32 2 59 17.5v29L32 62 5 46.5v-29L32 2Z"/>
+  <path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="7" d="M18 44V21l14 14 14-14v23"/>
+</svg>

branding/logo-dark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">MinerOps logo for dark backgrounds</title>
+  <path fill="#FFFFFF" d="M32 3 57 17.5v29L32 61 7 46.5v-29L32 3Zm0 6.9L13 20.8v22.4l19 10.9 19-10.9V20.8L32 9.9Z"/>
+  <path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
+</svg>

branding/logo-light.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">MinerOps logo for light backgrounds</title>
+  <path fill="none" stroke="#0F172A" stroke-linejoin="miter" stroke-width="6" d="M32 6.5 54 19v26L32 57.5 10 45V19L32 6.5Z"/>
+  <path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
+</svg>

branding/logo.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">MinerOps logo</title>
+  <path fill="#0F172A" d="M32 3 57 17.5v29L32 61 7 46.5v-29L32 3Zm0 6.9L13 20.8v22.4l19 10.9 19-10.9V20.8L32 9.9Z"/>
+  <path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
+</svg>

branding/wordmark.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 72" role="img" aria-labelledby="title">
+  <title id="title">MinerOps wordmark</title>
+  <g transform="translate(4 4) scale(.95)">
+    <path fill="#0F172A" d="M32 3 57 17.5v29L32 61 7 46.5v-29L32 3Zm0 6.9L13 20.8v22.4l19 10.9 19-10.9V20.8L32 9.9Z"/>
+    <path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
+  </g>
+  <text x="76" y="49" fill="#0F172A" font-family="Inter, IBM Plex Sans, Arial, sans-serif" font-size="42" font-weight="700">Miner</text>
+  <text x="188" y="49" fill="#F97316" font-family="Inter, IBM Plex Sans, Arial, sans-serif" font-size="42" font-weight="700">Ops</text>
+</svg>

compose.dev.yaml

@@ -0,0 +1,105 @@
+name: minerops-dev
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    volumes:
+      - postgres-dev:/var/lib/postgresql/data
+    networks:
+      - dev
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+
+  redis:
+    image: redis:7-alpine
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis-dev:/data
+    networks:
+      - dev
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+
+  backend:
+    build:
+      context: ./backend
+    env_file:
+      - .env.dev
+    command:
+      - /bin/sh
+      - -ec
+      - alembic upgrade head && exec uvicorn app.main:app --host 0.0.0.0 --port 8000
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - dev
+    read_only: true
+    tmpfs:
+      - /tmp
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+    healthcheck:
+      test:
+        - CMD
+        - python
+        - -c
+        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/health', timeout=3)"
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
+  gateway:
+    image: nginx:1.29-alpine
+    depends_on:
+      backend:
+        condition: service_healthy
+    ports:
+      - "${MINEROPS_DEV_PORT:-18000}:8080"
+    networks:
+      - dev
+      - edge
+    volumes:
+      - ./dev/nginx.conf:/etc/nginx/nginx.conf:ro
+    read_only: true
+    tmpfs:
+      - /tmp
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+    user: "101:101"
+    healthcheck:
+      test:
+        - CMD
+        - wget
+        - --quiet
+        - --spider
+        - http://127.0.0.1:8080/api/health
+      interval: 10s
+      timeout: 5s
+      retries: 12
+
+networks:
+  dev:
+    internal: true
+  edge:
+
+volumes:
+  postgres-dev:
+  redis-dev: