squash me: add docstrings

Author: emnoor-reef

validator/app/src/compute_horde_validator/validator/organic_jobs/miner_driver_sync.py

@@ -268,6 +268,22 @@ class DriverState(Enum):
 
 
 class SyncOrganicJobDriver:
+    """
+    Drives an organic job through its lifecycle via a state machine.
+
+    State flow:
+        CONNECT → RESERVE_EXECUTOR → WAIT_JOB_ACCEPTED → SEND_JOB_ACCEPTED_RECEIPT
+        → WAIT_EXECUTOR_READY → PREPARE_VOLUMES → WAIT_VOLUMES_READY
+        → [WAIT_STREAMING_JOB_READY] → WAIT_EXECUTION_DONE → COLLECT_RESULTS → COMPLETE
+
+    Any state can transition to FAILED if an error occurs or a timeout is reached.
+    The WAIT_STREAMING_JOB_READY state is only entered for streaming jobs.
+
+    The driver communicates with the miner via MinerClient and reports status updates
+    to the facilitator via the status_callback. Receipts are created and persisted
+    at key points (job started, accepted, finished) for the receipts protocol.
+    """
+
     def __init__(
         self,
         miner_client: MinerClient,
@@ -505,9 +521,16 @@ def _wait_for_message(
         timeout_status_reason: HordeFailureReason,
     ) -> _MinerMsgT | DriverState:
         """
-        Waits for a specific message type from the miner within a given timeout period.
-        Returns the received message if successful.
-        Returns a terminal DriverState if the timeout is reached or if an error message is received.
+        Waits for a specific message type from the miner within a timeout.
+
+        Returns either:
+        - The expected message type on success
+        - DriverState.FAILED if timeout/error occurs (job is marked failed, events recorded)
+
+        Handles protocol-level errors (GenericError, UnauthorizedError) and job-level
+        failures (V0DeclineJobRequest, V0JobFailedRequest, V0HordeFailedRequest) by
+        transitioning to the FAILED state. Ignores manifest requests and messages
+        for other jobs.
         """
         deadline = time.time() + timeout
         while True:
@@ -607,6 +630,10 @@ def _wait_for_message(
             )
 
     def run(self) -> None:
+        """
+        Execute the job lifecycle. Handles exceptions by marking the job as failed
+        and always ensures cleanup (sending failure receipt, undoing allowance, closing connection).
+        """
         try:
             self._run()
         except Exception as exc:
@@ -685,6 +712,10 @@ def _undo_allowance_if_failed(self) -> None:
             )
 
     def _run(self) -> None:
+        """
+        Main state machine loop. Each iteration executes the handler for the current
+        state, which returns the next state. Terminates when COMPLETE or FAILED.
+        """
         while True:
             match self._state:
                 case DriverState.CONNECT: