trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/urls.py

@@ -0,0 +1,217 @@
+"""Root URL configuration."""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.contrib import admin
+from django.urls import include, path
+from drf_spectacular.utils import extend_schema, inline_serializer
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerSplitView
+from rest_framework import serializers
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import AllowAny
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from trueppm_api.apps.observability.views import readyz
+from trueppm_api.core.auth_views import (
+    CookieTokenLogoutView,
+    CookieTokenObtainPairView,
+    CookieTokenRefreshView,
+)
+from trueppm_api.core.password_reset import (
+    PasswordResetConfirmView,
+    PasswordResetRequestView,
+)
+
+
+@extend_schema(
+    summary="Liveness probe",
+    description=(
+        'Returns HTTP 200 with `{"status": "ok"}` when the API process is running. '
+        "No authentication required. Use for Kubernetes liveness/readiness probes."
+    ),
+    responses={200: inline_serializer("HealthResponse", {"status": serializers.CharField()})},
+    auth=[],
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def health(_request: Request) -> Response:
+    return Response({"status": "ok"})
+
+
+@extend_schema(
+    summary="Running edition",
+    description=(
+        'Returns `{"edition": "community" | "enterprise"}` from the TRUEPPM_EDITION '
+        "Django setting. No authentication required. The React shell calls this once "
+        "at startup to decide the post-login redirect target (ADR-0029, ADR-0030).\n\n"
+        "Also carries the deployment's read-only demo mode (ADR-1197 D3/D4): "
+        "`demo_read_only` is always present, and `demo_login_hint` carries the "
+        "published shared credential when — and only when — that mode is on.\n\n"
+        "`demo_access_gate` names an external identity gate (e.g. Cloudflare Access) "
+        "the operator has declared in front of a demo host, so the app can disclose "
+        "that the visitor's email was collected before they reached it (#3969, "
+        "ADR-1197 D8). It is an operator **assertion** — nothing verifies it — and, "
+        "like the login hint, it is emitted only while `demo_read_only` is on.\n\n"
+        "`demo_reset_schedule` (#4152) carries the reset CronJob's own cron "
+        "expression, so the shell can state the cadence ('resets daily at 08:00 "
+        "UTC') from the value that actually drives the reset rather than a "
+        "hardcoded number. `null` when the reset is disabled or `demo_read_only` "
+        "is false."
+    ),
+    responses={
+        200: inline_serializer(
+            "EditionResponse",
+            {
+                "edition": serializers.CharField(),
+                "version": serializers.CharField(),
+                "build_sha": serializers.CharField(allow_blank=True),
+                "demo_read_only": serializers.BooleanField(),
+                "demo_login_hint": inline_serializer(
+                    "DemoLoginHint",
+                    {
+                        "username": serializers.CharField(),
+                        "password": serializers.CharField(),
+                    },
+                    allow_null=True,
+                    required=False,
+                ),
+                "demo_access_gate": inline_serializer(
+                    "DemoAccessGate",
+                    {
+                        "provider": serializers.CharField(),
+                        "privacy_url": serializers.CharField(allow_null=True),
+                    },
+                    allow_null=True,
+                    required=False,
+                ),
+                "demo_reset_schedule": serializers.CharField(allow_null=True, required=False),
+            },
+        )
+    },
+    auth=[],
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def edition(request: Request) -> Response:
+    """Return the running edition — community or enterprise.
+
+    Public endpoint (no auth required). The React shell calls this once at
+    startup to decide the post-login redirect target (ADR-0029, ADR-0030).
+    The value is controlled by the TRUEPPM_EDITION Django setting, which the
+    enterprise Helm chart sets to "enterprise".
+
+    Also the pre-login channel for the read-only demo mode (ADR-1197 D3/D4). It is
+    the only endpoint the shell already calls unauthenticated, so the login screen
+    can learn the deployment's mode without a second discovery route — and the
+    post-login shell reads the same cached response.
+    """
+    demo_read_only = bool(getattr(settings, "DEMO_READ_ONLY", False))
+    return Response(
+        {
+            "edition": settings.TRUEPPM_EDITION,
+            # Build identity (#2392): a bug report has to name the exact build it
+            # came from, and this is the one endpoint the shell already calls at
+            # startup without auth. `build_sha` is empty on a source checkout.
+            "version": settings.TRUEPPM_VERSION,
+            "build_sha": settings.TRUEPPM_BUILD_SHA,
+            # Always emitted, so a client can distinguish "not a demo" from "a server
+            # too old to say" without inferring it from an absent key.
+            "demo_read_only": demo_read_only,
+            # Gated on the MODE, not merely on the setting being present: the hint is
+            # a published credential, and an operator who leaves the variable set after
+            # turning the demo off must not keep broadcasting it from a live install.
+            "demo_login_hint": (
+                getattr(settings, "DEMO_LOGIN_HINT", None) if demo_read_only else None
+            ),
+            # Gated on the MODE for the same reason as the hint above, plus one of its
+            # own: on a normal install this would tell any unauthenticated caller what
+            # sits at the edge, which is free fingerprinting with no visitor benefit —
+            # an employee signing in through their own company's IdP is not owed a
+            # notice about it. The disclosure #3969 asks for is owed to a *demo*
+            # visitor, who had no relationship with this deployment before the gate
+            # took their email.
+            "demo_access_gate": (
+                getattr(settings, "DEMO_ACCESS_GATE", None) if demo_read_only else None
+            ),
+            # Gated on the MODE for the same reason as the hint and the access gate:
+            # a leftover TRUEPPM_DEMO_RESET_SCHEDULE on a normal install must not
+            # announce a reset cadence that does not apply to it (#4152).
+            "demo_reset_schedule": (
+                getattr(settings, "DEMO_RESET_SCHEDULE", None) if demo_read_only else None
+            ),
+        }
+    )
+
+
+# Versioned prefix every app router mounts under.
+_API_V1_PREFIX = "api/v1/"
+
+urlpatterns = [
+    path("api/v1/health/", health, name="health"),
+    # Dependency-aware readiness probe (#1894). Unauthenticated like /health/ so
+    # kubelet can call it, but returns 503 when the DB or cache is unreachable —
+    # unlike /health/, which is a shallow process-liveness check.
+    path("api/v1/readyz", readyz, name="readyz"),
+    path("api/v1/edition/", edition, name="edition"),
+    path("admin/", admin.site.urls),
+    # OpenAPI schema and interactive docs. The *split* Swagger view (not the
+    # default inline one) is required by our strict CSP: it delivers the UI
+    # bootstrap as a separate same-origin JS request instead of an inline
+    # <script>, which script-src 'self' would otherwise block (the page rendered
+    # blank — #1603). Asset bundles are served from drf-spectacular-sidecar
+    # ('self') via SWAGGER_UI_DIST=SIDECAR in settings.
+    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+    path("api/docs/", SpectacularSwaggerSplitView.as_view(url_name="schema"), name="swagger-ui"),
+    path(
+        "api/schema/swagger-ui/",
+        SpectacularSwaggerSplitView.as_view(url_name="schema"),
+        name="swagger-ui-compat",
+    ),
+    # JWT auth endpoints (#897). Login returns the access token in the body and
+    # sets the refresh token in an httpOnly cookie; refresh reads that cookie;
+    # logout clears it (and blacklists the token if the blacklist app is present).
+    path("api/v1/auth/token/", CookieTokenObtainPairView.as_view(), name="token_obtain_pair"),
+    path("api/v1/auth/token/refresh/", CookieTokenRefreshView.as_view(), name="token_refresh"),
+    path("api/v1/auth/logout/", CookieTokenLogoutView.as_view(), name="token_logout"),
+    # Self-service password reset (#765, ADR-0209). Both AllowAny + throttled with a
+    # dedicated "password_reset" scope. Request always returns 200 (no user
+    # enumeration); confirm validates a stateless token, sets the password, and
+    # revokes all of the account's other sessions.
+    path(
+        "api/v1/auth/password/reset/",
+        PasswordResetRequestView.as_view(),
+        name="password_reset",
+    ),
+    path(
+        "api/v1/auth/password/reset/confirm/",
+        PasswordResetConfirmView.as_view(),
+        name="password_reset_confirm",
+    ),
+    # Versioned API
+    path(_API_V1_PREFIX, include("trueppm_api.apps.access.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.projects.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.resources.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.scheduling.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.sync.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.history.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.msproject.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.jiraimport.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.csvimport.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.webhooks.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.taskruns.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.notifications.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.integrations.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.observability.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.workspace.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.teams.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.timetracking.urls")),
+    # Basic SSO — OIDC relying party (ADR-0187). Flow endpoints under
+    # auth/oidc/*, admin config under workspace/sso/*.
+    path(_API_V1_PREFIX, include("trueppm_api.apps.sso.urls")),
+    # Team-readable agent-action audit log (ADR-0112 RC1, #1805).
+    path(_API_V1_PREFIX, include("trueppm_api.apps.agents.urls")),
+]

trueppm_api/workflows/__init__.py

@@ -0,0 +1,38 @@
+"""TruePPM workflow execution — the single public import surface (ADR-0080).
+
+Workflow consumer code imports only from this package: the service functions to
+drive workflows and the value types to describe them. It must never import a
+backend, ``celery``, ``dbos``, or ``temporalio`` (ADR-0080 §E).
+"""
+
+from trueppm_api.workflows.interface import (
+    HistoryEvent,
+    RetryPolicy,
+    WorkflowState,
+    WorkflowStatus,
+)
+from trueppm_api.workflows.services import (
+    cancel_workflow,
+    get_history,
+    get_workflow_state,
+    query_workflow,
+    run_activity,
+    signal_workflow,
+    sleep,
+    start_workflow,
+)
+
+__all__ = [
+    "HistoryEvent",
+    "RetryPolicy",
+    "WorkflowState",
+    "WorkflowStatus",
+    "cancel_workflow",
+    "get_history",
+    "get_workflow_state",
+    "query_workflow",
+    "run_activity",
+    "signal_workflow",
+    "sleep",
+    "start_workflow",
+]

trueppm_api/workflows/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Workflow backend implementations.
+
+The default outbox-composing backend lands in ``default.py`` (ADR-0080 §A); a
+DBOS backend follows as the second OSS backend in 1.0. Backends are resolved by
+``trueppm_api.workflows.services.get_backend`` and never imported by consumer code.
+"""

trueppm_api/workflows/backends/default.py

@@ -0,0 +1,297 @@
+"""Default workflow backend — outbox-composing, Celery-driven (ADR-0080 §A, §D).
+
+Executes a declarative :class:`~trueppm_api.workflows.registry.WorkflowDefinition`
+step-by-step. Each step-advance writes a ``WorkflowOutboxRow`` in the same
+transaction as the state change and dispatches it via ``transaction.on_commit``,
+so a broker outage between commit and dispatch cannot drop a step — the
+``workflows_outbox_drain`` Beat task re-dispatches stranded rows. Activities are
+once-and-only-once at ``(workflow, activity_name, input_hash)``, which makes the
+backend safe under the outbox's at-least-once delivery.
+
+This module is a backend implementation, not consumer code — it may import
+Django and (lazily) Celery. The shared engine helpers live here so the step task
+(:mod:`trueppm_api.apps.workflow_engine.tasks`) can reuse them without a circular import.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import logging
+from collections.abc import Iterator
+from contextvars import ContextVar
+from datetime import timedelta
+from typing import Any
+
+from django.db import transaction
+from django.db.models import Max
+from django.utils import timezone
+
+from trueppm_api.apps.workflow_engine.models import (
+    WorkflowActivityExecution,
+    WorkflowHistoryEvent,
+    WorkflowInstance,
+    WorkflowOutboxRow,
+    WorkflowOutboxStatus,
+    WorkflowSignal,
+    WorkflowStatus,
+    WorkflowTimer,
+)
+from trueppm_api.workflows.interface import (
+    HistoryEvent,
+    RetryPolicy,
+    WorkflowBackend,
+    WorkflowState,
+)
+from trueppm_api.workflows.interface import (
+    WorkflowStatus as IWorkflowStatus,
+)
+from trueppm_api.workflows.registry import WORKFLOWS, Activity, WorkflowDefinition
+
+logger = logging.getLogger(__name__)
+
+_TERMINAL_STATUSES = frozenset(
+    {WorkflowStatus.COMPLETED, WorkflowStatus.FAILED, WorkflowStatus.CANCELED}
+)
+
+# Ambient "currently-executing workflow" id, set by the step task while an
+# activity runs so that run_activity() (called from within an activity) can
+# resolve its workflow without an explicit id. The codebase otherwise threads
+# context explicitly; this is the one place an implicit handle is warranted, and
+# it is confined to the default backend's execution window.
+_current_workflow_id: ContextVar[str | None] = ContextVar(
+    "trueppm_current_workflow_id", default=None
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared engine helpers (used here and by the step task)
+# ---------------------------------------------------------------------------
+
+
+def canonical_hash(obj: Any) -> str:
+    """Stable SHA-256 of a JSON-able object — order-independent for dicts."""
+    encoded = json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(encoded.encode()).hexdigest()
+
+
+def default_idempotency_key(name: str, workflow_input: dict[str, Any]) -> str:
+    """Deterministic start-dedup key: a retried start of the same name+input
+    collides on ``WorkflowInstance.idempotency_key`` and returns the original."""
+    return canonical_hash({"name": name, "input": workflow_input})
+
+
+def record_history(
+    instance: WorkflowInstance, event_type: str, payload: dict[str, Any]
+) -> WorkflowHistoryEvent:
+    """Append an ordered history event. Must be called while holding the
+    instance row lock so the per-workflow ``seq`` is allocated race-free."""
+    last_seq = WorkflowHistoryEvent.objects.filter(workflow=instance).aggregate(m=Max("seq"))["m"]
+    seq = 0 if last_seq is None else last_seq + 1
+    return WorkflowHistoryEvent.objects.create(
+        workflow=instance, seq=seq, event_type=event_type, payload=payload
+    )
+
+
+@contextlib.contextmanager
+def workflow_context(workflow_id: str) -> Iterator[None]:
+    """Bind the ambient workflow id for the duration of a step execution."""
+    token = _current_workflow_id.set(workflow_id)
+    try:
+        yield
+    finally:
+        _current_workflow_id.reset(token)
+
+
+def step_context(instance: WorkflowInstance) -> dict[str, Any]:
+    """The dict every step activity receives: the workflow input plus the
+    results of all previously-completed activities, keyed by activity name."""
+    prior = {
+        execution.activity_name: execution.result
+        for execution in WorkflowActivityExecution.objects.filter(workflow=instance).exclude(
+            result=None
+        )
+    }
+    return {"workflow_input": instance.input, "prior": prior}
+
+
+def run_activity_oaoo(
+    instance: WorkflowInstance,
+    activity_name: str,
+    activity_input: dict[str, Any],
+    activity: Activity,
+) -> dict[str, Any] | None:
+    """Execute an activity once-and-only-once.
+
+    A prior successful execution (matching ``(workflow, activity_name,
+    input_hash)``) returns its recorded result without re-running the side
+    effect. Callers must hold the instance row lock so two redelivered copies of
+    the same step cannot both execute the activity.
+    """
+    input_hash = canonical_hash(activity_input)
+    execution, created = WorkflowActivityExecution.objects.get_or_create(
+        workflow=instance, activity_name=activity_name, input_hash=input_hash
+    )
+    if not created and execution.result is not None:
+        cached: dict[str, Any] | None = execution.result
+        return cached
+    result = activity(activity_input)
+    execution.result = result
+    execution.save(update_fields=["result"])
+    return result
+
+
+def enqueue_step(instance_id: str, step_index: int) -> None:
+    """Write a step-advance outbox row and best-effort dispatch it.
+
+    Mirrors ``scheduling.services.enqueue_recalculate``: the row is the durable
+    record, the immediate ``.delay()`` is best-effort, and ``workflows_outbox_drain``
+    re-dispatches if the broker is down. Dispatch is deferred to
+    ``transaction.on_commit`` so the row is committed before the task reads it.
+    """
+    row = WorkflowOutboxRow.objects.create(
+        workflow_id=instance_id,
+        step_name=str(step_index),
+        step_input={"step_index": step_index},
+    )
+
+    def _dispatch() -> None:
+        from trueppm_api.apps.workflow_engine.tasks import advance_workflow_step
+
+        try:
+            result = advance_workflow_step.delay(str(row.id))
+        except Exception:
+            logger.exception(
+                "enqueue_step: immediate dispatch failed for outbox row %s "
+                "— workflows_outbox_drain will retry",
+                row.id,
+            )
+            return
+        WorkflowOutboxRow.objects.filter(id=row.id, status=WorkflowOutboxStatus.PENDING).update(
+            status=WorkflowOutboxStatus.DISPATCHED,
+            celery_task_id=result.id,
+            dispatched_at=timezone.now(),
+        )
+
+    transaction.on_commit(_dispatch)
+
+
+def resolve_activity(
+    definition: WorkflowDefinition, instance: WorkflowInstance, activity_name: str
+) -> Activity:
+    """Find the activity callable for ``activity_name`` in the workflow's chain."""
+    for step in definition.build_steps(instance.input):
+        if step.name == activity_name:
+            return step.activity
+    raise KeyError(f"workflow {instance.name!r} has no activity named {activity_name!r}")
+
+
+# ---------------------------------------------------------------------------
+# Backend
+# ---------------------------------------------------------------------------
+
+
+class DefaultWorkflowBackend(WorkflowBackend):
+    """The v1 OSS workflow backend: declarative chains over outbox + Celery."""
+
+    def start_workflow(
+        self,
+        name: str,
+        input: dict[str, Any],
+        *,
+        idempotency_key: str | None = None,
+        wait_for_completion: bool = False,
+    ) -> str:
+        if wait_for_completion:
+            raise NotImplementedError(
+                "the default backend is fire-and-forget; wait_for_completion is not "
+                "supported. Poll get_workflow_state() instead."
+            )
+        # Fail fast if the workflow name is not registered, before creating state.
+        WORKFLOWS.get(name)
+        key = idempotency_key or default_idempotency_key(name, input)
+        with transaction.atomic():
+            instance, created = WorkflowInstance.objects.get_or_create(
+                idempotency_key=key,
+                defaults={"name": name, "input": input, "status": WorkflowStatus.RUNNING},
+            )
+            if created:
+                record_history(instance, "workflow_started", {"input": input})
+                enqueue_step(str(instance.id), 0)
+        return str(instance.id)
+
+    def signal_workflow(self, workflow_id: str, signal: str, payload: dict[str, Any]) -> None:
+        # Durably record the signal in the inbox and history. v1 chains do not
+        # yet gate steps on signals; the inbox is what makes that a later,
+        # non-breaking addition (a step can drain unconsumed signals).
+        with transaction.atomic():
+            instance = WorkflowInstance.objects.select_for_update().get(id=workflow_id)
+            WorkflowSignal.objects.create(workflow=instance, signal_name=signal, payload=payload)
+            record_history(instance, "signal_received", {"signal": signal, "payload": payload})
+
+    def query_workflow(self, workflow_id: str, query: str, args: dict[str, Any]) -> Any:
+        instance = WorkflowInstance.objects.get(id=workflow_id)
+        return WORKFLOWS.get(instance.name).on_query(query, args)
+
+    def get_workflow_state(self, workflow_id: str) -> WorkflowState:
+        instance = WorkflowInstance.objects.get(id=workflow_id)
+        return WorkflowState(
+            workflow_id=str(instance.id),
+            name=instance.name,
+            status=IWorkflowStatus(instance.status),
+            result=instance.result,
+            error=instance.error,
+            created_at=instance.created_at,
+            updated_at=instance.updated_at,
+            completed_at=instance.completed_at,
+        )
+
+    def cancel_workflow(self, workflow_id: str, reason: str = "") -> None:
+        with transaction.atomic():
+            instance = WorkflowInstance.objects.select_for_update().get(id=workflow_id)
+            if instance.status in _TERMINAL_STATUSES:
+                return  # already finished — cancellation is a no-op
+            instance.status = WorkflowStatus.CANCELED
+            instance.cancel_reason = reason
+            instance.completed_at = timezone.now()
+            instance.save(update_fields=["status", "cancel_reason", "completed_at", "updated_at"])
+            record_history(instance, "workflow_canceled", {"reason": reason})
+
+    def sleep(self, workflow_id: str, duration: timedelta) -> None:
+        with transaction.atomic():
+            instance = WorkflowInstance.objects.select_for_update().get(id=workflow_id)
+            fire_at = timezone.now() + duration
+            WorkflowTimer.objects.create(workflow=instance, fire_at=fire_at)
+            if instance.status == WorkflowStatus.RUNNING:
+                instance.status = WorkflowStatus.SLEEPING
+                instance.save(update_fields=["status", "updated_at"])
+            record_history(instance, "sleep_started", {"fire_at": fire_at.isoformat()})
+
+    def run_activity(
+        self, name: str, input: dict[str, Any], retry_policy: RetryPolicy | None = None
+    ) -> Any:
+        # retry_policy is reserved: v1 derives retry from at-least-once outbox
+        # redelivery plus OAOO idempotency, not from a per-activity policy.
+        workflow_id = _current_workflow_id.get()
+        if workflow_id is None:
+            raise RuntimeError(
+                "run_activity() must be called within a workflow step execution; "
+                "no ambient workflow context is set."
+            )
+        instance = WorkflowInstance.objects.get(id=workflow_id)
+        activity = resolve_activity(WORKFLOWS.get(instance.name), instance, name)
+        return run_activity_oaoo(instance, name, input, activity)
+
+    def get_history(self, workflow_id: str) -> list[HistoryEvent]:
+        return [
+            HistoryEvent(
+                seq=event.seq,
+                event_type=event.event_type,
+                payload=event.payload,
+                occurred_at=event.created_at,
+            )
+            for event in WorkflowHistoryEvent.objects.filter(workflow__id=workflow_id).order_by(
+                "seq"
+            )
+        ]

trueppm_api/workflows/consumers/__init__.py

@@ -0,0 +1,11 @@
+"""Registered workflow definitions (ADR-0080 §A, §E).
+
+Consumer workflows author *what* runs as a declarative ``WorkflowDefinition``
+chain and register it against the ``WORKFLOWS`` registry from an
+``AppConfig.ready()``. Per ADR-0080 §E, consumer modules must not import an
+engine (``celery``, ``dbos``, ``temporalio``) directly — side effects go through
+a domain service, which is the only layer allowed to touch the engine. That keeps
+workflow authoring backend-neutral.
+"""
+
+from __future__ import annotations

trueppm_api/workflows/consumers/requeue_failed_task.py

@@ -0,0 +1,65 @@
+"""Requeue-failed-task workflow — the first consumer of the durable backend (ADR-0210).
+
+An operator requeue of a dead-lettered Celery task must round-trip through the
+#652 outbox-composing workflow backend (ADR-0080), *not* the raw
+``current_app.send_task`` side channel it replaces. This single-step workflow is
+how it does so: starting it via ``workflows.services.start_workflow`` writes a
+``WorkflowOutboxRow`` inside the request transaction and dispatches on
+``transaction.on_commit``; if the broker is down the ``workflows_outbox_drain``
+Beat task re-dispatches it, so the re-enqueue is durable.
+
+The one step, ``redispatch``, re-enqueues the original task. Per ADR-0080 §E this
+consumer module never imports Celery directly — it delegates the actual
+``send_task`` to ``scheduling.services.redispatch_dead_lettered_task``, the domain
+service that owns the engine boundary. The operator-chosen backoff is applied there
+as a Celery ``countdown`` (ADR-0210 §2: v1 has no chain-resuming durable ``sleep``,
+so the *delay* is best-effort while the *re-enqueue* is durable via the outbox).
+
+The activity is executed once-and-only-once by the engine (unique
+``(workflow, activity_name, input_hash)``), so an at-least-once outbox redelivery
+cannot double-dispatch the original task.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from trueppm_api.workflows.registry import WorkflowDefinition, WorkflowStep
+
+WORKFLOW_NAME = "scheduling.requeue_failed_task"
+
+
+def _redispatch_activity(ctx: dict[str, Any]) -> dict[str, Any] | None:
+    """Re-enqueue the original Celery task with the operator's backoff.
+
+    ``ctx`` is the engine-supplied step context: ``ctx["workflow_input"]`` holds the
+    requeue input assembled by the viewset. Delegates to the scheduling service so
+    this consumer stays free of a direct Celery import (ADR-0080 §E).
+    """
+    # Imported lazily and from the service layer (not `celery`) to honour the
+    # consumer import discipline; the service owns the `send_task` boundary.
+    from trueppm_api.apps.scheduling.services import redispatch_dead_lettered_task
+
+    wf_input = ctx["workflow_input"]
+    dispatched_task_id = redispatch_dead_lettered_task(
+        task_name=wf_input["task_name"],
+        args=wf_input.get("args", []),
+        kwargs=wf_input.get("kwargs", {}),
+        countdown=int(wf_input.get("backoff_seconds", 0) or 0),
+    )
+    return {
+        "failed_task_id": wf_input.get("failed_task_id"),
+        "dispatched_task_id": dispatched_task_id,
+    }
+
+
+class RequeueFailedTaskWorkflow(WorkflowDefinition):
+    """One-step workflow that durably re-dispatches a dead-lettered Celery task."""
+
+    name = WORKFLOW_NAME
+
+    def build_steps(self, workflow_input: dict[str, Any]) -> list[WorkflowStep]:
+        # Single step, no compensation: re-enqueueing is the terminal side effect and
+        # there is nothing to undo — if the re-dispatched task fails again it simply
+        # dead-letters back into FailedTask (ADR-0210 §Durable Execution 8).
+        return [WorkflowStep(name="redispatch", activity=_redispatch_activity)]