trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/scheduling/tasks.py

@@ -0,0 +1,1984 @@
+"""Celery tasks for the scheduling app."""
+
+from __future__ import annotations
+
+import functools
+import logging
+import operator
+import uuid
+from collections.abc import Iterable, Mapping
+from datetime import date, timedelta
+from typing import Any
+
+import redis as redis_lib
+from celery.exceptions import SoftTimeLimitExceeded
+from django.db import OperationalError
+
+from trueppm_api.apps.projects.services import clear_uncommitted_cpm_output
+from trueppm_api.core.idempotent import idempotent_task
+
+logger = logging.getLogger(__name__)
+
+# Exceptions that are transient and should trigger Celery's built-in retry.
+_RETRIABLE = (ConnectionError, redis_lib.ConnectionError, OperationalError)
+
+
+@idempotent_task(
+    lock_key_template="schedule_lock:{0}",
+    lock_ttl=300,
+    on_contention="queue",
+    queue_countdown=10,
+    max_queue_attempts=5,
+    autoretry_for=_RETRIABLE,
+    retry_backoff=30,
+    retry_backoff_max=300,
+    retry_jitter=True,
+    max_retries=3,
+    soft_time_limit=480,
+    time_limit=600,
+    acks_late=True,
+    reject_on_worker_lost=True,
+)
+def recalculate_schedule(
+    self: object,
+    project_id: str,
+) -> None:
+    """Run CPM on a project and persist the results.
+
+    Idempotency is enforced by the ``@idempotent_task`` decorator which
+    acquires a Redis SET NX lock keyed by project_id and auto-extends it
+    for long-running schedules. On lock contention the task is re-queued
+    with a 10-second countdown (up to 5 attempts).
+
+    Progress is tracked via TaskRunTracker, which persists status to the
+    TaskRun model and broadcasts task_run_* WebSocket events. The frontend
+    subscribes to these events instead of the old cpm_queued/complete/error
+    events (replaced by ADR-0020).
+
+    A full CPM recompute runs on every dispatch: the engine-level incremental
+    recompute designed in ADR-0027 is tracked separately under #235 (0.5). The
+    earlier API-layer write-back narrowing was removed in #1528 as unreachable
+    dead code — no dispatch site ever supplied the changed-task set.
+
+    Args:
+        project_id: UUID string of the project to reschedule.
+    """
+    from trueppm_api.apps.taskruns.tracker import TaskRunTracker
+
+    try:
+        with TaskRunTracker(
+            self,
+            project_id=project_id,
+            task_name="scheduling.recalculate",
+        ) as tracker:
+            _run_schedule(project_id, tracker)
+        # Stamp the successful CPM completion so the web Schedule view can show
+        # the "recalculating" badge until the first post-import pass lands
+        # (#1053). A bulk update avoids a save() + history row + server_version
+        # bump for a non-domain timestamp.
+        from django.utils import timezone
+
+        from trueppm_api.apps.projects.models import Project
+
+        Project.objects.filter(pk=project_id).update(recalculated_at=timezone.now())
+    except SoftTimeLimitExceeded:
+        logger.error(
+            "recalculate_schedule: soft time limit exceeded for project %s",
+            project_id,
+        )
+        from django.db import transaction
+
+        from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+        # Record the failure first, then broadcast cpm_error only after that row
+        # commits (#896): clients should not be told a recompute failed unless the
+        # dead-letter record actually persisted. Default-arg binding pins the id.
+        with transaction.atomic():
+            _dead_letter_current(
+                self, project_id, SoftTimeLimitExceeded("CPM computation timed out")
+            )
+
+            def _broadcast_error(pid: str = project_id) -> None:
+                broadcast_board_event(
+                    project_id=pid, event_type="cpm_error", payload={"error": "timeout"}
+                )
+
+            transaction.on_commit(_broadcast_error)
+
+
+@idempotent_task(
+    lock_key_template="drain_schedule_queue",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="scheduling.drain_schedule_queue",
+)
+def drain_schedule_queue(self: object) -> None:
+    """Dispatch any pending ScheduleRequest outbox rows.
+
+    Runs every 30 seconds via Celery Beat. For each project with a pending
+    row, calls recalculate_schedule.delay() and marks the row as dispatched.
+
+    Also recovers orphaned dispatched rows older than 10 minutes — the
+    recalculate_schedule soft_time_limit is 480 s (8 min), so 10 min ensures
+    any prior task invocation has either completed or timed out before we
+    re-dispatch.
+
+    The @idempotent_task singleton lock ensures at most one drain runs at a
+    time; on_contention="skip" drops any concurrent trigger rather than
+    queuing, because the next Beat tick will cover it.
+    """
+    _do_drain()
+
+
+@idempotent_task(
+    lock_key_template="purge_old_schedule_requests",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="scheduling.purge_old_schedule_requests",
+)
+def purge_old_schedule_requests(self: object) -> None:
+    """Delete done/dead ScheduleRequest rows older than 7 days.
+
+    Runs nightly at 02:15 UTC via Celery Beat. Keeps the outbox table small
+    so index scans on (status, requested_at) stay fast.
+    """
+    _do_purge()
+
+
+def _do_drain() -> None:
+    """Business logic for drain_schedule_queue — extracted for testability."""
+    from django.utils import timezone
+
+    from trueppm_api.apps.scheduling.models import ScheduleRequest, ScheduleRequestStatus
+
+    now = timezone.now()
+    orphan_cutoff = now - timedelta(minutes=10)
+
+    # Recover orphaned rows: dispatched but not completed within 10 minutes.
+    #
+    # A blanket flip of every stale dispatched row back to pending is unsafe: if
+    # the project already has a pending row (a fresh edit arrived after the row was
+    # dispatched but before its task finished/died), resurrecting the dead row
+    # creates a *second* pending row and violates the
+    # schedule_request_one_pending_per_project partial-unique constraint — which
+    # aborts the whole UPDATE, so no orphan is recovered and the drain wedges on
+    # every tick (#1693). Because CPM is a full recompute, that existing pending
+    # row already supersedes the dead dispatched one, so retire the dead row as
+    # done rather than resurrecting it. Only stale dispatched rows with no
+    # coexisting pending row are flipped back to pending for re-dispatch.
+    projects_with_pending = set(
+        ScheduleRequest.objects.filter(status=ScheduleRequestStatus.PENDING).values_list(
+            "project_id", flat=True
+        )
+    )
+    stale_dispatched = ScheduleRequest.objects.filter(
+        status=ScheduleRequestStatus.DISPATCHED,
+        dispatched_at__lt=orphan_cutoff,
+    )
+    superseded = stale_dispatched.filter(project_id__in=projects_with_pending).update(
+        status=ScheduleRequestStatus.DONE
+    )
+    recovered = stale_dispatched.exclude(project_id__in=projects_with_pending).update(
+        status=ScheduleRequestStatus.PENDING, celery_task_id=""
+    )
+    if recovered:
+        logger.warning("drain_schedule_queue: recovered %d orphaned dispatched row(s)", recovered)
+    if superseded:
+        logger.warning(
+            "drain_schedule_queue: retired %d stale dispatched row(s) superseded by a pending row",
+            superseded,
+        )
+
+    # Dispatch all currently pending rows (one Celery task per project).
+    pending = list(ScheduleRequest.objects.filter(status=ScheduleRequestStatus.PENDING))
+    dispatched = 0
+    for req in pending:
+        try:
+            result = recalculate_schedule.delay(str(req.project_id))
+        except Exception:
+            logger.warning(
+                "drain_schedule_queue: broker unavailable — project %s stays pending",
+                req.project_id,
+            )
+            continue
+        # Conditional update: only flip to dispatched if it's still pending
+        # (guards against a concurrent on_commit _enqueue_recalculate call).
+        ScheduleRequest.objects.filter(id=req.id, status=ScheduleRequestStatus.PENDING).update(
+            status=ScheduleRequestStatus.DISPATCHED,
+            celery_task_id=result.id,
+            dispatched_at=now,
+        )
+        dispatched += 1
+
+    if dispatched or recovered:
+        logger.info("drain_schedule_queue: dispatched=%d recovered=%d", dispatched, recovered)
+
+
+def _do_purge() -> None:
+    """Business logic for purge_old_schedule_requests — extracted for testability."""
+    from django.utils import timezone
+
+    from trueppm_api.apps.scheduling.models import ScheduleRequest, ScheduleRequestStatus
+
+    cutoff = timezone.now() - timedelta(days=7)
+    deleted, _ = ScheduleRequest.objects.filter(
+        status__in=[ScheduleRequestStatus.DONE, ScheduleRequestStatus.DEAD],
+        requested_at__lt=cutoff,
+    ).delete()
+    logger.info("purge_old_schedule_requests: deleted %d row(s)", deleted)
+
+
+@idempotent_task(
+    lock_key_template="purge_resolved_slip_conflicts",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="scheduling.purge_resolved_slip_conflicts",
+)
+def purge_resolved_slip_conflicts(self: object) -> None:
+    """Delete cross-project slip conflicts 90 days past resolution (ADR-0120 D4).
+
+    Runs nightly at 02:25 UTC. Removes ``CrossProjectSlipConflict`` rows whose
+    acknowledgment or auto-resolution is older than 90 days; unresolved and
+    unacknowledged rows are kept indefinitely (they are still live conflicts).
+    Idempotent: a re-run deletes nothing new.
+    """
+    _do_purge_resolved_slip_conflicts()
+
+
+def _do_purge_resolved_slip_conflicts() -> None:
+    """Business logic for purge_resolved_slip_conflicts — extracted for testability."""
+    from django.db.models import Q
+    from django.utils import timezone
+
+    from trueppm_api.apps.projects.models import CrossProjectSlipConflict
+
+    cutoff = timezone.now() - timedelta(days=90)
+    deleted, _ = CrossProjectSlipConflict.objects.filter(
+        Q(acknowledged_at__lt=cutoff) | Q(resolved_at__lt=cutoff)
+    ).delete()
+    if deleted:
+        logger.info("purge_resolved_slip_conflicts: deleted %d row(s)", deleted)
+
+
+@idempotent_task(
+    lock_key_template="purge_old_monte_carlo_runs",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="scheduling.purge_old_monte_carlo_runs",
+)
+def purge_old_monte_carlo_runs(self: object) -> None:
+    """Trim project Monte Carlo run history to the newest cap per project.
+
+    Runs nightly at 02:20 UTC via Celery Beat. Keeps the most recent N
+    ``MonteCarloRun`` rows per project, where N is the per-workspace-effective
+    retention cap (ADR-0144, #1232) — no longer the global constant — so
+    forecast-drift history stays bounded. No-ops for a project whose effective cap
+    is ``None`` (Enterprise unlimited). Idempotent: rank-based delete is safe to run
+    repeatedly.
+    """
+    _do_monte_carlo_run_purge()
+
+
+def _do_monte_carlo_run_purge() -> None:
+    """Business logic for purge_old_monte_carlo_runs — extracted for testability.
+
+    Each project's retention cap is resolved per-workspace-effective (ADR-0144,
+    #1232) via ``resolve_effective_mc_history`` rather than the global
+    ``MC_HISTORY_CAP`` constant — a workspace/program/project may raise or lower it
+    (clamped to MC_HISTORY_HARD_CAP in the resolver). For each project exceeding its
+    own cap, delete every run older than its cap-th most recent. The candidate set
+    is the projects whose total run count exceeds the global hard cap floor, so the
+    common case (projects under the cap) does no delete work; the per-project cap is
+    then applied exactly. A project whose effective cap is None (Enterprise
+    unlimited) is skipped.
+    """
+    from django.db.models import Count
+
+    from trueppm_api.apps.scheduling.forecast_history_settings import resolve_effective_mc_history
+    from trueppm_api.apps.scheduling.models import MonteCarloRun
+
+    # Candidate projects: any with more than one run. We can't pre-filter by a single
+    # global cap because each project's effective cap may differ; resolving per
+    # project below is bounded by the (small) set of projects that actually have
+    # history.
+    project_ids = (
+        MonteCarloRun.objects.values("project_id")
+        .annotate(n=Count("id"))
+        .filter(n__gt=1)
+        .values_list("project_id", flat=True)
+    )
+
+    from trueppm_api.apps.projects.models import Project
+    from trueppm_api.apps.workspace.models import Workspace
+
+    # Load the workspace singleton once and thread it through every per-project
+    # resolve. Workspace.load() is a get_or_create round-trip (not memoized), so
+    # passing it in avoids a redundant workspace query per candidate project.
+    workspace = Workspace.load()
+
+    total_deleted = 0
+    for project_id in list(project_ids):
+        project = Project.objects.filter(pk=project_id).select_related("program").first()
+        if project is None:
+            continue
+        cap: int | None = resolve_effective_mc_history(
+            project, "mc_history_retention_cap", workspace=workspace
+        )
+        if cap is None:
+            continue  # Enterprise unlimited: nothing to purge for this project.
+        # Find the taken_at of the cap-th most recent run; everything strictly
+        # older is surplus. Ordered by -taken_at so [cap - 1] is the boundary row.
+        boundary = list(
+            MonteCarloRun.objects.filter(project_id=project_id)
+            .order_by("-taken_at")
+            .values_list("taken_at", flat=True)[cap - 1 : cap]
+        )
+        if not boundary:
+            continue
+        deleted, _ = MonteCarloRun.objects.filter(
+            project_id=project_id, taken_at__lt=boundary[0]
+        ).delete()
+        total_deleted += deleted
+
+    if total_deleted:
+        logger.info("purge_old_monte_carlo_runs: deleted %d row(s)", total_deleted)
+
+
+@idempotent_task(
+    lock_key_template="capture_daily_forecast_floor",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=110,
+    time_limit=150,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="scheduling.capture_daily_forecast_floor",
+)
+def capture_daily_forecast_floor(self: object) -> None:
+    """Guarantee ≥1 forecast snapshot per active project per day (ADR-0154, #388).
+
+    Runs nightly at 00:30 UTC via Celery Beat. Captures a ``scheduled`` snapshot
+    for every non-deleted, non-archived project that has no snapshot in the last
+    24 h — covering quiet days with no recompute, and acting as the durability
+    backstop that backfills any ``recompute`` capture missed by a broker blip or a
+    worker death between commit and on_commit. Idempotent: a project already
+    covered in the window is skipped.
+    """
+    _do_daily_forecast_floor()
+
+
+def _do_daily_forecast_floor() -> None:
+    """Business logic for capture_daily_forecast_floor — extracted for testability."""
+    from django.utils import timezone
+
+    from trueppm_api.apps.projects.lifecycle import visible_projects
+    from trueppm_api.apps.projects.models import Project
+    from trueppm_api.apps.scheduling.models import ForecastSnapshotTrigger, ProjectForecastSnapshot
+    from trueppm_api.apps.scheduling.services import safe_capture_forecast_snapshot
+
+    cutoff = timezone.now() - timedelta(hours=24)
+    # Projects already covered in the window — skip them with a single query rather
+    # than letting the capture-path dedup absorb each one (dedup only skips when the
+    # forecast is *unchanged*; the floor's intent is one row/day regardless).
+    covered = set(
+        ProjectForecastSnapshot.objects.filter(captured_at__gte=cutoff)
+        .values_list("project_id", flat=True)
+        .distinct()
+    )
+    # Drafts are excluded (#2962/#3128). Two reasons, and the second is the one on
+    # the exclusion list: a forecast history for a plan nobody has committed to is
+    # noise by construction (the dates move because the plan is still being
+    # written), and every captured snapshot whose end date moved fires
+    # ``notify_project_end_date_shift`` at each ADMIN — a daily "your end date
+    # slipped" for a schedule the author is in the middle of typing. The commit
+    # moment captures baseline v1, which is where a draft's history should start.
+    project_ids = visible_projects(
+        Project.objects.filter(is_deleted=False, is_archived=False)
+    ).values_list("id", flat=True)
+    captured = 0
+    for project_id in project_ids:
+        if project_id in covered:
+            continue
+        safe_capture_forecast_snapshot(project_id, ForecastSnapshotTrigger.SCHEDULED)
+        captured += 1
+    if captured:
+        logger.info("capture_daily_forecast_floor: captured %d snapshot(s)", captured)
+
+
+@idempotent_task(
+    lock_key_template="prune_forecast_snapshots",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=110,
+    time_limit=150,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="scheduling.prune_forecast_snapshots",
+)
+def prune_forecast_snapshots(self: object) -> None:
+    """Apply the tiered retention curve to project forecast snapshots (ADR-0154, #388).
+
+    Runs nightly at 04:15 UTC via Celery Beat. Per ``settings.FORECAST_SNAPSHOT_RETENTION``:
+    keep all rows younger than ``daily_days`` (default 90); keep one-per-ISO-week up
+    to ``weekly_days`` (default 365); keep one-per-calendar-month beyond that (kept
+    forever). The same logic is exposed as the ``prune_forecast_snapshots`` management
+    command. Idempotent: re-running deletes nothing new.
+    """
+    _do_prune_forecast_snapshots()
+
+
+def _snapshot_ids_to_keep(rows: Any, daily_cutoff: Any, weekly_cutoff: Any) -> set[uuid.UUID]:
+    """Pick the representative snapshot id to retain in each retention bucket.
+
+    ``rows`` are ``(id, captured_at)`` pairs ordered newest-first, so the first
+    row seen in each ISO-week / calendar-month bucket is the freshest and wins.
+    Every row inside the recent (daily) tier is kept.
+    """
+    keep: set[uuid.UUID] = set()
+    seen_weeks: set[tuple[int, int]] = set()
+    seen_months: set[tuple[int, int]] = set()
+    for row_id, captured_at in rows:
+        if captured_at >= daily_cutoff:
+            keep.add(row_id)  # Recent tier: keep every row.
+        elif captured_at >= weekly_cutoff:
+            iso = captured_at.isocalendar()
+            key = (iso[0], iso[1])
+            if key not in seen_weeks:
+                seen_weeks.add(key)
+                keep.add(row_id)  # Newest row in this ISO week.
+        else:
+            key = (captured_at.year, captured_at.month)
+            if key not in seen_months:
+                seen_months.add(key)
+                keep.add(row_id)  # Newest row in this calendar month.
+    return keep
+
+
+def _do_prune_forecast_snapshots() -> int:
+    """Business logic for prune_forecast_snapshots — extracted for testability.
+
+    Returns the number of rows deleted. Scans each project's snapshots newest-first
+    and keeps the first (newest) row in each retention bucket, so the freshest
+    representative per day/week/month survives.
+    """
+    from django.conf import settings
+    from django.utils import timezone
+
+    from trueppm_api.apps.scheduling.models import ProjectForecastSnapshot
+
+    policy = getattr(settings, "FORECAST_SNAPSHOT_RETENTION", {})
+    daily_days = int(policy.get("daily_days", 90))
+    weekly_days = int(policy.get("weekly_days", 365))
+
+    now = timezone.now()
+    daily_cutoff = now - timedelta(days=daily_days)
+    weekly_cutoff = now - timedelta(days=weekly_days)
+
+    project_ids = ProjectForecastSnapshot.objects.values_list("project_id", flat=True).distinct()
+
+    total_deleted = 0
+    for project_id in list(project_ids):
+        rows = (
+            ProjectForecastSnapshot.objects.filter(project_id=project_id)
+            .order_by("-captured_at")
+            .values_list("id", "captured_at")
+        )
+        keep = _snapshot_ids_to_keep(rows, daily_cutoff, weekly_cutoff)
+
+        deleted, _ = (
+            ProjectForecastSnapshot.objects.filter(project_id=project_id)
+            .exclude(id__in=keep)
+            .delete()
+        )
+        total_deleted += deleted
+
+    if total_deleted:
+        logger.info("prune_forecast_snapshots: deleted %d row(s)", total_deleted)
+    return total_deleted
+
+
+def _dead_letter_current(task: object, project_id: str, exc: BaseException) -> None:
+    """Write a FailedTask record for the current task invocation."""
+    from trueppm_api.apps.scheduling.deadletter import record_failed_task
+
+    request = task.request  # type: ignore[attr-defined]
+    record_failed_task(
+        task_name=getattr(task, "name", "unknown"),
+        task_id=request.id or "unknown",
+        args=[project_id],
+        kwargs={},
+        exception=exc,
+        project_id=project_id,
+    )
+
+
+_WRITEBACK_BATCH_SIZE = 500
+"""Rows per ``bulk_update`` statement when persisting CPM results (#1529).
+
+On PostgreSQL Django's ``bulk_batch_size`` defaults to ``len(objs)``, so an
+unbatched write collapses every task into a single UPDATE built from per-field
+``CASE WHEN pk=… THEN …`` chains (~17 params/row → ~85K interpolated values at 5K
+tasks). psycopg3's client-side binding keeps this under the 65,535 protocol
+ceiling, but the multi-MB SQL string is slow to build, parse, and plan and lands
+on the <500 ms schedule-trigger budget. Batching bounds each statement's size
+without changing the result — the whole writeback still runs in one transaction."""
+
+CPM_DELTA_BROADCAST_CAP = 500
+"""Max moved-task count to ship as per-task ``task_dates_updated`` deltas (ADR-0091).
+
+Above this the WS frame grows large enough that a client-side full re-fetch is cheaper
+than splicing, so we emit a ``truncated`` signal instead and let the client invalidate.
+A delta row serializes to ≈264 bytes, so a 500-row payload is ≈130 KB.
+
+The cap counts the *moved* set, not the write-back set (#2573). A recalc always
+re-assigns every engine-returned row, so counting the write-back set put every
+project above ~500 tasks permanently into the truncated branch and made ADR-0091's
+splice path unreachable at the documented envelope.
+
+Sized against the moved subset the truncated branch is reachable only when the recalc
+genuinely moved that many rows. Note that the backward pass seeds every task's late
+dates from the project finish, so **any edit that shifts the project finish moves the
+whole network's late dates and floats** — a critical-path edit therefore still
+truncates on a large project even though few bars actually move. Narrowing that case
+(splitting early dates from late/float churn, or re-sizing the cap) is tracked in
+#2598; the other wide cases are a first-ever pass, a calendar change, and a
+project-start shift.
+"""
+
+
+# Per-task schedule-shift activity events (ADR-0207, #1604). The CPM writeback
+# persists only the history-excluded early_*/late_* fields via bulk_update, so a
+# recompute leaves no per-task audit row; these helpers emit one instead.
+def _active_baseline_finishes(project_ids: list[Any]) -> dict[str, tuple[str, date]]:
+    """Return ``{task_id: (baseline_id, baseline_finish)}`` for each project's active baseline.
+
+    One entry per snapshotted task with a non-null finish, drawn from the single
+    active baseline per project (enforced by a DB unique constraint). Two indexed
+    queries; empty and cheap when no project in ``project_ids`` has an active
+    baseline, so the drift check adds no cost to the common no-baseline recalc.
+    """
+    from trueppm_api.apps.projects.models import Baseline, BaselineTask
+
+    baseline_ids = list(
+        Baseline.objects.filter(
+            project_id__in=project_ids, is_active=True, is_deleted=False
+        ).values_list("id", flat=True)
+    )
+    if not baseline_ids:
+        return {}
+    finishes: dict[str, tuple[str, date]] = {}
+    for row in BaselineTask.objects.filter(
+        baseline_id__in=baseline_ids, finish__isnull=False
+    ).values("task_id", "finish", "baseline_id"):
+        finish = row["finish"]
+        if finish is None:  # narrows the nullable DateField for mypy; excluded by the filter
+            continue
+        finishes[str(row["task_id"])] = (str(row["baseline_id"]), finish)
+    return finishes
+
+
+def _iso_or_none(value: Any) -> str | None:
+    return value.isoformat() if value is not None else None
+
+
+def _cpm_dates_changed(old: tuple[Any, Any, Any, Any], t: Any) -> bool:
+    """True when any of a task's four CPM dates differ from its pre-writeback snapshot."""
+    old_es, old_ef, old_ls, old_lf = old
+    return bool(
+        old_es != t.early_start
+        or old_ef != t.early_finish
+        or old_ls != t.late_start
+        or old_lf != t.late_finish
+    )
+
+
+def _recalc_project_aggregates(
+    tasks_to_update: list[Any],
+    old_dates: dict[str, tuple[Any, Any, Any, Any]],
+) -> tuple[dict[Any, int], dict[Any, date], dict[Any, date]]:
+    """Per-project recalc summary denormalized onto every ``cpm_recalculated`` row (#1948).
+
+    Returns ``(moved_by_project, new_finish_by_project, prior_finish_by_project)``.
+    WHY grouped strictly per ``project_id`` and not globally: this feeds a helper
+    shared by the program-scoped writeback, where ``tasks_to_update`` spans several
+    member projects in one call. A single program-wide count stamped onto every row
+    would leak one project's schedule scope onto another project's activity row and
+    violate the OSS project-isolation boundary (enterprise-check constraint #1) — so
+    each row carries only *its own* project's aggregate.
+    """
+    moved_by_project: dict[Any, int] = {}
+    new_finish_by_project: dict[Any, date] = {}
+    prior_finish_by_project: dict[Any, date] = {}
+    for t in tasks_to_update:
+        pid = t.project_id
+        # New finish: latest early_finish across every task in this project,
+        # moved or not (an unmoved late task still defines where finish sits).
+        cur_new = new_finish_by_project.get(pid)
+        if t.early_finish is not None and (cur_new is None or t.early_finish > cur_new):
+            new_finish_by_project[pid] = t.early_finish
+        old = old_dates.get(str(t.id))
+        if old is None:
+            continue
+        old_ef = old[1]
+        cur_prior = prior_finish_by_project.get(pid)
+        if old_ef is not None and (cur_prior is None or old_ef > cur_prior):
+            prior_finish_by_project[pid] = old_ef
+        if _cpm_dates_changed(old, t):
+            moved_by_project[pid] = moved_by_project.get(pid, 0) + 1
+    return moved_by_project, new_finish_by_project, prior_finish_by_project
+
+
+def _cpm_recalculated_event(
+    t: Any,
+    old: tuple[Any, Any, Any, Any],
+    moved_by_project: dict[Any, int],
+    new_finish_by_project: dict[Any, date],
+    prior_finish_by_project: dict[Any, date],
+) -> Any:
+    """Build a ``cpm_recalculated`` activity row for a task whose CPM dates moved."""
+    from trueppm_api.apps.projects.models import TaskActivityEvent
+
+    old_es, old_ef, old_ls, old_lf = old
+    new_f = new_finish_by_project.get(t.project_id)
+    prior_f = prior_finish_by_project.get(t.project_id)
+    # Signed day delta of the project finish (+ = slip later, - = pulled in).
+    # None when either side is missing — most importantly the first-ever recalc,
+    # where no prior early_finish exists for any task.
+    delta = (new_f - prior_f).days if new_f is not None and prior_f is not None else None
+    return TaskActivityEvent(
+        task_id=t.id,
+        actor=None,
+        event_type="cpm_recalculated",
+        detail={
+            "early_start": {"from": _iso_or_none(old_es), "to": _iso_or_none(t.early_start)},
+            "early_finish": {"from": _iso_or_none(old_ef), "to": _iso_or_none(t.early_finish)},
+            "late_start": {"from": _iso_or_none(old_ls), "to": _iso_or_none(t.late_start)},
+            "late_finish": {"from": _iso_or_none(old_lf), "to": _iso_or_none(t.late_finish)},
+            "total_float": t.total_float,
+            "is_critical": t.is_critical,
+            # Per-project recalc summary (#1948) — see _recalc_project_aggregates.
+            "recalc_moved_count": moved_by_project.get(t.project_id, 0),
+            "recalc_finish": _iso_or_none(new_f),
+            "recalc_finish_delta_days": delta,
+        },
+    )
+
+
+def _baseline_drift_event(t: Any, old_ef: Any, baseline: tuple[str, date]) -> Any | None:
+    """Build a ``baseline_drift_detected`` row, but only on the transition *into* drift.
+
+    Emitted only when a task was within its baseline finish and is now past it, so a
+    persistently-drifted task does not re-fire every recalc. Returns ``None`` otherwise.
+    """
+    baseline_id, baseline_finish = baseline
+    was_drifted = old_ef is not None and old_ef > baseline_finish
+    is_drifted = t.early_finish is not None and t.early_finish > baseline_finish
+    if not (is_drifted and not was_drifted):
+        return None
+
+    from trueppm_api.apps.projects.models import TaskActivityEvent
+
+    return TaskActivityEvent(
+        task_id=t.id,
+        actor=None,
+        event_type="baseline_drift_detected",
+        detail={
+            "baseline_id": baseline_id,
+            "baseline_finish": baseline_finish.isoformat(),
+            "early_finish": t.early_finish.isoformat(),
+            "drift_days": (t.early_finish - baseline_finish).days,
+        },
+    )
+
+
+def _build_schedule_shift_events(
+    tasks_to_update: list[Any],
+    old_dates: dict[str, tuple[Any, Any, Any, Any]],
+    baseline_finishes: dict[str, tuple[str, date]],
+    *,
+    suppress_movement_events: bool = False,
+) -> list[Any]:
+    """Build ``TaskActivityEvent`` rows for CPM recomputes and baseline-drift crossings.
+
+    ``old_dates`` maps a task id to its ``(early_start, early_finish, late_start,
+    late_finish)`` captured *before* the writeback loop overwrote the in-memory Task
+    fields, so a move is detected by comparing against the now-mutated values. A
+    ``cpm_recalculated`` row is emitted for every task whose four CPM dates changed;
+    a ``baseline_drift_detected`` row is emitted only on the transition *into* drift
+    (was within baseline, now past it) so a persistently-drifted task does not
+    re-fire every recalc. Actor is null — CPM runs in Celery with no request user.
+
+    Each ``cpm_recalculated`` row also carries a per-project recalc summary
+    (#1948): ``recalc_moved_count`` (how many of the project's tasks moved),
+    ``recalc_finish`` (the project's latest early_finish after the pass), and
+    ``recalc_finish_delta_days`` (signed slip/pull-in of that finish). These are
+    grouped strictly per ``project_id`` because the helper is shared by the
+    program-scoped writeback, where a program-wide count would leak cross-project
+    scope (see :func:`_recalc_project_aggregates`).
+
+    ``suppress_movement_events`` (ADR-0752 §7) skips the ``cpm_recalculated`` rows
+    specifically — the one-shot recalculation that arms a project's status_date
+    floor for the first time moves dates as an engine correction, not a user
+    action, and must not be recorded as ordinary per-task movement. This is a
+    feed-persistence half of the suppression; the caller must also withhold the
+    matching ADR-0091 ``task_dates_updated`` broadcast, or the entries reappear on
+    that surface instead (ADR-0752 §10). ``baseline_drift_detected`` is left
+    unsuppressed — it names an outcome (drift vs. plan), not a change attributed
+    to an actor, and is exactly the kind of information the echoed status_date
+    exists to make sense of.
+    """
+    moved_by_project, new_finish_by_project, prior_finish_by_project = _recalc_project_aggregates(
+        tasks_to_update, old_dates
+    )
+
+    events: list[Any] = []
+    for t in tasks_to_update:
+        old = old_dates.get(str(t.id))
+        if old is None:
+            continue
+        if _cpm_dates_changed(old, t) and not suppress_movement_events:
+            events.append(
+                _cpm_recalculated_event(
+                    t,
+                    old,
+                    moved_by_project,
+                    new_finish_by_project,
+                    prior_finish_by_project,
+                )
+            )
+        baseline = baseline_finishes.get(str(t.id))
+        if baseline is not None:
+            drift = _baseline_drift_event(t, old[1], baseline)
+            if drift is not None:
+                events.append(drift)
+    return events
+
+
+_CPM_DELTA_FIELDS: tuple[str, ...] = (
+    "early_start",
+    "early_finish",
+    "late_start",
+    "late_finish",
+    "total_float",
+    "free_float",
+    "is_critical",
+    "duration",
+    # scheduled_start (ADR-0752): the task's span start, distinct from
+    # early_start's remaining-work window. Same write-back, same broadcast —
+    # a client rendering the span bar needs to know it moved too.
+    "scheduled_start",
+)
+"""Every CPM-owned field a ``task_dates_updated`` delta can carry (ADR-0091, #2573).
+
+Deliberately the same set the write-back persists, so "this row changed" and "this
+row needs to ship in the delta" are the same question. ``planned_start`` also rides
+in the payload but is a user-owned field the CPM write-back never touches, so it
+cannot make a row moved.
+"""
+
+
+_cpm_delta_snapshot = operator.attrgetter(*_CPM_DELTA_FIELDS)
+"""Snapshot the broadcast-relevant CPM fields of a Task for a moved/unmoved diff.
+
+``attrgetter`` rather than a ``getattr`` generator: this runs twice per task inside
+the ``_apply_cpm_results`` hot loop, and the C-level multi-attribute form is ~4x
+faster than the Python-level loop (0.19 µs vs 0.85 µs per call), which at 5,000
+tasks is ~8 ms → ~2 ms. Every name is a concrete column on ``Task`` and neither CPM
+load path defers columns, so no access can trigger a deferred-field query.
+"""
+
+
+def summary_working_day_durations(
+    result_map: dict[str, Any],
+    summary_ids: set[str],
+    db_task_by_id: dict[str, Any],
+    calendar_by_project: Mapping[str, Any],
+) -> dict[str, int]:
+    """Working-day duration for each rolled-up summary row (#3530).
+
+    ``Task.duration`` is documented and consumed everywhere as **working days**
+    (``help_text="Duration in working days"``; the MSPDI exporter multiplies it by
+    ``HOURS_PER_WORKING_DAY``, ``project_span_days`` sums it, and
+    ``build_sched_tasks`` feeds it straight back to the engine as
+    ``timedelta(days=…)``). The write-back used to store the raw **calendar-day**
+    span ``(early_finish - early_start).days`` on summary rows instead, justified by
+    a comment asserting nothing read a summary's duration. That was locally true of
+    the leaf CPM pass and globally false — a ~1.4x inflation reached every consumer
+    above, and 49 of 50 summary rows in the dev database carried it.
+
+    So: count working days in the summary's rolled-up span, **inclusive of both
+    endpoints**, which is the engine's own duration convention
+    (``_finish_from_start(start, 1) == start``). The counter answers the half-open
+    ``[start, end)``, so the finish day is added back — conditionally; see the
+    comment on that line for the weekend-``actual_finish`` case it guards.
+
+    WHY a batched pre-pass rather than a call inside the write-back loop: the scalar
+    counter is an O(span) day walk, so per-summary calls are O(summaries · span) —
+    a deeply nested WBS re-walks the whole project span once per level.
+    :class:`_WorkingDayCounter` (#822) pays O(span) once per calendar and answers
+    each span with two binary searches. Measured: one ``build`` over a 2-year span
+    costs about the same as one scalar walk of it (0.24 ms, 0.35 ms with 25 calendar
+    exceptions) and each ``between`` is 1.4 µs, so break-even is under two summaries
+    — and a project's root summary alone already spans the hull. At 50 summaries in
+    a 2-year project the batched form is ~0.35 ms against up to ~11 ms.
+
+    Be honest about the other comparison: what this replaced was an O(1) timedelta
+    subtraction, so the correct answer costs ~0.24–1.4 ms per project per recompute
+    where the wrong one cost nothing. Working days cannot be derived without walking
+    a calendar, and that is <0.3% of the recompute budget.
+
+    ``schedule()`` builds a counter of its own for float computation, which this
+    duplicates on the single-project path. It is local to that function and never
+    returned, and the program pass needs one counter *per member calendar* anyway
+    (ADR-0120 D3), so reusing it would mean widening the PyPI package's public
+    surface for ~1 ms. Left duplicated deliberately.
+
+    Args:
+        result_map: Engine rows keyed by task id, **after** ``apply_summary_rollups``
+            has added the synthetic summary rows.
+        summary_ids: Task ids that have at least one WBS child.
+        db_task_by_id: Django ``Task`` rows keyed by ``str(id)`` — read only for
+            each summary's ``project_id``, to pick its calendar.
+        calendar_by_project: Composed engine ``Calendar`` per ``str(project_id)``.
+            The program pass holds one per member project (ADR-0120 D3), so a
+            summary is always measured on its own project's working week.
+
+    Returns:
+        ``{summary_id: working_day_duration}``, omitting any summary the engine did
+        not roll up (no scheduled leaves) or whose project has no calendar.
+    """
+    # Private engine symbols, same boundary crossing `scheduling.services` already
+    # makes for `_collect_leaves`. `trueppm-scheduler` ships to PyPI on its own
+    # semver, so this couples the API to unexported internals: a change to either
+    # one's signature or complexity breaks the paragraph above, not just this call.
+    # The alternative — a public working-day-count export — is a public-surface
+    # change to an Apache 2.0 package and belongs in that package's own MR.
+    from trueppm_scheduler.engine import _WorkingDayCounter
+
+    # One pass: collect each summary's span and, per project, the enclosing range
+    # its counter must cover. Grouped as we go rather than re-scanning `spans` per
+    # project — a program pass holds many member projects and this would otherwise
+    # be O(projects · summaries).
+    spans: dict[str, tuple[str, Any, Any]] = {}
+    ranges: dict[str, tuple[Any, Any]] = {}
+    for sid in summary_ids:
+        sched = result_map.get(sid)
+        db_task = db_task_by_id.get(sid)
+        if sched is None or db_task is None:
+            continue
+        if sched.early_start is None or sched.early_finish is None:
+            continue
+        project_key = str(db_task.project_id)
+        spans[sid] = (project_key, sched.early_start, sched.early_finish)
+        lo, hi = ranges.get(project_key, (sched.early_start, sched.early_finish))
+        ranges[project_key] = (
+            min(lo, sched.early_start),
+            max(hi, sched.early_finish),
+        )
+
+    # One counter per calendar, covering that project's full summary date range.
+    # Paired with the calendar itself: the closed-interval correction below needs
+    # `is_working_day`, which the counter does not expose.
+    counters: dict[str, tuple[Any, Any]] = {}
+    for project_key, (lo, hi) in ranges.items():
+        cal = calendar_by_project.get(project_key)
+        if cal is not None:
+            counters[project_key] = (_WorkingDayCounter.build(lo, hi, cal), cal)
+
+    durations: dict[str, int] = {}
+    for sid, (project_key, early_start, early_finish) in spans.items():
+        entry = counters.get(project_key)
+        if entry is None:
+            # No calendar for this summary's project — leave its stored duration
+            # alone rather than write a value measured on the wrong working week.
+            continue
+        counter, cal = entry
+        # `between` counts the HALF-OPEN [early_start, early_finish); a duration is
+        # INCLUSIVE of its finish day, so add the finish back — but only if it is
+        # itself a working day. It need not be: a completed task pinned to a weekend
+        # `actual_finish` (ADR-0136) contributes a non-working `early_finish` to the
+        # rollup's max, and the engine says so in `_gather_successor_constraints`'
+        # own docstring. Adding an unconditional 1 there would report a phase as a
+        # day longer than the work inside it.
+        working = counter.between(early_start, early_finish)
+        if cal.is_working_day(early_finish):
+            working += 1
+        # Floor at 1: a summary whose whole span collapsed onto non-working days
+        # still occupied a day of the plan, and 0 reads as a milestone.
+        durations[sid] = max(1, working)
+    return durations
+
+
+def _apply_cpm_results(
+    db_tasks: Iterable[Any],
+    result_map: dict[str, Any],
+    summary_durations: Mapping[str, int],
+) -> tuple[list[Any], dict[str, tuple[Any, Any, Any, Any]], list[Any]]:
+    """Write engine CPM results onto Task rows in memory.
+
+    Returns ``(tasks_to_update, old_cpm_dates, moved_tasks)``.
+
+    ``old_cpm_dates`` snapshots each task's four CPM dates *before* they are
+    overwritten, so :func:`_build_schedule_shift_events` can tell which tasks
+    actually moved (ADR-0207).
+
+    ``moved_tasks`` is the subset of ``tasks_to_update`` whose broadcast-relevant
+    CPM fields (:data:`_CPM_DELTA_FIELDS`) actually changed in this pass. WHY it is
+    computed here and not by the caller: a CPM run is a *full* write-back — every
+    engine-returned row is re-assigned whether or not its value moved — so the only
+    place the pre-write value still exists is inside this loop. Broadcasting the
+    full write-back set instead of the moved subset put every project above 500
+    tasks permanently into the ``truncated`` branch, which made each connected
+    client re-fetch the whole paginated task list on every single-field edit and
+    left ADR-0091's splice path effectively dead (#2573). ``tasks_to_update``
+    itself stays the full set — the write-back and the ADR-0207 activity events
+    must still see every row.
+
+    INTENTIONAL DESIGN: the caller persists these via ``bulk_update``, which
+    bypasses ``VersionedModel.save()`` so ``server_version`` is NOT incremented —
+    CPM fields (early_start, is_critical, etc.) are read-only computed values the
+    mobile client derives locally, and bumping server_version here would flood
+    every connected client with sync deltas on every recalc. Do NOT change the
+    call sites to ``save()`` without understanding that consequence.
+    """
+    tasks_to_update: list[Any] = []
+    old_cpm_dates: dict[str, tuple[Any, Any, Any, Any]] = {}
+    moved_tasks: list[Any] = []
+    for db_task in db_tasks:
+        # One `str(UUID)` for the row, reused by all three lookups below. Same
+        # rationale as the `attrgetter` snapshot above: this loop runs once per task
+        # and the conversion is not free at 5,000 rows.
+        task_key = str(db_task.id)
+        sched = result_map.get(task_key)
+        if sched is None:
+            continue
+        old_cpm_dates[task_key] = (
+            db_task.early_start,
+            db_task.early_finish,
+            db_task.late_start,
+            db_task.late_finish,
+        )
+        before = _cpm_delta_snapshot(db_task)
+        db_task.early_start = sched.early_start
+        db_task.early_finish = sched.early_finish
+        db_task.late_start = sched.late_start
+        db_task.late_finish = sched.late_finish
+        # `is not None`, NOT truthiness: bool(timedelta(0)) is False, so a truthy
+        # test writes NULL for zero float — the defining value of every
+        # critical-path task. NULL means "not scheduled"; 0 means "no slack", and
+        # collapsing the two blanked the Float cell on exactly the tasks a PM
+        # inspects and made capture_forecast_snapshot's Min("total_float") skip
+        # them, reporting the project's tightest slack as the smallest *positive*
+        # float on the plan (#2802).
+        db_task.total_float = sched.total_float.days if sched.total_float is not None else None
+        db_task.free_float = sched.free_float.days if sched.free_float is not None else None
+        db_task.is_critical = sched.is_critical
+        # ADR-0752: the task's span start, distinct from early_start's
+        # remaining-work window.
+        db_task.scheduled_start = sched.scheduled_start
+        # Belt-and-suspenders: milestones are single-point gates. Even if the
+        # boundary normalisation is bypassed, a milestone's finish must equal its
+        # start so client-facing rows never render a date range.
+        if db_task.is_milestone:
+            db_task.early_finish = db_task.early_start
+            db_task.late_finish = db_task.late_start
+        # For summary tasks, overwrite duration with the WORKING-day span of the
+        # rolled-up window, so the stored value means what the column documents and
+        # what every consumer of it assumes (#3530). Precomputed by
+        # `summary_working_day_durations` — the calendar walk is batched per
+        # calendar rather than run inside this hot loop. `summary_durations` is keyed
+        # exclusively by summary id, so the lookup IS the summary test; a leaf misses
+        # it, and so does a summary the engine did not roll up (which keeps its
+        # stored duration rather than getting a wrong one).
+        new_duration = summary_durations.get(task_key)
+        if new_duration is not None:
+            db_task.duration = new_duration
+        tasks_to_update.append(db_task)
+        if _cpm_delta_snapshot(db_task) != before:
+            moved_tasks.append(db_task)
+    return tasks_to_update, old_cpm_dates, moved_tasks
+
+
+def _apply_driving_flags(deps: list[Any], driving_edges: Iterable[Any]) -> None:
+    """Set ``is_driving`` on each stored Dependency whose edge has zero relationship
+    free float (#2095).
+
+    Keyed by ``(predecessor_id, successor_id, dep_type)`` on leaf task ids exactly
+    as the engine reports; summary-level edges (expanded before CPM) carry no
+    driving fact and stay non-driving (the visual default). bulk_update at the call
+    site bypasses ``VersionedModel.save`` — is_driving is a derived CPM output, not
+    a user edit, and must not trigger a mobile-sync pull.
+    """
+    driving_edge_keys = {(e.predecessor_id, e.successor_id, e.dep_type) for e in driving_edges}
+    for dep in deps:
+        dep.is_driving = (
+            str(dep.predecessor_id),
+            str(dep.successor_id),
+            dep.dep_type,
+        ) in driving_edge_keys
+
+
+def _clear_output_of_fully_groomed_project(project_id: str) -> None:
+    """Clear stale CPM output for a project whose committed set is empty.
+
+    Deliberately separate from the run's ``_settle_empty()``: its other callers are
+    the project-not-found path (nothing to clear) and the two escalate-to-program
+    paths, where the program run is the sole writer and clears the whole program's
+    project set itself.
+    """
+    from trueppm_api.apps.projects.models import Task
+
+    cleared = clear_uncommitted_cpm_output(Task, project_ids=[project_id])
+    if cleared:
+        logger.info(
+            "recalculate_schedule: project %s cleared CPM output on %d unscheduled row(s)",
+            project_id,
+            cleared,
+        )
+
+
+def _persist_driving_flags_and_shift_events(
+    db_deps: list[Any], schedule_shift_events: list[Any]
+) -> None:
+    """Persist driving-link flags and schedule-shift events inside the caller's atomic block.
+
+    bulk_update bypasses VersionedModel.save so it never bumps server_version —
+    is_driving is a derived CPM output, not a user edit, and must not trigger a
+    mobile-sync pull (same rationale as Task).
+    """
+    from trueppm_api.apps.projects.models import Dependency, TaskActivityEvent
+
+    if db_deps:
+        Dependency.objects.bulk_update(db_deps, ["is_driving"], batch_size=_WRITEBACK_BATCH_SIZE)
+    if schedule_shift_events:
+        TaskActivityEvent.objects.bulk_create(
+            schedule_shift_events, batch_size=_WRITEBACK_BATCH_SIZE
+        )
+
+
+def _run_schedule(
+    project_id: str,
+    tracker: object = None,
+) -> None:
+    """Load tasks/dependencies, run CPM, bulk_update results, broadcast completion.
+
+    CPM runs on the full project and every affected task's results are written
+    back. The engine-level incremental recompute (recompute only the changed
+    subgraph) is tracked under #235 (0.5, ADR-0027).
+
+    Args:
+        project_id: UUID string of the project to schedule.
+        tracker: Optional TaskRunTracker for progress reporting.
+    """
+    from trueppm_scheduler.engine import schedule
+    from trueppm_scheduler.models import Dependency as SchedDependency
+    from trueppm_scheduler.models import DependencyType
+    from trueppm_scheduler.models import Project as SchedProject
+
+    from trueppm_api.apps.observability.otel import attributes
+    from trueppm_api.apps.projects.models import (
+        Dependency,
+        EstimationMode,
+        Project,
+        Task,
+        TaskStatus,
+        TaskType,
+    )
+    from trueppm_api.apps.scheduling.calendars import compose_project_calendar
+    from trueppm_api.apps.scheduling.services import (
+        apply_summary_rollups,
+        build_sched_graph,
+        build_sched_tasks,
+        resolve_cpm_status_date,
+    )
+    from trueppm_api.apps.scheduling.telemetry import cpm_span
+
+    def _update(pct: int, msg: str) -> None:
+        if tracker is not None:
+            tracker.update(pct, msg)  # type: ignore[attr-defined]
+
+    def _settle_empty() -> None:
+        """Record a dateless-but-settled result on paths that return before the
+        CPM write. Without this the tracker emits task_run_completed with
+        result_summary=None, which the web client cannot distinguish from an
+        in-flight run, so the "Recalculating…" badge spins forever (#1976). The
+        frontend also clears on any completed scheduling run; this keeps the
+        result_summary a non-null object for audit and other API consumers."""
+        if tracker is not None:
+            tracker.set_result({"project_finish": None, "critical_path": []})  # type: ignore[attr-defined]
+
+    _update(10, "Loading project data…")
+
+    try:
+        db_project = (
+            Project.objects.select_related("calendar", "program__calendar")
+            # tasks__sprint: build_sched_tasks reads each task's sprint.start_date
+            # for the ADR-0168 sprint-window floor; prefetch it to avoid an N+1.
+            # calendar__exceptions + calendar_layers__calendar__exceptions:
+            # compose_project_calendar reads every CalendarException row of the
+            # base calendar (#1491) AND of every applied overlay (#906); prefetch
+            # both to avoid an N+1. program__calendar__exceptions: when the project
+            # inherits its base calendar from the program (ADR-0441), the resolver
+            # reads the program calendar's exceptions too — prefetch to avoid an N+1.
+            .prefetch_related(
+                "tasks",
+                "tasks__sprint",
+                "tasks__predecessors",
+                "calendar__exceptions",
+                "calendar_layers__calendar__exceptions",
+                "program__calendar__exceptions",
+            )
+            .get(pk=project_id)
+        )
+    except Project.DoesNotExist:
+        logger.warning("recalculate_schedule: project %s not found, skipping", project_id)
+        _settle_empty()
+        return
+
+    # ADR-0752 §4/§7: resolve the floor once, up front, from the state this
+    # project was loaded in — before anything below can mutate it. A project
+    # with no explicit status_date and no prior arming is about to have its
+    # floor armed for the first time by *this* recalculation.
+    resolved_status_date = resolve_cpm_status_date(db_project.status_date)
+    is_first_status_date_floor_use = (
+        db_project.status_date is None and db_project.status_date_floor_armed_at is None
+    )
+
+    # ADR-0120 D3: if this project belongs to a program that has ≥1 accepted
+    # cross-project edge, a single-project CPM would compute program-FALSE floats
+    # and criticality (it cannot see the cross-boundary demand). Escalate to the
+    # merged program-scoped pass and stop here, *before* any write — the program
+    # run is the sole writer for every member project while escalation holds, so no
+    # stale single-project dates are ever persisted. The DISPATCHED outbox row is
+    # left for the program run to mark done.
+    if _escalate_to_program(project_id, db_project.program_id):
+        _settle_empty()
+        return
+
+    # Exclude recurrence templates and their generated occurrences from the CPM feed.
+    # Recurring tasks are parallel, calendar-driven activities — admitting them to the
+    # scheduling engine would corrupt float, the critical path, and Monte Carlo
+    # P50/P80/P95. is_recurring is the single load-bearing exclusion key (ADR-0090);
+    # CommittedTaskManager applies the same filter for Monte Carlo / capacity / PDF.
+    #
+    # type=EPIC is excluded for the same reason (ADR-0105): an epic is a grouping
+    # node, not schedulable work — its rollup dates are computed from child stories, not
+    # fed to CPM. CommittedTaskManager applies the matching exclusion at its boundary.
+    #
+    # status=BACKLOG and soft-deleted tombstones are excluded so the deterministic CPM
+    # feed matches CommittedTaskManager exactly (#1772). Monte Carlo already reads from
+    # Task.committed; feeding CPM from the unfiltered manager let backlog ideas and
+    # deleted rows into the network, so grooming the backlog could move the deterministic
+    # critical path and the two engines could structurally disagree on the Overview page.
+    # Filtered in Python so the prefetch cache from the queryset above is reused.
+    db_tasks = [
+        t
+        for t in db_project.tasks.all()
+        if not t.is_recurring
+        and t.type != TaskType.EPIC
+        and t.status != TaskStatus.BACKLOG
+        and not t.is_deleted
+    ]
+    if not db_tasks:
+        logger.info("recalculate_schedule: project %s has no tasks, skipping", project_id)
+        # ADR-1152: a project whose entire committed set was groomed away still holds
+        # every row's last schedule, and this return is BEFORE the write-back — so the
+        # worst case (100% of rows stale) is exactly the one the atomic block below
+        # never reaches. Clear here so the invariant holds on this path too (#3578).
+        # Deliberately NOT inside _settle_empty(): its other three callers are the
+        # project-not-found path (nothing to clear) and the two escalate-to-program
+        # paths, where the program run is the sole writer and clears the whole
+        # program's project set itself.
+        _clear_output_of_fully_groomed_project(project_id)
+        _settle_empty()
+        return
+
+    _update(25, "Building schedule model…")
+
+    # Build a trueppm_scheduler.Calendar from the OVERLAY of the project's applied
+    # calendars — base + holiday/shutdown overlays — as one composed non-working
+    # mask (#906, ADR-0251). Routes through the shared composer so the CPM pass,
+    # Monte Carlo, and program scheduling can never drift on which calendars apply.
+    sched_calendar = compose_project_calendar(db_project)
+
+    # Convert Django Task objects to scheduler dataclasses through the shared
+    # converter (ADR-0132), the single source of truth the Monte Carlo endpoint
+    # also uses — so progress/actual fields and milestone normalisation can never
+    # drift between the two engines (the cause of #1185). The suggest_approve gate
+    # is a no-op for the deterministic CPM pass (which ignores PERT) but is passed
+    # for parity so both paths run identical code.
+    sched_tasks = build_sched_tasks(
+        db_tasks,
+        suggest_approve=db_project.estimation_mode == EstimationMode.SUGGEST_APPROVE,
+    )
+
+    # Convert Django Dependency objects to scheduler dataclasses. Drop any edge that
+    # touches an excluded (recurring) task — its endpoint is absent from sched_tasks,
+    # so handing it to the engine would create a dangling dependency. See ADR-0090.
+    included_ids = {str(t.id) for t in db_tasks}
+    # Dependency.live, not .objects: a soft-deleted edge is a deleted constraint.
+    # Feeding it to the engine keeps a link the user removed in the UI binding the
+    # persisted CPM dates forever (#3532).
+    db_deps = list(
+        Dependency.live.filter(predecessor__project_id=project_id).select_related(
+            "predecessor", "successor"
+        )
+    )
+    sched_deps = [
+        SchedDependency(
+            predecessor_id=str(d.predecessor_id),
+            successor_id=str(d.successor_id),
+            dep_type=DependencyType(d.dep_type),
+            lag=timedelta(days=d.lag),
+        )
+        for d in db_deps
+        if str(d.predecessor_id) in included_ids and str(d.successor_id) in included_ids
+    ]
+
+    # Strip summary rows and fan their edges down to leaves before CPM (ADR-0105).
+    # Shared with every Monte Carlo path since #3527 — one shaping step, one network.
+    db_task_by_id = {str(t.id): t for t in db_tasks}
+    graph = build_sched_graph(db_tasks, sched_tasks, sched_deps)
+    children_map = graph.children_map
+    summary_ids = graph.summary_ids
+    leaf_tasks, expanded_deps = graph.tasks, graph.dependencies
+
+    sched_project = SchedProject(
+        id=project_id,
+        name=db_project.name,
+        start_date=db_project.start_date,
+        tasks=leaf_tasks,
+        dependencies=expanded_deps,
+        calendar=sched_calendar,
+        # The stored plan honors recorded actuals (completed tasks pin, in-progress
+        # tasks use remaining duration) always, and floors not-started work at the
+        # data date: the PM's explicit status_date when set, otherwise today
+        # (resolved once, above, as resolved_status_date — ADR-0752 §4, correcting
+        # ADR-0132 §1). The deterministic CPM pass and the Monte Carlo forecast now
+        # share this same resolution; the CPM path no longer passes a null
+        # status_date raw (which previously meant "no floor at all").
+        status_date=resolved_status_date,
+    )
+
+    _update(50, "Running CPM…")
+
+    # Exceptions propagate to TaskRunTracker.__exit__, which marks the run FAILED
+    # and broadcasts task_run_failed to connected clients. The manual CPM span
+    # (#709) times the engine call and records the graph shape; it is a no-op span
+    # unless OTel export is configured. Runs inside the enqueued Celery task span,
+    # so the trace links the recompute back to the request that triggered it.
+    with cpm_span(project_id, dependency_count=len(sched_deps)) as _cpm_span:
+        result = schedule(sched_project)
+        _cpm_span.set_attribute(attributes.SCHEDULE_TASK_COUNT, len(result.tasks))
+        _cpm_span.set_attribute(attributes.SCHEDULE_CRITICAL_COUNT, len(result.critical_path))
+
+    _update(80, "Writing results…")
+
+    # Build a map from task id string to computed CPM values.
+    result_map = {t.id: t for t in result.tasks}
+
+    # Compute summary task dates by rolling up from their leaf descendants
+    # (ADR-0105) via the shared helper, so this single-project write-back and the
+    # program-scoped write-back derive summary dates through identical code.
+    apply_summary_rollups(result_map, summary_ids, children_map, db_task_by_id)
+
+    # Working-day duration for each rolled-up summary (#3530), on the project's own
+    # composed calendar — the same one the CPM pass just ran on.
+    summary_durations = summary_working_day_durations(
+        result_map, summary_ids, db_task_by_id, {str(db_project.pk): sched_calendar}
+    )
+
+    # Driving-link flags (#2095): set in memory here and persisted via bulk_update
+    # below (like Task CPM fields — no server_version bump).
+    _apply_driving_flags(db_deps, result.driving_edges)
+
+    # Write CPM results back for every task the engine returned (server_version is
+    # intentionally NOT bumped — see _apply_cpm_results). old_cpm_dates snapshots
+    # each task's dates before the overwrite so the shift-events helper can tell
+    # which tasks actually moved (ADR-0207); moved_tasks is that same moved subset
+    # as a list, and is what the ADR-0091 delta broadcast ships (#2573).
+    tasks_to_update, old_cpm_dates, moved_tasks = _apply_cpm_results(
+        db_tasks, result_map, summary_durations
+    )
+
+    # ADR-0752 §7: the suppression only makes sense once there is a prior
+    # schedule to have moved *from*. A project's very first-ever CPM pass
+    # transitions every task from null to computed — exactly like any other
+    # first schedule, floor or no floor — and is not the "someone moved my
+    # schedule" confusion this ADR guards against, so it is reported normally
+    # (matching the existing null -> computed behavior). is_first_status_date_
+    # floor_use still governs whether the armed flag gets persisted below,
+    # regardless of this refinement, so the *next* recalculation is never
+    # treated as arming again.
+    is_arming_status_date_floor = is_first_status_date_floor_use and any(
+        old[0] is not None for old in old_cpm_dates.values()
+    )
+
+    from django.db import transaction
+
+    from trueppm_api.apps.scheduling.models import ScheduleRequest, ScheduleRequestStatus
+
+    cpm_payload: dict[str, object] = {
+        "project_finish": result.project_finish.isoformat(),
+        "critical_path": result.critical_path,
+        # The data date this run was actually computed against (ADR-0752 §4) —
+        # echoed unconditionally (including on the arming run) so every consumer
+        # of cpm_complete/task_run_completed/the schedule.recalculated webhook
+        # knows which "today" produced these dates, mirroring the MC status_date
+        # provenance convention (#2638).
+        "status_date": resolved_status_date.isoformat(),
+    }
+
+    # Per-task CPM date deltas (ADR-0091). Broadcast the tasks whose dates just moved so
+    # collaborators' Gantt bars slide in real time, with no full re-fetch. Built from
+    # moved_tasks (already in scope, fields mutated in-memory) so it costs no query.
+    # It MUST be the moved subset, not the full write-back set: a CPM pass re-assigns
+    # every engine-returned row, so shipping tasks_to_update put any project over
+    # CPM_DELTA_BROADCAST_CAP permanently into the truncated branch and turned every
+    # single-field edit into a full paginated re-fetch per connected client (#2573).
+    # Best-effort, same tier as cpm_complete. Field names mirror SyncTaskSerializer so the
+    # web client can splice the payload straight into its task cache (and a future mobile
+    # client could too); the server_version carve-out above is preserved — this is an
+    # optimization layer over the sync protocol, not a replacement for it. server_version
+    # is intentionally NOT in the payload: clients splice these as optimistic CPM updates,
+    # they are not a sync anchor (bulk_update bypasses VersionedModel.save(), ADR-0091).
+    # Built via the shared helper so the single-project and program-pass deltas (and
+    # their >CPM_DELTA_BROADCAST_CAP truncation) can never drift.
+    delta_payload = _member_cpm_delta(moved_tasks)
+
+    # Persist results and mark the outbox row done in a single transaction, and
+    # defer the board broadcasts to on_commit (#896). Previously the bulk_update
+    # and the two broadcasts ran in autocommit, *before* the ScheduleRequest
+    # status update — a failure on that update (e.g. a lost DB connection) left
+    # clients showing CPM dates that were never committed. Wrapping the writes in
+    # one atomic block and registering the broadcasts with transaction.on_commit
+    # means clients only ever see dates that actually persisted; a rollback
+    # broadcasts nothing. Default-arg binding pins the payloads so the deferred
+    # callbacks can't late-bind a mutated value.
+    # ADR-0120 D3 pre-write guard: a cross-project edge may have been accepted
+    # while this single-project CPM was running. Re-check the escalation predicate
+    # immediately before the write — if the program now has an accepted cross edge,
+    # discard this (now program-FALSE) single-project result and hand off to the
+    # program pass rather than persisting stale single-project dates. Cheap EXISTS.
+    if _escalate_to_program(project_id, db_project.program_id):
+        _settle_empty()
+        return
+
+    # Per-task schedule-shift activity events (ADR-0207, #1604), built from the
+    # mutated in-memory tasks and the project's active baseline. Written inside the
+    # same atomic block as the writeback so they commit or roll back with it.
+    # suppress_movement_events (ADR-0752 §7) withholds the cpm_recalculated rows
+    # on this project's one-shot floor-arming recalculation only.
+    schedule_shift_events = _build_schedule_shift_events(
+        tasks_to_update,
+        old_cpm_dates,
+        _active_baseline_finishes([project_id]),
+        suppress_movement_events=is_arming_status_date_floor,
+    )
+
+    with transaction.atomic():
+        Task.objects.bulk_update(
+            tasks_to_update,
+            [
+                "early_start",
+                "early_finish",
+                "late_start",
+                "late_finish",
+                "total_float",
+                "free_float",
+                "is_critical",
+                "duration",
+                "scheduled_start",
+            ],
+            batch_size=_WRITEBACK_BATCH_SIZE,
+        )
+
+        # ADR-1152 (#3578): the write-back above covers only the rows the engine
+        # returned, which is the committed set. Rows that LEFT it keep their last
+        # schedule forever unless something clears them, and nothing did — so a
+        # groomed-out card was still read as current by the task serializer and by
+        # nine project-level aggregates over Task.objects. Same atomic block as the
+        # bulk_update on purpose: the committed set's new dates and the non-committed
+        # set's nulls are one consistent picture, or neither lands.
+        clear_uncommitted_cpm_output(Task, project_ids=[project_id])
+
+        # Persist driving-link flags (#2095). bulk_update bypasses VersionedModel.save
+        # so it never bumps server_version — is_driving is a derived CPM output, not a
+        # user edit, and must not trigger a mobile-sync pull (same rationale as Task).
+        _persist_driving_flags_and_shift_events(db_deps, schedule_shift_events)
+
+        # Mark the outbox row done so the drain task knows this project is clean.
+        # Filter on status=dispatched to avoid racing with the drain during orphan
+        # recovery (which resets rows back to pending).
+        ScheduleRequest.objects.filter(
+            project_id=project_id, status=ScheduleRequestStatus.DISPATCHED
+        ).update(status=ScheduleRequestStatus.DONE)
+
+        # ADR-0752 §4/§7: persist the one-shot arming flag (if this is the
+        # first use of the floor) and register the on-commit broadcasts,
+        # withholding the per-task movement broadcast on the arming run.
+        # Extracted to its own function to keep this transaction block's
+        # branching flat.
+        _finalize_status_date_floor_arming(
+            project_id,
+            cpm_payload=cpm_payload,
+            delta_payload=delta_payload,
+            is_first_status_date_floor_use=is_first_status_date_floor_use,
+            is_arming_status_date_floor=is_arming_status_date_floor,
+        )
+
+        # Capture a project-grain forecast snapshot for drift history (ADR-0154,
+        # #388). Strictly post-commit and best-effort: a capture failure must never
+        # roll back the CPM write above. Any miss is backfilled by the daily-floor
+        # task, so we do not need an outbox here.
+        def _capture_forecast(pid: str = project_id) -> None:
+            from trueppm_api.apps.scheduling.models import ForecastSnapshotTrigger
+            from trueppm_api.apps.scheduling.services import safe_capture_forecast_snapshot
+
+            safe_capture_forecast_snapshot(pid, ForecastSnapshotTrigger.RECOMPUTE)
+
+        transaction.on_commit(_capture_forecast)
+
+    logger.info(
+        "recalculate_schedule: updated %d tasks for project %s (finish=%s)",
+        len(tasks_to_update),
+        project_id,
+        result.project_finish,
+    )
+
+    # Store CPM result summary for audit / frontend access.
+    if tracker is not None:
+        tracker.set_result(cpm_payload)  # type: ignore[attr-defined]
+
+    # Dispatch schedule.recalculated webhook to external subscribers. Fired after
+    # the transaction so subscribers are only notified of committed results.
+    from trueppm_api.apps.webhooks.dispatch import dispatch_webhooks
+
+    dispatch_webhooks(
+        project_id=project_id,
+        event_type="schedule.recalculated",
+        payload={"project": project_id, **cpm_payload},
+    )
+
+
+def _broadcast_cpm_complete(
+    *,
+    project_id: str,
+    project_finish: str | None,
+    critical_path: list[str],
+    status_date: str | None,
+) -> None:
+    """Emit ``cpm_complete`` with the one payload shape shared by both CPM passes.
+
+    Both the single-project write-back (``_finalize_status_date_floor_arming``)
+    and the program-scoped write-back (``_register_program_broadcasts``) route
+    through this one function so the two passes can never again drift on this
+    event's keys (#3776 — before this fix they built the payload as two
+    separate dict *variables*, one carrying ``status_date`` and one not, and
+    both landed in ``test_broadcast_payload_shape.py``'s unscannable bucket,
+    which is exactly what let the drift go undetected). The literal dict below
+    is what makes this call site — now the *only* ``cpm_complete`` call site —
+    scannable by that gate instead of contributing two entries to it.
+
+    Call from inside a ``transaction.on_commit()`` registration (via
+    ``functools.partial`` to pin the arguments at registration time, matching
+    the default-arg-binding pattern used elsewhere in this module) so clients
+    only ever see a payload for a write that actually committed.
+
+    ``status_date`` is the CPM data date this run resolved (ADR-0752 §4),
+    echoed so a consumer knows which "today" produced these dates. It is
+    ``None`` on the program-scoped pass: ``gather_program_schedule`` runs the
+    merged engine with ``status_date=None`` on purpose, because member
+    projects can carry different ``status_date`` values and no single one
+    would honestly describe what the merged pass floored against — the
+    program view shows the earliest honest schedule, not a data-date floor.
+    Echoing ``None`` states that plainly rather than fabricating a value or
+    silently dropping the key.
+    """
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    broadcast_board_event(
+        project_id=project_id,
+        event_type="cpm_complete",
+        payload={
+            "project_finish": project_finish,
+            "critical_path": critical_path,
+            "status_date": status_date,
+        },
+    )
+
+
+def _finalize_status_date_floor_arming(
+    project_id: str,
+    *,
+    cpm_payload: dict[str, object],
+    delta_payload: dict[str, object],
+    is_first_status_date_floor_use: bool,
+    is_arming_status_date_floor: bool,
+) -> None:
+    """Persist the one-shot arming flag and register the on-commit CPM broadcasts.
+
+    ADR-0752 §4/§7: ``is_first_status_date_floor_use`` marks the recalculation
+    that first resolves this project's null ``status_date`` to today — the
+    armed flag is persisted here so no later recalculation is ever treated as
+    the first use again. ``is_arming_status_date_floor`` is the narrower
+    condition that actually withholds the ADR-0091 ``task_dates_updated``
+    per-task delta broadcast: first use *and* at least one task already had a
+    prior computed date (i.e. this is a genuine correction to an established
+    schedule, not a brand-new project's first-ever pass, which reports
+    null -> computed transitions exactly like it always has). This is the
+    pub/sub surface the §10 threat model names explicitly; suppressing only
+    the ``cpm_recalculated`` TaskActivityEvent rows (see
+    ``_build_schedule_shift_events``) and still firing this broadcast would
+    let the same movement reach connected clients as ordinary activity through
+    a different channel. ``cpm_complete`` still fires unconditionally,
+    including on the arming run — it carries ``project_finish``/
+    ``status_date``, not per-task movement, so it is not part of what §7
+    suppresses.
+
+    MUST be called from inside the writeback's ``transaction.atomic()`` block,
+    matching ``_register_program_broadcasts`` below: the ``.update()`` call
+    needs to commit or roll back with the Task writeback, and ``on_commit``
+    callbacks must be registered before that block exits. Default-arg binding
+    (and, for ``cpm_complete``, ``functools.partial``) pins each payload
+    against late mutation.
+    """
+    from typing import cast
+
+    from django.db import transaction
+    from django.utils import timezone
+
+    from trueppm_api.apps.projects.models import Project
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    if is_first_status_date_floor_use:
+        # A plain .update() bypasses VersionedModel.save() — no server_version
+        # bump, no history row, no mobile-sync pull — for this server-owned
+        # bookkeeping field, matching the existing recalculated_at pattern.
+        Project.objects.filter(pk=project_id).update(status_date_floor_armed_at=timezone.now())
+
+    # Routed through the shared _broadcast_cpm_complete() (#3776) so this and
+    # the program-scoped pass can never again ship cpm_complete with different
+    # keys. functools.partial evaluates its keyword arguments immediately,
+    # pinning cpm_payload's fields at registration time exactly like the
+    # default-arg pattern used for task_dates_updated just below. The casts
+    # only narrow cpm_payload's declared dict[str, object] value type back to
+    # what _run_schedule actually put there (str project_finish/status_date,
+    # list[str] critical_path) — this function never sees a program-pass
+    # cpm_payload, whose caller passes its own concretely-typed values instead.
+    transaction.on_commit(
+        functools.partial(
+            _broadcast_cpm_complete,
+            project_id=project_id,
+            project_finish=cast("str", cpm_payload["project_finish"]),
+            critical_path=cast("list[str]", cpm_payload["critical_path"]),
+            status_date=cast("str", cpm_payload["status_date"]),
+        )
+    )
+
+    if not is_arming_status_date_floor:
+
+        def _broadcast_dates(pid: str = project_id, pay: dict[str, object] = delta_payload) -> None:
+            broadcast_board_event(project_id=pid, event_type="task_dates_updated", payload=pay)
+
+        transaction.on_commit(_broadcast_dates)
+
+
+# ---------------------------------------------------------------------------
+# Program-scoped CPM dispatch pass — ADR-0120 D3 (#1117)
+# ---------------------------------------------------------------------------
+
+
+def _escalate_to_program(project_id: str, program_id: object) -> bool:
+    """Dispatch the program-scoped pass instead of a single-project one, if needed.
+
+    Returns ``True`` when the project's program has ≥1 accepted cross-project edge
+    (ADR-0120 D3) and a ``recalculate_program_schedule`` was dispatched (best
+    effort) — the caller must then return *without* writing single-project results,
+    because a single-project CPM cannot see the cross-boundary demand and would
+    persist program-FALSE floats/criticality. ``False`` keeps today's per-project
+    path. If the dispatch itself fails (broker down) the outbox row stays
+    DISPATCHED and the 10-minute orphan sweep re-escalates it — so this never
+    silently drops the recompute.
+    """
+    if program_id is None:
+        return False
+    from trueppm_api.apps.projects.program_schedule import program_has_accepted_cross_edges
+
+    if not program_has_accepted_cross_edges(program_id):
+        return False
+    try:
+        recalculate_program_schedule.delay(str(program_id))
+    except Exception:
+        logger.exception(
+            "recalculate_schedule: could not dispatch program pass for program %s "
+            "— orphan recovery will re-escalate within 10 min",
+            program_id,
+        )
+    return True
+
+
+@idempotent_task(
+    lock_key_template="schedule_lock:program:{0}",
+    lock_ttl=300,
+    on_contention="queue",
+    queue_countdown=10,
+    max_queue_attempts=30,
+    autoretry_for=_RETRIABLE,
+    retry_backoff=30,
+    retry_backoff_max=300,
+    retry_jitter=True,
+    max_retries=3,
+    soft_time_limit=480,
+    time_limit=600,
+    acks_late=True,
+    reject_on_worker_lost=True,
+)
+def recalculate_program_schedule(self: object, program_id: str) -> None:
+    """Run the merged, program-true CPM for one program and persist it (ADR-0120 D3).
+
+    Escalated to from ``recalculate_schedule`` whenever a member project's program
+    holds ≥1 accepted cross-project edge. It merges every member project's tasks
+    and every accepted cross edge into one engine graph (the shared
+    ``gather_program_schedule``), runs CPM once, writes program-true CPM fields back
+    to every member project, fans the ``cpm_complete`` / ``task_dates_updated``
+    broadcasts out to each member project's board channel (there is no program WS
+    channel in 0.3 — the program view subscribes per member project), upserts any
+    D4 sprint-boundary conflicts, and coalesces every member project's outbox row.
+
+    Idempotent: a pure recompute, safe to run twice. ``schedule_lock:program:{id}``
+    serializes program runs; ``max_queue_attempts`` is sized so contenders ride out
+    a held lock rather than dropping, and the outbox orphan sweep is the backstop on
+    a crash. The lock namespace is disjoint from the per-project ``schedule_lock:{id}``,
+    but a per-project task can never *write* while escalation holds (it self-aborts
+    at the pre-write guard), so the two never produce a torn write.
+    """
+    _run_program_schedule(program_id)
+
+
+def _member_cpm_delta(moved_tasks: list[Any]) -> dict[str, object]:
+    """Build one project's ``task_dates_updated`` delta payload (ADR-0091 shape).
+
+    ``moved_tasks`` must be the *changed set* — only the rows whose CPM fields
+    actually moved this pass — not the full write-back set. ``count`` is therefore
+    the moved-task count in both branches, as ADR-0091 specifies. Mirrors the
+    single-project delta exactly so a web client can splice program-pass results
+    into its task cache the same way; above ``CPM_DELTA_BROADCAST_CAP`` it emits a
+    ``truncated`` signal and lets the client re-fetch.
+    """
+    if len(moved_tasks) > CPM_DELTA_BROADCAST_CAP:
+        return {"count": len(moved_tasks), "truncated": True}
+    return {
+        "count": len(moved_tasks),
+        "tasks": [
+            {
+                "id": str(t.id),
+                "early_start": t.early_start.isoformat() if t.early_start else None,
+                "early_finish": t.early_finish.isoformat() if t.early_finish else None,
+                "late_start": t.late_start.isoformat() if t.late_start else None,
+                "late_finish": t.late_finish.isoformat() if t.late_finish else None,
+                "total_float": t.total_float,
+                "free_float": t.free_float,
+                "is_critical": t.is_critical,
+                "planned_start": t.planned_start.isoformat() if t.planned_start else None,
+                "duration": t.duration,
+                # ADR-0752: the task's span start, distinct from early_start's
+                # remaining-work window. Reaches the same project subscribers
+                # early_start already does — no new field-leak (ADR §10).
+                "scheduled_start": t.scheduled_start.isoformat() if t.scheduled_start else None,
+            }
+            for t in moved_tasks
+        ],
+    }
+
+
+_PROGRAM_WRITE_FIELDS = [
+    "early_start",
+    "early_finish",
+    "late_start",
+    "late_finish",
+    "total_float",
+    "free_float",
+    "is_critical",
+    "duration",
+    "scheduled_start",
+]
+
+
+def _register_program_broadcasts(
+    graph: Any,
+    by_project: dict[object, list[Any]],
+    moved_by_project: dict[object, list[Any]],
+    crit_order: list[str],
+) -> None:
+    """Register each member project's post-commit broadcasts for a program pass.
+
+    Ships a ``cpm_complete`` (full program-true critical path restricted to the
+    project) and ``task_dates_updated`` delta per project, plus a forecast-capture,
+    all deferred to commit (#896) so clients only ever see dates that persisted; a
+    rollback broadcasts nothing. MUST be called from inside the writeback's
+    ``transaction.atomic()`` block. Default-arg binding (``task_dates_updated``,
+    the forecast capture) and ``functools.partial`` (``cpm_complete``, via the
+    shared ``_broadcast_cpm_complete()``) both pin each project's payload against
+    late mutation from this loop's next iteration.
+
+    Two groupings, deliberately: ``by_project`` is the full write-back set and
+    defines each project's ``project_finish`` (an *unmoved* late task still sets
+    where finish sits), while ``moved_by_project`` is the changed subset the
+    ADR-0091 delta ships (#2573). Collapsing them would either mis-report the
+    finish or re-introduce the full-project delta.
+    """
+    from django.db import transaction
+
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    for p in graph.member_projects:
+        pid = str(p.id)
+        project_tasks = by_project.get(p.id, [])
+        # The project's full program-true critical path — every critical task in this
+        # project, NOT just the ones whose dates moved this pass (a client that
+        # replaces its critical-path state on cpm_complete must get the whole set,
+        # matching the single-project _run_schedule which ships the full path).
+        project_crit = [
+            tid
+            for tid in crit_order
+            if tid in graph.db_task_by_id and graph.db_task_by_id[tid].project_id == p.id
+        ]
+        project_finish = max(
+            (t.early_finish for t in project_tasks if t.early_finish is not None),
+            default=None,
+        )
+        delta_payload = _member_cpm_delta(moved_by_project.get(p.id, []))
+
+        def _dates(pid: str = pid, pay: dict[str, object] = delta_payload) -> None:
+            broadcast_board_event(project_id=pid, event_type="task_dates_updated", payload=pay)
+
+        def _capture(pid: str = pid) -> None:
+            from trueppm_api.apps.scheduling.models import ForecastSnapshotTrigger
+            from trueppm_api.apps.scheduling.services import safe_capture_forecast_snapshot
+
+            safe_capture_forecast_snapshot(pid, ForecastSnapshotTrigger.RECOMPUTE)
+
+        # Routed through the shared _broadcast_cpm_complete() (#3776) so this
+        # pass and the single-project write-back can never again ship
+        # cpm_complete with different keys — status_date=None documents that
+        # the merged program pass floors nothing (see that function's
+        # docstring). functools.partial pins pid/project_finish/project_crit
+        # at this loop iteration, same as the default-arg pattern _dates and
+        # _capture use just above.
+        transaction.on_commit(
+            functools.partial(
+                _broadcast_cpm_complete,
+                project_id=pid,
+                project_finish=project_finish.isoformat() if project_finish else None,
+                critical_path=project_crit,
+                status_date=None,
+            )
+        )
+        transaction.on_commit(_dates)
+        transaction.on_commit(_capture)
+
+
+def _run_program_schedule(program_id: str) -> None:
+    """Gather, run, and persist the program-true schedule for ``program_id``.
+
+    Extracted from the Celery task for testability — exercised directly by the
+    program-pass tests without a broker.
+    """
+    from django.db import transaction
+    from django.utils import timezone
+
+    from trueppm_api.apps.projects.lifecycle import visible_projects
+    from trueppm_api.apps.projects.models import (
+        Dependency,
+        Program,
+        Project,
+        Task,
+        TaskActivityEvent,
+    )
+    from trueppm_api.apps.projects.program_schedule import gather_program_schedule
+    from trueppm_api.apps.projects.slip_conflict import detect_and_upsert_slip_conflicts
+    from trueppm_api.apps.scheduling.models import ScheduleRequest, ScheduleRequestStatus
+    from trueppm_api.apps.scheduling.services import apply_summary_rollups
+    from trueppm_api.apps.webhooks.dispatch import dispatch_webhooks
+
+    try:
+        program = Program.objects.get(pk=program_id, is_deleted=False)
+    except Program.DoesNotExist:
+        logger.warning("recalculate_program_schedule: program %s not found, skipping", program_id)
+        return
+
+    # Drafts are excluded (#2962/#3128) to stay consistent with
+    # ``gather_program_schedule``, which drops them from the merged graph. If this
+    # list still carried a draft, the pass would stamp ``recalculated_at`` on a
+    # project it never scheduled and drain its ScheduleRequests against a result
+    # that does not mention it.
+    member_ids = list(
+        visible_projects(
+            Project.objects.filter(program_id=program_id, is_deleted=False)
+        ).values_list("id", flat=True)
+    )
+    if not member_ids:
+        return
+
+    # CLAIM before reading data: capture exactly the member outbox rows that are
+    # already DISPATCHED. Only these row ids are marked DONE at the end, so a row
+    # dispatched *after* this point (a concurrent edit while we run) is never
+    # swallowed — it lands a fresh row and is serviced by the next pass.
+    claimed_ids = list(
+        ScheduleRequest.objects.filter(
+            project_id__in=member_ids, status=ScheduleRequestStatus.DISPATCHED
+        ).values_list("id", flat=True)
+    )
+
+    graph = gather_program_schedule(program, enforce_max=False)
+
+    now = timezone.now()
+    tasks_to_update: list[Task] = []
+    # The subset of tasks_to_update whose CPM fields actually moved — what the
+    # ADR-0091 delta broadcast ships (#2573).
+    moved_tasks: list[Task] = []
+    # Driving-link flags across every member project (#2095), persisted alongside
+    # the task write-back below. Empty when the program has no schedulable result.
+    program_db_deps: list[Dependency] = []
+    # Snapshot CPM dates before overwrite, for the schedule-shift events (ADR-0207).
+    old_cpm_dates: dict[str, tuple[Any, Any, Any, Any]] = {}
+    if graph.result is not None:
+        result_map = graph.result_map
+        # Roll summary dates up from leaves through the shared helper (parity with
+        # the single-project write-back).
+        summary_ids = graph.summary_ids
+        apply_summary_rollups(result_map, summary_ids, graph.children_map, graph.db_task_by_id)
+        # Working-day summary durations (#3530). ADR-0120 D3 holds one calendar per
+        # member project, so each summary is measured on its own project's working
+        # week rather than a single program-wide one.
+        summary_durations = summary_working_day_durations(
+            result_map, summary_ids, graph.db_task_by_id, graph.calendars
+        )
+        # Full write-back across every member project (the program pass is coarse;
+        # incremental subgraph writes are a later optimization). Shared helper with
+        # _run_schedule, so field assignment — milestone single-point normalisation
+        # and summary working-day duration included — can never drift.
+        tasks_to_update, old_cpm_dates, moved_tasks = _apply_cpm_results(
+            graph.db_task_by_id.values(), result_map, summary_durations
+        )
+
+        # Driving-link flags across the program (#2095), same shared helper as the
+        # single-project path; summary-level edges stay non-driving.
+        # Dependency.live: the driving-link flag is a CPM output, and the program
+        # graph this result came from already excluded soft-deleted edges
+        # (gather_program_schedule). Writing flags to a deleted edge would be
+        # scoring a constraint that is not in the network (#3532).
+        program_db_deps = list(Dependency.live.filter(predecessor__project_id__in=member_ids))
+        _apply_driving_flags(program_db_deps, graph.result.driving_edges)
+
+    # Group the full write-back set by project — this is what defines each member
+    # project's finish (an unmoved late task still sets where finish sits).
+    by_project: dict[object, list[Task]] = {}
+    for t in tasks_to_update:
+        by_project.setdefault(t.project_id, []).append(t)
+
+    # And the moved subset by project — this is what the ADR-0091 delta ships, so a
+    # program pass over many member projects does not force every subscriber into
+    # the truncated full-refetch branch (#2573).
+    moved_by_project: dict[object, list[Task]] = {}
+    for t in moved_tasks:
+        moved_by_project.setdefault(t.project_id, []).append(t)
+
+    # Program-true critical path restricted to each project (clients consuming a
+    # project's cpm_complete expect that project's critical ids).
+    crit_order = list(graph.result.critical_path) if graph.result is not None else []
+
+    # Per-task schedule-shift activity events across every member project (ADR-0207),
+    # keyed off each project's own active baseline for the drift crossings.
+    schedule_shift_events = _build_schedule_shift_events(
+        tasks_to_update, old_cpm_dates, _active_baseline_finishes(member_ids)
+    )
+
+    with transaction.atomic():
+        if tasks_to_update:
+            Task.objects.bulk_update(
+                tasks_to_update, _PROGRAM_WRITE_FIELDS, batch_size=_WRITEBACK_BATCH_SIZE
+            )
+
+        # ADR-1152 (#3578): mirror of the single-project clear. Scoped to every member
+        # project, NOT to the schedulable subset — a member whose whole committed set
+        # was groomed away contributes no rows to `tasks_to_update` yet is precisely
+        # the project holding the most residue. This also covers the two
+        # escalate-to-program returns in _run_schedule, which deliberately clear
+        # nothing themselves because the program run is the sole writer while
+        # escalation holds (ADR-0120 D3).
+        clear_uncommitted_cpm_output(Task, project_ids=member_ids)
+
+        # Persist driving-link flags (#2095) — bulk_update, no server_version bump.
+        if program_db_deps:
+            Dependency.objects.bulk_update(
+                program_db_deps, ["is_driving"], batch_size=_WRITEBACK_BATCH_SIZE
+            )
+
+        if schedule_shift_events:
+            TaskActivityEvent.objects.bulk_create(
+                schedule_shift_events, batch_size=_WRITEBACK_BATCH_SIZE
+            )
+
+        # Coalesce: mark exactly the claimed member outbox rows done (DISPATCHED →
+        # DONE). Filtering on DISPATCHED avoids racing the drain's orphan recovery.
+        if claimed_ids:
+            ScheduleRequest.objects.filter(
+                id__in=claimed_ids, status=ScheduleRequestStatus.DISPATCHED
+            ).update(status=ScheduleRequestStatus.DONE)
+
+        # Stamp recalculated_at on every member project so each project's Schedule
+        # view clears its "recalculating" badge (#1053), bulk to skip history.
+        Project.objects.filter(pk__in=member_ids).update(recalculated_at=now)
+
+        # D4 sprint-boundary firewall: detect and upsert cross-project slip
+        # conflicts in the same transaction as the write-back, so a conflict is
+        # never visible against dates that did not commit.
+        if graph.result is not None:
+            detect_and_upsert_slip_conflicts(graph)
+
+        # Per-project broadcasts + forecast capture, deferred to commit (#896) so
+        # clients only ever see dates that persisted. Registered from inside this
+        # atomic block so the on_commit callbacks are tied to this transaction.
+        _register_program_broadcasts(graph, by_project, moved_by_project, crit_order)
+
+    logger.info(
+        "recalculate_program_schedule: program %s — %d member project(s), %d task(s) updated",
+        program_id,
+        len(member_ids),
+        len(tasks_to_update),
+    )
+
+    # schedule.recalculated webhook per member project, after commit.
+    for p in graph.member_projects:
+        pid = str(p.id)
+        project_tasks = by_project.get(p.id, [])
+        project_finish = max(
+            (t.early_finish for t in project_tasks if t.early_finish is not None),
+            default=None,
+        )
+        dispatch_webhooks(
+            project_id=pid,
+            event_type="schedule.recalculated",
+            payload={
+                "project": pid,
+                "project_finish": project_finish.isoformat() if project_finish else None,
+            },
+        )