feat: manage external source lifecycle

apps/api/app/source_lifecycle.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Literal
+
+from sqlalchemy.orm import Session
+
+from .models import ExternalObservation, ModerationStatus
+
+
+SourceCheckStatus = Literal["available", "missing", "temporary_error", "blocked"]
+
+
+def record_source_check(
+    session: Session,
+    observation: ExternalObservation,
+    status: SourceCheckStatus,
+    *,
+    checked_at: datetime | None = None,
+) -> ExternalObservation:
+    """Persist a check performed during an already scheduled source request.
+
+    Only an authoritative 404/410-style ``missing`` result withdraws published
+    data. Transient errors and access blocks remain diagnostic and never remove
+    an observation from activity.
+    """
+    current = checked_at or datetime.now(timezone.utc)
+    observation.source_check_status = status
+    observation.source_checked_at = current
+    if status == "missing" and observation.status != "withdrawn":
+        if observation.catch_report is not None:
+            observation.catch_report.moderation_status = ModerationStatus.pending
+        observation.status = "withdrawn"
+        observation.review_note = "Source record missing; withdrawn pending moderator review"
+        observation.reviewed_at = current
+        observation.moderation_version += 1
+    session.commit()
+    return observation