US05-04: Verify, Retry, and Resolve Uncertain Uploads (#74)

photo_pipeline/services/upload_batches.py

@@ -16,7 +16,8 @@ cannot undo, so the discipline is:
 - **an interrupted attempt is uncertain, not failed.** Immich may have accepted
   files the app never saw a report for, so ``recover`` marks a batch whose worker
   vanished ``unknown_requires_verification`` (concept §15) instead of retrying it
-  blindly. Resolving that is US05-04.
+  blindly. :func:`~photo_pipeline.services.upload_verification.retry_blockers`
+  (US05-04) is what decides whether an attempt may start at all.
 
 Per-asset upload *results* are not interpreted here: after the attempt ends the
 report is handed to :class:`~photo_pipeline.services.upload_reports.
@@ -40,6 +41,7 @@ from photo_pipeline.integrations import immich_go
 from photo_pipeline.models import UploadBatch, UploadItem
 from photo_pipeline.services.hashing import sha1_file
 from photo_pipeline.services.upload_reports import UploadReportService
+from photo_pipeline.services.upload_verification import retry_blockers
 from photo_pipeline.services.uploads import UploadService
 
 
@@ -62,6 +64,7 @@ RUNNABLE_STATES = frozenset({BatchState.PLANNED, BatchState.FAILED, BatchState.C
 # States whose batch is still the live one for its album.
 OPEN_STATES = frozenset({BatchState.PLANNED, BatchState.RUNNING, BatchState.CANCELLING})
 
+
 class ItemState:
     PENDING = "pending"
     # ``sent`` means the batch process exited cleanly, not that Immich confirmed the
@@ -162,13 +165,11 @@ class UploadBatchService:
     def run(self, batch_id: str, *, worker_id: str = "uploader", cancelled=None) -> dict:
         """Run one batch to completion. Blocks for the duration of the upload."""
         batch = self._require(batch_id)
-        if batch["state"] not in RUNNABLE_STATES:
-            code = (
-                "requires_verification"
-                if batch["state"] == BatchState.UNKNOWN
-                else "not_runnable"
-            )
-            raise BatchError(code, f"batch {batch_id} is {batch['state']}")
+        # Retry policy (US05-04): a safe failure may run again, an uncertain outcome
+        # or bytes edited after upload may not.
+        blocked = retry_blockers(batch)
+        if blocked:
+            raise BatchError(blocked[0]["code"], blocked[0]["message"])
         busy = [row for row in self.list() if row["id"] != batch_id and row["state"] in LANE_STATES]
         if busy:
             raise BatchConflict("lane_busy", f"upload batch {busy[0]['id']} is still running")
@@ -189,9 +190,7 @@ class UploadBatchService:
 
         token = self._claim(batch_id, worker_id=worker_id)
         attempt = self.get(batch_id)["attempt_count"]
-        report_path = (
-            Path(self._config.data_dir) / "uploads" / f"{batch_id}-attempt-{attempt}.log"
-        )
+        report_path = Path(self._config.data_dir) / "uploads" / f"{batch_id}-attempt-{attempt}.log"
         key = self._config.immich_api_key.get_secret_value() if self._config.immich_api_key else ""
         command = immich_go.build_command(
             binary=self._config.immich_go_binary,
@@ -426,6 +425,10 @@ def _batch_dict(row: UploadBatch, items: list[UploadItem]) -> dict:
         "outcome_state": row.outcome_state,
         "outcome_counts": json.loads(row.outcome_counts) if row.outcome_counts else None,
         "report_counts": json.loads(row.report_counts) if row.report_counts else None,
+        # Verification evidence (US05-04). ``stale_bytes`` is the visible warning
+        # that an uploaded file has since been edited.
+        "verified_at": row.verified_at.isoformat() if row.verified_at else None,
+        "stale_bytes": row.stale_bytes,
         "started_at": row.started_at.isoformat() if row.started_at else None,
         "finished_at": row.finished_at.isoformat() if row.finished_at else None,
         "items": [
@@ -438,6 +441,10 @@ def _batch_dict(row: UploadBatch, items: list[UploadItem]) -> dict:
                 "outcome": item.outcome,
                 "evidence": item.evidence,
                 "outcome_at": item.outcome_at.isoformat() if item.outcome_at else None,
+                "verification": item.verification,
+                "verified_at": item.verified_at.isoformat() if item.verified_at else None,
+                "observed_sha256": item.observed_sha256,
+                "changed_after_upload": item.changed_after_upload,
             }
             for item in items
         ],