trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/workflow_engine/models.py

@@ -0,0 +1,265 @@
+"""Persistence layer for the default workflow backend (ADR-0080).
+
+These tables back the outbox-composing default backend. They are deliberately
+NOT synced to mobile clients — workflows are internal infrastructure with no
+REST or sync surface in 0.4 — so none of them inherit ``VersionedModel`` or
+carry ``server_version`` (cf. ``scheduling.ScheduleRequest``).
+
+The state machine composes with the existing transactional outbox (#66):
+advancing a workflow step writes a ``WorkflowOutboxRow`` inside the same
+``transaction.on_commit()`` boundary as the state transition, so a broker
+outage between commit and dispatch cannot drop the step — the drain re-dispatches.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from django.db import models
+
+
+class WorkflowStatus(models.TextChoices):
+    """Lifecycle of a workflow instance."""
+
+    PENDING = "pending", "Pending"
+    RUNNING = "running", "Running"
+    SLEEPING = "sleeping", "Sleeping"
+    COMPLETED = "completed", "Completed"
+    FAILED = "failed", "Failed"
+    CANCELED = "canceled", "Canceled"
+
+
+class WorkflowInstance(models.Model):
+    """A single workflow execution.
+
+    ``idempotency_key`` is globally unique and is the start-dedup mechanism: a
+    retried ``start_workflow`` with the same ``name + input`` produces the same
+    default key (a deterministic hash), collides on this constraint, and the
+    backend returns the existing instance instead of starting a duplicate
+    (once-and-only-once start semantics, ADR-0080 §Implementation Notes 7).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=255, db_index=True)
+    status = models.CharField(
+        max_length=16,
+        choices=WorkflowStatus.choices,
+        default=WorkflowStatus.PENDING,
+    )
+    input = models.JSONField(default=dict)
+    result = models.JSONField(null=True, blank=True)
+    error = models.TextField(blank=True, default="")
+    idempotency_key = models.CharField(max_length=64)
+    cancel_reason = models.CharField(max_length=255, blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    completed_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["idempotency_key"],
+                name="workflow_idempotency_key_uniq",
+            ),
+        ]
+        indexes = [
+            # Drain / dashboard: filter by status, scan oldest-first.
+            models.Index(fields=["status", "created_at"], name="workflow_status_idx"),
+            # Retention sweep of finished instances.
+            models.Index(fields=["completed_at"], name="workflow_completed_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"WorkflowInstance({self.name}, {self.status})"
+
+
+class WorkflowHistoryEvent(models.Model):
+    """Append-only, per-workflow ordered event log.
+
+    Ordered by an explicit monotonic ``seq`` rather than ``created_at``: events
+    written in the same transaction share a timestamp to sub-millisecond
+    precision, and ``get_history`` must return a deterministic order. ``seq``
+    also pre-positions the log for sequence-based replay / gap detection (#321).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    workflow = models.ForeignKey(
+        WorkflowInstance,
+        on_delete=models.CASCADE,
+        related_name="history",
+    )
+    seq = models.BigIntegerField()
+    event_type = models.CharField(max_length=32)
+    payload = models.JSONField(default=dict)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ["workflow_id", "seq"]
+        constraints = [
+            # The unique B-tree on (workflow, seq) also serves the ordered
+            # get_history lookup and the Max(seq) aggregate in record_history, so
+            # no separate (workflow, seq) index is needed — a named one would be
+            # pure write amplification on this hot, every-step-written table.
+            models.UniqueConstraint(
+                fields=["workflow", "seq"],
+                name="workflow_history_seq_uniq",
+            ),
+        ]
+        indexes = [
+            # Retention sweep (30-day default, configurable).
+            models.Index(fields=["created_at"], name="workflow_history_retention_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"WorkflowHistoryEvent({self.workflow_id}, {self.seq}, {self.event_type})"
+
+
+class WorkflowTimer(models.Model):
+    """Backs the first-class ``sleep(workflow_id, duration)`` primitive.
+
+    A Beat task fires due timers (``fired=False, fire_at <= now``) and signals
+    the sleeping workflow to resume. The ``(fired, fire_at)`` composite serves
+    the drain query directly.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    workflow = models.ForeignKey(
+        WorkflowInstance,
+        on_delete=models.CASCADE,
+        related_name="timers",
+    )
+    fire_at = models.DateTimeField()
+    fired = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        indexes = [
+            models.Index(fields=["fired", "fire_at"], name="workflow_timer_due_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"WorkflowTimer({self.workflow_id}, fire_at={self.fire_at:%Y-%m-%d %H:%M})"
+
+
+class WorkflowOutboxStatus(models.TextChoices):
+    """Lifecycle of a workflow step-dispatch outbox row."""
+
+    PENDING = "pending", "Pending"
+    DISPATCHED = "dispatched", "Dispatched"
+    DONE = "done", "Done"
+    DEAD = "dead", "Dead"
+
+
+class WorkflowOutboxRow(models.Model):
+    """Transactional outbox for advancing a workflow step.
+
+    Distinct from the event outbox (#66): the row schema and dispatch target
+    differ — this dispatches a workflow *step*, not an event consumer
+    (ADR-0080 §Implementation Notes 2). Written atomically with the workflow
+    state transition; the ``workflows_outbox_drain`` Beat task re-dispatches
+    ``PENDING`` rows older than the 5-minute orphan window so it never races
+    with an in-flight commit. Rows with ``attempt_count > 0`` are inside
+    Celery's own retry chain and are skipped by the drain (same rule as
+    ``WebhookDelivery``).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    workflow = models.ForeignKey(
+        WorkflowInstance,
+        on_delete=models.CASCADE,
+        related_name="outbox_rows",
+    )
+    step_name = models.CharField(max_length=255)
+    step_input = models.JSONField(default=dict)
+    status = models.CharField(
+        max_length=16,
+        choices=WorkflowOutboxStatus.choices,
+        default=WorkflowOutboxStatus.PENDING,
+    )
+    attempt_count = models.PositiveIntegerField(default=0)
+    celery_task_id = models.CharField(max_length=255, blank=True, default="")
+    created_at = models.DateTimeField(auto_now_add=True)
+    dispatched_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        ordering = ["created_at"]
+        indexes = [
+            models.Index(fields=["status", "created_at"], name="workflow_outbox_drain_idx"),
+            # Orphan recovery: the drain ranges on dispatched_at for DISPATCHED
+            # rows past the recovery window; without dispatched_at as the 2nd
+            # column Postgres post-filters the (status, created_at) scan.
+            models.Index(fields=["status", "dispatched_at"], name="workflow_outbox_recovery_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"WorkflowOutboxRow({self.workflow_id}, {self.step_name}, {self.status})"
+
+
+class WorkflowActivityExecution(models.Model):
+    """Once-and-only-once cache for a workflow activity result.
+
+    The unique ``(workflow, activity_name, input_hash)`` constraint
+    (ADR-0080 §Implementation Notes 7) makes ``run_activity`` idempotent: a
+    replayed activity finds the prior row and returns its stored ``result``
+    rather than re-executing the side effect. Storing the result (not merely
+    detecting the duplicate) is what lets a replaying workflow get its original
+    answer back.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    workflow = models.ForeignKey(
+        WorkflowInstance,
+        on_delete=models.CASCADE,
+        related_name="activity_executions",
+    )
+    activity_name = models.CharField(max_length=255)
+    input_hash = models.CharField(max_length=64)
+    result = models.JSONField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["workflow", "activity_name", "input_hash"],
+                name="workflow_activity_oaoo_uniq",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"WorkflowActivityExecution({self.workflow_id}, {self.activity_name})"
+
+
+class WorkflowSignal(models.Model):
+    """Durable inbox for signals delivered to a workflow.
+
+    Signals can arrive before the workflow reaches the point where it waits for
+    them, so they must be persisted rather than delivered transiently. The
+    backend consumes unconsumed rows (``consumed=False``) in arrival order when
+    a workflow reaches a wait point. Kept as a dedicated table rather than
+    derived from the history log so consumption is a simple indexed query, not a
+    scan-and-reconcile over an append-only stream.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    workflow = models.ForeignKey(
+        WorkflowInstance,
+        on_delete=models.CASCADE,
+        related_name="signals",
+    )
+    signal_name = models.CharField(max_length=255)
+    payload = models.JSONField(default=dict)
+    consumed = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        ordering = ["created_at"]
+        indexes = [
+            # Wait-point lookup: unconsumed signals for a workflow, in arrival order.
+            models.Index(
+                fields=["workflow", "consumed", "created_at"],
+                name="workflow_signal_inbox_idx",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"WorkflowSignal({self.workflow_id}, {self.signal_name}, consumed={self.consumed})"

trueppm_api/apps/workflow_engine/tasks.py

@@ -0,0 +1,371 @@
+"""Celery tasks for the default workflow backend (ADR-0080 §D).
+
+``advance_workflow_step`` is the work task that executes one step of a workflow
+chain: run the step's activity (once-and-only-once), record history, then either
+enqueue the next step's outbox row or finish the workflow. It is dispatched by
+the backend's ``enqueue_step`` and re-dispatched by ``workflows_outbox_drain``.
+
+This module also owns the engine's Beat tasks: ``workflows_outbox_drain``
+(re-dispatch stranded step rows), ``workflows_timer_drain`` (fire due sleep
+timers), and ``purge_old_workflow_records`` (retention).
+
+Idempotency under the outbox's at-least-once delivery comes from two guards: the
+outbox row's terminal-status check (a re-delivered DONE/DEAD row is a no-op) and
+a ``select_for_update`` on the workflow instance that serializes advancement, so
+two copies of the same step cannot run the activity concurrently.
+
+This is backend machinery (it may import Celery), not consumer code — it lives
+in the app, never under ``workflows/consumers/``.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from celery import shared_task
+from celery.exceptions import SoftTimeLimitExceeded
+from django.conf import settings
+from django.db import transaction
+from django.utils import timezone
+
+if TYPE_CHECKING:
+    from django.db.models import QuerySet
+
+from trueppm_api.apps.workflow_engine.models import (
+    WorkflowHistoryEvent,
+    WorkflowInstance,
+    WorkflowOutboxRow,
+    WorkflowOutboxStatus,
+    WorkflowStatus,
+    WorkflowTimer,
+)
+from trueppm_api.core.idempotent import idempotent_task
+from trueppm_api.workflows.backends.default import (
+    _TERMINAL_STATUSES,
+    enqueue_step,
+    record_history,
+    run_activity_oaoo,
+    step_context,
+    workflow_context,
+)
+from trueppm_api.workflows.registry import WORKFLOWS, WorkflowDefinition, WorkflowStep
+
+logger = logging.getLogger(__name__)
+
+_DONE_OR_DEAD = (WorkflowOutboxStatus.DONE, WorkflowOutboxStatus.DEAD)
+
+# Re-dispatch PENDING step rows only once they are older than this, so the drain
+# never races an in-flight enqueue_step on_commit dispatch (ADR-0080 §IN 3). A
+# DISPATCHED row is considered orphaned past the recovery window (worker died
+# before advance_workflow_step's 300 s time_limit), and reset to PENDING.
+_OUTBOX_ORPHAN_WINDOW = timedelta(minutes=5)
+_OUTBOX_RECOVERY_WINDOW = timedelta(minutes=10)
+_OUTBOX_RETENTION = timedelta(days=7)
+
+
+def _mark_row(row: WorkflowOutboxRow, status: str) -> None:
+    WorkflowOutboxRow.objects.filter(id=row.id).update(status=status)
+
+
+def _complete(instance: WorkflowInstance, results: dict[str, Any]) -> None:
+    """Finalize a workflow whose last step just completed.
+
+    ``results`` is the already-aggregated activity output, passed in by the
+    caller, which holds it from the step context it just built — re-querying
+    ``WorkflowActivityExecution`` here would be a redundant scan on the
+    completion path of every workflow.
+    """
+    instance.status = WorkflowStatus.COMPLETED
+    instance.result = results
+    instance.completed_at = timezone.now()
+    instance.save(update_fields=["status", "result", "completed_at", "updated_at"])
+    record_history(instance, "workflow_completed", {"result": results})
+
+
+def _handle_failure(
+    instance: WorkflowInstance,
+    steps: list[WorkflowStep],
+    failed_index: int,
+    exc: Exception,
+) -> None:
+    """Saga rollback: compensate completed steps in reverse, then mark FAILED.
+
+    Compensation is best-effort — a failed rollback is logged but does not stop
+    the others, and never masks the original failure recorded on the instance.
+    Only steps *before* the failed one are compensated; the failed step did not
+    complete its side effect to a recorded result.
+    """
+    context = step_context(instance)
+    for index in range(failed_index - 1, -1, -1):
+        step = steps[index]
+        if step.compensate is None:
+            continue
+        try:
+            step.compensate(context)
+            record_history(instance, "step_compensated", {"step": step.name, "index": index})
+        except Exception:  # TODO(#4421): also swallows SoftTimeLimitExceeded
+            logger.exception(
+                "compensation failed for step %s of workflow %s", step.name, instance.id
+            )
+    instance.status = WorkflowStatus.FAILED
+    instance.error = repr(exc)
+    instance.completed_at = timezone.now()
+    instance.save(update_fields=["status", "error", "completed_at", "updated_at"])
+    record_history(
+        instance, "workflow_failed", {"step": steps[failed_index].name, "error": str(exc)}
+    )
+
+
+def _do_advance(outbox_row_id: str) -> None:
+    """Execute one workflow step. Extracted from the task body so tests can call
+    it directly without a Celery worker (the codebase convention for drains)."""
+    try:
+        row = WorkflowOutboxRow.objects.select_related("workflow").get(id=outbox_row_id)
+    except WorkflowOutboxRow.DoesNotExist:
+        logger.warning("advance_workflow_step: outbox row %s no longer exists", outbox_row_id)
+        return
+    if row.status in _DONE_OR_DEAD:
+        return
+
+    with transaction.atomic():
+        instance = WorkflowInstance.objects.select_for_update().get(id=row.workflow_id)
+        # Re-read the row under the instance lock: a concurrent delivery may have
+        # finished it between our first read and acquiring the lock.
+        row.refresh_from_db()
+        if row.status in _DONE_OR_DEAD:
+            return
+        if instance.status in _TERMINAL_STATUSES:
+            _mark_row(row, WorkflowOutboxStatus.DONE)
+            return
+
+        definition: WorkflowDefinition = WORKFLOWS.get(instance.name)
+        steps = definition.build_steps(instance.input)
+        step_index = int(row.step_input.get("step_index", 0))
+        if step_index >= len(steps):
+            logger.warning(
+                "advance_workflow_step: step_index %s out of range (%s steps) for workflow %s",
+                step_index,
+                len(steps),
+                instance.id,
+            )
+            _mark_row(row, WorkflowOutboxStatus.DONE)
+            return
+
+        step = steps[step_index]
+        if instance.status != WorkflowStatus.RUNNING:
+            instance.status = WorkflowStatus.RUNNING
+            instance.save(update_fields=["status", "updated_at"])
+
+        context = step_context(instance)
+        try:
+            with workflow_context(str(instance.id)):
+                result = run_activity_oaoo(instance, step.name, context, step.activity)
+        except Exception as exc:
+            _handle_failure(instance, steps, step_index, exc)
+            _mark_row(row, WorkflowOutboxStatus.DEAD)
+            return
+
+        record_history(
+            instance,
+            "step_completed",
+            {"step": step.name, "index": step_index, "result": result},
+        )
+        _mark_row(row, WorkflowOutboxStatus.DONE)
+
+        if step_index + 1 < len(steps):
+            enqueue_step(str(instance.id), step_index + 1)
+        else:
+            # The final aggregate is the prior-step results (already fetched into
+            # the step context, excluding None) plus this step's result. Holding
+            # the instance lock, no other step can have written an execution
+            # between step_context() and here, so this reproduces the full scan
+            # without re-querying. None results stay excluded, matching get_state.
+            results = dict(context["prior"])
+            if result is not None:
+                results[step.name] = result
+            _complete(instance, results)
+
+
+@shared_task(  # type: ignore[untyped-decorator]
+    bind=True,
+    name="workflows.advance_step",
+    soft_time_limit=240,
+    time_limit=300,
+    acks_late=True,
+    reject_on_worker_lost=True,
+)
+def advance_workflow_step(self: object, outbox_row_id: str) -> None:
+    """Advance one workflow step. See :func:`_do_advance`.
+
+    ``time_limit`` (300 s) is kept at or below the workflow outbox drain's
+    orphan window so a killed step is dead before the drain re-dispatches its row.
+    """
+    _do_advance(outbox_row_id)
+
+
+# ---------------------------------------------------------------------------
+# Beat tasks: drain, timer fire, retention
+# ---------------------------------------------------------------------------
+
+
+def _do_outbox_drain() -> None:
+    """Re-dispatch stranded step rows and recover orphaned dispatched rows.
+
+    Only PENDING rows older than the orphan window are re-dispatched, so the
+    drain never races an in-flight ``enqueue_step`` ``on_commit`` dispatch.
+    DISPATCHED rows past the recovery window are treated as orphaned (the worker
+    died) and reset to PENDING.
+    """
+    now = timezone.now()
+    recovered = WorkflowOutboxRow.objects.filter(
+        status=WorkflowOutboxStatus.DISPATCHED,
+        dispatched_at__lt=now - _OUTBOX_RECOVERY_WINDOW,
+    ).update(status=WorkflowOutboxStatus.PENDING, celery_task_id="")
+    if recovered:
+        logger.warning("workflows_outbox_drain: recovered %d orphaned dispatched row(s)", recovered)
+
+    pending = list(
+        WorkflowOutboxRow.objects.filter(
+            status=WorkflowOutboxStatus.PENDING,
+            created_at__lt=now - _OUTBOX_ORPHAN_WINDOW,
+        ).order_by("created_at")[: settings.WORKFLOW_DRAIN_BATCH_SIZE]
+    )
+    dispatched = 0
+    for row in pending:
+        try:
+            result = advance_workflow_step.delay(str(row.id))
+        except SoftTimeLimitExceeded:
+            raise
+        except Exception:
+            logger.warning(
+                "workflows_outbox_drain: broker unavailable — row %s stays pending", row.id
+            )
+            continue
+        WorkflowOutboxRow.objects.filter(id=row.id, status=WorkflowOutboxStatus.PENDING).update(
+            status=WorkflowOutboxStatus.DISPATCHED,
+            celery_task_id=result.id,
+            dispatched_at=now,
+        )
+        dispatched += 1
+    if dispatched or recovered:
+        logger.info("workflows_outbox_drain: dispatched=%d recovered=%d", dispatched, recovered)
+
+
+def _do_timer_drain() -> None:
+    """Fire due sleep timers and wake the sleeping workflows.
+
+    v1 records the wake (SLEEPING → RUNNING) durably and marks the timer fired.
+    Re-entering the step chain from a mid-chain sleep is a later enhancement —
+    v1 linear chains do not sleep — so the timer infra is durable without
+    prematurely wiring chain resumption.
+    """
+    now = timezone.now()
+    due = list(
+        WorkflowTimer.objects.filter(fired=False, fire_at__lte=now).order_by("fire_at")[
+            : settings.WORKFLOW_DRAIN_BATCH_SIZE
+        ]
+    )
+    fired = 0
+    for timer in due:
+        with transaction.atomic():
+            instance = WorkflowInstance.objects.select_for_update().get(id=timer.workflow_id)
+            WorkflowTimer.objects.filter(id=timer.id, fired=False).update(fired=True)
+            record_history(instance, "timer_fired", {"timer_id": str(timer.id)})
+            if instance.status == WorkflowStatus.SLEEPING:
+                instance.status = WorkflowStatus.RUNNING
+                instance.save(update_fields=["status", "updated_at"])
+        fired += 1
+    if fired:
+        logger.info("workflows_timer_drain: fired=%d", fired)
+
+
+def _chunked_delete(queryset: QuerySet[Any], batch_size: int) -> int:
+    """Delete every row matching ``queryset`` in bounded ``batch_size`` chunks.
+
+    Each chunk is a separate statement, so the purge never holds a single lock
+    over an unbounded slice of the table — important on the first run of a mature
+    install, where the eligible set can be a large fraction of the table. The
+    filter is re-evaluated per pass, so rows deleted (or newly written) between
+    passes are naturally excluded.
+    """
+    model = queryset.model
+    total = 0
+    while True:
+        batch_ids = list(queryset.values_list("pk", flat=True)[:batch_size])
+        if not batch_ids:
+            break
+        deleted, _ = model.objects.filter(pk__in=batch_ids).delete()
+        total += deleted
+        if len(batch_ids) < batch_size:
+            break
+    return total
+
+
+def _do_purge_workflow_records() -> None:
+    """Delete terminal step rows past 7 days and history past the retention window."""
+    now = timezone.now()
+    batch_size = settings.WORKFLOW_PURGE_BATCH_SIZE
+    outbox_deleted = _chunked_delete(
+        WorkflowOutboxRow.objects.filter(
+            status__in=[WorkflowOutboxStatus.DONE, WorkflowOutboxStatus.DEAD],
+            created_at__lt=now - _OUTBOX_RETENTION,
+        ),
+        batch_size,
+    )
+    history_days = settings.WORKFLOW_HISTORY_RETENTION_DAYS
+    history_deleted = 0
+    if history_days:
+        history_deleted = _chunked_delete(
+            WorkflowHistoryEvent.objects.filter(
+                created_at__lt=now - timedelta(days=history_days),
+            ),
+            batch_size,
+        )
+    logger.info("purge_old_workflow_records: outbox=%d history=%d", outbox_deleted, history_deleted)
+
+
+@idempotent_task(
+    lock_key_template="workflows_outbox_drain",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workflows.outbox_drain",
+)
+def workflows_outbox_drain(self: object) -> None:
+    """Re-dispatch stranded workflow step rows every 30 s (ADR-0080 §D)."""
+    _do_outbox_drain()
+
+
+@idempotent_task(
+    lock_key_template="workflows_timer_drain",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workflows.timer_drain",
+)
+def workflows_timer_drain(self: object) -> None:
+    """Fire due sleep timers and wake their workflows."""
+    _do_timer_drain()
+
+
+@idempotent_task(
+    lock_key_template="purge_old_workflow_records",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="workflows.purge_old_records",
+)
+def purge_old_workflow_records(self: object) -> None:
+    """Nightly retention sweep: terminal outbox rows >7 d, history past window."""
+    _do_purge_workflow_records()

trueppm_api/apps/workspace/apps.py

@@ -0,0 +1,10 @@
+"""App config for the workspace app (org-level config, membership, groups — ADR-0087)."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class WorkspaceConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "trueppm_api.apps.workspace"