trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/retro_board_services.py

@@ -0,0 +1,368 @@
+"""Live retro board + team-health pulse service layer (ADR-0117).
+
+Every board-item write goes through here so the single broadcast point — a
+best-effort ``broadcast_board_event`` deferred with ``transaction.on_commit``
+(ADR-0117 §DE.1) — lives in one place and the viewset stays thin. Concurrency is
+per-item last-write-wins on ``server_version``: writes always apply and bump the
+version; the broadcast carries the winning state so a client whose in-flight edit
+was superseded reconciles (and offers a non-destructive undo) on its side.
+
+The pulse path deliberately does **not** broadcast: a project-board event reaches
+every connected client including the PM band, so even a content-free "pulse
+answered" ping is a read-receipt signal Morgan's hard-NO forbids. The trend is a
+reflective view, refetched on retro open — not a live race — and is gated on read
+by ADR-0104's ``pulse`` signal (team + coach only; PM/PMO omitted entirely;
+non-member denied).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from django.db import transaction
+from rest_framework.exceptions import ValidationError
+
+# Server-side cap on a sticky body (ADR-0117 §1). Bounds storage and the broadcast
+# fan-out — a sticky is a short note, not a document.
+MAX_STICKY_LEN = 2000
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+    from rest_framework.request import Request
+
+    from trueppm_api.apps.projects.models import (
+        PulseResponse,
+        RetroActionItem,
+        RetroBoardItem,
+        Sprint,
+        SprintRetro,
+    )
+
+
+def _assert_board_writable(sprint: Sprint) -> None:
+    """Guard the editable window (ADR-0117 §6). PLANNED/CANCELLED reject writes.
+
+    The live ceremony usually runs at/just-after close, so a hard ACTIVE-only lock
+    would shut the board at the exact moment teams use it — ACTIVE *and* COMPLETED
+    are writable; CANCELLED (and not-yet-started PLANNED) are read-only.
+    """
+    from trueppm_api.apps.projects.models import SprintState
+
+    if sprint.state not in (SprintState.ACTIVE, SprintState.COMPLETED):
+        raise ValidationError(
+            f"The retro board is read-only while the sprint is {sprint.state}; "
+            "it opens when the sprint is active and stays editable after close."
+        )
+
+
+def _get_or_create_retro(sprint: Sprint, actor: User) -> SprintRetro:
+    """Lazily create the SprintRetro the first sticky/pulse attaches to.
+
+    Mirrors the single-author retro upsert's lazy creation so an existing sprint
+    needs no data migration — a retro simply springs into being on first use.
+    """
+    from trueppm_api.apps.projects.models import SprintRetro
+
+    retro, _ = SprintRetro.objects.get_or_create(
+        sprint=sprint,
+        defaults={"created_by": actor},
+    )
+    return retro
+
+
+def _broadcast(project_id: Any, event_type: str, payload: dict[str, Any]) -> None:
+    """Defer a best-effort board broadcast until the surrounding tx commits."""
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    pid = str(project_id)
+    transaction.on_commit(lambda: broadcast_board_event(pid, event_type, payload))
+
+
+# ---------------------------------------------------------------------------
+# Board stickies — concurrent multi-writer CRUD (ADR-0117 §1, §3)
+# ---------------------------------------------------------------------------
+
+
+def create_board_item(
+    sprint: Sprint,
+    *,
+    column: str,
+    text: str,
+    color: str,
+    author: User,
+) -> RetroBoardItem:
+    """Create a sticky, appended to the end of its column.
+
+    Position is ``max(column) + 1`` so a new card lands at the bottom; a later
+    drag computes a fractional midpoint via :func:`move_board_item`.
+    """
+    from django.db.models import Max
+
+    from trueppm_api.apps.projects.models import RetroBoardItem, RetroColumn
+
+    _assert_board_writable(sprint)
+    body = (text or "").strip()
+    if not body:
+        raise ValidationError({"text": "A sticky cannot be empty."})
+    if len(body) > MAX_STICKY_LEN:
+        raise ValidationError({"text": f"A sticky cannot exceed {MAX_STICKY_LEN} characters."})
+    if column not in RetroColumn.values:
+        raise ValidationError({"column": f"Unknown column '{column}'."})
+
+    with transaction.atomic():
+        retro = _get_or_create_retro(sprint, author)
+        last = (
+            RetroBoardItem.objects.filter(retro=retro, column=column, is_deleted=False)
+            .aggregate(m=Max("position"))
+            .get("m")
+        )
+        item = RetroBoardItem.objects.create(
+            retro=retro,
+            column=column,
+            text=body,
+            color=color or "",
+            author=author,
+            position=(last or 0.0) + 1.0,
+        )
+        _broadcast(
+            sprint.project_id,
+            "retro_item_created",
+            {
+                "id": str(item.id),
+                "retro_id": str(retro.id),
+                "sprint_id": str(sprint.id),
+                "column": item.column,
+                "author_id": author.pk,
+            },
+        )
+    return item
+
+
+def update_board_item(
+    item: RetroBoardItem, *, text: str | None, color: str | None
+) -> RetroBoardItem:
+    """Edit a sticky's text/color (last-write-wins; ADR-0117 §3).
+
+    Always applies — no version precondition. The bumped ``server_version`` and
+    the broadcast let a client whose edit was superseded detect the collision and
+    offer its non-destructive undo. Editing never moves the sticky (see
+    :func:`move_board_item`).
+    """
+    _assert_board_writable(item.retro.sprint)
+    fields: list[str] = []
+    if text is not None:
+        body = text.strip()
+        if not body:
+            raise ValidationError({"text": "A sticky cannot be empty."})
+        if len(body) > MAX_STICKY_LEN:
+            raise ValidationError({"text": f"A sticky cannot exceed {MAX_STICKY_LEN} characters."})
+        item.text = body
+        fields.append("text")
+    if color is not None:
+        item.color = color
+        fields.append("color")
+    if fields:
+        # Couple the save to its broadcast in one transaction (#1323), matching
+        # create_board_item: the on_commit broadcast then fires only if the save
+        # commits, and is deferred to that commit rather than the surrounding
+        # autocommit boundary.
+        with transaction.atomic():
+            item.save(update_fields=[*fields, "updated_at", "server_version"])
+            _broadcast(
+                item.retro.sprint.project_id,
+                "retro_item_updated",
+                {"id": str(item.id), "retro_id": str(item.retro_id)},
+            )
+    return item
+
+
+def move_board_item(item: RetroBoardItem, *, column: str, position: float) -> RetroBoardItem:
+    """Move a sticky to a column + fractional position (drag-reorder; ADR-0117 §3)."""
+    from trueppm_api.apps.projects.models import RetroColumn
+
+    _assert_board_writable(item.retro.sprint)
+    if column not in RetroColumn.values:
+        raise ValidationError({"column": f"Unknown column '{column}'."})
+    item.column = column
+    item.position = position
+    # Couple the save to its broadcast in one transaction (#1323).
+    with transaction.atomic():
+        item.save(update_fields=["column", "position", "updated_at", "server_version"])
+        _broadcast(
+            item.retro.sprint.project_id,
+            "retro_item_moved",
+            {"id": str(item.id), "retro_id": str(item.retro_id), "column": column},
+        )
+    return item
+
+
+def delete_board_item(item: RetroBoardItem) -> None:
+    """Soft-delete a sticky and broadcast its removal."""
+    _assert_board_writable(item.retro.sprint)
+    project_id = item.retro.sprint.project_id
+    retro_id = item.retro_id
+    item_id = item.id
+    item.is_deleted = True
+    # Couple the soft-delete to its broadcast in one transaction (#1323).
+    with transaction.atomic():
+        item.save(update_fields=["is_deleted", "updated_at", "server_version"])
+        _broadcast(
+            project_id,
+            "retro_item_deleted",
+            {"id": str(item_id), "retro_id": str(retro_id)},
+        )
+
+
+def convert_to_action(item: RetroBoardItem, actor: User) -> RetroActionItem:
+    """Distil a discussion sticky into a RetroActionItem (ADR-0117 §1).
+
+    Idempotent (ADR-0117 §DE.7): a sticky already converted returns its existing
+    action item rather than creating a duplicate. The new action item then uses the
+    unchanged #858 promote flow.
+    """
+    from trueppm_api.apps.projects.models import RetroActionItem
+
+    _assert_board_writable(item.retro.sprint)
+    with transaction.atomic():
+        locked = item.__class__.objects.select_for_update().get(pk=item.pk)
+        if locked.converted_action_item_id is not None:
+            existing = RetroActionItem.objects.filter(
+                pk=locked.converted_action_item_id, is_deleted=False
+            ).first()
+            if existing is not None:
+                return existing
+        action = RetroActionItem.objects.create(retro=locked.retro, text=locked.text)
+        locked.converted_action_item_id = action.pk
+        locked.save(update_fields=["converted_action_item_id", "updated_at", "server_version"])
+        _broadcast(
+            locked.retro.sprint.project_id,
+            "retro_item_updated",
+            {"id": str(locked.id), "retro_id": str(locked.retro_id)},
+        )
+    return action
+
+
+# ---------------------------------------------------------------------------
+# Team-health pulse (ADR-0117 §5; ADR-0104 pulse gate consumed verbatim)
+# ---------------------------------------------------------------------------
+
+
+def upsert_pulse_response(
+    sprint: Sprint,
+    *,
+    respondent: User,
+    mood: int | None,
+    energy: int | None,
+    confidence: int | None,
+) -> PulseResponse:
+    """One-tap upsert of the requester's own pulse response (ADR-0117 §5).
+
+    Keyed on ``unique(retro, respondent)`` so a re-tap updates rather than
+    duplicates. Deliberately does **not** broadcast — a pulse event would reach
+    PM-band clients as a read-receipt (Morgan 🔴). Validates each dimension to 1..5.
+    """
+    from trueppm_api.apps.projects.models import PulseResponse
+
+    _assert_board_writable(sprint)
+    # Explicit per-field guards (not a loop) so the type narrows to ``int`` for the
+    # update_or_create below — mypy --strict + django-stubs reject ``int | None`` on
+    # the non-null model fields.
+    if mood is None or not (1 <= mood <= 5):
+        raise ValidationError({"mood": "Must be an integer 1-5."})
+    if energy is None or not (1 <= energy <= 5):
+        raise ValidationError({"energy": "Must be an integer 1-5."})
+    if confidence is not None and not (1 <= confidence <= 5):
+        raise ValidationError({"confidence": "Must be an integer 1-5 or omitted."})
+
+    with transaction.atomic():
+        retro = _get_or_create_retro(sprint, respondent)
+        response, _ = PulseResponse.objects.update_or_create(
+            retro=retro,
+            respondent=respondent,
+            is_deleted=False,
+            defaults={"mood": mood, "energy": energy, "confidence": confidence},
+        )
+    return response
+
+
+def my_pulse_response(sprint: Sprint, respondent: User) -> PulseResponse | None:
+    """The requester's own current response for this sprint, echoed so they can change it."""
+    from trueppm_api.apps.projects.models import PulseResponse, SprintRetro
+
+    retro = SprintRetro.objects.filter(sprint=sprint, is_deleted=False).first()
+    if retro is None:
+        return None
+    return PulseResponse.objects.filter(
+        retro=retro, respondent=respondent, is_deleted=False
+    ).first()
+
+
+def pulse_trend(request: Request, sprint: Sprint) -> dict[str, Any]:
+    """Cross-sprint pulse trend, gated by ADR-0104's ``pulse`` signal (the 🔴).
+
+    Returns ``{"gated": True}`` and **no data** for any requester outside the
+    signal's audience (PM/PMO band by default; non-member always) — a redacted
+    aggregate is no pulse (ADR-0104 §2.3). For the team + coach band, returns
+    aggregate-only per-sprint points (never an individual's raw answer) ordered by
+    sprint start, plus a server-computed ``energy_declining`` flag (the
+    "two-sprints-before-velocity" signal), the response count, and the requester's
+    own current response echoed back.
+    """
+    from django.db.models import Avg, Count
+
+    from trueppm_api.apps.projects.models import PulseResponse
+    from trueppm_api.apps.projects.signal_privacy_services import can_read_signal
+
+    if not can_read_signal(request, sprint.project_id, "pulse"):
+        # Omit entirely — no count, no points, nothing to infer from (ADR-0104 §2.3).
+        return {"gated": True}
+
+    # Aggregate per sprint across the whole project, oldest → newest. Grouping by
+    # the sprint behind each retro keeps individual rows invisible — only means and
+    # counts leave the server.
+    rows = (
+        PulseResponse.objects.filter(
+            retro__sprint__project_id=sprint.project_id,
+            is_deleted=False,
+        )
+        .values("retro__sprint_id", "retro__sprint__name", "retro__sprint__start_date")
+        .annotate(
+            avg_mood=Avg("mood"),
+            avg_energy=Avg("energy"),
+            avg_confidence=Avg("confidence"),
+            response_count=Count("id"),
+        )
+        .order_by("retro__sprint__start_date", "retro__sprint__name")
+    )
+    points = [
+        {
+            "sprint_id": str(r["retro__sprint_id"]),
+            "sprint_name": r["retro__sprint__name"],
+            "avg_mood": round(r["avg_mood"], 2) if r["avg_mood"] is not None else None,
+            "avg_energy": round(r["avg_energy"], 2) if r["avg_energy"] is not None else None,
+            "avg_confidence": (
+                round(r["avg_confidence"], 2) if r["avg_confidence"] is not None else None
+            ),
+            "response_count": r["response_count"],
+        }
+        for r in rows
+    ]
+
+    # energy_declining: the last two points both fell — the coach's early-warning
+    # signal. Computed server-side so the client renders a fact, not a derivation.
+    energy_declining = False
+    energies = [p["avg_energy"] for p in points if p["avg_energy"] is not None]
+    if len(energies) >= 3:
+        energy_declining = energies[-1] < energies[-2] < energies[-3]
+
+    mine = my_pulse_response(sprint, request.user)  # type: ignore[arg-type]
+    return {
+        "gated": False,
+        "points": points,
+        "energy_declining": energy_declining,
+        "my_response": (
+            {"mood": mine.mood, "energy": mine.energy, "confidence": mine.confidence}
+            if mine is not None
+            else None
+        ),
+    }

trueppm_api/apps/projects/retro_services.py

@@ -0,0 +1,285 @@
+"""Retrospective service layer (ADR-0071).
+
+Two operations: promote a ``RetroActionItem`` into a project-backlog ``Task``
+(``promote_retro_action_item``) and atomically promote + pull into a
+``PLANNED`` sprint as one SCHEDULER+ action (``pull_carryover_item_to_sprint``).
+
+Sprint sovereignty is enforced at this layer: ``promote_retro_action_item``
+never accepts a sprint argument; the resulting Task is unconditionally created
+with ``sprint=None``. The only path that puts a retro action item into a
+sprint is ``pull_carryover_item_to_sprint``, which requires SCHEDULER+ role
+and an explicit ``target_sprint`` argument.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from django.core.exceptions import ValidationError
+from django.db import transaction
+from django.utils import timezone
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+
+    from trueppm_api.apps.projects.models import (
+        RetroActionItem,
+        Sprint,
+        Task,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class AlreadyPromotedError(ValidationError):
+    """Raised when promote is attempted on an action item that already has a Task.
+
+    Carries ``existing_task_id`` so the view layer can include it in the 409
+    response payload (the client can navigate to the existing task instead of
+    retrying).
+    """
+
+    def __init__(self, existing_task_id: str) -> None:
+        super().__init__("Action item already promoted.")
+        self.existing_task_id = existing_task_id
+
+
+def promote_retro_action_item(
+    action_item: RetroActionItem,
+    actor: User,
+) -> Task:
+    """Promote a RetroActionItem into a project-backlog Task.
+
+    Atomic:
+      1. SELECT FOR UPDATE on the action item; assert promoted_task_id IS NULL
+         (else raise AlreadyPromotedError).
+      2. Create Task(status=BACKLOG, sprint=None) in the action item's project.
+      3. If the action item's assignee differs from the actor, create a
+         TaskSuggestedAssignee (PENDING) instead of setting Task.assignee.
+         Self-claim binds Task.assignee directly.
+      4. Stamp action_item.promoted_task_id = task.pk and save.
+      5. On commit: broadcast ``task_created`` + enqueue CPM recalculate.
+
+    The new Task is unconditionally ``sprint=None``. Sprint assignment is a
+    separate SCHEDULER+ action (see ``pull_carryover_item_to_sprint``).
+    """
+    from trueppm_api.apps.projects.models import (
+        RetroActionItem,
+        SuggestionSource,
+        SuggestionState,
+        Task,
+        TaskStatus,
+        TaskSuggestedAssignee,
+    )
+    from trueppm_api.apps.scheduling.models import ScheduleRequestReason
+    from trueppm_api.apps.scheduling.services import enqueue_recalculate
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    with transaction.atomic():
+        # Re-read with row lock; the in-memory action_item passed in may be stale.
+        locked = (
+            RetroActionItem.objects.select_for_update()
+            .select_related("retro__sprint__project")
+            .get(pk=action_item.pk)
+        )
+        if locked.promoted_task_id is not None:
+            raise AlreadyPromotedError(str(locked.promoted_task_id))
+
+        project = locked.retro.sprint.project
+        retro_short_id = locked.retro.sprint.short_id or str(locked.retro.sprint_id)[:8]
+
+        # Self-claim binds Task.assignee directly; assigning someone else
+        # creates a soft suggestion the assignee must accept on My Work.
+        is_self_claim = locked.assignee_id is not None and locked.assignee_id == actor.pk
+        bound_assignee = locked.assignee if is_self_claim else None
+
+        task = Task.objects.create(
+            project=project,
+            name=locked.text[:255],
+            duration=1,
+            status=TaskStatus.BACKLOG,
+            sprint=None,
+            assignee=bound_assignee,
+            story_points=locked.story_points,
+            notes=f'source: "retrospective" (from Sprint {retro_short_id} retro)',
+        )
+
+        suggestion: TaskSuggestedAssignee | None = None
+        if locked.assignee_id is not None and not is_self_claim:
+            # locked.assignee_id guard above narrows locked.assignee to non-None
+            # at runtime; cast for mypy since FK type still includes None.
+            suggested_user = locked.assignee
+            assert suggested_user is not None
+            suggestion = TaskSuggestedAssignee.objects.create(
+                task=task,
+                suggested_user=suggested_user,
+                suggested_by=actor,
+                source=SuggestionSource.RETROSPECTIVE,
+                state=SuggestionState.PENDING,
+                reason=f"from retro of Sprint {retro_short_id}",
+            )
+
+        locked.promoted_task_id = task.pk
+        locked.save(update_fields=["promoted_task_id"])
+
+        # Snapshot every broadcast value to a plain scalar *at registration time*
+        # so the deferred dispatch can never read a later-mutated (or by-then
+        # garbage-collected) ORM instance (#1323). `suggestion.pk` and
+        # `locked.assignee_id` were the last live ORM reads left in the closure.
+        project_id = str(project.pk)
+        task_id = str(task.pk)
+        action_item_id = str(locked.pk)
+        retro_id = str(locked.retro_id)
+        suggestion_id = str(suggestion.pk) if suggestion is not None else None
+        suggested_user_id = locked.assignee_id
+
+        def _on_commit_dispatch() -> None:
+            # Same ``id``-omission defect as the carryover ``task_updated`` below
+            # (#2843), found by the payload-shape guard rather than by the audit:
+            # every other ``task_created`` site emits ``{"id": ...}``, and a client
+            # keying on ``payload.id`` cannot see this one at all. ``task_id`` stays
+            # for one release; drop it after 0.5.
+            broadcast_board_event(
+                project_id,
+                "task_created",
+                {
+                    "id": task_id,
+                    "task_id": task_id,
+                    "source": "retrospective",
+                    "retro_id": retro_id,
+                    "action_item_id": action_item_id,
+                },
+            )
+            if suggestion_id is not None:
+                broadcast_board_event(
+                    project_id,
+                    "suggestion_created",
+                    {
+                        "task_id": task_id,
+                        "suggestion_id": suggestion_id,
+                        "suggested_user_id": suggested_user_id,
+                    },
+                )
+            enqueue_recalculate(
+                project_id,
+                reason=ScheduleRequestReason.TASK_CHANGE,
+            )
+
+        transaction.on_commit(_on_commit_dispatch)
+
+    return task
+
+
+def pull_carryover_item_to_sprint(
+    action_item: RetroActionItem,
+    target_sprint: Sprint,
+    actor: User,
+) -> Task:
+    """Atomically promote an action item and assign the resulting Task to a sprint.
+
+    SCHEDULER+ role is enforced at the view layer; this service trusts the
+    caller has been gated. The target sprint must be in the same project as
+    the action item's source retro (raises ValidationError otherwise).
+
+    Behaviour:
+      - If the action item is already promoted, reuses the existing Task and
+        sets ``task.sprint = target_sprint``.
+      - Otherwise calls ``promote_retro_action_item`` first, then sets
+        ``task.sprint = target_sprint``.
+      - Fires a single ``task_updated`` broadcast at commit (in addition to
+        the ``task_created`` broadcast from promotion, if the promote happened
+        in this call) — clients can dedupe by task_id.
+
+    Returns the Task in its post-assign state (sprint set).
+    """
+    from trueppm_api.apps.projects.models import (
+        RetroActionItem,
+        Sprint,
+        SprintState,
+        Task,
+    )
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    with transaction.atomic():
+        locked = (
+            RetroActionItem.objects.select_for_update()
+            .select_related("retro__sprint__project")
+            .get(pk=action_item.pk)
+        )
+        source_project_id = locked.retro.sprint.project_id
+
+        target_locked = Sprint.objects.select_for_update().get(pk=target_sprint.pk)
+        if target_locked.project_id != source_project_id:
+            raise ValidationError(
+                "Target sprint must be in the same project as the retro action item."
+            )
+        if target_locked.state != SprintState.PLANNED:
+            raise ValidationError(
+                "Carryover pull is only permitted into PLANNED sprints; "
+                f"target sprint state is {target_locked.state}."
+            )
+
+        if locked.promoted_task_id is None:
+            # Promote first; the service handles broadcast + recalc enqueue.
+            # Note: promote_retro_action_item opens its own atomic block but
+            # uses the outer transaction (Django nests via savepoints).
+            task = promote_retro_action_item(locked, actor)
+        else:
+            task = Task.objects.select_for_update().get(pk=locked.promoted_task_id)
+
+        task.sprint = target_locked
+        task.save(update_fields=["sprint", "server_version"])
+
+        project_id = str(source_project_id)
+        task_id = str(task.pk)
+        sprint_id = str(target_locked.pk)
+
+        def _broadcast_carryover() -> None:
+            # ``id`` is the task identity every other ``task_updated`` site emits and
+            # the only one websockets.md documents (#2843). This was the single site
+            # in the tree using ``task_id``, which made the frontend's
+            # ``typeof payload.id === 'string' ? payload.id : null`` resolve to null:
+            # the ADR-0152 per-task version dedup was skipped and the history
+            # invalidation widened from one task to the whole project.
+            #
+            # ``task_id`` is kept alongside for one release in case anything reads
+            # it; drop it after 0.5.
+            broadcast_board_event(
+                project_id,
+                "task_updated",
+                {
+                    "id": task_id,
+                    "task_id": task_id,
+                    "sprint_id": sprint_id,
+                    "source": "retro_carryover",
+                },
+            )
+
+        transaction.on_commit(_broadcast_carryover)
+
+    return task
+
+
+def reset_promoted_task_on_delete(task_id: str) -> None:
+    """Reset RetroActionItem.promoted_task_id to NULL when its Task is soft-deleted.
+
+    Wired to the ``Task`` post_delete (or post_save when ``is_deleted=True``)
+    signal so a re-deleted Task automatically frees the originating action
+    item to be re-promoted. ADR-0071 §2 rollback.
+    """
+    from trueppm_api.apps.projects.models import RetroActionItem
+
+    updated = RetroActionItem.objects.filter(promoted_task_id=task_id).update(promoted_task_id=None)
+    if updated:
+        logger.info(
+            "reset_promoted_task_on_delete: freed %s action items linked to task %s",
+            updated,
+            task_id,
+        )
+
+
+def now_utc() -> datetime:
+    """Centralized timezone-aware now for tests to monkey-patch."""
+    return timezone.now()