trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/scheduling/models.py

@@ -0,0 +1,516 @@
+"""Models for the scheduling app — Celery task infrastructure."""
+
+from __future__ import annotations
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+# Lazy FK target — Django serializes the FK target to this resolved string, so
+# using the constant produces no migration change.
+_PROJECT_MODEL = "projects.Project"
+
+
+class ScheduleRequestStatus(models.TextChoices):
+    """Lifecycle of a transactional outbox row for CPM recalculation."""
+
+    PENDING = "pending", "Pending"
+    DISPATCHED = "dispatched", "Dispatched"
+    DONE = "done", "Done"
+    DEAD = "dead", "Dead"
+
+
+class ScheduleRequestReason(models.TextChoices):
+    """Why a CPM recalculation was requested — used for audit trail and drain dedup."""
+
+    TASK_CHANGE = "task_change", "Task Change"
+    DEPENDENCY_CHANGE = "dependency_change", "Dependency Change"
+    # A project's working calendar is a CPM input — lag is calendar-aware — so a
+    # calendar swap shifts every task's working-day math and forces a full recompute.
+    CALENDAR_CHANGE = "calendar_change", "Calendar Change"
+    # An accepted cross-project edge mutated (created/accepted/deleted): the
+    # project's program now needs a merged, program-scoped recompute so the
+    # cross-project critical path stays program-true (ADR-0120 D3). Recorded on
+    # the outbox rows of *both* endpoint projects; the drain/dispatch coalesces
+    # them into one program-scoped pass.
+    CROSS_PROJECT_DEPENDENCY = "cross_project_dependency", "Cross-Project Dependency"
+    SPRINT_CLOSED = "sprint_closed", "Sprint Closed"
+    MANUAL = "manual", "Manual"
+
+
+class ScheduleRequest(models.Model):
+    """Transactional outbox record for CPM recalculation requests.
+
+    Each write operation on a project's task graph inserts one row here
+    (or silently ignores a duplicate via the partial unique constraint) in
+    the same DB transaction. A Celery Beat drain task dispatches pending rows
+    every 30 seconds, and recalculate_schedule marks its own row done on
+    completion.
+
+    Two partial unique constraints enforce at-most-one pending and at-most-one
+    dispatched row per project at any time, so duplicate suppression is cheap
+    and correct under concurrent writes.
+
+    Does NOT inherit VersionedModel — not synced to mobile clients.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.CASCADE,
+        related_name="schedule_requests",
+    )
+    status = models.CharField(
+        max_length=16,
+        choices=ScheduleRequestStatus.choices,
+        default=ScheduleRequestStatus.PENDING,
+    )
+    reason = models.CharField(
+        max_length=24,
+        choices=ScheduleRequestReason.choices,
+        default=ScheduleRequestReason.TASK_CHANGE,
+        db_index=True,
+    )
+    requested_at = models.DateTimeField(auto_now_add=True)
+    dispatched_at = models.DateTimeField(null=True, blank=True)
+    celery_task_id = models.CharField(max_length=255, blank=True, default="")
+
+    class Meta:
+        ordering = ["requested_at"]
+        constraints = [
+            models.UniqueConstraint(
+                fields=["project"],
+                condition=models.Q(status="pending"),
+                name="schedule_request_one_pending_per_project",
+            ),
+            models.UniqueConstraint(
+                fields=["project"],
+                condition=models.Q(status="dispatched"),
+                name="schedule_request_one_dispatched_per_project",
+            ),
+        ]
+        indexes = [
+            models.Index(
+                fields=["status", "requested_at"],
+                name="schedule_request_status_idx",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"ScheduleRequest({self.project_id}, {self.status})"
+
+
+class MCAttributionAudience(models.TextChoices):
+    """Who may see the run-author name on Monte Carlo forecast history (ADR-0144).
+
+    Defined here (not on Workspace) because both the per-workspace config columns
+    and the ``MonteCarloHistoryView`` attribution gate reference it; placing it on
+    the scheduling model keeps a single source and avoids a workspace ``→`` scheduling
+    import cycle (workspace/projects import this enum, never the reverse).
+
+    The default ``ADMIN_OWNER`` preserves the pre-0143 hardcoded Admin/Owner gate
+    exactly, so the three-valued enum is backward-compatible and reversible.
+    """
+
+    ADMIN_OWNER = "admin_owner", "Admins and Owners"
+    SCHEDULER_PLUS = "scheduler_plus", "Schedulers and above"
+    NONE = "none", "No one"
+
+
+class FailedTaskStatus(models.TextChoices):
+    """Lifecycle of a dead-lettered Celery task."""
+
+    PENDING_RETRY = "pending_retry", "Pending Retry"
+    DEAD = "dead", "Dead"
+    DISMISSED = "dismissed", "Dismissed"
+    RETRIED = "retried", "Retried"
+
+
+class FailedTask(models.Model):
+    """Persistent record of a Celery task that exhausted all retries.
+
+    Does NOT inherit VersionedModel — not synced to mobile, not part of the
+    project data graph. Exists for admin visibility and manual retry/dismiss.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    task_name = models.CharField(max_length=255, db_index=True)
+    task_id = models.CharField(max_length=255, unique=True)
+    # Attribution for the dead-letter queue (#1917). Nullable: not every
+    # dead-lettered task is project-scoped (e.g. the nightly cross-project purge
+    # tasks), and existing rows predate this column. SET_NULL rather than CASCADE
+    # — deleting a project must never delete the failure audit trail that explains
+    # what it was doing when it broke; the row just loses its project reference.
+    # Populated by ``deadletter.record_failed_task`` from whatever ``project_id``
+    # the failing task already knew (most scheduling tasks take one as an arg).
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="failed_tasks",
+        help_text="Project the failing task acted on, when known.",
+    )
+    args = models.JSONField(default=list)
+    kwargs = models.JSONField(default=dict)
+    exception_type = models.CharField(max_length=255)
+    exception_message = models.TextField()
+    traceback = models.TextField()
+    failure_count = models.PositiveIntegerField(default=1)
+    first_failed_at = models.DateTimeField(auto_now_add=True)
+    last_failed_at = models.DateTimeField(auto_now=True)
+    status = models.CharField(
+        max_length=16,
+        choices=FailedTaskStatus.choices,
+        default=FailedTaskStatus.DEAD,
+        db_index=True,
+    )
+    # Operator-action audit (ADR-0210). Stamped on both requeue and drop so every
+    # write action against a parked task is attributable (who/when), and drop can
+    # carry a free-text reason. Nullable/defaulted because the vast majority of
+    # rows are written by the automatic dead-letter path, which never resolves them
+    # — only an explicit operator action sets these. Retained (never hard-deleted)
+    # so the audit survives a drop; ADR-0084 "no silent discards".
+    resolution_note = models.TextField(
+        blank=True,
+        default="",
+        help_text="Operator's free-text note recorded when the task was dropped.",
+    )
+    resolved_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="+",
+        help_text="Workspace admin who requeued or dropped this task.",
+    )
+    resolved_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When an operator requeued or dropped this task.",
+    )
+
+    class Meta:
+        ordering = ["-last_failed_at"]
+        indexes = [
+            models.Index(fields=["status", "last_failed_at"], name="failed_task_status_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.task_name} ({self.task_id}) — {self.status}"
+
+
+class VelocitySuggestion(models.Model):
+    """Non-destructive duration recommendation generated on sprint close (ADR-0065).
+
+    When a sprint closes, the drain computes a rolling 6-sprint team velocity
+    (``completed_points / sprint_working_days``) and, for tasks in the closing
+    sprint with ``story_points`` set, records a suggested
+    ``most_likely_duration = story_points / team_velocity_per_day`` here. The
+    PM accepts or dismisses each suggestion from the Task Detail Drawer; the
+    underlying ``Task.most_likely_duration`` is never overwritten without
+    explicit consent so PM-committed baselines stay intact and the
+    accept/dismiss history is auditable per (task, sprint).
+
+    A unique constraint on (task, sprint) makes the sprint-close drain
+    idempotent: a duplicate run upserts the row rather than producing
+    duplicate prompts.
+
+    Not synced to mobile clients — surfaces only in the PM-facing Task Detail
+    Drawer.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    task = models.ForeignKey(
+        "projects.Task",
+        on_delete=models.CASCADE,
+        related_name="velocity_suggestions",
+    )
+    sprint = models.ForeignKey(
+        "projects.Sprint",
+        on_delete=models.CASCADE,
+        related_name="velocity_suggestions",
+    )
+    # Suggested most_likely_duration in working days. Stored as integer to match
+    # Task.most_likely_duration; rounding happens in the service layer.
+    suggested_duration = models.PositiveIntegerField()
+    team_velocity_per_day = models.DecimalField(
+        max_digits=6,
+        decimal_places=3,
+        help_text="Rolling 6-sprint average of completed_points / sprint_working_days.",
+    )
+    # When estimation_mode=SUGGEST_APPROVE the suggestion is flagged so the
+    # governance review surface can route the accept decision through a
+    # Scheduler-role user; in OPEN and PM_ONLY modes any PM may accept directly.
+    flag_for_review = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    # Exactly one of accepted_at / dismissed_at is non-null at a time; the
+    # other stays null. The pair encodes the PM decision lifecycle without an
+    # extra status enum (similar to the actual_start / actual_finish pattern).
+    accepted_at = models.DateTimeField(null=True, blank=True)
+    accepted_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="accepted_velocity_suggestions",
+    )
+    dismissed_at = models.DateTimeField(null=True, blank=True)
+    dismissed_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="dismissed_velocity_suggestions",
+    )
+
+    class Meta:
+        ordering = ["-created_at"]
+        constraints = [
+            models.UniqueConstraint(
+                fields=["task", "sprint"],
+                name="unique_velocity_suggestion_per_task_sprint",
+            ),
+        ]
+        indexes = [
+            # Pending suggestions for a task — the Task Detail Drawer query.
+            models.Index(
+                fields=["task", "accepted_at", "dismissed_at"],
+                name="velocity_sugg_task_pending_idx",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"VelocitySuggestion(task={self.task_id}, sprint={self.sprint_id})"
+
+    @property
+    def project_id(self) -> object:
+        """Expose the task's project_id so _get_project_id_from_obj can find it.
+
+        Required for IsProjectAdmin.has_object_permission to resolve the project
+        context when DRF's get_object() runs check_object_permissions on a
+        VelocitySuggestion (no direct FK to Project). Mirrors the same pattern
+        used by resources.TaskResource.
+        """
+        return self.task.project_id
+
+    @property
+    def is_pending(self) -> bool:
+        """True when neither accepted nor dismissed — pending PM decision."""
+        return self.accepted_at is None and self.dismissed_at is None
+
+
+class MonteCarloRun(models.Model):
+    """One persisted project-level Monte Carlo simulation run (ADR-0175, #961).
+
+    Written synchronously per ``POST /projects/<pk>/monte-carlo/`` run so the PM
+    can read finish-date forecast *drift* over time ("my P80 was Aug 14 two weeks
+    ago, now Aug 28"). Distinct from ``projects.ForecastSnapshot`` (ADR-0106 §5),
+    which is milestone-scoped, latest-per-milestone, and carries the velocity
+    -privacy band — this model is the explicit project-level CPM Monte Carlo run
+    history and stores P95 (which ForecastSnapshot does not).
+
+    A plain ``models.Model`` (not a ``VersionedModel``) — display/forecast
+    metadata, consistent with ``ForecastSnapshot`` / ``VelocitySuggestion``; not
+    on the mobile sync surface (Monte Carlo requires server compute, so history
+    is an online read).
+
+    Retention is the OSS cap applied to run *count*: a nightly purge keeps the
+    newest ``settings.MC_HISTORY_CAP`` rows per project (Enterprise overrides to
+    ``None`` = unlimited). Bounded history, never unlimited — the portfolio /
+    cross-program rollup is the Enterprise upsell (ADR-0175).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.CASCADE,
+        related_name="monte_carlo_runs",
+    )
+    taken_at = models.DateTimeField(auto_now_add=True)
+    # SET_NULL + null: account deletion never cascades away forecast history, and
+    # the attribution is optional metadata. Serialized ONLY to Admin/Owner so
+    # forecast drift cannot become a named-individual performance signal at the
+    # team level (ADR-0175 / VoC Morgan). related_name="+": no reverse accessor
+    # needed (we never list a user's runs).
+    triggered_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="+",
+    )
+    # The probabilistic finish-date percentiles as of this run. Nullable: a
+    # project with no committed tasks yields no distribution to anchor on.
+    p50 = models.DateField(null=True, blank=True)
+    p80 = models.DateField(null=True, blank=True)
+    p95 = models.DateField(null=True, blank=True)
+    # The deterministic CPM spine at run time (max early_finish of committed
+    # tasks), kept for context alongside the probabilistic band.
+    cpm_finish = models.DateField(null=True, blank=True)
+    # Inputs needed to interpret the run.
+    n_simulations = models.PositiveIntegerField()
+    task_count = models.PositiveIntegerField(null=True, blank=True)
+    # The full per-run distribution payload — the same
+    # ``{histogram_buckets, confidence_curve, sensitivity}`` shape written to the
+    # ``mc_latest`` cache (#1231, ADR-0144; key built by
+    # ``views.mc_latest_cache_key``). Persisted so the histogram +
+    # tornado survive cache expiry and a past run stays re-viewable.
+    #
+    # Nullable with NO backfill: pre-0143 runs have no stored distribution and the
+    # frontend renders the empty-state prose for them (legacy runs are a tail that
+    # ages out under the retention cap). Capped at MC_DISTRIBUTION_MAX_BYTES with
+    # bucket down-sampling at persist time (the cache copy stays full) so a
+    # pathological high-bucket run cannot bloat the row.
+    distribution = models.JSONField(null=True, blank=True)
+    # Why this run has — or lacks — an uncertainty band: the
+    # ``{deterministic, reason, tasks_total, tasks_with_variance, ...}`` payload
+    # from :func:`forecast_diagnostic` (#1340), persisted with the run (#2483).
+    #
+    # Load-bearing for the "added time" metric, not merely informational. A flat
+    # run yields a premium of exactly 0 days, and a project with no three-point
+    # estimates is always flat — so without the reason code a structural zero is
+    # indistinguishable from a measured zero, and Overview would tell an
+    # unestimated project it carries no schedule risk. Re-deriving the reason at
+    # read time would mean loading every committed task on a hot endpoint, so the
+    # run carries its own.
+    #
+    # Nullable with NO backfill: runs recorded before #2483 have no diagnostic and
+    # the frontend falls back to the measured presentation with the band collapsed
+    # (it never guesses "unmeasurable" from a missing reason).
+    diagnostic = models.JSONField(null=True, blank=True)
+    # The data date this run was actually computed against — ADR-0132 floors a null
+    # ``Project.status_date`` at "today" for Monte Carlo (never forecast remaining
+    # work in the past), but that substitution used to happen only in memory and was
+    # never recorded, so a past run could not be re-derived and two runs of an
+    # unchanged project on different days returned different percentiles with nothing
+    # in the row explaining why (#2638). ADR-0132's Implementation Notes already
+    # called this out as "additive on ADR-0175" when this model was designed; it
+    # simply never landed until now.
+    #
+    # Nullable with NO backfill, same pattern as ``distribution``/``diagnostic``:
+    # runs recorded before #2638 have no stored data date and read back as
+    # ``status_date: null`` rather than a guessed value.
+    status_date = models.DateField(null=True, blank=True)
+    # The plan version this run was computed against — the project's
+    # ``last_sync_version`` (ADR-0686) read *before* the task set was loaded (#3140).
+    #
+    # This is what makes "is the forecast still about the current plan?" a server fact
+    # instead of a client guess. Compared against the project's live value at response
+    # time by :mod:`.forecast_staleness`; a difference means the plan has been written to
+    # since the run. The web forecast bar previously answered the same question with a
+    # session-local mutation counter, which missed every write path but one and reset on
+    # reload — and once #3132 gated the Rerun *action* on it, a stale forecast could
+    # offer no recompute at all.
+    #
+    # Read before the tasks, not after, and the ordering is the correctness property: a
+    # write landing mid-simulation then leaves ``plan_version`` behind the project's
+    # value, so the run reads stale. Capturing it afterwards would claim the run covered
+    # a write it never saw — false-fresh, which is the direction that loses the action.
+    #
+    # Nullable with NO backfill, the same pattern as ``distribution``/``diagnostic``/
+    # ``status_date`` above: runs recorded before #3140 have no plan version and classify
+    # as ``unknown`` rather than a guessed ``current``. No index — this model is only ever
+    # read as "newest row for this project", which ``mcrun_project_recent_idx`` covers.
+    plan_version = models.BigIntegerField(null=True, blank=True)
+
+    class Meta:
+        db_table = "scheduling_montecarlorun"
+        ordering = ["-taken_at"]
+        indexes = [
+            # Newest-first history read + the nightly rank-based purge.
+            models.Index(fields=["project", "-taken_at"], name="mcrun_project_recent_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"MonteCarloRun(project={self.project_id} @ {self.taken_at:%Y-%m-%d})"
+
+
+class ForecastSnapshotTrigger(models.TextChoices):
+    """What caused a ``ProjectForecastSnapshot`` to be captured."""
+
+    RECOMPUTE = "recompute", "Recompute"
+    SCHEDULED = "scheduled", "Scheduled"
+    MANUAL = "manual", "Manual"
+
+
+class ProjectForecastSnapshot(models.Model):
+    """One project-grain forecast point-in-time, captured on each recompute (ADR-0154, #388).
+
+    The continuous record of how a project's *whole-project* forecast drifts over
+    time — "we were saying end of June a month ago, now we're saying end of August".
+    Written best-effort after every CPM recompute (plus a daily floor) so ~30 days of
+    real history accrue before the forecast-trend chart (#368) and history-aware
+    sample loader (#376) consume it.
+
+    Distinct from the two adjacent forecast-history models, and deliberately not a
+    merge of either:
+
+    * ``projects.ForecastSnapshot`` (ADR-0106 §5) is *milestone*-grain,
+      latest-per-milestone, and carries a velocity-privacy band — a different read
+      contract. (Its FK already owns ``related_name="forecast_snapshots"`` on
+      Project, which is why this model uses ``project_forecast_snapshots``.)
+    * ``MonteCarloRun`` (ADR-0175) is written only when a user *explicitly* runs
+      Monte Carlo and is capped to the newest N runs — it never captures CPM-finish
+      drift on a project that has never been simulated, and its flat cap drops the
+      long tail the trend chart needs.
+
+    This model is CPM-primary: ``cpm_finish``/``total_float_days`` come from the
+    just-recomputed schedule, while the Monte Carlo percentiles are copied
+    best-effort from the project's most-recent ``MonteCarloRun`` (so the MC line
+    stays flat — truthfully — until someone reruns MC).
+
+    A plain ``models.Model`` (not a ``VersionedModel``) with no ``server_version``
+    and not on the mobile sync surface — consistent with ``MonteCarloRun`` /
+    ``ForecastSnapshot``; this is a high-churn, server-generated, online-read-only
+    history table with no mobile consumer (ADR-0154 §2).
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    project = models.ForeignKey(
+        _PROJECT_MODEL,
+        on_delete=models.CASCADE,
+        related_name="project_forecast_snapshots",
+    )
+    captured_at = models.DateTimeField(auto_now_add=True)
+    triggered_by = models.CharField(
+        max_length=16,
+        choices=ForecastSnapshotTrigger.choices,
+        default=ForecastSnapshotTrigger.RECOMPUTE,
+    )
+    # Every aggregate below is over ``Task.committed`` — the population CPM is
+    # actually run on — never over all non-deleted tasks (#3539). A BACKLOG/EPIC/
+    # recurring row is never scheduled, so any early_finish/total_float it carries
+    # is scheduling output left over from before it was groomed out, and admitting
+    # it here reports a forecast for a schedule that was never computed.
+    #
+    # Deterministic CPM spine at capture time: the project's latest committed task
+    # finish. Nullable — a project with no scheduled tasks has no finish to anchor on.
+    cpm_finish = models.DateField(null=True, blank=True)
+    # The tightest total float (minimum across the committed set): 0 on an
+    # unconstrained critical path, negative when a deadline/constraint is breached —
+    # so drift in schedule *pressure* is visible, not just the finish date.
+    total_float_days = models.IntegerField(null=True, blank=True)
+    # Probabilistic finish-date percentiles, copied best-effort from the project's
+    # most-recent MonteCarloRun at capture time. Null when MC has never run; may
+    # predate this capture (no newer probabilistic data exists to report).
+    mc_p50_finish = models.DateField(null=True, blank=True)
+    mc_p80_finish = models.DateField(null=True, blank=True)
+    mc_p95_finish = models.DateField(null=True, blank=True)
+    mc_iterations = models.PositiveIntegerField(null=True, blank=True)
+    # Schedule shape at capture time — context for interpreting the forecast, and
+    # therefore counted over the same committed population as cpm_finish above.
+    task_count = models.PositiveIntegerField(default=0)
+    completed_task_count = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        db_table = "scheduling_projectforecastsnapshot"
+        ordering = ["-captured_at"]
+        indexes = [
+            # Newest-first history read + the per-project tiered prune scan.
+            models.Index(fields=["project", "-captured_at"], name="projfcast_proj_recent_idx"),
+        ]
+
+    def __str__(self) -> str:
+        return f"ProjectForecastSnapshot(project={self.project_id} @ {self.captured_at:%Y-%m-%d})"

trueppm_api/apps/scheduling/receivers.py

@@ -0,0 +1,160 @@
+"""OSS signal receivers for the scheduling app.
+
+The default dead-letter alerting receiver (ADR-0084). When a Celery task is
+permanently dead-lettered, OSS emits a single structured WARNING line that an
+operator (or a log-based metrics aggregator) can alert on. Enterprise registers
+*additional* receivers on the same signal for PagerDuty/Slack in its own
+AppConfig.ready() — this module is never imported by enterprise and imports
+nothing from it.
+
+Also holds the start/success/retry structured-log receivers (#1917) that
+complement the dead-letter alert above — each Celery task's full lifecycle
+(started → succeeded, or started → retried → ... → dead-lettered) is now a
+structured, greppable/aggregatable log line rather than the ad-hoc
+``logger.info`` calls scattered across individual task bodies.
+
+Wired by SchedulingConfig.ready() via ``from . import receivers``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.dispatch import receiver
+
+from trueppm_api.apps.scheduling.signals import (
+    celery_task_permanently_failed,
+    celery_task_retried,
+    celery_task_started,
+    celery_task_succeeded,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@receiver(celery_task_permanently_failed)
+def log_dead_letter_alert(
+    sender: Any,
+    task_id: str = "",
+    task_name: str = "",
+    exception: BaseException | None = None,
+    project_id: str | None = None,
+    **_kwargs: Any,
+) -> None:
+    """Emit a WARNING alert line for a newly dead-lettered task.
+
+    Distinct from the ERROR line in ``record_failed_task`` (which records the
+    raw failure): this is the *alert*, carrying structured ``extra`` fields so
+    log pipelines can build the ``trueppm_task_dead_letter_count`` series by
+    ``task_name`` without parsing the message. Broad ``except`` because an
+    alerting failure must never propagate back into the dead-letter path — the
+    signal is dispatched with ``send_robust`` for the same reason, so this is
+    belt-and-braces against a logging-config error masking a task failure.
+    """
+    try:
+        logger.warning(
+            "dead-letter alert: task %s (%s) permanently failed: %s",
+            task_name,
+            task_id,
+            type(exception).__qualname__ if exception is not None else "unknown",
+            extra={
+                "task_name": task_name,
+                "task_id": task_id,
+                "exception_type": (
+                    type(exception).__qualname__ if exception is not None else "unknown"
+                ),
+                "project_id": project_id,
+            },
+        )
+    except Exception:
+        logger.exception("dead-letter alert receiver failed")
+
+
+@receiver(celery_task_started)
+def log_task_started(
+    sender: Any,
+    task_id: str = "",
+    task_name: str = "",
+    **_kwargs: Any,
+) -> None:
+    """Emit a structured INFO line when a Celery task begins execution (#1917).
+
+    Bridged from the ``task_prerun`` framework signal in
+    ``SchedulingConfig.ready()`` for every task in the process. Broad ``except``
+    (matching ``log_dead_letter_alert``): this is bridged via a plain (not
+    ``send_robust``) Django signal fired synchronously inside the worker's task
+    execution path, so a logging-config error here must never surface as (or
+    interrupt) a task failure.
+    """
+    try:
+        logger.info(
+            "task started: %s (%s)",
+            task_name,
+            task_id,
+            extra={"task_name": task_name, "task_id": task_id, "outcome": "started"},
+        )
+    except Exception:
+        logger.exception("task-started log receiver failed")
+
+
+@receiver(celery_task_succeeded)
+def log_task_succeeded(
+    sender: Any,
+    task_id: str = "",
+    task_name: str = "",
+    runtime_seconds: float = 0.0,
+    **_kwargs: Any,
+) -> None:
+    """Emit a structured INFO line when a Celery task completes successfully (#1917)."""
+    try:
+        logger.info(
+            "task succeeded: %s (%s) in %.3fs",
+            task_name,
+            task_id,
+            runtime_seconds,
+            extra={
+                "task_name": task_name,
+                "task_id": task_id,
+                "outcome": "succeeded",
+                "runtime_seconds": runtime_seconds,
+            },
+        )
+    except Exception:
+        logger.exception("task-succeeded log receiver failed")
+
+
+@receiver(celery_task_retried)
+def log_task_retried(
+    sender: Any,
+    task_id: str = "",
+    task_name: str = "",
+    attempt: int = 0,
+    exception: BaseException | None = None,
+    **_kwargs: Any,
+) -> None:
+    """Emit a structured WARNING line when a Celery task is about to be retried (#1917).
+
+    Distinct from ``log_dead_letter_alert``: this fires on *every* retry attempt
+    (the task will run again), the dead-letter alert fires once, only on the
+    terminal transition after retries are exhausted.
+    """
+    try:
+        logger.warning(
+            "task retry: %s (%s) attempt %s: %s",
+            task_name,
+            task_id,
+            attempt,
+            exception,
+            extra={
+                "task_name": task_name,
+                "task_id": task_id,
+                "outcome": "retried",
+                "attempt": attempt,
+                "exception_type": (
+                    type(exception).__qualname__ if exception is not None else "unknown"
+                ),
+            },
+        )
+    except Exception:
+        logger.exception("task-retried log receiver failed")