Expose supported Operator checker recovery

.ci/behavior-ownership/partition.v1.json

@@ -84,6 +84,10 @@
       "group": "shared",
       "target": "backend/app/api/deps/authorization.py"
     },
+    {
+      "group": "artifacts",
+      "target": "backend/app/api/deps/checker_recovery.py"
+    },
     {
       "group": "artifacts",
       "target": "backend/app/api/deps/checker_registry.py"
@@ -592,6 +596,10 @@
       "group": "auth",
       "target": "backend/app/modules/authorization/checker_retry_authorization.py"
     },
+    {
+      "group": "auth",
+      "target": "backend/app/modules/authorization/checker_retry_read.py"
+    },
     {
       "group": "auth",
       "target": "backend/app/modules/authorization/contribution_policy_authorization.py"
@@ -636,6 +644,10 @@
       "group": "auth",
       "target": "backend/app/modules/authorization/domain/checker_retry.py"
     },
+    {
+      "group": "auth",
+      "target": "backend/app/modules/authorization/domain/checker_retry_reads.py"
+    },
     {
       "group": "auth",
       "target": "backend/app/modules/authorization/domain/contribution_policies.py"
@@ -2105,7 +2117,7 @@
       "target": "backend/scripts/validate_test_lane_evidence.py"
     }
   ],
-  "authority_digest": "72ede56f55522908d9102eaad07c05349bc6485c314d8fa9c57631b5e797641b",
+  "authority_digest": "63bd7c5bf88c7ee20bbec0dbcc08359c5e77d7acc79dea93363cf61f9b108c73",
   "protected_base_commit": "7676ce4347db0c9694962a9b587a20765e16eac6",
   "schema": "workstream.behavior-ownership-partition.v1"
 }

backend/app/adapters/auth/__init__.py

@@ -297,6 +297,22 @@ def task_queue_authorization(kernel, secret):
     return TaskQueueReadAuthorization(kernel, secret)
 
 
+def checker_retry_discovery_authorization(session, context, secret):
+    """Compose exact Operator retry-source reads through the shared AUTH kernel."""
+    from app.modules.authorization.checker_retry_read import (
+        CheckerRetryDiscoveryAuthorization,
+    )
+    from app.modules.authorization.kernel import AuthorizationService
+
+    repository = AdminAuthorizationRepository(session)
+    return CheckerRetryDiscoveryAuthorization(
+        AuthorizationService(
+            session, context, admin_repository=repository,
+        ),
+        secret,
+    )
+
+
 def contributor_read_authorization(kernel, session: AsyncSession, secret):
     """Compose the caller's own-work AUTH adapter in the shared decision transaction."""
     from app.modules.authorization.contributor_read import ContributorReadAuthorization

backend/app/adapters/checkers/__init__.py

@@ -281,10 +281,12 @@ def evaluation_coordinator(session) -> EvaluationCoordinationPort:
     return EvaluationCoordinator(session, tasks=evaluation_task_guard(session))
 
 
-def checker_retry_service(session, context):
-    """Compose hidden Operator retry from existing owner operations only."""
+def checker_retry_service(session, context, *, cursor_secret=None):
+    """Compose supported Operator recovery from existing owner operations."""
     from app.adapters.audit import checker_retry_audit
-    from app.adapters.auth import checker_retry_authorization
+    from app.adapters.auth import (
+        checker_retry_authorization, checker_retry_discovery_authorization,
+    )
     from app.adapters.outbox import outbox_append
     from app.adapters.tasks import evaluation_task_guard
     from app.modules.checkers.checker_retry import CheckerRetryService
@@ -295,6 +297,9 @@ def checker_retry_service(session, context):
         session, actor_profile_id=context.actor_profile_id,
         tasks=tasks, evaluations=EvaluationCoordinator(session, tasks=tasks),
         authorization=checker_retry_authorization(session, context),
+        discovery=checker_retry_discovery_authorization(
+            session, context, cursor_secret,
+        ),
         events=outbox_append(session), audit=checker_retry_audit(session),
     )
 

backend/app/api/deps/checker_recovery.py

@@ -0,0 +1,214 @@
+"""HTTP transaction roots for exact Operator checker recovery."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import Depends, Request
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.adapters.checkers import checker_retry_service
+from app.api.deps.auth import get_auth_verification_result
+from app.api.deps.authorization import (
+    AuthorizationDenied,
+    AuthorizationEvidenceUnavailable,
+    ResolvedActor,
+    _authorization_context,
+    get_authorization_actor,
+)
+from app.core.api_controls import StructuredHTTPException, parse_idempotency_key, request_ids
+from app.db.session import get_db_session
+from app.modules.checkers.api.execution import (
+    CheckerExecutionUnavailable,
+    CheckerRequestConflict,
+    CheckerRetryAuthorityDenied,
+    CheckerRetryCommand,
+    CheckerRetryCursorInvalid,
+    CheckerRetryOperationUnavailable,
+    CheckerRetryRequest,
+    CheckerRetryResult,
+    CheckerRetrySourceUnavailable,
+    CheckerRetrySourcePage,
+    CheckerRetrySourceQuery,
+)
+from app.schemas.auth import AuthVerificationResult
+
+
+def require_checker_retry_key(request: Request) -> UUID:
+    """Reject absent, duplicate or malformed retry keys before product mutation."""
+    values = request.headers.getlist("Idempotency-Key")
+    return parse_idempotency_key(values[0] if len(values) == 1 else "")
+
+
+async def require_checker_retry_human(
+    key: Annotated[UUID, Depends(require_checker_retry_key)],
+    result: Annotated[AuthVerificationResult, Depends(get_auth_verification_result)],
+) -> None:
+    """Conceal nonhuman retry callers before resolving product dependencies."""
+    del key
+    if result.token.subject_kind != "human":
+        raise _concealed()
+
+
+def _concealed() -> StructuredHTTPException:
+    return StructuredHTTPException(
+        status_code=404,
+        detail="Checker recovery source not found",
+        error_code="checker_recovery_source_not_found",
+        error_message="Checker recovery source not found",
+    )
+
+
+def _unavailable() -> StructuredHTTPException:
+    return StructuredHTTPException(
+        status_code=503,
+        detail="Checker recovery unavailable",
+        error_code="checker_recovery_unavailable",
+        error_message="Checker recovery unavailable",
+        retryable=True,
+    )
+
+
+class CheckerRetryCommands:
+    """Bind the public selector/body to CHECKERS's existing atomic writer."""
+
+    def __init__(self, session: AsyncSession, service, key: UUID) -> None:
+        self._session, self._service, self._key = session, service, key
+
+    async def retry(
+        self, project_id: UUID, source_run_id: UUID, request: CheckerRetryRequest,
+    ) -> CheckerRetryResult:
+        result = await self._service.retry(CheckerRetryCommand(
+            project_id=project_id,
+            source_run_id=source_run_id,
+            request_key=self._key,
+            reason=request.reason,
+        ))
+        await self._session.commit()
+        return result
+
+
+class CheckerRetryReads:
+    """Authorize, project and commit one exact discovery page."""
+
+    def __init__(self, session: AsyncSession, service) -> None:
+        self._session, self._service = session, service
+
+    async def discover(
+        self, project_id: UUID, *, limit: int, cursor: str | None,
+    ) -> CheckerRetrySourcePage:
+        result = await self._service.discover(CheckerRetrySourceQuery(
+            project_id=project_id, limit=limit, cursor=cursor,
+        ))
+        await self._session.commit()
+        return result
+
+
+@asynccontextmanager
+async def _checker_retry_commands(
+    request: Request,
+    key: UUID,
+    resolved: ResolvedActor,
+    session: AsyncSession,
+) -> AsyncIterator[CheckerRetryCommands]:
+    """Own mutation commit, canonical denial evidence and fail-closed rollback."""
+    context = _authorization_context(resolved, key, key)
+    await session.rollback()
+    service = checker_retry_service(
+        session,
+        context,
+        cursor_secret=request.app.state.settings.pagination_cursor_hmac_secret,
+    )
+    try:
+        await session.begin()
+        yield CheckerRetryCommands(session, service, key)
+    except CheckerRetryAuthorityDenied as exc:
+        await session.rollback()
+        try:
+            if await service.restage_denial(exc):
+                await session.commit()
+        except (AuthorizationEvidenceUnavailable, SQLAlchemyError) as evidence_error:
+            await session.rollback()
+            raise _unavailable() from evidence_error
+        raise _concealed() from exc
+    except CheckerRequestConflict as exc:
+        await session.rollback()
+        raise StructuredHTTPException(
+            status_code=409,
+            detail="Checker retry request conflicts with retained facts",
+            error_code="checker_retry_request_conflict",
+            error_message="Checker retry request conflicts with retained facts",
+        ) from exc
+    except CheckerRetrySourceUnavailable as exc:
+        await session.rollback()
+        raise _concealed() from exc
+    except (
+        CheckerRetryOperationUnavailable,
+        AuthorizationEvidenceUnavailable,
+        SQLAlchemyError,
+    ) as exc:
+        await session.rollback()
+        raise _unavailable() from exc
+    except BaseException:
+        await session.rollback()
+        raise
+    finally:
+        if session.in_transaction():
+            await session.rollback()
+
+
+async def get_checker_retry_commands(
+    request: Request,
+    key: Annotated[UUID, Depends(require_checker_retry_key)],
+    resolved: Annotated[ResolvedActor, Depends(get_authorization_actor)],
+    session: Annotated[AsyncSession, Depends(get_db_session)],
+) -> AsyncIterator[CheckerRetryCommands]:
+    """Forward endpoint failures through the mutation transaction owner."""
+    async with _checker_retry_commands(request, key, resolved, session) as commands:
+        yield commands
+
+
+async def get_checker_retry_reads(
+    request: Request,
+    resolved: Annotated[ResolvedActor, Depends(get_authorization_actor)],
+    session: Annotated[AsyncSession, Depends(get_db_session)],
+) -> AsyncIterator[CheckerRetryReads]:
+    """Own read decision commit and canonical concealed denial evidence."""
+    request_id, correlation_id = (UUID(value) for value in request_ids(request))
+    context = _authorization_context(resolved, request_id, correlation_id)
+    await session.rollback()
+    service = checker_retry_service(
+        session,
+        context,
+        cursor_secret=request.app.state.settings.pagination_cursor_hmac_secret,
+    )
+    try:
+        yield CheckerRetryReads(session, service)
+    except AuthorizationDenied as exc:
+        await session.rollback()
+        try:
+            if await service.restage_discovery_denial(exc):
+                await session.commit()
+        except (AuthorizationEvidenceUnavailable, SQLAlchemyError) as evidence_error:
+            await session.rollback()
+            raise _unavailable() from evidence_error
+        raise _concealed() from exc
+    except CheckerRetryCursorInvalid as exc:
+        await session.rollback()
+        raise StructuredHTTPException(
+            status_code=422,
+            detail="Invalid checker recovery cursor",
+            error_code="validation_error",
+            error_message="Invalid checker recovery cursor",
+        ) from exc
+    except (CheckerExecutionUnavailable, AuthorizationEvidenceUnavailable, SQLAlchemyError) as exc:
+        await session.rollback()
+        raise _unavailable() from exc
+    except BaseException:
+        await session.rollback()
+        raise
+    finally:
+        if session.in_transaction():
+            await session.rollback()

backend/app/modules/authorization/catalogue.py

@@ -205,6 +205,7 @@ class ActionId(StrEnum):
     OPERATIONS_TASK_START_OVERRIDE = "operations.task.start_override"
     OPERATIONS_SUBMISSION_GATE_REPAIR = "operations.submission_gate.repair"
     OPERATIONS_CHECKER_RETRY = "operations.checker.retry"
+    OPERATIONS_CHECKER_RETRY_SOURCE_LIST = "operations.checker_retry_source.list"
     SUBMISSION_CREATE = "submission.create"
     REVIEW_QUEUE_READ = "review.queue.read"
     REVIEW_QUEUE_INSPECT = "review.queue.inspect"
@@ -621,6 +622,11 @@ def _active(
         ActionOwner.AUTH_14,
     ),
     _active(ActionId.OPERATIONS_CHECKER_RETRY, PermissionId.OPERATIONS_CHECKER_RETRY, ActionOwner.AUTH_14),
+    _active(
+        ActionId.OPERATIONS_CHECKER_RETRY_SOURCE_LIST,
+        PermissionId.OPERATIONS_STATUS_READ,
+        ActionOwner.AUTH_14,
+    ),
     _active(
         ActionId.CHECKER_REGISTRY_READ,
         PermissionId.OPERATIONS_STATUS_READ,
@@ -823,7 +829,7 @@ def _active(
 
 def _require_catalogue_counts() -> None:
     """Keep the closed action inventory and permission boundary exact."""
-    if len(PERMISSION_IDS) != 82 or len(ACTION_IDS) != 163:
+    if len(PERMISSION_IDS) != 82 or len(ACTION_IDS) != 164:
         raise RuntimeError("authorization catalogue count mismatch")
     if len(HISTORICAL_PERMISSION_IDS) != 49 or len(NEW_PERMISSION_IDS) != 33:
         raise RuntimeError("authorization permission boundary mismatch")
@@ -973,6 +979,7 @@ def _index_actions(definitions: tuple[ActionDefinition, ...]) -> MappingProxyTyp
         ActionId.TASK_READ, ActionId.TASK_SUBMISSION_REQUIREMENTS_READ,
         ActionId.PROJECT_TASK_READ, ActionId.PROJECT_TASK_SUBMISSION_REQUIREMENTS_READ,
         ActionId.AUDIT_TASK_EVIDENCE_READ, ActionId.OPERATIONS_CHECKER_RETRY,
+        ActionId.OPERATIONS_CHECKER_RETRY_SOURCE_LIST,
     } | TASK_LOCKED_CONTEXT_READ_ACTIONS | HISTORY_READ_ACTIONS:
         raise RuntimeError("authorization active action boundary mismatch")
     _validate_action_definitions(definitions)