feat: add safe miner control foundation

backend/app/miner_control/models.py

@@ -0,0 +1,85 @@
+"""Typed contracts for miner control capabilities and operations."""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+
+ControlAction = Literal["suspend", "resume", "performance_mode"]
+CapabilityState = Literal["supported", "unavailable", "unknown"]
+QueueStatus = Literal["pending", "claimed", "completed", "failed", "cancelled"]
+VerificationStatus = Literal[
+    "confirmed", "verification_failed", "unconfirmed", "unavailable"
+]
+PerformanceMode = Literal["low", "normal", "high"]
+
+
+class EmptyControlRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class PerformanceModeRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mode: PerformanceMode
+
+
+class ControlCapability(BaseModel):
+    state: CapabilityState
+    reason: str | None = None
+
+
+class ControlAgentAvailability(BaseModel):
+    state: CapabilityState
+    reason: str | None = None
+    last_checkin_at: AwareDatetime | None = None
+    version: str | None = None
+
+
+class MinerControlOperation(BaseModel):
+    operation_id: str
+    miner_id: UUID
+    action: ControlAction
+    requested_value: str | None = None
+    status: QueueStatus
+    verification_status: VerificationStatus | None = None
+    command_accepted: bool | None = None
+    observed_performance_mode: PerformanceMode | None = None
+    failure_code: str | None = None
+    created_at: AwareDatetime
+    claimed_at: AwareDatetime | None = None
+    completed_at: AwareDatetime | None = None
+
+
+class MinerControlProjection(BaseModel):
+    miner_id: UUID
+    runtime_state: str | None = None
+    performance_mode: PerformanceMode | None = None
+    agent: ControlAgentAvailability
+    service_control: ControlCapability
+    performance_mode_control: ControlCapability
+    available_service_action: Literal["suspend", "resume"] | None = None
+    recent_operations: list[MinerControlOperation]
+
+
+class MinerControlResponse(BaseModel):
+    data: MinerControlProjection
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class MinerControlAccepted(BaseModel):
+    operation_id: str
+    miner_id: UUID
+    action: ControlAction
+    requested_value: str | None = None
+    status: Literal["pending"]
+    created_at: datetime
+
+
+class MinerControlAcceptedResponse(BaseModel):
+    data: MinerControlAccepted
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None